Kernsignal/API docs

Quickstart

Run your first audit

About five minutes, with a sandbox key and two small sample files.

Before you start

export KERNSIGNAL_API_KEY=ks_test_your_key_here

1. Download the sample files

Two small CSV files of made-up respondents: a human wave and a synthetic panel for the same questionnaire. They are illustrative, not real data.

curl -sSfO https://kernsignal.ai/docs/sample/synthetic.csv -O https://kernsignal.ai/docs/sample/human.csv

2. Create an audit

The request returns at once with a job in queued state. human_weight names the weight column in the human file; subgroups lists up to five columns present in both files.

AUDIT_ID=$(curl -sSf https://api.kernsignal.ai/v1/audits \
  -H "Authorization: Bearer $KERNSIGNAL_API_KEY" \
  -F synthetic_file=@synthetic.csv \
  -F human_file=@human.csv \
  -F 'config={"human_weight":"weight","subgroups":["gender"]}' | jq -r .id)
echo "$AUDIT_ID"

3. Wait for it to finish

while true; do
  STATUS=$(curl -sSf https://api.kernsignal.ai/v1/audits/$AUDIT_ID \
    -H "Authorization: Bearer $KERNSIGNAL_API_KEY" | jq -r .status)
  echo "status: $STATUS"
  [ "$STATUS" = "succeeded" ] && break
  [ "$STATUS" = "failed" ] && { echo "audit failed"; exit 1; }
  sleep 2
done

4. Read the result and the report

The three bins say what to do with each question: use the synthetic answers, spot-check with humans, or field with humans.

curl -sSf https://api.kernsignal.ai/v1/audits/$AUDIT_ID \
  -H "Authorization: Bearer $KERNSIGNAL_API_KEY" | jq .result.summary.bins
curl -sSf https://api.kernsignal.ai/v1/audits/$AUDIT_ID/report.html \
  -H "Authorization: Bearer $KERNSIGNAL_API_KEY" -o report.html
ls -l report.html

5. Get the verification record

This issues a signed record of what was audited and returns the address of its public page. Anyone can open that address; no key is needed.

VERIFY_URL=$(curl -sSf https://api.kernsignal.ai/v1/audits/$AUDIT_ID/verification \
  -H "Authorization: Bearer $KERNSIGNAL_API_KEY" | jq -r .verify_url)
echo "$VERIFY_URL"
curl -sSf -H "Accept: application/json" "$VERIFY_URL" | jq '{status, mode, signature_valid}'

Open $VERIFY_URL in a browser to see the page. A sandbox record is marked as such.

6. Delete the audit

curl -sSf -X DELETE https://api.kernsignal.ai/v1/audits/$AUDIT_ID \
  -H "Authorization: Bearer $KERNSIGNAL_API_KEY"

Deleting an audit removes its result from the live system immediately; nightly backups hold it for up to 14 days. The verification record persists until you revoke it.

The same flow in Python

python3 -m venv .venv && . .venv/bin/activate
pip install --quiet https://kernsignal.ai/docs/downloads/kernsignal-0.1.0-py3-none-any.whl
import os

from kernsignal import Kernsignal

client = Kernsignal(os.environ["KERNSIGNAL_API_KEY"])

audit = client.audits.create(
    "synthetic.csv",
    human_file="human.csv",
    config={"human_weight": "weight", "subgroups": ["gender"]},
)
audit = client.audits.wait(audit["id"])
print("status:", audit["status"])
print("bins:", audit["result"]["summary"]["bins"])

verification = client.audits.verification(audit["id"])
print("verify page:", verification["verify_url"])
print("record status:", client.verifications.retrieve(verification["id"])["status"])

client.audits.delete(audit["id"])

Next