Ingest a file into a chunked document
POST/v1/projects/:project_id/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
- 202
- 400
- 401
- 403
- 404
- 409
- 413
- 429
- 500
- 502
- 4XX
Ingestion completed synchronously (only when ?wait=true). The document is fully indexed and ready for search.
Ingestion accepted. The document record has been created with status=pending and processing runs in the background. Poll GET /v1/projects/{project_id}/documents/{document_id} until status is ready or failed.
Invalid request, file not found, unsupported content type, or an unknown session_id (SESSION_NOT_FOUND) or actor_id (ACTOR_NOT_FOUND) in the project
Unauthorized
Forbidden
The project does not exist or the caller is not a member of it (RESOURCE_NOT_FOUND).
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), the path it would be filed at is held by another file in the project (NAME_CONFLICT), or the project's storage_bytes quota is exceeded (QUOTA_STORAGE_EXCEEDED; delete stored content or raise the quota — no Retry-After is sent, since no window reset clears a stored total).
The file is too large to ingest synchronously (?wait=true). Retry in background mode and poll the document status.
QUOTA_EXCEEDED — a requests quota on the calling API key or its project is spent for the window; Retry-After says when it reopens
Response Headers
Seconds until the quota window admits a request again
Unexpected server error — INTERNAL_ERROR, with the raw message never forwarded
The deployment's admission service is asked about this write and did not answer — ADMISSION_UNAVAILABLE; the write did not happen
The deployment's admission service refused this write — answered under the service's own 4xx status, with its code (matching ^[A-Za-z_][A-Za-z0-9_]{0,63}$, not necessarily an ERROR_CODES key), message and meta; the write did not happen. A status this operation also declares on its own is documented there