Documents

Documents are the source material for grounded query. Provide exactly one of text, url, or file_base64 when ingesting. Ingest costs 5 credits.

Ingest a document

POST /v1/brain/documents

string

Raw text to ingest (exactly one of text / url / file_base64).

string

A URL to fetch and ingest (SSRF-guarded; private/local hosts blocked).

string

Base64-encoded file bytes (PDF/DOCX/XLSX/text).

string

Optional filename/label.

string

MIME type when uploading file_base64.

string

Provenance tag (e.g. upload, web, agent:researcher).

string

Target KB (defaults to the company’s default brain).

curl -X POST https://api.usenaive.ai/v1/brain/documents \
  -H "Authorization: Bearer nv_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "text": "Our refund policy is 30 days.", "filename": "refunds.md", "source": "policy" }'

{ "id": "doc-uuid", "filename": "refunds.md", "status": "ready", "source": "policy", "created_at": "2026-07-09T12:00:00.000Z" }

Large text, URLs, and files ingest asynchronously (status processing → ready/failed). Poll GET /v1/brain/documents/:id to refresh. Multipart upload of a file field is also supported.

Replace a document

PUT /v1/brain/documents/:id — replace/refresh content in place, keeping the document id. Same body as ingest; 5 credits.

List documents

GET /v1/brain/documents?knowledge_base_id=kb-uuid

{ "documents": [ { "id": "doc-uuid", "filename": "refunds.md", "status": "ready" } ], "count": 1 }

Get a document

GET /v1/brain/documents/:id — returns the document with a refreshed processing status.

Delete a document

DELETE /v1/brain/documents/:id — permanent. Approval-gated for agent callers (returns 202 pending); returns a deletion receipt on completion.

{ "deleted": true, "receipt": { "provider": "postgres", "provider_confirmed": true, "verified": true, "deleted_at": "2026-07-09T12:00:00.000Z" } }

Overview

Endpoints

Ingest a document

Replace a document

List documents

Get a document

Delete a document

​Ingest a document

​Replace a document

​List documents

​Get a document

​Delete a document

Ingest a document

Replace a document

List documents

Get a document

Delete a document