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.
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 | — |
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, andtextLayer.pagesWithoutTextlists 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).errorsays 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:
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:
# 1. Open: answers uploadId, partSize, partCount and expiresAtcurl -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 etagcurl -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.
From a link
Section titled “From a link”Send url in place of a file, and Nicia fetches the original itself:
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”.
Converting again
Section titled “Converting again”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.
Markdown notes in the console
Section titled “Markdown notes in the console”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.
Scanned pages and slide images
Section titled “Scanned pages and slide images”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:
- Run OCR, or a vision model, over each page.
- Write one
# Page Nheading per page, using the number printed on the page, so a citation can name the page. See Citing a page. - Record the converter in
metadata, for example{ "converted_with": "tesseract 5.3" }. - 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.
Your id, not ours
Section titled “Your id, not ours”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.
# Same id, new content — replaces version 1curl -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.
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:
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.
Checking on a document
Section titled “Checking on a document”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:
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.
Reading the text and the original
Section titled “Reading the text and the original”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:
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.
Listing what you sent
Section titled “Listing what you sent”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.
Batches
Section titled “Batches”Send up to 100 documents in one request. Each is indexed independently, so one bad document does not fail the rest:
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.
What happens next
Section titled “What happens next”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.
# See what was extracted from a documentcurl "$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 }Superseding
Section titled “Superseding”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.