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

Observed outputs

An observed output is text an agent or a person produced: a drafted reply, a report, a summary. You submit it so it can be checked against what the Brain holds. The check this page describes is deterministic and needs no model: if you say which read the output was produced under, the Brain tells you, when you read the output back, which of the records that read served have since changed, been retired, replaced or reopened. That is the finding “this output predates current knowledge”. It does not say the output was wrong.

$API is as in the quickstart. Submitting needs write.

Terminal window
curl -X POST "$API/v1/brains/tenant:acme/observed-outputs" \
-H "authorization: Bearer $NICIA_KEY" \
-H "idempotency-key: reply-4417" \
-H "content-type: application/json" \
-d '{
"text": "Hi Dana, annual billing is our default. Monthly is available on request.",
"receiptId": "01JD4Z8K2M7QX3P9V6T1R0WNHB",
"task": "answer the billing question in ticket 4417",
"producer": "support-agent@3"
}'
{
"text": "Hi Dana, annual billing is our default. Monthly is available on request.",
"receiptId": "01JD4Z8K2M7QX3P9V6T1R0WNHB",
"task": "answer the billing question in ticket 4417",
"producer": "support-agent@3"
}

The answer is 201 with the output’s summary, and never its text:

{
"data": {
"output": {
"id": "0192a3b4-c5d6-7e8f-9012-3456789abcde",
"receiptId": "01JD4Z8K2M7QX3P9V6T1R0WNHB",
"task": "answer the billing question in ticket 4417",
"producer": "support-agent@3",
"contentHash": "sha256:6d1f0c52b8a74e39c1d5f2a9b3e70486c5d2a1f90b7e3c48d6a5f1e2c9b04a73",
"sizeBytes": 72,
"retainUntil": "2026-12-19T09:00:00.000Z",
"createdByKeyId": "key_7f3a1c",
"createdAt": "2026-11-19T09:00:00.000Z"
}
}
}
  • text is required, at most 262,144 characters (at most 1 MiB), held in the output’s own record.
  • receiptId is the receipt of the read the output was produced under, for example the receipt a POST /context answer carried. It must exist in this Brain and be readable by the key submitting, or the submission is a 404: a receipt from another Brain, or one another key committed (readable only by a key with review), is refused.
  • task (at most 500 characters) and producer (at most 200) are free labels.
  • retainDays is how long to keep the output: 30 when omitted, at most 365. When it ends the output reads as 404 and its text is removed.

Send an Idempotency-Key. A retry of a submission that already stored answers 200 with the same output; the same key for a different request is a 409 (error.details.reason idempotency_key_reused). Without a key, two submissions are two outputs.

Terminal window
curl "$API/v1/brains/tenant:acme/observed-outputs/0192a3b4-c5d6-7e8f-9012-3456789abcde?text=true" \
-H "authorization: Bearer $NICIA_KEY"

GET /observed-outputs/{id} answers the summary, the text with ?text=true, and, when the output names a receipt, its standing:

{
"data": {
"output": {
"id": "0192a3b4-c5d6-7e8f-9012-3456789abcde",
"receiptId": "01JD4Z8K2M7QX3P9V6T1R0WNHB",
"task": "answer the billing question in ticket 4417",
"producer": "support-agent@3",
"contentHash": "sha256:6d1f0c52b8a74e39c1d5f2a9b3e70486c5d2a1f90b7e3c48d6a5f1e2c9b04a73",
"sizeBytes": 72,
"retainUntil": "2026-12-19T09:00:00.000Z",
"createdByKeyId": "key_7f3a1c",
"createdAt": "2026-11-19T09:00:00.000Z"
},
"text": "Hi Dana, annual billing is our default. Monthly is available on request.",
"standing": {
"receipt": "01JD4Z8K2M7QX3P9V6T1R0WNHB",
"checkedAt": "2026-11-26T09:00:00.000Z",
"state": "moved",
"now": {
"changed": [
{
"source": "quote-annual-first",
"shownVersion": 1,
"currentVersion": 2,
"status": "active"
}
],
"unchanged": 0,
"deleted": 0,
"imported": [],
"answers": [],
"evidence": []
}
}
}
}

standing is the receipt’s comparison with the Brain now (GET /receipts/{id}/now), computed when you read the output, so it reflects the Brain as it is at that moment:

standing.state Meaning
quiet Nothing the receipt served has changed, been retired, replaced or reopened.
moved Something has. now says what: edited or retired records in changed, and rules and decisions reopened because what they rest on changed in answers (grounds_moved).
unavailable The comparison could not be made for this reader (the receipt is no longer readable by this key). now is absent.

It says that the world moved after the output was produced. It does not say the output contradicts anything. Comparing the text itself with your rules is a separate step that you run with Compare documents.

Compare an output with your rules, and keep a failure

Section titled “Compare an output with your rules, and keep a failure”

An output is a Compare target: { "source": "@observed", "id": "<output id>", "role": "target" } beside a @record reference. A reviewer who confirms a finding turns it into a regression case: the case keeps the output past its retention, and it cannot be deleted while the case stands (409, reason observed_output_kept_by_case; a reviewer withdraws the case first, with POST /corpus-analyses/{id}/withdrawn, and then the output can be deleted) and marks a later output that fails the same rule. It opens no Review item. To be told, with no model, when what the output was produced under moves again, enroll a watch on the receipt the output names: read output.receiptId, then POST /watches with { "question": { "kind": "receipt", "receiptId": "…" } }. See Compare documents and how to withdraw a case.

  • The key that submitted it, even a key that holds only write.
  • A key holding review reads every output in the Brain, and lists them all. For a person’s session or organization key, their current role decides: owners, admins and editors may; viewers hold neither write nor review, so may do nothing here.
  • admin conveys no read of content: an admin-only key can neither read nor list another key’s output (403; a caller whose capabilities reach the operation but not that output gets 404). It may only delete.
  • Anyone else gets 404, the same as for an id that does not exist.
  • A key holding only read neither submits nor reads an output.

GET /observed-outputs lists the outputs the caller may read, newest first, a page at a time with nextCursor. It lists summaries, never text, and leaves out deleted and expired outputs.

DELETE /observed-outputs/{id} deletes an output you submitted (or any, with admin, which administers without reading it). Its text is removed in the same step. A tombstone remains: the id and the time it was deleted, with the task, producer and receipt cleared. It is idempotent: deleting again answers 200 and changes nothing.

  • Never served. No /context, /search, /query, document listing, export, MCP read, Compare documents’ corpus or reference, source snapshot or watch returns it, even when its text matches a query exactly. Nothing is chunked, extracted or indexed from it.
  • Never a citation. A record or statement that cites it cannot: the Brain does not serve it, so a record write drops the citation with a notice and a statement is refused.
  • No Review item by itself. Submitting an output opens nothing for a person.
  • No MCP tool. It is the HTTP API and the client only: submitObservedOutput, listObservedOutputs, getObservedOutput and deleteObservedOutput in @nicia/brain-client.

Submitting journals one output.observed event and deleting one output.deleted, each carrying the output’s id and nothing else, so any key that can read the event stream sees that an output exists but never its text, task, producer or receipt.