Document scans

Upload a document with POST /v1/scan/document. Send Prefer: respond-async to accept background work and poll for the result. Omit that header to wait for inline processing. Both modes use the same multipart request body.

Upload and accept work#

Use an active project key with scan:write to upload and result:read to poll. The API creates the scan_uuid; no separate document creation request is needed.

export ZAUN_BASE_URL='https://api.zaun.ai'
export ZAUN_API_KEY='zaun_REPLACE_WITH_YOUR_KEY'

curl --silent --show-error --fail-with-body --include \
  "$ZAUN_BASE_URL/v1/scan/document" \
  -H "Authorization: Bearer $ZAUN_API_KEY" \
  -H 'Prefer: respond-async' \
  -F 'file=@./document.pdf' \
  -F 'metadata={"source":"upload"}'

Let your HTTP client set Content-Type: multipart/form-data and its boundary. The file part contains the actual bytes. Do not send a URL or base64 JSON. There is no async body parameter.

TXT, Markdown, CSV, HTML, PDF, DOC, DOCX, XLS and XLSX are supported. Detection uses the file contents. The file limit is 10,485,760 bytes (10 MiB); the entire multipart body must fit within 11,534,336 bytes (11 MiB), including fields and boundaries.

New asynchronous acceptance returns:

HTTP/1.1 202 Accepted
Location: /v1/result/7ba30cda-7c73-4e44-ad37-8829327602ad
Preference-Applied: respond-async
Retry-After: 2
Content-Type: application/json

{
  "scan_uuid": "7ba30cda-7c73-4e44-ad37-8829327602ad",
  "status": "in_progress",
  "status_url": "/v1/result/7ba30cda-7c73-4e44-ad37-8829327602ad"
}

A 202 confirms acceptance for background processing. Poll for the final result; acceptance is separate from the classification outcome.

Poll for the result#

Resolve status_url against the same API base URL. Authenticate with a result:read key from the same project.

curl --silent --show-error --fail-with-body --include \
  -H "Authorization: Bearer $ZAUN_API_KEY" \
  "$ZAUN_BASE_URL/v1/result/7ba30cda-7c73-4e44-ad37-8829327602ad"

While processing, polling returns HTTP 202, status: in_progress and a job_state of queued or running. Wait for the Retry-After interval before polling again. A retry may move work from running back to queued without changing its scan_uuid.

Terminal retrieval returns HTTP 200. Inspect the result body:

HTTP 200 means the result was retrieved; it does not mean the document is safe. Use the API reference for complete response schemas and scan concepts for verdict interpretation.

Retrieve an accepted scan#

Poll the returned status_url to retrieve accepted work without submitting another scan. Each POST creates a new request and returns its own scan_uuid.

For HTTP 429 or 503, honor Retry-After when present. Invalid, unsupported or oversized uploads require correcting the request.

Background processing#

Use asynchronous mode to submit work and retrieve the result without keeping the upload connection open. Accepted jobs are queued for processing. Poll the returned status_url and honor Retry-After until processing finishes. If a job fails or expires, inspect its error before submitting a new scan.

Synchronous mode waits for processing within the request.

Extraction evidence and deletion#

Document results can include extraction geometry and OCR confidence. Coordinates are normalized page fractions; OCR confidence is on a 0–100 scale and is not a security confidence score. Recognized regions do not identify exact attack spans. Extracted document text is not returned in the public result.

Temporary document bytes and extraction checkpoints are retained while durable work is pending and are scheduled for cleanup after completion or deletion.

To delete a result or cancel pending work, use DELETE /v1/result/{scan_uuid} with result:delete permission in the same project. Deletion prevents later publication and schedules cleanup; it cannot undo a provider call already in flight.