Sources

A source is one producer’s stream of documents: one customer’s content, one repository’s docs folder, one CRM export. You send a source its documents as snapshots — the whole current set, or an explicitly partial one — and the Brain compares each snapshot with what the source said before and what the Brain has accepted, before anything is served.

Use a source when the content you send has an owner that revises it as a set. Keep using POST /documents when you only ever add or rewrite documents one at a time.

What a source is

A source is a name you choose, one per Brain. The name is part of the URL; the credential only has to be allowed to write:

curl -X POST "$API/v1/brains/tenant:acme/sources/acme-content/snapshots" \
  -H "authorization: Bearer $NICIA_KEY" \
  -H "idempotency-key: acme-content-2026-09-23"

A name is lowercase letters, digits and hyphens, starts with a letter or digit, and is at most 64 characters. Three things follow from the name being the identity:

Any key that may write continues the source. A new key, a replacement for a revoked one, a management key and the console all name acme-content and get the same source, the same documents and the same served values. A source never forks into a second copy that answers beside the first.
The first writer is recorded as its owner. owner names the key that first opened the source. It is attribution, not a gate: it does not change when another key writes, and it does not stop anyone else with the capability.
One snapshot is open at a time. Opening a snapshot supersedes the source’s open one, whichever key opened it.

A document belongs to exactly one source, addressed by the source and the id you gave it there. The same text sent under two sources is two documents, and retiring a document from one source never touches the other.

Listing sources

Any key with read can list every source in the Brain, whoever owns it, with each one’s newest snapshot. It answers names, owners and counts — no content:

curl "$API/v1/brains/tenant:acme/sources" \
  -H "authorization: Bearer $NICIA_KEY"

{
  "data": {
    "sources": [
      {
        "name": "acme-content",
        "owner": { "keyId": "key_7f3a1c" },
        "latestSnapshot": {
          "id": "01a0cdbb-66e1-75be-a056-c758c4b3ee4c",
          "source": "acme-content",
          "status": "applied",
          "completeness": "complete",
          "documents": 2,
          "bytes": 58,
          "openedAt": "2026-09-23T10:06:45.984Z",
          "sealedAt": "2026-09-23T10:06:46.025Z",
          "plannedAt": "2026-09-23T10:06:46.068Z",
          "closedAt": "2026-09-23T10:07:12.310Z",
          "expiresAt": "2026-09-30T10:06:46.068Z",
          "appliedPlanRevision": 1,
          "appliedAt": "2026-09-23T10:06:46.099Z"
        }
      }
    ]
  }
}

GET /v1/brains/{handle}/sources/{name} reads one: the source with that name. A source exists once a snapshot has been opened for it.

How reads name a source’s documents

A receipt names a document of a source by the source and your id for it: the item carries document: { "source": "acme-content", "id": "pricing" } and uses pricing as its source.

A /context document item does too: its id is the Brain’s own id for the document, and it also carries document: { "source", "id" }.

/context citations and /search results do not do that yet. They name a source’s document by the Brain’s own id for it — a source-document:… string — which GET /v1/brains/{handle}/documents/{documentId} accepts, and which the document listing uses too.

Sources and `POST /documents`

POST /documents is unchanged, and it is not a source. A document written there is served at once, is never compared with anything, and is never retired because a later write left it out. Documents you send through a source and documents you send through POST /documents are separate: sending the same id both ways makes two documents.

A document written with POST /documents therefore cannot be withdrawn: there is no delete for it. If a data room will have drafts that are later superseded or withdrawn, send it through a source, so that a complete snapshot that leaves the draft out retires it through review.

Moving documents between sources

Nothing records that a document “moved”: a document one source stops sending is withdrawn by that source’s next complete snapshot, and a record only that document supported is proposed for deletion, even when another source now sends the same document. Push the new source’s snapshot first, and let the old source’s complete refresh run after it: the record then keeps the new source’s support and the old source’s withdrawal only removes its own. Run in the other order, the record is deleted by the old source’s refresh and created again by the new source’s snapshot, and anything linked to it is left holding a link to a deleted record in the window between.

Snapshots — sending a source its documents.
Receipts — what a read was served, and the text it pinned.