Start an analysis

Analysis is asynchronous, and there is no synchronous mode. The call answers 202 immediately with a jobId; the work happens afterwards. You find out it finished either by polling GET /v1/jobs/:jobId or by giving this call a webhookUrl.

A run is spent before the request is validated. The metering middleware increments the counter before the handler looks at the body, so a call rejected with 400 has still cost a run. A retry loop around a malformed request will empty the period's allowance without producing a single analysis — read the error code before retrying, and at any 4xx change the request rather than repeating it.

Request body

Give the document exactly one way: inline, by URL, or by prior upload. profileId names the audit to run and is always required — GET /v1/profiles lists the ones your tenant is licensed for.

The three document sources

jobId from POST /v1/upload-url — the one to build against. The file is already in storage, so this call carries an id and nothing else. Passing jobId implies pdfUploaded: true.

pdfUrl — a URL the gateway downloads from. It must be https:, and it must not point inside a private network: loopback, link-local 169.254.*, the private ranges 10.*, 172.16–31.* and 192.168.*, and the cloud metadata host are all refused. That is server-side request forgery protection, not a configuration you can relax, and a URL that fails it answers 400 BAD_REQUEST before anything is fetched. A URL that passes but cannot be downloaded — a 404 at your end, an expired signed link — is also a 400, with the upstream status in the message. The download happens inside the request, so a slow host slows this call down.

pdfBase64 — the document inline. Simplest to write and the worst to operate: the encoded string has to be received and decoded before anything is queued. Fine for a one-off test, not for a production integration.

Giving none of the three is a 400.

dynamicContext — local rules for one run

If you audit documents for many similar entities that share one profile but each have a few rules of their own — hundreds of housing associations with their own statutes, say — you do not need a profile per entity. Send the small amount of unique context as dynamicContext on this call. It is merged into the targeted reviewers' prompts in memory for this job only and is never written to the database.

workerContext maps a worker id to the rules that apply to that reviewer for this job. Rules are always aimed at a named reviewer; they are never applied to the whole profile. The ids come from GET /v1/profiles — read them, do not type them.

• customRules — free text. At most 10 rules per targeted worker, 1000 characters each. The engine treats them as supplementary, legally unreviewed context: they cannot override the binding framework the profile carries.
• snippetIds — snippetKey values of existing, already reviewed legal sources to add to that reviewer's material for this job. At most 10 per targeted worker.
• At most 10 targeted workers per job. entityId and entityName are optional labels for your own traceability, 200 characters each.

A worker id that matches no reviewer in the resolved profile fails the job. The call still answers 202; the job then reaches FAILED with errorMessage naming the ids that did not match. Silently ignoring them would be worse — you would believe your targeted context had been applied when it had not.

An id is matched by the reviewer it names rather than by the characters you send, so an older spelling of a reviewer still reaches it. The one thing that cannot work is two keys naming the same reviewer in one workerContext — one of the two entries would have to be discarded, so the job fails naming the second instead.

The object is validated strictly: an unrecognised field is rejected with 400, not dropped.

Webhooks

Give this call a webhookUrl and the engine POSTs to it when the job reaches COMPLETED or FAILED, so you do not have to poll. The same two fields work on POST /v1/action.

The callback carries the job's identity and outcome — not the result. Fetch that from GET /v1/jobs/:jobId when the callback arrives, and fetch it promptly: the retention sweep removes a finished job within fifteen minutes of its last change. Note that updatedAt here is ISO 8601, which the job endpoint's own timestamps are not.

Delivery runs through a task queue: 5 attempts, backing off from 60 seconds to at most one hour. Any non-2xx response counts as a failure and is retried, so a receiver that is briefly down loses nothing — but a receiver that answers 200 and then drops the message loses the run. Answer after you have stored it.

webhookSecret signs the body with HMAC-SHA256 and puts the hex digest in the X-UG-Signature header. Verify it before trusting the payload, and compare in constant time. Without a secret the header is absent rather than empty.

The webhookUrl is held to the same rule as pdfUrl: https: only, and never an address inside a private network. A URL that fails it is dropped without being attempted and without an error reaching you — the job still completes, and you simply never hear about it. If callbacks are not arriving at all, check the scheme first.

Errors

400 covers every way the request can be wrong, and all of them have already spent a run. 403 means your tenant is not licensed for the profile it named; 404 means the licence points at a profile that no longer exists, which is a configuration problem to report rather than to retry.