API REFERENCE · PREVIEW
One endpoint does
the work.
The API is available to pilot firms. This preview documents the core call so your engineers can size the integration before you commit: it is one POST in front of your publication flow.
01AUTHENTICATION
Bearer keys, issued per environment during pilot onboarding. Keys are scoped to your firm and revocable instantly.
Authorization: Bearer vk_live_... # or vk_test_...
02RUN A CHECK
POST /v1/checks
Submit an artefact by URL or inline content. The call is synchronous for typical documents and deterministic: the same artefact and rulebook version always return the same verdict and the same receipt.
POST /v1/checks
Content-Type: application/json
{
"artefact_url": "https://firm.com/promo.pdf",
"rulebook": "uk-fca", // rulebook id
"modules": ["COBS4", "CONC3"], // optional narrowing
"mode": "pre_publication" // or "retrospective"
}200 OK
{
"id": "chk_01j8...",
"verdict": "pass" | "fail" | "refused",
"breach": { "rule": "COBS 4.12A.34R", "reason": "..." }, // on fail
"escalation":{ "reason": "insufficient_grounding" }, // on refused
"citations": ["COBS 4.2.1R", "COBS 4.5.2R"],
"grounding": "sufficient" | "insufficient",
"receipt": {
"sha256": "9f2c41d8...a41e",
"chained": true,
"prev": "b31e07c4...52aa"
},
"evidence_pack_url": "https://.../packs/chk_01j8.pdf",
"rulebook_version": "uk-fca@2026.07"
}03ERRORS & GUARANTEES
400invalid_request — malformed body, unknown rulebook or module
401unauthenticated — missing or revoked key
413artefact_too_large — split the document
422unprocessable_artefact — format not supported for extraction
429rate_limited — retry with backoff; limits sized per pilot
GUARANTEES: DETERMINISTIC (SAME INPUT + RULEBOOK VERSION = SAME VERDICT) · IDEMPOTENT ON RETRY · A REFUSAL IS A FIRST-CLASS RESULT, NOT AN ERROR · EVERY RESPONSE CARRIES ITS RECEIPT