Three calls. Or none.

view=jobs (the default) lists jobs; view=items lists checked items with your references, for search: exact filters on reference, process, subject_reference, decision and input_type, and q, a prefix of an item's reference, its subject_reference, its file name or its check id (job_id, or job_id/index). metadata is never searched, and lists leave it out (read the item for it). Both views take since and until (on created_at) and page with an opaque cursor: pass the previous page's next_cursor (null on the last page). Cursors are stable: checks made while you page never shift a page. A filter of the other view (status and source are jobs-only) is 400 naming it; so is a cursor this route did not issue.

A multipart body with one JSON part request (a CheckRequest) plus one file part per uploaded file, named as the items name them (file, references); or a JSON CheckRequest whose inputs are all URLs ({"url": "https://…"}, fetched once each from your allowlisted hosts and S3 buckets). All the URL fetches of one request share a 60 s deadline (then 504 timeout with reason: fetch_deadline); a body arriving slower than 64 KiB per 10 s fails with fetch_failed, reason: body_stalled.

The job id is request.job_id, else the Idempotency-Key. Exactly one item whose document has at most 10 pages is checked in the request: 200 with the check result. Anything larger is queued: 202 with job_id and status_url (also in Location). If no capacity frees up within the budget the job continues asynchronously and the answer is 503 busy with job_id and status_url; if the item exceeds its 30 s budget, 504 timeout with the same members.

Streaming. With Accept: text/event-stream (exactly one item) the answer is a Server-Sent Events stream (see x-sse-events on the 200 response). The stream closes after decision or error; a : keep-alive comment is sent every 10 s. A stream is not replayable: retrying its Idempotency-Key is 409 idempotency_not_replayable pointing at GET /nib/checks/{job_id}.

Session tokens may call this route only streamed, with one item whose subject_reference is the session's subject and no references, URL inputs, policy, target, template_id (403) or job_id (400). They send no Idempotency-Key.

Results are paginated by item_index: pass next_cursor as cursor. With format=ndjson a finished job's result lines stream as application/x-ndjson (409 conflict while it runs). decision keeps only the items with those decisions (ERROR: items without one); the pagination is unchanged.

A grey PNG of one located signature of the item: its box with 8% padding on each side, at most 640 px on the long side, rendered from the item's input. The crop is kept beside that input (nib/inbox/<job_id>/.crops/) and never outlives it: it expires with the inbox (inbox_ttl, 24 h by default) and with the job's history. 404 when the item has no located signature, or when its input has expired (detail: "the input has expired"). Images have their own rate limit (50/s, burst 200): they never use your API rate.

Records a reviewer's confirmation (the first is kept; audited as check.confirm) and, unless your tenant's learning is off, queues the item for learning. The entry bar is applied later (parent §8.2). No body. See docs/api/learning.md.

Your subjects with their reference counts (live references; anchors are the ones you enrolled, learned the ones Nib learned) and their last check. q is a prefix of the subject reference. Page with cursor (the previous page's next_cursor).

Also the subject's checks over time: checks.recent holds its newest 25 checked items (as in GET /nib/checks?view=items), checks.total counts them all, and checks.next lists them all.

Also revokes the subject's sessions. Audited.

Adds to the subject's references, creating the subject if new. Multipart: one file part per reference, named by its ref_id (PNG, JPEG, TIFF or PDF; at most 20 files and 20 MB in total), each optionally with a text field source.<ref_id>. Or JSON: references by URL. An upload replaces that ref_id. Up to 3 references are enrolled in the request (200); more are queued (202, each queued). ref_ids starting with learned- are reserved (400). A PUT needs no Idempotency-Key: it is idempotent.

A learned reference (learned-…) is removed with unlearn instead (409).

A grey PNG of the stored reference (its first page), at most 512 px on the long side. 404 when the reference or its file is gone, or it was unlearned. Images have their own rate limit (50/s, burst 200): they never use your API rate.

Removes learned references by time (since, by check time) or by source check, deletes their files and blocks those checks from ever being learned again. since blocks the checks recorded up to this call; a job still running then (submitted inside the window) records its checks later and is not blocked. Audited (reference.unlearn). See docs/api/learning.md.

The same as DELETE /nib/subjects/{subject_reference}/references/{ref_id} for the one ref_id that the static unlearn path shadows.

For end-user apps, which never hold an API key. The token is limited to one subject and one streamed check, works only on GET /nib/live and streamed POST /nib/checks, and is shown once (Cache-Control: no-store). No Idempotency-Key (a stored response would keep the token): a retry mints another session. 404 for an unknown subject. While the organisation (or one above it) is suspended, its session tokens are refused with 401 unauthorized, like expired ones.

204 also when already revoked. Open live connections of it close within 30 s.

A WebSocket upgrade. Authenticate with an API key or dashboard token holding nib:checks:create, or a session token in Authorization: Bearer …; browsers, which cannot set that header, send Sec-WebSocket-Protocol: unforged.session, <session token> and the server selects unforged.session.

Send each downscaled preview frame as one binary message: a PNG or JPEG of at most 640 px on its long side and 512 KB, at most 5 per second. Each message gets exactly one JSON text reply, in order (see x-websocket-messages). Frames are analysed in memory and never stored.

A connection closes after 60 s without a data message, after 10 minutes, and when its credential is no longer valid (close code 1008, checked every 30 s): the session expires or is revoked, the API key is revoked, or the organisation (or the one acted in with Unforged-Org) is suspended. At most 20 open connections per tenant (429 before the upgrade) and 200 per instance (503).

201 with the new version; 200 with the latest one when the body equals it (a retried PUT does not mint versions). Versions are immutable; checks use the latest version of the policy they name and record name@version in versions.policy. Audited.

Multipart: a template JSON part (TemplateCreate) and a blank file part (PNG or PDF, at most 20 MB). 409 when the id exists (delete it first) or you have 200 templates. Audited.

The secret is shown once (Cache-Control: no-store). At most 2 active keys (409). The body, if any, must be {}. No Idempotency-Key: a retry issues another key. Audited.

id is a bkt_… id or an access key id of your IAM user. Audited.

The tenant's history retention (default 90 days), the results/ lifecycle backstop derived from it, and the audit log's fixed retention. See docs/api/retention.md.

Finished jobs (jobs, their result rows, nib/results/<job_id>/ and anything left in nib/inbox/<job_id>/) are purged once older than the retention, within about a minute. A job that a live learned reference came from is kept until that reference is unlearned or evicted. Usage records (billing) and the monthly quota count are never affected. A change is audited (settings.retention.set); setting the current value again is not.

Whether accepted signatures can become extra references of their subject, and the bar they must reach. The defaults (learning off, 0.99, 10) until they are set. Also terms_accepted, the tenant's most recent biometric-retention terms acceptance (null if none was ever recorded; Task 9 fix round 1). See docs/api/learning.md.

Replaces the three settings (all are required). learn_min_band_lo is 0.5 to 1 and max_learned 0 to 50; a refusal is 400 naming the field. Turning learning on (from off) is refused with 409 learning_terms_required unless the tenant has accepted the current biometric-retention terms (POST /nib/settings/learning/terms); turning it off is always allowed. The next check uses the new settings. A change is audited (settings.learning); setting the current value again is not.

The URL must be https (port 443, or an explicit port ≥ 1024) and resolve to public addresses only. Before the endpoint is created, a webhook.test event signed with the new secret is posted to the URL: anything but a 2xx within 10 s is 400 webhook_test_failed and nothing is created. The secret (whsec_…) is shown once (Cache-Control: no-store). At most 20 endpoints (409). 503 not_ready while the service has no master key. No Idempotency-Key. See docs/api/webhooks.md.

Deliveries still queued for it are dropped. Audited.

A new secret (whsec_…, shown once, Cache-Control: no-store) replaces the old one at once: every delivery from now on, including retries of earlier events, is signed with the new secret only. Update your endpoint's secret straight away. 503 not_ready while the service has no master key. No Idempotency-Key. Audited.

Queues a new delivery of the same event (same id and body). 503 not_ready while the service has no master key. Audited. The delivery log keeps attempts 30 days; an older delivery_id is 404.

One UTC calendar month (period: current, the default, or YYYY-MM). checks and billable_checks count the checked items and the billable ones (a decision of AUTO_APPROVE, APPROVE, FLAG or FAILED); not_charged and decisions count the month's checked items by decision (errors: items without one). The estimate is $0.50 per billable check. For an organisation billed through its parent (billing.mode: parent) the parent is invoiced; the amount is still shown. daily lists every day of the month that has begun.

The key is shown once (Cache-Control: no-store); only its display prefix, its id and the hash of its secret are stored. It carries the organisation's home region as a routing hint (not a secret: the secret part is). No Idempotency-Key: a retry issues another key. Audited.

204 also when already revoked. As for creation, the key's permissions must be within the caller's own (else 403 permission_denied naming the excess; an owner holds every permission). An API-key caller cannot revoke the last active key holding org:keys:manage (409). Takes effect on the next request. Audited.

Exists only when the operator configured a metrics token (UNF_METRICS_TOKEN); else 404 exactly like an unknown route. The token (not an API key) is required as a bearer token (401 otherwise).