Beacons

A beacon is a ranked collection of related signals, and it is the unit a decision is made on: promote it to a spec, hold it, or dismiss it. Its rankScore is one integer from 0 to 100, blended from severity (0.35), reach (0.30), producer weight (0.20) and recency (0.15). How nima decides has the full formula and the thresholds behind it.

Read beacons with an API key

Three beacon routes accept an API key: list, get one, and count facets.

Every other beacon route carries no scope. Send a key or an OAuth token to one of them and you get a 403 reading This endpoint does not accept OAuth access tokens, whatever scopes the key holds. There is no MCP tool that promotes, holds, dismisses, edits, creates or deletes a beacon, and none that removes member signals.

Every call takes your key as a bearer token and is scoped to the workspace that key belongs to:

curl https://api.getnima.io/v1/beacons \
  -H "Authorization: Bearer $NIMA_API_KEY"

See Authentication for how to create one.

List beacons

Get a beacon

Count the facets

Beacon object fields

rankBreakdown is stored, not recomputed on read, so it is what nima knew at computedAt:

Filter beacons with a JSON expression

filter is one JSON object, URL-encoded, containing a combinator (and or or) and a conditions array. A condition is { "field", "operator", "value" }; a nested group is another object of the same shape.

rankScore compares against the same integer 0 to 100 the object carries. Date values are ISO 8601 UTC strings, between takes a two-element array, and in_last takes { "amount": 14, "unit": "day" } with a unit of day, week or month. The four operators that ask about presence (is_set, is_not_set, exists, not_exists) take no value.

curl -G https://api.getnima.io/v1/beacons \
  -H "Authorization: Bearer $NIMA_API_KEY" \
  --data-urlencode 'filter={"combinator":"and","conditions":[{"field":"status","operator":"in","value":["ready"]},{"field":"rankScore","operator":"gte","value":70},{"field":"hasSpec","operator":"not_exists"}]}'

The limits are 3 levels of nesting, 32 conditions across the whole tree, 50 values in one in or not_in, and 200 characters in a text value. Breaking one is a 400 that says which. So is a filter that is not a single JSON string, is not valid JSON, or names a field or operator that is not in the table above.

Session-only beacon routes

Every route that changes a beacon needs a signed-in session token (the JWT the nima app sends), not an API key or OAuth token. The admin panel has no beacon page, so in practice these are called by the nima team or with a session token you hold. All of them are scoped to the caller's workspace, and a beacon in another workspace answers 404. MEMBER roles can call all of them except the permanent delete, which needs OWNER or ADMIN.

Member lists in a request take 1 to 100 signal ids, all UUIDs. Creating, merging, promoting and permanently deleting each have their own budget of 15 requests per 30 seconds, counted per client address.

Promote a beacon to a spec

POST /v1/beacons/{id}/promote starts spec generation from the beacon's signals and creates the spec document immediately. The body is optional: repositoryId (string, up to 64 characters) picks the repository the spec is grounded in. Without it nima uses the only indexed repository, or ranks your indexed repositories against the beacon's evidence and searches up to three of them.

The response is { beaconId, notification, specId, evidenceCount }. specId is the new spec document, which exists from the call even though its body fills in as research and writing finish; notification is the progress record for the run. Up to 20 member signals ride along, ranked. The beacon's pmNotes become the writer's brief. When generation finishes, the beacon moves to promoted and promotedSpecId is set. When it fails, the in-flight marker clears and you can promote again.

The route is declared under plan feature copilot_chat. A workspace whose plan lacks it can get 403 INSUFFICIENT_PERMISSIONS with details.feature set to copilot_chat, so handle it.

See Anatomy of a spec for what the run produces and the 24 hour decision pause.

Hold, un-hold and edit a beacon

PATCH /v1/beacons/{id} changes any of title (up to 300 characters, not blank), summary (up to 10000), status, heldReason (up to 1000) and pmNotes (up to 10000). Send only the fields you change.

• To hold a beacon, send status: "held" with a heldReason. Holding without a reason is a 400 reading heldReason is required to hold a beacon.
• To un-hold, send status: "ready" or "forming", with heldReason: null to clear the old reason.
• status: "promoted" is refused with 409: only the promote route sets it.
• A beacon promoted to a spec that still exists cannot change status (409, delete the spec to un-promote it).

Group, add, remove and merge beacon signals

POST /v1/beacons takes { "title": "...", "signalIds": [ ... ] } with title optional and 1 to 100 ids. A signal belongs to at most one beacon, so grouping moves each signal out of any other open beacon it was in. If a signal's current beacon is promoted the call is a 409 (Signal is already evidence behind a promoted beacon), and if none of the ids are in your workspace it is a 404. Ids must be version-4 UUIDs. Both this route and the add route below return the beacon with skippedSignalIds: ids not found in your workspace are skipped, and the call fails with 404 only when none are found.

POST /v1/beacons/{id}/signals adds signals and DELETE /v1/beacons/{id}/signals removes them, both with { "signalIds": [ ... ] }. Adding to a dismissed or promoted beacon is a 409 (Beacon is no longer active). Removing every member leaves an empty beacon; it is not deleted. Both queue a fresh ask line (summary) about 15 seconds later.

POST /v1/beacons/{id}/merge takes { "sourceIds": [ ... ] }. Their evidence moves into the beacon in the path and each source is dismissed. If any source is promoted, the whole merge fails with 409. nima never merges beacons on its own: two open beacons whose evidence later overlaps stay separate until a person merges them.

Dismiss or permanently delete a beacon

DELETE /v1/beacons/{id} dismisses the beacon and keeps its history. DELETE /v1/beacons/{id}/permanent needs OWNER or ADMIN, never accepts an OAuth token, and cascades to the spec, its cards, PR links and drift checks. Its body is { "confirmTitle": "...", "signalDisposition": "release" | "dismiss" }. confirmTitle must equal the beacon title, or the call is a 400. release returns the member signals to the pool of ungrouped signals, where nima may place them in a new beacon within about a minute, and dismiss dismisses them too. It is a 409 while spec generation is running for the beacon.

How the beacon status field reaches ready

A beacon nima opens, or one with an urgent incident, is ready at once; one grouped by hand needs 3 member signals and rank 70. The full rules are in When a beacon becomes ready.

Disposition of a beacon: fix or decide

disposition on a beacon is fix or decide, set when nima opens it. fix marks a plain defect where no product choice remains, and decide is the default whenever nima is unsure. It changes nothing about which routes you can call; it only tells a person how much judgment the beacon needs.

Beacon errors and rate limits

Errors use the standard envelope. Below 500 it carries details; at 500 and above it carries an incidentId instead, which is also the X-Request-Id header on the response.

{
  "statusCode": 404,
  "error": "RESOURCE_NOT_FOUND",
  "message": "Beacon not found",
  "details": { "beaconId": "7d3c9e52-4b18-4a6f-9c20-5e81f7a0d4b3" },
  "timestamp": "2026-09-21T08:31:55.104Z",
  "path": "/v1/beacons/7d3c9e52-4b18-4a6f-9c20-5e81f7a0d4b3"
}

The three read routes carry no budget of their own, so they draw on the default: 100 requests per 60 seconds. The counter is keyed by client address, not by key, so two keys calling from one machine share one bucket. A successful response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 carries Retry-After in seconds instead, and its body is the envelope above with the message ThrottlerException: Too Many Requests and no retry field.