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

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.

A question is one of two kinds:

  • A query. { "kind": "query", "query": … }, where query is the body you would send to POST /query, unchanged. The watch follows the whole answer, so limit, cursor and consumerId are accepted and dropped. branch is a 400: 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.

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_KEY is your management key (nsk_), the key from the quickstart. Only step 1 uses it, to create the Brain and mint the Brain key.
  • $NICIA_KEY is a Brain key (nbk_) for that Brain with read and write, minted at the end of step 1. Every later step uses it: the record write needs write, and the watch, the events and the watch read need read. 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.

Terminal window
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.

Terminal window
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.

Terminal window
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"
}
}
}
  • fingerprint is an opaque digest of the answer. It is what you compare.
  • position is the journal position the fingerprint was taken at, and evaluatedThrough is how far the watch has been checked. They are decimal strings.
  • cursor is an events cursor just past position. Start reading /events from 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. The answer.changed event that tells a change is journaled just after that change’s position, so reading from the watch’s cursor again re-delivers the watch’s events. Keep the cursor each /events page returns and resume from that, not from the watch’s.
  • A watch created while its question could not be resolved is unknown, and its cursor sits 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.

Terminal window
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:

Terminal window
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:

Terminal window
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.

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:

Terminal window
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.

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.

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.

  • 500 active watches per Brain. The 501st is 409 with error.details.reason watch_limit_reached (and limit). Cancel one with DELETE /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=true evaluates 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 notifyBefore is 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 with refresh=true.
  • Main only. answer.changed is 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.

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