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

Compare documents

POST /v1/brains/{handle}/corpus-analyses reads documents you select, discovers the propositions they share, or compares a target with selected references. Creating one answers 202 and runs in the background; poll GET /corpus-analyses/{id} until status is complete or incomplete.

Terminal window
curl -X POST "$API/v1/brains/tenant:acme/corpus-analyses" \
-H "authorization: Bearer $NICIA_KEY" \
-H "idempotency-key: compare-1" \
-H "content-type: application/json" \
-d '{
"documents": [
{ "source": "@record", "id": "rule-discount-cap", "role": "reference" },
{ "source": "@observed", "id": "0192a3b4-c5d6-7e8f-9012-3456789abcde", "role": "target" }
],
"targetComplete": true
}'
source Names Roles
a source name a document the Brain serves, by id reference, target, corpus
@record a native record page (a rule, a decision), by its slug reference, target, corpus
@observed an observed output, by its id target only

@observed as a reference or a corpus is a 400 with error.details.reason observed_output_target_only: an output is evidence about behaviour, never a standard to hold others to. An analysis compares one output at a time (observed_output_single). You must be able to read the output, or the answer is the 404 a missing one gets. The run pins the output by its id and content hash and never copies its text into the analysis.

Adopting is refused. POST /corpus-analyses/{id}/adopt on an analysis whose target is an output is a 409 (observed_output_not_adoptable), and none of its statements is offered as adoptable. An output is never a source of knowledge.

When a reference is a @record, the rules that are an exception_to it are read beside it. Only a rule that is accepted and current counts (not one still waiting in Review, withdrawn or replaced). They appear in the analysis’s documents with exceptionTo naming the reference, and the reference’s own entry reports what was found:

{ "id": "rule-discount-cap", "role": "reference", "exceptions": { "included": 1, "truncated": false } }

A draft that follows an approved exception for the scope it states is not reported as changes. At most 10 exceptions are read per reference, and within the analysis’s 50-document and 500 KB bounds; when a bound cuts the list, truncated is true and the comparison says so rather than reading as complete. An exception added after the analysis ran does not make it stale: re-run it.

A Brain key sees the analyses that key created. An analysis over an observed output is also read by any key that holds review, and by a person whose role may review now, because reviewing is how a finding gets confirmed and the reviewer is rarely the one who ran the comparison. A key that holds only read or write still sees none of them, and an analysis that reads no output stays private to the key that created it.

A reviewer who agrees a finding is a real failure confirms it: POST /corpus-analyses/{id}/confirmed (needs review):

{
"fingerprint": "<the analysis result's fingerprint>",
"findingFingerprint": "<the finding's fingerprint>",
"correction": "Discounts above the cap need an approved exception on file.",
"expectedRecordIds": ["rule-discount-cap"],
"allowedExceptionRecordId": "rule-acme-exception"
}

The finding must be a supported changes or omits of an analysis whose target is an observed output. The records you name must be ones the analysis read: the expected references, and an exception read beside them. The answer is the analysis, with the case in cases. Retry with the same Idempotency-Key to get the same case; confirming the same finding again is a 409 (case_exists).

A confirmed case:

  • keeps the output past its retention, so the failure can be replayed. While the case stands the output cannot be deleted (409, reason observed_output_kept_by_case); withdraw the case first.
  • is listed with GET /corpus-analyses?confirmed=true.
  • opens no Review item and changes no knowledge.
  • marks a repeat: a finding in a later analysis, over a different observed output, that fails the same reference proposition carries recurrenceOf: <case id>.

A case that was wrong, or whose output holds customer data you now need to delete, is withdrawn by a reviewer: POST /corpus-analyses/{id}/withdrawn (needs review) with the finding’s fingerprint.

{ "findingFingerprint": "<the finding's fingerprint>" }

The answer is the analysis, with the case still listed in cases and marked withdrawnAt. Withdrawing does not delete anything. It stops the case keeping its output, which returns to its normal retention, so deleting it with DELETE /observed-outputs/{id} now works and clears its text; and it stops the case marking later findings with recurrenceOf, and removes it from GET /corpus-analyses?confirmed=true. If another standing case names the same output, that case keeps it instead. It is idempotent, and the finding may be confirmed again afterwards. A key without review is refused (403); a finding no case holds is a 404.

By a fingerprint of the reference side only: the normalized text, applicability, scope, conditions, value and terms of the proposition the output failed. It ignores the target’s text, and the record’s id, version and the quote offsets, so the same rule read from a newer version of its record still matches. It is exact: when the owner rewrites the rule it is a different proposition, and a case confirmed against the old wording does not mark a failure of the new one; a model that rewords the proposition between runs misses a repeat. It never marks a repeat that is not one. Only the newest 200 cases of a Brain are matched.

Confirming a case does not enroll anything. To be told when what the case rested on moves, enroll a watch on the receipt behind it: GET /observed-outputs/{id} names it as output.receiptId, and POST /watches with { "question": { "kind": "receipt", "receiptId": "…" } } delivers answer.changed when anything that read served changes. Re-running the agent and grading it stay yours.