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.
Submit an output
Section titled “Submit an output”$API is as in the quickstart. Submitting needs write.
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" } }}textis required, at most 262,144 characters (at most 1 MiB), held in the output’s own record.receiptIdis the receipt of the read the output was produced under, for example thereceiptaPOST /contextanswer carried. It must exist in this Brain and be readable by the key submitting, or the submission is a404: a receipt from another Brain, or one another key committed (readable only by a key withreview), is refused.task(at most 500 characters) andproducer(at most 200) are free labels.retainDaysis how long to keep the output: 30 when omitted, at most 365. When it ends the output reads as404and its text is removed.
Retry safely
Section titled “Retry safely”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.
Read an output, and its standing
Section titled “Read an output, and its standing”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.
Who can read an output
Section titled “Who can read an output”- The key that submitted it, even a key that holds only
write. - A key holding
reviewreads 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 neitherwritenorreview, so may do nothing here. adminconveys no read of content: anadmin-only key can neither read nor list another key’s output (403; a caller whose capabilities reach the operation but not that output gets404). It may only delete.- Anyone else gets
404, the same as for an id that does not exist. - A key holding only
readneither 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 an output
Section titled “Delete an output”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.
What it is not
Section titled “What it is not”- 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,getObservedOutputanddeleteObservedOutputin@nicia/brain-client.
Events
Section titled “Events”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.