Kernsignal/API docs

SDKs and examples

SDKs and examples

A small Python client, dependency-free JavaScript helpers for fetch, and runnable examples.

Python

pip install https://kernsignal.ai/docs/downloads/kernsignal-0.1.0-py3-none-any.whl

Python 3.9 or newer; the only dependency is httpx.

import os
from kernsignal import Kernsignal

client = Kernsignal(os.environ["KERNSIGNAL_API_KEY"])          # base_url defaults to https://api.kernsignal.ai/v1
audit = client.audits.create("synthetic.csv", human_file="human.csv", config={"subgroups": ["gender"]})
audit = client.audits.wait(audit["id"], timeout=600)           # returns on succeeded or failed
html = client.audits.report(audit["id"], "html")               # also "pdf" and "csv"
record = client.audits.verification(audit["id"])
public = client.verifications.retrieve(record["id"])           # no key needed for this call
client.audits.delete(audit["id"])
CallDoes
audits.create(synthetic_file, human_file=None, config=None, idempotency_key=None)Files may be paths, bytes, open files or (filename, bytes).
audits.retrieve(id) / audits.wait(id, timeout=600, poll_interval=2)wait raises WaitTimeoutError on timeout; a failed audit is returned, not raised.
audits.report(id, format="html")Bytes of the report (html, pdf) or of questions.csv (csv).
audits.delete(id)Remove the result from the live system now.
audits.verification(id, display_name=...), audits.revoke_verification(id, reason)See Verification. Raises InvalidRequestError with code verification_requires_human_evidence for an audit that has no human evidence.
verifications.retrieve(id)The public record.
webhooks.create / list / delete / deliveriesManage endpoints. See Webhooks.
webhooks.construct_event(payload, signature_header, secret)Verify a delivery and return the event.

Errors

Every error response raises a subclass of kernsignal.APIError with status, type, code, message and param: InvalidRequestError, AuthenticationError, KernsignalPermissionError, NotFoundError, RateLimitError (with retry_after) and InternalServerError. Network failures raise APIConnectionError. Reads, deletes and creates with an idempotency key are retried twice on 429, 502, 503, 504 and connection errors.

from kernsignal import NotFoundError

try:
    client.audits.retrieve("aud_missing")
except NotFoundError as err:
    print(err.code, err.message)

JavaScript

One file, no dependencies, Node 20 or newer: kernsignal.mjs. It exports createAudit, getAudit, waitForAudit, getVerification, constructEvent (webhook signatures) and verifyRecordSignature.

import { createAudit, waitForAudit, getVerification } from "./kernsignal.mjs";

const apiKey = process.env.KERNSIGNAL_API_KEY;
const job = await createAudit({
  apiKey,
  files: { synthetic: new File([syntheticBytes], "synthetic.csv"), human: new File([humanBytes], "human.csv") },
  config: { subgroups: ["gender"] },
});
const audit = await waitForAudit({ apiKey, id: job.id });
const verification = await getVerification({ apiKey, id: audit.id });

Call the API from your server, not from a browser page: the key must stay secret.

Examples