Skip to content
Beta. This surface may change before GA; breaking changes are dated in the changelog.

Documents

A document is anything you want the Brain to know: a call note, a support thread, a wiki page, a commit message, or a file such as a PDF or a spreadsheet. Send its text and it becomes searchable and citable immediately. Send a file, or a link to one, and Nicia converts it to text in the background.

Terminal window
curl -X POST "$API/v1/brains/tenant:acme/documents" \
-H "authorization: Bearer $NICIA_KEY" \
-H "content-type: application/json" \
-d '{
"id": "zendesk:ticket:8821",
"title": "SSO login loop after IdP change",
"text": "Customer reports a redirect loop after switching to Okta…",
"metadata": { "source": "zendesk", "status": "resolved", "priority": "p1" },
"occurredAt": "2026-08-02T14:20:00Z"
}'
{
"data": {
"document": {
"id": "zendesk:ticket:8821",
"status": "queued",
"consoleLinks": {
"accepted": "https://app.nicia.ai/knowledge/brains/brain_3a91c7?page=zendesk%3Aticket%3A8821"
}
}
}
}

Only text is required. Everything else is optional and useful. consoleLinks.accepted is where a person opens the document in the Nicia console, after signing in as usual; the link carries no credential.

Keep a document’s headings as markdown headings: a standing answer cites a document by section (§ <heading>), and text with no headings can be cited only by line range. A citation can also name a PDF’s page or a spreadsheet’s row, and the Brain checks it: see Citing a page or a row.

A document can also be a file. The Brain keeps the original as it arrived, with its media type and filename, and a text layer that search, /context, citations and receipts read.

Accepted: PDF, PNG, JPEG, WebP, GIF, HTML, Word (.docx), Excel (.xlsx), Markdown, plain text, CSV and TSV. SVG is refused, because an SVG can carry scripts. Nicia checks the file’s first bytes against the mediaType you declare and refuses a mismatch with 400; a docx and an xlsx are told apart by the zip’s [Content_Types].xml.

Nicia converts a file to text when you send none. The original is kept as it arrived, and the text layer is derived from it, in the background, never on your request:

Format Text layer Converted by
Markdown, plain text the file itself —
PDF the text of each page, with a ## Page N heading at each page Cloudflare’s markdown conversion
Word (.docx) markdown, keeping headings, lists and tables Cloudflare’s markdown conversion
HTML markdown, keeping headings, links and tables; scripts dropped Nicia
Excel (.xlsx) one table per sheet under the sheet’s name, values only Nicia
CSV, TSV one markdown table, header row kept Nicia (tabular-v1)
PNG, JPEG, WebP, GIF none —

The write answers converting. A read then reports indexed once the text is searchable, or one of:

  • partial_text: a PDF whose text covers little of it, because it averages under 200 characters a page or has a page with no text. It is indexed and searchable for the text it has, and textLayer.pagesWithoutText lists the empty pages.
  • conversion_failed: conversion ran five times without success, or cannot succeed (a PDF or Word file over 25 MiB, or a text layer over 12 MiB). error says why. See Converting again.
  • stored: an image. Nicia runs no OCR and no model over a file, so an image or a scanned page has no text unless you send it; see Scanned pages and slide images.

Every converted PDF carries textLayer.coverage: "text_only": figures and charts drawn as images are not read, whatever the text looks like, so a deck whose numbers live in charts converts to its titles and footnotes. Read textLayer to see how a text layer was made: source is writer or converted, and a converted one names its converter and outputHash.

Your own text still wins. Send the file with text, your own markdown of it, and that is the text layer; nothing is converted. Do this when you can read the file better than a converter, as an agent with the domain usually can. For a PDF, mark each page with a ## Page N heading (or # Page N) so its text can be read and cited page by page.

Small files go inline, base64, up to 12 MiB decoded:

Terminal window
curl -X POST "$API/v1/brains/tenant:acme/documents" \
-H "authorization: Bearer $NICIA_KEY" \
-H "content-type: application/json" \
-d '{
"id": "filings:10q-2026-q2",
"title": "Q2 10-Q",
"file": { "base64": "JVBERi0xLjcK…", "mediaType": "application/pdf", "filename": "10q-q2.pdf" },
"text": "# Page 1\nQuarterly report…\n\n# Page 2\n…"
}'

Any size goes in parts. Open an upload with the file’s exact size, send each part’s bytes, then commit the upload as the document:

Terminal window
# 1. Open: answers uploadId, partSize, partCount and expiresAt
curl -X POST "$API/v1/brains/tenant:acme/documents/uploads" \
-H "authorization: Bearer $NICIA_KEY" \
-H "content-type: application/json" \
-d '{ "filename": "data-room.pdf", "mediaType": "application/pdf", "size": 48318382 }'
# 2. Send part n: exactly partSize bytes (the last part holds the rest).
# Parts may go in parallel and be retried. Keep each answer's etag.
curl -X PUT "$API/v1/brains/tenant:acme/documents/uploads/$UPLOAD_ID/parts/1" \
-H "authorization: Bearer $NICIA_KEY" \
-H "content-type: application/octet-stream" \
--data-binary @part-1.bin
# 3. Commit it as a document, naming every part and its etag
curl -X POST "$API/v1/brains/tenant:acme/documents" \
-H "authorization: Bearer $NICIA_KEY" \
-H "content-type: application/json" \
-d '{ "id": "data-room", "upload": "'$UPLOAD_ID'", "parts": [{ "n": 1, "etag": "…" }, { "n": 2, "etag": "…" }] }'

Send the parts and the commit with the key that opened the upload. Parts stream straight to storage, so there is no limit on the file’s size beyond what one upload’s 10,000 parts can carry. A commit before every part has arrived answers 409; commit again once they have. Committing the same upload twice answers the same document version. An upload not committed by expiresAt, 24 hours after it opened, is discarded, and a commit after that answers 409 saying the upload expired. You may send sha256 when you open an upload; Nicia hashes any file of 12 MiB or less itself, and refuses one whose hash disagrees with yours.

The same file sent again under the same id with the same text is the same version, as a text document is. For an uploaded file larger than 12 MiB, Nicia only has your declared hash, so sending it again writes a new version.

Files are written on main; a branch takes text documents only.

Send url in place of a file, and Nicia fetches the original itself:

Terminal window
curl -X POST "$API/v1/brains/tenant:acme/documents" \
-H "authorization: Bearer $NICIA_KEY" \
-H "content-type: application/json" \
-d '{ "id": "filings:8k-2026-10", "title": "8-K", "url": "https://www.sec.gov/Archives/edgar/data/…/exhibit99.htm" }'

The write answers converting at once: the fetch runs in the background and the document is then converted like any other file. The read keeps the address as url. The fetch refuses private and internal addresses, at every redirect; takes at most 5 GiB, counted as it arrives; and gives up after ten minutes. Name the file’s mediaType when the address does not end in its extension. A link behind a sign-in cannot be fetched: a 401 or 403, or a web page answered where a file was expected, reads conversion_failed with “Upload the file instead”.

POST /v1/brains/{handle}/documents/{id}/convert, with a write key, re-queues conversion of the document’s latest version: one whose conversion failed, or a file stored before its format could be converted. It answers 202 with converting; read the document for the result. A document that already has a text layer, or an image, answers 409.

Size. A document written over HTTP holds at most 12 MiB (12,582,912 bytes) of UTF-8 text, and a batch carries up to 100 documents. Over MCP the limits are tighter: import takes up to 8 documents per call, 200,000 bytes each and 1,000,000 together, and the rest are answered not imported. Split a longer filing by exhibit or by part, each under its own id. MCP import also takes a document’s url in place of its text, fetched and converted as above; files themselves do not travel over MCP.

Evidence documents written through /documents are not gated by the Brain’s admission level. They land at every level, attributed to the key that wrote them, and a staged record change that cites it does not hold it back. To have documents wait for review, send them as a source snapshot, or write them on a branch with the records that cite them and propose both together; see Review.

The console’s Documents library brings source documents and authored notes into one reading surface. A Markdown note authored there is a governed note record, with its text in fields.body. Its edits follow record admission, unlike the evidence upload endpoint described above. A staged edit waits in Review and leaves the accepted note unchanged.

When the source is images, such as a scanned filing or a slide deck exported as pictures, the Brain cannot read it, and Nicia does not run OCR. A scanned PDF converts to little or no text and reads partial_text; an image is stored. Your agent converts it to text and sends it with the file:

  1. Run OCR, or a vision model, over each page.
  2. Write one # Page N heading per page, using the number printed on the page, so a citation can name the page. See Citing a page.
  3. Record the converter in metadata, for example { "converted_with": "tesseract 5.3" }.
  4. Write the file with that text as its text.

A citation’s quote check proves the quote is in the stored text. It does not prove the quote is on the original image, because the converter may have misread it. For a figure that matters, have a person compare it with the page.

id is a string you choose, and it is the document’s permanent handle. Re-send the same id and you replace that document.

Send one. A document with your id is an upsert, which makes it naturally idempotent — a retry after a timeout is one document, not two. Omit it and Nicia mints an id, but then a retry needs an Idempotency-Key or you get duplicates. See Idempotency.

Use the id from the system the content came from — zendesk:ticket:8821, notion:page:abc. Then a nightly sync is a loop of POSTs with no bookkeeping, no diffing, and no “have I sent this already” table.

Terminal window
# Same id, new content — replaces version 1
curl -X POST "$API/v1/brains/tenant:acme/documents" \
-H "authorization: Bearer $NICIA_KEY" \
-H "content-type: application/json" \
-d '{ "id": "zendesk:ticket:8821", "text": "…updated transcript…" }'

Nicia keeps prior versions. A receipt issued last month still names the version it was served, and the key that made that read can still fetch the text that version held.

Ids beginning nicia: are reserved for documents the Brain keeps itself, so writing one is a 400. The one there is today is a note’s text: nicia:note:<record id> holds the prose of a note record, written by the Brain whenever the note changes, so a rule can cite a passage of the note. You read it like any document, and you change it by writing the note.

Metadata is free-form, and nothing drops it

Section titled “Metadata is free-form, and nothing drops it”

metadata takes any flat JSON object. Nothing needs declaring and nothing is discarded — every key you send comes back on the document when you read it. The one refusal: keys beginning nicia: are reserved — that is where the server keeps the document’s own title and occurredAt — so writing one is a 400, never a key that is silently dropped.

Terminal window
curl "$API/v1/brains/tenant:acme/documents/zendesk:ticket:8821" \
-H "authorization: Bearer $NICIA_KEY"

What metadata is not is an index. No read filters on it: /context and /search take no filter at all, and /query’s where index-resolves exact slug equality only — free-form document metadata is never a predicate. Metadata is how a value survives the trip; it is not how you find it again.

So send it freely — source system, document type, author, team, status, language, confidentiality. Wanting to govern one of them is the signal that it belongs declared as a field on the record kind it describes (returned and governed; non-slug filtering still waits on a property index). Resolve by slug today:

Terminal window
curl -X POST "$API/v1/brains/tenant:acme/query" \
-H "authorization: Bearer $NICIA_KEY" \
-H "content-type: application/json" \
-d '{ "kind": "ticket", "where": { "slug": "zendesk-ticket-8821" } }'

A declared field governs and returns everything already written, because nothing you sent was thrown away. The declaring itself happens when the Brain is created — see when a schema is chosen. A declared field is also filterable in /query; an undeclared one is returned but not queryable.

A document can take a moment to index. The write answers queued — the bytes are stored and the document is already addressable by your id — and a read reports processing until body search can reach it, then indexed. A file being converted answers converting, and then indexed, partial_text or conversion_failed; an image answers stored. A document the Brain refused is rejected, with the reason on it, which in a batch is how one bad document reports itself while the rest land. Read it back to check:

Terminal window
curl "$API/v1/brains/tenant:acme/documents/doc_91ab" \
-H "authorization: Bearer $NICIA_KEY"
{
"data": {
"document": {
"id": "doc_91ab",
"status": "indexed",
"version": 1,
"mediaType": "text/markdown",
"size": 18342,
"textLayer": { "source": "writer" },
"createdAt": "2026-08-14T09:41:02Z",
"updatedAt": "2026-08-14T09:41:05Z"
}
}
}

The read shows the document’s latest version: a replacement file is visible at once, even while it has no text layer. mediaType, filename and size describe its original. textLayer says where its text came from, and is absent while it has none. error says why a conversion or a fetch failed, and url is the address a linked document was fetched from.

Two reads hand a document’s content out, and both need a key with read.

GET /v1/brains/{handle}/documents/{id}/text returns the text layer in pieces. A PDF whose text marks its pages comes back by page, up to 50 pages a read; anything else by character, up to 2 MiB a read. from and to choose the pages (inclusive) or the character offsets, and nextFrom says where to continue:

Terminal window
curl "$API/v1/brains/tenant:acme/documents/filings:10q-2026-q2/text?from=2&to=3" \
-H "authorization: Bearer $NICIA_KEY"
{
"data": {
"version": 1,
"status": "indexed",
"pages": [
{ "page": 2, "text": "…" },
{ "page": 3, "text": "…" }
],
"receipt": "0b9c3f6e-…"
}
}

It reads the version the Brain serves. ?version=N reads an earlier version, but only for a key that a receipt shows was served that version; any other key gets 404. A document with no text layer answers its status and no text.

GET /v1/brains/{handle}/documents/{id}/original downloads the original file of the latest version, with its media type, as an attachment, with X-Content-Type-Options: nosniff and Content-Security-Policy: sandbox, so a browser never renders it as a page of yours.

Each read commits a receipt before it answers: the version, whether it served the text or the original, and for text the pages or characters it served. Reading that receipt’s documents back returns exactly those pages or characters, and for an original read names the file it served rather than any text. /original returns the receipt’s id in the X-Nicia-Receipt header.

GET /v1/brains/{handle}/documents pages through every document you submitted to the Brain over the API, newest version of each, keyset paged by document id. prefix keeps the documents whose id begins with it, taken literally: when your ids are file paths, ?prefix=notes/2026-10 lists one folder.

It is a listing of submissions, not an inventory of everything the Brain can answer from. Content that arrived another way — a synced folder or URL source, say — has no submission behind it and no document id to address, so it is not here, but /context, /query, and /search all read it. Use the listing to reconcile your own pipeline against what landed; use /context to see what the Brain will actually answer with.

Send up to 100 documents in one request. Each is indexed independently, so one bad document does not fail the rest:

Terminal window
curl -X POST "$API/v1/brains/tenant:acme/documents" \
-H "authorization: Bearer $NICIA_KEY" \
-H "content-type: application/json" \
-d '{ "documents": [
{ "id": "zendesk:ticket:8821", "text": "…" },
{ "id": "zendesk:ticket:8822", "text": "…" }
] }'
{
"data": {
"documents": [
{
"id": "zendesk:ticket:8821",
"status": "queued",
"consoleLinks": {
"accepted": "https://app.nicia.ai/knowledge/brains/brain_3a91c7?page=zendesk%3Aticket%3A8821"
}
},
{
"id": "zendesk:ticket:8822",
"status": "rejected",
"error": "text is empty"
}
]
}
}

Per-item isolation is a batch’s promise and only a batch’s. A single-document write that the Brain refuses fails with the refusal’s own status — never a 201 whose body reports a document that was not stored.

An indexed document is immediately available to /context and /search. That is the whole requirement — you can stop here and have a working retrieval system.

Separately, a document write can ask Nicia to turn what it recognises in prose into proposed structured changes, each anchored to the exact passage it came from. This is off by default: send "extract": true to ask for it. In open mode those changes land directly; in reviewed mode they queue for approval. Either way the document itself was already useful.

Structuring a document is usually your agent’s job: it knows the domain and writes the records itself. Ask for extraction when you want Nicia’s proposals beside your agent’s own writes in Review. A file sent without text is extracted once, after it is converted; an image, which has no text, is not.

Terminal window
# See what was extracted from a document
curl "$API/v1/brains/tenant:acme/documents/zendesk:ticket:8821/records" \
-H "authorization: Bearer $NICIA_KEY"

That answers the record addresses this document produced and what kind each one is — not their values. Every read that returns values returns them under a receipt, so read the records themselves through /context or the record read.

Turn extraction on per document:

{ "id": "raw:log:5512", "text": "…", "extract": true }

Documents are addressed, so the way to replace one is to write it again under the same id. The new text becomes the current version, the old version is kept, and a receipt that cited the old version still names it — its text stays readable through that receipt.

There is no document delete, and a document written here is never retired: it is served until you write it again. Removing its influence means retiring every record extracted from it and marking every receipt that cited it — that is correction work over the accepted state, not a delete, and Nicia would rather have no operation than one that quietly leaves derived records standing.

When the content you send is revised as a whole set — one customer’s documents, say — send it as a source instead. A complete snapshot that leaves a document out proposes retiring it, through the Brain’s review policy, together with the record values only that document supported. A retired document stops being served; its versions are kept, and the receipts that pinned them still resolve.