Ingest a file into a chunked document

POST 
/api/v1/documents/ingest

Parses an already-uploaded file and creates one Document split into one or more embedded chunks. The source format is detected from the file's content type: PDFs are parsed page-by-page; text/plain and text/markdown files are read as a single source. How the source is chunked is controlled by chunk_strategy.

A file can only back one Document — a second call with the same file_id returns 409 FILE_ALREADY_INGESTED. To re-process an already-ingested file (e.g. with a different chunk_strategy), use POST /documents/{document_id}/ingest; to ingest the same source under a different path, upload a new copy of the file first.

Request

Responses

201

Ingestion completed synchronously (only when ?wait=true). The document is fully indexed and ready for search.

202

Ingestion accepted. The document record has been created with status=pending and processing runs in the background. Poll GET /api/v1/documents/{document_id} until status is ready or failed.

400

Invalid request, file not found, or unsupported content type

401

Unauthorized

403

Forbidden

409

The file already backs a Document (a file can only be ingested once). Use POST /documents/{document_id}/ingest to re-process the existing document, or upload a new copy of the file to ingest it separately.

413

The file is too large to ingest synchronously (?wait=true). Retry in background mode and poll the document status.