Skip to main content

Ingest a Document

Upload one document (up to 500 MB) into a source and queue it for extraction. Alias of POST /v1/sources/{id}/documents with batch mode support.

The ingest endpoint uploads one document (up to 500 MB) into a source and queues it for extraction. It is an alias of POST /v1/sources/{id}/documents, provided as a clearer verb for one-off document ingestion. Pass the file as multipart form data; optionally set processing_mode to batch for deferred, lower-cost extraction (otherwise realtime).

Use ingest when your integration submits documents one at a time, for example from an email handler or an upload form. The document is queued immediately and the response returns a document_id you can use to track extraction progress via the documents API.

Ingest requires an API key with the extract scope. Batch mode (processing_mode=batch) trades latency for cost: results arrive within 48 hours at a 50% credit discount.
POST/v1/sources/:id/ingest

Parameters

id*stringThe source id (path).
file*fileThe document to ingest (multipart, max 500 MB).
processing_modestringbatch or realtime. Batch defers extraction at lower cost.

Request

Response

Response fields

document_idstringThe created document UUID.
filenamestringThe uploaded filename.
statusstring`queued` when accepted for processing.
processing_modestringThe mode the document will be processed in.
source_idstringThe source it was ingested into.
linksobjectRelated resource URLs (document, source).

Response

{
  "document_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "filename": "contract-2024.pdf",
  "status": "queued",
  "processing_mode": "realtime",
  "source_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "links": {
    "document": "/v1/documents/d4e5f6a7-b8c9-0123-defa-234567890123",
    "source": "/v1/sources/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Errors

Error responses

401unauthorizedMissing or invalid API key, or the key lacks the extract scope.
404not_foundNo source with this ID exists for your organization.
413file_too_largeThe file exceeds your plan's maximum upload size (at most 500 MB).
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

Source Documents
List Inputs
List Documents