Watches and inbox

A watch is a standing request: when a supported event happens to one signal, beacon, spec or pull request, nima tells you. It sends a Slack DM, keeps an item in your inbox, and folds lower-priority items into a 09:00 local-time digest. The routes below create and manage your watches, list the events a watch can react to, and read the inbox. For how watches behave, see Watches and reminders.

Watches and inbox items are personal. Every route below is scoped to your workspace and to you: there is no way to list anyone else's watches or inbox, and another person's watch id answers 404, exactly like an id that does not exist.

Watch and inbox operations

Paths are relative to https://api.getnima.io. Every call carries Authorization: Bearer <your key>. The three scopes are in the default set an MCP client is asked to consent to. See Scopes and permissions and Authentication. The tools are documented on Watch and inbox tools.

Creating, updating or pausing a watch needs a member, admin or owner role. Your membership is checked again every time a watch fires. To read what happened to a subject, use GET /v1/events.

List the event types a watch can react to

Create a watch

Update or resume a watch

List your watches

Pause a watch

Read your inbox

Create a workspace rule for tracker tickets

POST /v1/watches with "scope": "org" creates a workspace rule instead of a personal watch: one rule over every ticket event in a connected tracker (Jira). It is separate from personal watches and has stricter requirements.

All of these must hold, and a failed check answers 403 or 409:

• The caller has the owner or admin role.
• The call comes from a signed-in owner or admin session. No API key, MCP connection or other OAuth token can create a workspace rule today. The route needs subscriptions:write, and a token also needs integrations:write to create a workspace rule, but no key or token can carry both. API keys and the MCP consent screen offer only the consumer scopes, and the key from /nima mcp-key integrations in Slack carries only integrations:write, so POST /v1/watches refuses it with 403. Otherwise, ask the nima team.
• triggersEnabled is on, and outbound dispatch is on for the workspace (dispatchEnabled), or the call answers 409 "Outbound dispatch is not enabled for this workspace".

A workspace rule takes no subjectKind or subjectId. Its triggerTypes are one or more of ticket.opened, ticket.assigned and ticket.comment_added. Its handler is one of:

• { "kind": "notify", "to": { "role": "owner" | "assignee" | "reporter" | "spec_owner" }, "fallback": "owner" | "none" } with templateKey: "tracker_assignee_reminder". fallback defaults to none. The mention option is rejected today.
• { "kind": "agent", "instructions": "...", "context": "...", "tools": ["reply_on_ticket"], "maxActions": 1 }. context is optional, 1 to 8000 characters. maxActions can only be 1, and the actions the rule proposes still go through approval.

A rule fires only on events created after the rule. It cannot be edited or resumed through PATCH. Pausing a rule with DELETE is final; create a new rule to start again.

The watch object

The watch object is what every watch route returns: POST, PATCH and DELETE return one, GET /v1/watches returns an array.

{
  "id": "0b8d4c52-0000-4000-8000-000000000000",
  "name": "Your requested update",
  "handler": { "kind": "ai_response" },
  "payloadEquals": { "verdict": "drifted" },
  "subjectKind": "spec",
  "subjectId": "6f1c2a3e-0000-4000-8000-000000000000",
  "triggerTypes": ["pr.drift_checked"],
  "templateKey": null,
  "createdVia": "api",
  "state": "active",
  "pausedReason": null,
  "expiresAt": null,
  "lastFiredAt": null,
  "fireCount": 0,
  "createdAt": "2026-09-30T09:00:00.000Z"
}

The handler value above is abbreviated: an ai_response handler also stores your saved instructions and context, and list_watches returns them.

The inbox item object

An inbox item is one message nima sent you, or held for you, about something you watch.

Errors from watch and inbox routes

The routes use the standard error envelope. Beyond the per-route errors above, these apply unless noted:

What watches do not do

• A watch pins one existing signal, beacon, spec or pull request. There are no topic or keyword watches, and no watch on items that do not exist yet.
• Conditions are exact equality only. There are no timers, after or unless conditions and no recurring schedules.
• Personal watches deliver only to their owner, by Slack DM, the inbox and the 09:00 digest (a workspace rule can instead notify a ticket's assignee, reporter or spec owner). There is no webhook, pull feed or channel posting.
• To be reminded at a time you choose, use scheduled messages.