Documents

Re-ingest an existing document

Re-runs ingestion for an existing document against its already-stored source file. Existing chunks are discarded and the document is reset to status=pending before re-processing. Use this to recover a document stuck in processing/failed or to re-chunk with a different strategy without re-uploading the file. Background by default (202); pass ?wait=true to run synchronously (201).

post/v1/projects/{project_id}/documents/{document_id}/ingest

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/documents/{document_id}/ingest
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

document_idstring required
Example:doc_V1StGXR8Z5jdHi6B

Document ID

Query parameters

waitboolean

When omitted or false (default), processing runs in the background and 202 Accepted is returned immediately with status=pending. Pass true to block until processing completes and receive 201 Created with status=ready.

Request body

chunk_strategy'page' | 'whole' | 'size'

How to split the source into chunks. Defaults to page.

chunk_sizeinteger

Window size in characters when chunk_strategy=size. Defaults to 1000.

chunk_overlapinteger

Overlap in characters between consecutive windows when chunk_strategy=size. Defaults to 200.

session_idstring

Session the ingest runs for. The converter's generation and the chunk embeddings are metered against the session and its actor.

actor_idstring

Actor the ingest runs for when there is no session; metered like session_id. Beside session_id it must be that session's actor, else 400 VALIDATION_FAILED.

Example request

{
  "chunk_size": 1000,
  "chunk_overlap": 200,
  "session_id": "sess_V1StGXR8Z5jdHi6B",
  "actor_id": "actor_V1StGXR8Z5jdHi6B"
}

Response

Re-ingestion completed synchronously (only when ?wait=true).

idstring

Document ID

file_idstring

Underlying file ID

project_idstring

Project ID

pathstring nullable

Logical path of the document within the project (e.g. /reports/q1.txt)

filenamestring

Original filename

content_typestring

Media type of the source file the document was ingested from. Absent when the underlying file is gone.

sizeinteger

File size in bytes

status'pending' | 'processing' | 'ready' | 'failed' | 'withdrawn'

Ingestion lifecycle state. pending — enqueued; processing — chunks being extracted and embedded; ready — fully indexed; failed — processing error (see the error field on GET /documents/{id}/status); withdrawn — taken out of listings and search, with its chunks dropped, and restorable from an earlier version.

versioninteger

The document's content version, starting at 1. Every write that changes the content or its annotations archives the state it replaced and increments this.

contentstring nullable

Text content (only present on getDocument, and only when status is ready)

chunk_strategy'page' | 'whole' | 'size'

The chunk strategy the document was last (re-)ingested with. Absent when the default (whole) was used — the mapper omits the key rather than sending null.

chunk_sizeinteger

Window size in characters used when chunk_strategy=size. Absent otherwise.

chunk_overlapinteger

Overlap in characters between consecutive windows used when chunk_strategy=size. Absent otherwise.

created_atstring date-time
updated_atstring date-time
chunk_countinteger

Number of chunks created from the file.

Example response

{
  "id": "doc_V1StGXR8Z5jdHi6B",
  "file_id": "file_V1StGXR8Z5jdHi6B",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "path": "/reports/q1.txt",
  "filename": "my-doc.txt",
  "content_type": "application/pdf",
  "size": 42,
  "status": "ready",
  "version": 1,
  "content": "The quick brown fox jumps over the lazy dog.",
  "chunk_strategy": "size",
  "chunk_size": 800,
  "chunk_overlap": 120,
  "chunk_count": 10
}

Changes

No recorded changes to this operation across all 1 revision of this API.