---
title: "Re-ingest an existing document"
method: POST
path: "/v1/projects/{project_id}/documents/{document_id}/ingest"
tags: ["Documents"]
---

# Re-ingest an existing document

`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`)

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`).

## Path parameters

- `document_id` string, required

## Query parameters

- `wait` boolean

## Request body

- object
  - `chunk_strategy` 'page' | 'whole' | 'size': How to split the source into chunks. Defaults to `page`.
  - `chunk_size` integer: Window size in characters when `chunk_strategy=size`. Defaults to 1000.
  - `chunk_overlap` integer: Overlap in characters between consecutive windows when `chunk_strategy=size`. Defaults to 200.
  - `session_id` string: Session the ingest runs for. The converter's generation and the chunk embeddings are metered against the session and its actor.
  - `actor_id` string: 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`.

## Response `201`

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

- IngestedDocumentRecord
  - `id` string: Document ID
  - `file_id` string: Underlying file ID
  - `project_id` string: Project ID
  - `path` string, nullable: Logical path of the document within the project (e.g. /reports/q1.txt)
  - `filename` string: Original filename
  - `content_type` string: Media type of the source file the document was ingested from. Absent when the underlying file is gone.
  - `size` integer: 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.
  - `version` integer: 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.
  - `content` string, 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_size` integer: Window size in characters used when `chunk_strategy=size`. Absent otherwise.
  - `chunk_overlap` integer: Overlap in characters between consecutive windows used when `chunk_strategy=size`. Absent otherwise.
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `chunk_count` integer: Number of chunks created from the file.

## Other responses

- `202`: Re-ingestion accepted. The document was reset to `status=pending` and processing runs in the background. Poll `GET /v1/projects/{project_id}/documents/{document_id}/status`.
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Document not found
- `409`: The project's `storage_bytes` quota is exceeded (`QUOTA_STORAGE_EXCEEDED`). Delete stored content, or raise the quota — no window reset clears a stored total, so no `Retry-After` is sent.
- `413`: The file is too large to re-ingest synchronously (`?wait=true`). Retry in background mode.

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)