Watches
A watch is a standing question. You hand the Brain a question you have already
asked, and when a later evaluation of that question gives a different answer,
the Brain writes one answer.changed event to the
event stream. The event names the watch and a journal
position. It carries no content: you read the answer the way you always do, and
you decide what to do about it.
Nicia reports the change. Your own runner, scheduler or agent harness acts on it: nothing here starts an agent or runs anything on your behalf.
What you can watch
Section titled “What you can watch”A question is one of two kinds:
- A query.
{ "kind": "query", "query": … }, wherequeryis the body you would send toPOST /query, unchanged. The watch follows the whole answer, solimit,cursorandconsumerIdare accepted and dropped.branchis a400: a watch follows the accepted main state. - A receipt.
{ "kind": "receipt", "receiptId": … }: the records that read was served, at the versions and standings it was served. Use it when you want to know whether what one particular answer rested on has moved.
A question is judged by what it is materially: each matching record’s id, kind, field values, validity and support. A label edit or a re-cite of the same words is not a change. A rule that is withdrawn or reopened is, even when no field value moved. A new record the old answer never held is too, because the question is run again, not its citations walked.
Watch an answer and be told when it moves
Section titled “Watch an answer and be told when it moves”The sequence below uses only what an earlier step made. $API is as in the
quickstart. It uses two credentials, and each step
says which:
$NICIA_MANAGEMENT_KEYis your management key (nsk_), the key from the quickstart. Only step 1 uses it, to create the Brain and mint the Brain key.$NICIA_KEYis a Brain key (nbk_) for that Brain withreadandwrite, minted at the end of step 1. Every later step uses it: the record write needswrite, and the watch, the events and the watch read needread. See Authentication.
The watch belongs to that Brain key. Created with your management credential instead, it would belong to you as a person, and a person who administers the Brain is also told of every other principal’s watches (see What the event shows, and to whom).
1. A Brain with a site kind, a Brain key, and a gold site. The management
key creates the Brain and mints the Brain key; the Brain key writes the record.
curl -X PUT "$API/v1/brains/tenant:acme" \ -H "authorization: Bearer $NICIA_MANAGEMENT_KEY" \ -H "content-type: application/json" \ -d '{ "name": "Acme", "schema": { "kinds": [ { "name": "site", "fields": [ { "name": "name", "type": "string" }, { "name": "tier", "type": "enum", "values": ["gold", "silver", "bronze"] } ] } ], "links": [] } }'
curl -X POST "$API/v1/brains/tenant:acme/keys" \ -H "authorization: Bearer $NICIA_MANAGEMENT_KEY" \ -H "content-type: application/json" \ -d '{ "name": "watcher", "capabilities": ["read", "write"] }'The mint response carries the key’s secret once; export it as $NICIA_KEY.
curl -X PUT "$API/v1/brains/tenant:acme/records/site-042" \ -H "authorization: Bearer $NICIA_KEY" \ -H "content-type: application/json" \ -d '{ "kind": "site", "fields": { "name": "Harbour Street", "tier": "gold" } }'2. Watch “which sites are gold”, with the Brain key.
curl -X POST "$API/v1/brains/tenant:acme/watches" \ -H "authorization: Bearer $NICIA_KEY" \ -H "content-type: application/json" \ -d '{ "question": { "kind": "query", "query": { "kind": "site", "where": { "tier": "gold" } } } }'{ "question": { "kind": "query", "query": { "kind": "site", "where": { "tier": "gold" } } }}The Brain evaluates the question once, now, and answers 201:
{ "data": { "watch": { "id": "019b0f4e-2c61-7a3d-8e10-4b7c9a1d5f02", "question": { "kind": "query", "query": { "kind": "site", "where": { "tier": "gold" } } }, "status": "active", "resultState": "current", "fingerprint": "8d1c5f0a3b7e49c2a6f1d8e0b4c37a95e2f6d1a8c0b3e7f4a9d2c5b8e1f06a3d", "position": "57", "evaluatedThrough": "57", "cursor": "e1.58.0.gen_7Hq2", "createdByKeyId": "key_7f3a1c", "createdAt": "2026-11-19T09:00:00.000Z", "updatedAt": "2026-11-19T09:00:00.000Z" } }}fingerprintis an opaque digest of the answer. It is what you compare.positionis the journal position the fingerprint was taken at, andevaluatedThroughis how far the watch has been checked. They are decimal strings.cursoris an events cursor just pastposition. Start reading/eventsfrom it and you never read the Brain’s history from the beginning. It is fixed at the watch’s baseline: it moves only when the watch’s fingerprint does, never as the feed advances. Theanswer.changedevent that tells a change is journaled just after that change’sposition, so reading from the watch’scursoragain re-delivers the watch’s events. Keep thecursoreach/eventspage returns and resume from that, not from the watch’s.- A watch created while its question could not be resolved is
unknown, and itscursorsits at the creation position. The first evaluation that resolves sets the baseline, and no event is journaled for it: the first answer a watch resolves is never a change.
Posting the same question again from the same key returns the existing watch
with 200, not a second one. Idempotency-Key is accepted, and not needed: a
watch’s identity is its question.
3. Change what the answer rests on.
curl -X PATCH "$API/v1/brains/tenant:acme/records/site-042" \ -H "authorization: Bearer $NICIA_KEY" \ -H "content-type: application/json" \ -d '{ "fields": { "tier": "silver" } }'4. Read the event. Pass the watch’s cursor as after, and narrow the
stream to this watch’s changes:
curl "$API/v1/brains/tenant:acme/events?after=e1.58.0.gen_7Hq2&types=answer.changed&watch=019b0f4e-2c61-7a3d-8e10-4b7c9a1d5f02" \ -H "authorization: Bearer $NICIA_KEY"{ "data": { "events": [ { "cursor": "e1.60.1.gen_7Hq2", "type": "answer.changed", "branchId": "default", "occurredAt": "2026-11-19T09:00:41.207Z", "data": { "watch": "019b0f4e-2c61-7a3d-8e10-4b7c9a1d5f02", "position": "59" } } ], "cursor": "e1.61.0.gen_7Hq2", "hasMore": false }}The event arrives within about a minute of the write: the Brain checks once a
minute, and no faster than that is promised. That holds for a quiet Brain. On a
Brain that uses the built-in kinds every watch is re-evaluated on every change, at
up to 50 evaluations per Brain per minute, so 500 watches take about ten minutes
to catch up after one write, and a write rate that stays above that leaves the
last watches behind (see Limits). Keep the page’s cursor and pass
it back as after, also when events is empty.
5. Read the watch and compare fingerprints. The event says that the answer
moved, not to what. GET /watches/{id} returns the watch as it stands now:
curl "$API/v1/brains/tenant:acme/watches/019b0f4e-2c61-7a3d-8e10-4b7c9a1d5f02" \ -H "authorization: Bearer $NICIA_KEY"{ "data": { "watch": { "id": "019b0f4e-2c61-7a3d-8e10-4b7c9a1d5f02", "question": { "kind": "query", "query": { "kind": "site", "where": { "tier": "gold" } } }, "status": "active", "resultState": "current", "fingerprint": "3a9e7c14d02b58f6a1c4e9d7b03f82a6c5d1e8b4097f3a2c6e0d5b8a1f47c92e", "position": "59", "evaluatedThrough": "59", "cursor": "e1.60.0.gen_7Hq2", "createdByKeyId": "key_7f3a1c", "createdAt": "2026-11-19T09:00:00.000Z", "updatedAt": "2026-11-19T09:00:41.207Z" }, "head": "59" }}The fingerprint differs from the one step 2 returned, so the answer changed.
Ask the question again, with POST /query, to see what it is now; that read has
a receipt like any other.
The completion check
Section titled “The completion check”An agent that read an answer, did some work, and wants to know whether the
answer is still the one it read at, holds the fingerprint it read at and asks
the Brain now:
curl "$API/v1/brains/tenant:acme/watches/$WATCH_ID?refresh=true" \ -H "authorization: Bearer $NICIA_KEY"With refresh=true the Brain evaluates the question before it answers, so a
change the minute sweep has not reached cannot be missed. A watch that was
resolved within the last 10 seconds, with nothing journaled since, is answered as
stored instead of being read again: you see it as evaluatedThrough equal to
head, and a poll costs one evaluation per window rather than one per call.
Without refresh the watch is as of the last sweep: compare evaluatedThrough
with head, the Brain’s journal position now. When they are equal the watch is
caught up.
If the fingerprint you get back is the one you read at, nothing material moved. If it differs, read the question again. The TypeScript client has the loop as one call:
const { changed, watch } = await brain.watchChangedSince(watchId, readAtFingerprint);createWatch returns { created, watch }: created is true for a new watch
(201) and false for the one you already held (200).
It calls GET /watches/{id}?refresh=true and compares. It adds no protocol of
its own.
What current, incomplete and unknown mean
Section titled “What current, incomplete and unknown mean”resultState says how far to trust the fingerprint:
| State | Meaning |
|---|---|
current |
The fingerprint is the answer as of evaluatedThrough. |
incomplete |
The answer holds more than 500 records, so no fingerprint of it can detect a change. The watch reports no change while it stays over that bound; entering or leaving the bound is one event. |
unknown |
The last evaluation could not be resolved (a failed read, an uncertain one). failure says why and nextAttemptAt says when it is tried again. It is never reported as unchanged. |
An unknown watch keeps the last fingerprint it resolved. When a later
evaluation resolves, it is compared against that one, so a change made while the
watch could not be evaluated is still told.
What the event shows, and to whom
Section titled “What the event shows, and to whom”The event carries the watch id and a position, nothing else: no values, no text,
not even which record moved. Any key with read on the Brain can read the
stream, so any such key can see that a watch’s answer changed. It cannot see
the question, which belongs to the principal that created the watch: another gets
404 for it. Read access to the answer itself is whatever /query and
/context already give that key.
A watch belongs to the principal that created it: one Brain key, one OAuth
agent’s access, or, for a person using a management credential, that person’s
own access to the Brain (a session and each of that person’s nsk_ keys count as
separate principals). Whoever may read a Brain may create watches and
cancel their own, including a viewer; what a viewer cannot do is touch anyone
else’s. A viewer also cannot watch a receipt another key committed, as they
cannot open it.
An administrator of the Brain may pass all=true to GET /watches to list
every principal’s watches, and may read or cancel any of them. Who that is
depends on the credential:
- a person using a management credential, when their organization role may administer Brains: an owner, an admin or an editor. It is their role now, read on every call, so lowering it takes effect at once. Their credential’s own capabilities do not matter; a viewer’s key carries the viewer’s role;
- a Brain key that was granted
admin; - never an OAuth agent’s connection, whatever it was granted.
A watch is revoked when the key that created it is revoked, and a revoked
watch emits nothing. Only an administrator ever sees a createdByKeyId that is
not their own.
Limits
Section titled “Limits”- 500 active watches per Brain. The 501st is
409witherror.details.reasonwatch_limit_reached(andlimit). Cancel one withDELETE /watches/{id}; cancelling again returns it as it stands. Creating and cancelling in a loop is bounded by the ordinary request rate limit, not by a limit of its own, and each create evaluates the question once. - How fast a change is told. Within about a minute of the write, and no
faster. On a Brain that uses the built-in kinds every watch is re-evaluated on
every change, at up to 50 evaluations per Brain per minute, so 500 watches take
ten minutes to catch up after one write (measured on a development database:
ten consecutive ticks, two to five seconds each before the sweep shared reads
within a tick and about a third less after), and a write rate that stays above
that leaves the last watches behind. Each evaluation is a fixed cost of about
30 database statements however large the Brain is (about 45 before that
sharing, a third fewer now), so the rate is set by the budget, not by the data. A Brain with nothing due costs one cheap scan per
minute. This is a measurement of how the sweep behaves, not a promise.
refresh=trueevaluates one watch now, unless it was resolved within the last 10 seconds and the journal has not moved since. - Two changes a watch cannot see. A date passing on a custom kind’s date
field that declares no
notifyBeforeis not a journal event. And what an outside source now says about an external citation is an observation, not a journal event. A watch finds either only when something else touches its question, or when you read it withrefresh=true. - Main only.
answer.changedis written to the main stream. A branch-scoped key cannot hold a watch.
A webhook subscribed to answer.changed receives the event of every watch on
the Brain, whoever created it: it cannot yet be narrowed to one watch, and it is
an administrator’s operation to create (a webhook needs admin). Read
/events?watch= when you want one.
Operations
Section titled “Operations”| Operation | Needs | Does |
|---|---|---|
POST /v1/brains/{handle}/watches |
read |
Watch a question; 201, or 200 for one you already hold |
GET /v1/brains/{handle}/watches |
read |
Your active watches, newest first; status=, all=true (administrators), cursor, limit |
GET /v1/brains/{handle}/watches/{id} |
read |
The watch beside the Brain’s journal head; refresh=true |
DELETE /v1/brains/{handle}/watches/{id} |
read |
Cancel; idempotent |
- Events and webhooks — the stream a watch writes to.
- Receipts — what a read served, and what changed since.