The whole of Veil's second front door: authenticate, open a case, upload documents, read what came back and hear about it when it changes. Every mutating endpoint is a thin adapter over the same function the dashboard calls, so there is no second implementation of any rule.
Every request carries an API key as a bearer token. A key begins with pv_live_ and is shown once, in the Developer area, when it is created. Veil stores only a hash of it, so a key that is lost is replaced rather than recovered.
A key is not a shared credential with a role attached. It has its own identity inside your organisation, so row level security applies to every read it makes, and the audit log, which holds no personal data, records what the key did rather than who created it. Revoking a key stops it immediately and leaves its history intact.
A key holds a role, capped at the role of the person who created it and never owner, and a set of scopes. Scopes narrow the role; they never widen it. A key whose role is member and whose scopes include releasing a case still cannot release one, because the check that matters happens in the database.
A request outside the key's scopes is refused with a fixed code, before anything is written. Give a key the smallest set its integration needs: a key that can read cases and download bundles cannot open, advance or release one, and only a key holding cases:erase can abandon a case and erase its material.
The code is drawn from a closed vocabulary, so a client branches on it rather than on prose. The message is a fixed English sentence and never quotes the input: a validation failure names the field that was wrong and never the value that was in it, because that value may be the personal data the whole product exists to keep in one place.
The request id is generated per request, returned in the body and in an X-Request-Id header, and appears in the one log line the request writes. It is what to quote in a support mail, and quoting it does not mean quoting anything else.
Every failure
{
"error": {
"code": "case_not_released",
"message": "The case has not been released yet.",
"request_id": "01J8ZQ9C4R7K2M6N0P3T5V8W1X"
}
}
Every error code the API answers with
Status
Code
Message
400
idempotency_key_required
This endpoint requires an Idempotency-Key header.
400
invalid_cursor
The cursor is not one this API issued.
400
invalid_request
The request does not match the contract.
401
invalid_key
The API key is missing, unknown, revoked or expired.
403
api_access_unavailable
This organisation's plan does not currently include API access.
403
decision_requires_a_person
This decision discloses personal data and is made by a person in the Veil dashboard.
403
insufficient_scope
The API key does not hold the scope this endpoint requires.
403
not_authorized
The API key's role does not allow this.
404
not_found
No such resource.
409
bundle_not_ready
The case has not been packaged, so it has no bundle yet.
409
case_not_draft
The case has left draft, so its intake can no longer be changed.
409
case_not_ready
The case is not ready to be released.
409
case_not_released
The case has not been released yet.
409
case_purged
The case has been purged, so its documents and reports are gone; its record carries the tombstone.
409
entity_not_editable
The entity's current state does not allow this change.
409
idempotency_key_reused
This Idempotency-Key was already used with a different request body.
409
plan_limit_reached
A plan limit refused this request.
409
report_not_ready
The case has not been packaged, so it has no quality report yet.
409
review_not_open
The case is not in review, so entity decisions cannot be changed.
409
spot_check_miss_stalled
The spot check reported a miss whose reprocessing failed; an admin can retry it in the dashboard.
409
spot_check_miss_unresolved
The spot check reported a miss and the case is still being reprocessed.
409
spot_check_pending
The case's spot check has pages that nobody has answered yet.
409
transition_refused
The case's current state does not allow this.
422
anchor_not_derivable
No searchable variant could be derived from that anchor.
429
rate_limited
Too many requests for this API key in the current window.
Every list is cursor paginated. A response carries the rows and a next cursor, which is opaque: it encodes an instant and an id, and the only correct thing to do with one is to send it back.
It is not an offset, and that is a correctness decision rather than a performance one. A case list mutates under a client that is paginating through it, and an offset silently skips rows when it does.
An Idempotency-Key header is accepted on every request that creates or advances something, and required on case creation. Veil stores the key with your organisation, the endpoint, a hash of the request body and the response, for 24 hours.
A replay with the same key and the same body returns the stored response and says so in an Idempotency-Replayed header. A replay with the same key and a different body is refused. That is what makes a retrying integration safe: a client that times out creating a case and tries again gets one case, not two, and does not spend a second slot against its plan.
A key may make 120 requests in a 60 second window. Two endpoints start work that costs model calls and take a smaller budget of 10 in the same window.
POST /cases
POST /cases/{caseId}/process
Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and, once a limit is reached, Retry-After. Honour that last one: a client that retries immediately spends its next window on refusals.
Refused: a person answers spot check pages in the dashboard
Scope
cases:write
Behind it
nothing, answered 403 decision_requires_a_person before anything is read
Idempotency key
accepted
Always refused with 403 decision_requires_a_person. A spot check page is answered by a person in the Veil dashboard, not over the API. To process cases through the API alone, an admin can set spot checks to None under Settings, Organization; every plan with API access allows it, and it applies to cases packaged after the change.
Register an endpoint in the Developer area, pick the events it should hear, and Veil posts to it. The signing secret is shown once, at registration and again on rotation, and is stored encrypted: nothing hands it back, which is why an endpoint offers rotation rather than a reveal.
Payloads carry ids, statuses, counts, timestamps and the case reference, and nothing else. No filename, no entity label, no anchor value, no document excerpt, no address, no name. The reference is included because it is Veil's own generated string and names nobody, and one human readable handle is what a customer needs to reconcile against their own ticket. The external reference you can set when you create a case is not in a payload either: it is your own string and may point at a person, so a receiver that wants it reads the case by its id.
Payloads are signed and not encrypted. TLS protects them in transit, and there is nothing in one whose disclosure to a network observer would matter, which is what makes the rule above load bearing rather than decorative.
A member of your organisation can send a delivery again from the delivery log in the Developer area, for as long as the log keeps it. That queues a new delivery with a new Veil-Delivery and a fresh signature, carrying the same payload, which is why a receiver deduplicates on the payload's id rather than on the header. Sending a delivery again is a dashboard action and has no API endpoint.
POSTcase.status_changed
Sent to every active endpoint of the organisation subscribed to case.status_changed. Verify Veil-Signature over the raw body before parsing it.
Every delivery carries Veil-Signature alongside Veil-Delivery and Veil-Event. The algorithm is HMAC-SHA256 over <t>.<raw request body>, keyed with the endpoint's signing secret.
Veil-Signature
t=<unix seconds>,v1=<hex>
01Read the raw request body as text before parsing it. A JSON round trip reorders keys and changes whitespace, and either would change the bytes the signature was taken over.
02Split the Veil-Signature header on commas into t and v1.
03Recompute HMAC-SHA256 over the exact string t + "." + body, keyed with your endpoint's signing secret, and compare the hex digest with v1 in constant time.
04Refuse a timestamp more than 300 seconds old, which is what makes a captured delivery useless as a replay.
05Deduplicate on the payload's id. Veil-Delivery stays the same across the retries of one delivery, but a delivery sent again from the delivery log carries a new Veil-Delivery and the same payload, so only the payload's id recognises the event you already handled. Delivery is at least once; it is not exactly once.
Signature verification is the part of a webhook integration that is easy to get subtly wrong, and getting it wrong fails open. Veil publishes a verifier alongside the contract so that the check is a call rather than a transcription of the recipe below. The same package carries the request and response types, the closed error vocabulary and the scope list, so a client branches on constants rather than on strings it typed. The verifier is verifyWebhookSignature, exported from @pritect-veil/api.
Deliveries are dispatched by a scheduled job rather than at the instant of the transition, so a delivery waits up to one minute plus the dispatch itself. Do not build a synchronous flow on top of it.
A delivery is attempted up to 6 times. The first goes on the next dispatch tick, then Veil waits 1 minute, then 5 minutes, then 25 minutes, then 2 hours, then 6 hours. A 4xx other than 408 and 429 is terminal on the first response. 408, 429, every 5xx, a timeout at 10 seconds and a connection failure are retried.
After 20 consecutive failures an endpoint is disabled and somebody has to enable it again, because an endpoint nobody is listening to should stop generating traffic and start generating a message. Redirects are not followed. The delivery log holds 30 days.
A case moves to ready when verification completes, the last stage of the pipeline, and packaging starts after that: the bundle is written next, and the spot check pages are sampled immediately after the bundle. So a consumer that reacts to case.ready and presses release in the same breath is refused bundle_not_ready until the bundle exists, which takes seconds for a small case and minutes for a large one, and a consumer that reads the sample in that window can legitimately get an empty list. Poll the spot check until pages appear, or attempt the release and treat bundle_not_ready and spot_check_pending as the two signals that packaging is still landing and a page is still waiting to be answered. Do not read one empty list and conclude the case was sampled and had nothing to check.
A boundary stated is a boundary somebody can build around. These are deliberate, and each one has a reason that is not a roadmap entry.
Two decisions a person makes
Marking an entity as the data subject and keeping one as non personal both disclose personal data into the released bundle, which is the judgement what a disclosure keeps and what comes out is about. Both are made in the dashboard behind a gate that has to be typed out, and the API answers a request to make either of them with a refusal rather than a quiet success.
Anything that carries document text
The dashboard can show the sentence an entity was found in. The API cannot, because every field that carries document text is a field a customer's log aggregator may end up holding. The three decisions version one does allow need none of it.
Answering a spot check
A spot check exists so that a person looks at sampled pages of the redacted output before release, so clearing a page over the API is refused with the same answer as the two decisions above. Reporting a miss stays in the dashboard too: a miss carries a leaked value somebody typed, and there that value is encrypted under the case key a purge destroys before it touches a row. The API can read a spot check. To process cases through the API alone, an admin sets spot checks to None under Settings, Organization; every plan with API access allows it, and it applies to cases packaged after the change.
Resuming a case stopped on quality
The API can withhold a failed document and retry packaging, which are the levers a stopped case usually needs. Resuming a case stopped at blocked_health afterwards, and sending documents the verifier withheld back through render and verify, are an admin's acts in the dashboard.
Connector pulls and the settings tree
Starting a pull from a connected workspace needs an interactive consent that already exists in the dashboard. There is no organisation, member, invitation, billing or subscription endpoint either: the API drives cases, not the tenancy. Releasing a case through this API meters it exactly as releasing it from the dashboard does, at the rate the published plans state.
A console on this page
There is no button here that sends a request. A console needs a live key in a browser, which is the one place a key should never be, and building one honestly needs a test mode that does not exist yet.
This page is generated from the contract itself. Every path, scope, error code, payload and interval on it is read from the document Veil serves, so it describes the API that is running rather than the one that was written about.