Documents
Upload, processing, and the document status lifecycle.
A document moves through four statuses. Uploading and processing are separate calls on purpose, so you can batch, retry, and decide when to spend processing time.
Statuses
| Status | Meaning |
|---|---|
uploaded | Stored. Not yet parsed, not extractable. |
processing | Being parsed. A second POST /documents/process will not re-fire it. |
processed | Parsed and ready to extract. |
failed | Parsing failed. Re-process to retry. |
Upload
POST /documents accepts multipart (file=), a URL ({ url }), or inline base64 ({ base64, fileName }). Pass projectId to link the document to a project, or omit it for a library upload you attach later with POST /extractions/{id}/documents. The response carries status uploaded and, once webhooks are configured, fires document.uploaded.
The optional reference is an opaque string-to-string object echoed back on the document's jobs and on every webhook about it — up to 20 keys, key 64 characters, value 500, 4 KB total. It is your correlation id. Never put personal data or secrets in it; it appears in webhook payloads and server-side logs.
Process
POST /documents/process starts parsing for up to 50 already-uploaded documents in one call. It answers 202 with a per-document status and a single batch jobId covering all of them. Documents already processed are skipped unless force: true; an unknown or cross-organization id comes back as not_found rather than an error.
Track completion by polling that job, or per document through the document.processed and document.processing_failed webhooks — each of which carries its own single-document jobId.
Everything else
GET /documents lists a project's documents with their statuses; GET /documents/{id} reads one; GET /documents/{id}/content downloads the original file exactly as uploaded; PATCH /documents/{id} renames; DELETE /documents/{id} removes it and its results. Deletion requires the admin role.