Start a field-detection run
Asks the detection agent to find the signature, initials, text, date, and checkbox fields in a document, and returns the run's id straight away.
Detection is a run, not a synchronous call. Nothing in this response carries fields. Two ways to get them:
- Poll GET /documents/{documentId}/detect/{runId} until status is completed or failed.
- Subscribe to the detection.completed and detection.failed webhook events and wait for one.
The status code says what happened. 202 means a new run was reserved and queued. 200 means no new work was started: either a completed run for the same document and agent version was reused (cached: true, status: "completed"), or a run for this document was already in flight and the caller was joined to it (status: "processing").
Send {"force": true} to skip the completed-run cache and start a fresh run. Forcing never returns, mutates, or deletes an earlier run: history is kept for audit and comparison and is listed by GET /documents/{documentId}/detect. What forcing does not skip is the in-flight guard, since a run happening right now is already producing fresh output, so a forced request joins it rather than paying twice for the same answer. Unknown body keys are rejected rather than ignored, so a misspelled force fails loudly instead of quietly handing back the cached run it was meant to bypass.
The document must be ready; anything else answers 409 document_not_ready. A document over the 200-page limit answers 422. Detection is throttled at five runs per workspace per minute, answering 429 rate_limited, and against a daily spend cap, answering 429 daily_budget_exceeded; forcing buys neither a larger budget nor a larger allowance. Spend is charged to the workspace that owns the document, never to the user who issued the credential. On a deployment with no model provider configured, this endpoint answers 501.
Detection failure is a distinct signal from envelope failure: the envelope is untouched and fields can still be placed by hand.
Accepts an Idempotency-Key: a retry with the same key replays the original response instead of starting a second run.
Request
- Base URL: https://inkseal.net/api/v1
- URL: https://inkseal.net/api/v1/documents/{documentId}/detect
- Auth: HTTP bearer
Headers
Makes this mutation retry-safe. 1 to 255 printable ASCII characters (0x20 to 0x7e), trimmed before use. The key is scoped to the workspace and the credential that sent it. Reusing it with a different method, path, or payload answers 422 idempotency_key_reuse. A completed attempt replays its stored status and body with an Idempotent-Replay: true response header; 5xx, 429, and non-JSON answers leave the key retryable. A concurrent request holding the 90 second lease answers 409 idempotency_in_progress. Records are retained 24 hours.
Request body
Example request
{
"force": true
}Response
No new run was started. Either a cached completed run answered the request, or an in-flight run was joined.
Example response
{
"data": {
"detectionRunId": 4821,
"status": "queued",
"cached": false,
"forced": true
}
}Changes
No recorded changes to this operation across all 1 revision of this API.