Documents

Get a document by ID

Returns a document with its text content

get/v1/projects/{project_id}/documents/{document_id}

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/documents/{document_id}
  • 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

Response

Document found

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

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
}

Changes

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