Documents

Ingest a normalized document

Source → Indexer → Candidates → Brain: stores + chunks the text, runs the selected indexers, commits grounded candidates as facts. mode: "async" fans out per-indexer queue jobs instead (requires DOCUMENT_MULTI_INDEXER_ENABLED). Throttled to 10 requests/min per credential. Part of the document pipeline — answers 503 feature_disabled until DOCUMENT_INGEST_ENABLED=1. Source: src/documents/documents-ingest.controller.ts.

Required scope: brain:write.

post/v1/ingest/document

Request

  • Base URL: https://brain.inite.ai
  • URL: https://brain.inite.ai/v1/ingest/document
  • Auth: HTTP bearer

Request body

kindstring required

Container kind the connector normalized from (pdf/markdown/email/…). Open string — provenance metadata only.

metaobject

Operator-supplied metadata, projected onto derived facts' source.meta.

mode'sync' | 'async'

'async' requires DOCUMENT_MULTI_INDEXER_ENABLED and storeContent.

occurredAtstring date-time required

ISO 8601 — becomes the derived facts' validFrom.

originUristring

Pointer back to the raw container (URL, path, message id…).

storeContentboolean

Store the normalized chunks server-side. false keeps only contentHash + metadata (no re-index, no span re-validation).

textstring required

Normalized document text (DOC_MAX_CHARS may lower the cap).

titlestring
toolObservationRefstring

Provenance hop to the tool result this document derives from (tool_observation:<id>, migration 0111). Honored only under TOOL_OBSERVATIONS_ENABLED; folded into committed facts' source.evidence[].

userIdstring

Per-user memory scope (0128): stamps the stored document, every committed fact and any projected scenes with this end-user; dedupe is scope-local. M2M-asserted; a user-bound token pins it to its own user (mismatch = 403).

Response

Ingest outcome — shape follows the requested mode.

OR

Changes

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