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

Releases

A release is a frozen copy. You name part of a Brain’s records, the Brain copies the values those records hold right now, numbers the copy 1, 2, 3, and keeps it. Nothing about the copy changes afterwards, whatever happens to the records.

It is not sync. Cutting a release applies nothing to any Brain, no Brain reads through it, and no link crosses from one Brain to another. A release reaches another Brain only when someone applies it: a copy, staged under that Brain’s own admission, after which nothing is inherited.

$API is as in the quickstart. Cutting needs admin, and read as well, because a release holds content: a key granted admin alone is refused. For a management key or a session, the person’s role decides: owners, admins and editors may cut, viewers may not.

Terminal window
curl -X POST "$API/v1/brains/tenant:acme/releases" \
-H "authorization: Bearer $NICIA_KEY" \
-H "idempotency-key: method-v1" \
-H "content-type: application/json" \
-d '{ "name": "Method v1", "scope": { "kinds": ["playbook"], "where": { "stage": "live" } } }'
{
"name": "Method v1",
"scope": { "kinds": ["playbook"], "where": { "stage": "live" } }
}

The answer is 201 with the release’s summary:

{
"data": {
"release": {
"number": 1,
"name": "Method v1",
"scope": { "kinds": ["playbook"], "where": { "stage": "live" } },
"position": "57",
"itemCount": 12,
"manifestHash": "4c1a9e72f0b83d65a1c7e0f2b9d4836a5e1f70c2b8a3d9e6f4017a5c2b8d3e91",
"createdByKeyId": "key_7f3a1c",
"createdAt": "2026-11-19T09:00:00.000Z"
}
}
}
  • number counts up per Brain from 1, in the order cuts commit, with no gaps.
  • position is the journal position the records were read at: the items are the records as of it. Events that change no record (another cut, an answer.changed) may sit between it and this release’s release.cut event.
  • manifestHash is a digest of the ordered items. It never changes for a release, so equal digests mean equal copies. To verify it, take the items as GET /releases/{number}?items=true serves them (kind, then id, order), build the array ["release-manifest-v1", [kind, id, fields, recordedAt], ...], serialize it as JSON with object keys sorted and no whitespace, and take the SHA-256 hex of its UTF-8 bytes.
  • name is optional and is only a label.

scope.kinds names one to twenty kinds. The release holds every current, accepted record of each, narrowed by scope.where, which is the same predicate object POST /query takes and applies to each named kind: every kind must declare the fields it names.

  • A record that is retired or deleted is not in it, and neither is one still staged for review: a release holds what the Brain accepts.
  • Each item carries the record’s declared values, including its prose body, and the instant its accepted version was recorded.
  • Edges between records are not carried: a declared relationship is not an item.
  • Documents are not carried. A release is of records.

A scope that resolves to nothing is refused, so a release never has zero items. One that resolves to more than 20,000 records, or more bytes of values than a table snapshot holds, is refused too: narrow it.

Refusal Status error.details
release_empty 400 reason
release_too_large 409 reason, limit (records), limitBytes
release_scope_moving 409 reason: the Brain kept changing; retry the cut
idempotency_key_reused 409 reason: that key cut a different release
Terminal window
curl "$API/v1/brains/tenant:acme/releases" -H "authorization: Bearer $NICIA_KEY"
curl "$API/v1/brains/tenant:acme/releases/1?items=true&limit=100" \
-H "authorization: Bearer $NICIA_KEY"

GET /releases lists summaries, newest first, with a nextCursor. GET /releases/{number} answers the summary, and with items=true the frozen items in a fixed order (kind, then id), a page at a time:

{
"data": {
"release": {
"number": 1,
"name": "Method v1",
"scope": { "kinds": ["playbook"], "where": { "stage": "live" } },
"position": "57",
"itemCount": 12,
"manifestHash": "4c1a9e72f0b83d65a1c7e0f2b9d4836a5e1f70c2b8a3d9e6f4017a5c2b8d3e91",
"createdByKeyId": "key_7f3a1c",
"createdAt": "2026-11-19T09:00:00.000Z"
},
"items": [
{
"kind": "playbook",
"id": "first-call",
"fields": { "name": "First call", "stage": "live", "owner": "ops" },
"recordedAt": "2026-11-18T16:20:00.000Z"
}
],
"nextCursor": "0"
}
}

Reading needs read. Edit a record, retire it, or add another afterwards and the release’s items and manifestHash stay exactly as they were; cut again to freeze the new state as the next number. There is no operation to roll a release back or delete one.

Send an Idempotency-Key. A retry of a cut that already committed answers 200 with that release instead of cutting a second; the same key for a different name or scope is a 409. Without a key, two cuts are two releases.

POST /v1/brains/{handle}/releases/apply is called on the receiving Brain and names the publisher and a release number. Both Brains must be in the same organization.

Terminal window
curl -X POST "$API/v1/brains/client-a/releases/apply" \
-H "x-api-key: $NICIA_MANAGEMENT_KEY" \
-H "content-type: application/json" \
-d '{ "from": "tenant:acme", "release": 2 }'
{ "from": "tenant:acme", "release": 2 }

There is no separate write path. The whole release is one snapshot: one complete snapshot of a source in the receiving Brain, with one table per kind, stating the release number as its revision. The source is named for the publisher (a digest of its Brain id; no kind is in the name), so release 1, 2 and 3 of one publisher are three snapshots of one source. A snapshot is complete for the source, not per kind: that is why a release withdraws a kind it no longer holds, and why nothing else should be written to a release-… source. It is sealed and applies in the background, exactly as a CSV import does, so the receiving Brain’s own admission decides what lands. One snapshot is one plan, one set of decisions and one apply, so a release is never half-applied and the revision advances once, only when everything applied.

  • A record it does not hold is created, and one it holds is updated when that source alone supports the value. A list that shrank between releases loses the element the release dropped.
  • A value a person set in the receiving Brain is not overwritten. Where the field declares multiplicity: "single" (and for a record’s prose body, which is always single-valued) the release’s value is contested and the record waits in Review as one Proposal, and the person’s value is still what is served. Where the field declares no multiplicity (every field of the built-in rule, decision, bet and belief kinds), the person’s value is kept and the release’s value is an advisory disagrees in the plan, with nothing staged.
  • A record the new release no longer holds is a withdrawal, and so is every record of a kind the new release no longer holds: the source’s support goes, and the record is deleted when nothing else supports it.
  • Who needs to say yes depends on the receiving Brain’s mode. On an open Brain a management credential’s apply lands its updates and withdrawals without a review. On a reviewed Brain nothing lands: the snapshot stops at planned with processing.heldBecause set, the receiving Brain’s records read exactly as before (a release serves nothing ahead of its apply, so the new records are not yet visible), and ?plan=true shows what the release would do. A person decides, and their apply lands every entry. On an unrestricted Brain there is no contest: the release’s values overwrite what is there, a hand edit included.
  • Applying a release counts as confirming the rules it writes. The person who applied it meant to ship the whole thing, so every decision, rule or belief the apply created or updated, and that actually landed, is recorded as affirmed (“Still holds”) by that person, with the note Applied release N.: the same statement POST /records/{id}/affirm writes, one per record, in one batched write right after the apply. Nothing is affirmed that did not land: a contested change waiting in Review is not (approving it is what confirms it, by the approver), a record the release did not touch is not, and a withdrawal is not. So a release that rewrites rules does not leave each one on every client’s list of unconfirmed records. This governs release apply only: a CSV import or a document sync, whose owner did not choose each row, still leaves a rewritten rule unconfirmed.
  • Release 1 then release 3 is fine. An older release than one already applied is refused with source_revision_stale, before anything is staged, and the refusal is kept as the source’s last refusal.

The answer is 202 once every kind is staged and sealed. It names the one source and the one snapshot, and that snapshot’s status endpoint is the outcome of the whole release: GET /v1/brains/{handle}/sources/{source}/snapshots/{snapshot.id}.

{
"data": {
"from": "tenant:acme",
"release": 2,
"source": "release-2281193b167a",
"kinds": ["decision", "rule"],
"snapshot": {
"id": "01a1f294-5ea7-749b-a762-e95c2fb64aec",
"source": "release-2281193b167a",
"status": "sealed",
"completeness": "complete",
"documents": 5,
"bytes": 537,
"revision": 2,
"openedAt": "2026-11-19T09:10:00.000Z",
"sealedAt": "2026-11-19T09:10:00.200Z",
"expiresAt": "2026-11-19T09:40:00.000Z",
"processing": { "state": "queued", "step": "seal" }
}
}
}

Poll the status endpoint. status: "applied" means everything landed; awaiting_review means something waits for a person (the rest has landed); processing.state: "failed", with its error, means a background step stopped and none of it landed: the source’s applied revision has not moved, and repeating the seal retries it. ?plan=true lists every entry and its class.

A management credential only: a session or an organization key whose person, by their role now, administers the receiving Brain and can read the publisher. A Brain key is refused with 401, whatever it is granted, so a client Brain’s key can never be used to read the upstream Brain. A publisher in another organization is a 404.

Overlays: local knowledge on top of a release

Section titled “Overlays: local knowledge on top of a release”

What a receiving Brain adds is its own and stays its own. A person’s hand edit of a released value is protected as above. A local record that rests on a released rule (a rule with exception_to pointing at it) is grounded on it, so when a later release changes what it rests on, the exception reopens and is served as needing review. Nothing local is visible to the publisher or to any other receiving Brain.

A release is applied whole or not at all. A value that would not read back as itself through the table pipeline refuses the whole apply with 409 and reason release_values_not_carried, whose error.details.problems names each kind and field, why, how many items, and examples. Nothing is staged.

  • Carried exactly: strings, numbers, booleans, enum members, dates and datetimes, a list of strings (one column per element), and a record’s prose body. The body is read as one single-valued field named body on every kind (unless the kind declares a field of that name), written as the record’s body, and protected like a field. Prose is markdown, so it is compared as written, not like a short field: only leading and trailing whitespace and the difference between CRLF and LF line endings are ignored. A body that differs in case, line breaks, paragraph breaks or indentation is an update; a byte-identical one is a no-op; and a body a person edited in the receiving Brain is contested, not overwritten.
  • Refused, naming it: a field the receiving kind does not declare, or a value its field’s type cannot hold (field_not_declared, value_not_readable_as_field_type).
  • Not values: a string’s surrounding whitespace is trimmed, and an empty string or a null is no value.
  • Never in a release, so never applied: links (edges between records) and documents. A local record that should rest on a released one is written in the receiving Brain.
  • No grounds: a rule, decision, bet or belief created this way states no grounds, so it has nothing to reopen. The Brain serves it as it serves any such record that rests on nothing: current, with an empty closure.
  • A kind the receiving Brain does not declare is 409 release_kind_not_declared (details.kinds); roll the schema out first. A kind table rows cannot be read into (a platform kind, a page, a quote-bodied kind) is release_kind_not_appliable.

GET /v1/brains/{handle}/releases/applied lists the sources a release apply created in this Brain, one per publisher, with the publisher’s handle (as it was when the latest release was applied), the highest release number applied (source.revision.applied) and the last refusal. It reads nothing from the publisher, and it is for a management credential only, because it names the upstream Brain: a Brain key is refused with 401. A receiving Brain’s own keys can still see in GET /sources that a source named release-<hash> exists and the revision it has applied (the release number), but never the publisher’s handle or id.

Applying the same release again is a refresh: it stages the same values, which change nothing, and affirms nothing new.

A plan a person has to apply (a reviewed Brain, an apply that asked for a person) is listed by GET /attention as an import_exception item with heldBecause and no staged change, until it is applied. Rejecting the change a contested record staged settles the snapshot’s Proposal, as publishing it does; the rejected value is remembered, so a later release that restates it raises nothing again.

A record a release stated carries release: { number, from? } wherever the Brain serves it: GET /records/{id}, each record of POST /query, a record item of POST /context with format: "items", and each native item of a receipt. number is the highest release applied to this Brain whose snapshot held the record. A record written here has no release.

  • A management credential also sees from, the publisher’s handle as it was when that release was applied.
  • A Brain key never sees from. A client Brain’s agent is told that a rule came from a release, and which one, never whose. The release source’s own name (release- and a digest) is visible to a Brain key, and does not name the publisher. A released rule is served once, as its record: the release’s row document is kept as evidence but is not served beside the record when the record says everything the row does.
  • On a receipt, it is the release the Brain held when the receipt committed, so a later release never rewrites what an earlier read was shown.
  • release says where the record came from, not that every value is unchanged: a body a person edited here is still served under the release that stated the record.

Nothing is stored for it: it is derived from the snapshots a release apply already keeps, in one batched lookup per served page.

GET /v1/brains/{handle}/releases/subscribers is the publisher’s fleet view: the Brains of the organization that have applied any release of this Brain, a page at a time (limit, up to 100, and nextCursor). Each carries:

  • handle, the receiving Brain’s handle now;
  • applied, the highest release it has applied, and behind, how many releases were cut after it (latestRelease minus applied; 0 is current);
  • latestApply, its newest apply whatever became of it, with processing: failed (with error), needs_review (contested values in Review, or a plan a reviewed Brain holds for a person, with heldBecause), or applied;
  • lastRefusal, the last release it refused as stale.

Read latestApply.processing.state beside applied: the applied release advances when the plan applies, before a contested value is decided, so a Brain can read applied: 3 while its release 3 still waits in Review.

It is a management credential’s read, because it names other Brains: a Brain key, the publisher’s own included, is refused with 401. The person’s role now must be able to read this Brain, and a role reads every Brain of the organization. It never opens another Brain’s records: one bounded query over what each apply recorded.

{
"data": {
"latestRelease": 4,
"subscribers": [
{
"handle": "client-a",
"applied": 3,
"behind": 1,
"latestApply": {
"snapshot": "01a1f294-5ea7-749b-a762-e95c2fb64aec",
"release": 3,
"status": "awaiting_review",
"processing": { "state": "needs_review" },
"startedAt": "2026-11-19T09:10:00.000Z"
}
},
{
"handle": "client-c",
"applied": 4,
"behind": 0,
"latestApply": {
"snapshot": "01a1f294-6bb1-7c10-9a58-0e3a1f5d7c21",
"release": 4,
"status": "applied",
"processing": { "state": "applied" },
"startedAt": "2026-11-19T09:12:00.000Z"
},
"lastRefusal": {
"reason": "source_revision_stale",
"statedRevision": 1,
"appliedRevision": 2,
"refusedAt": "2026-11-19T09:11:00.000Z",
"keyId": "key_7f3a1c"
}
}
]
}
}

Every cut journals one release.cut event carrying the number, name, item count and manifest hash, never a value, so a runner following the event stream learns that a new release exists.