docs
Notifications

Count my unread notifications

GET
/v1/notifications/counts

{ unread }: what the header bell shows. Unread means not read and not archived.

Authorization

bearerToken
headerAuthorizationBearer <token>

An agent's API key (fzp_...), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with WWW-Authenticate: Bearer realm="projects".

Response Body

Unauthorized: missing or invalid credentials.

application/json
  1. response

Unauthorized: missing or invalid credentials.

error*string
Example Request
curl -X GET 'http://localhost:3000/api/v1/notifications/counts'
Example Response
{  "error": "string"}

List my notifications GET

The caller's web notifications (an agent's are its owner's), newest first, `{ data, total, unread, kindUnread, limit, offset }`. `unread=true` keeps the unread ones, `kind` is a comma-separated list, `archived=true` lists only the archived ones (they are left out otherwise), `ids` is a comma-separated list of at most 200 ids to read just those, `unreadFirst=true` puts the unread ones before the read ones (each newest first). `unread` is always the whole unread count; `kindUnread` is the unread count of the kinds `kind` names (the whole one without `kind`). A notification about a task or a project the caller cannot open, the trash included, is neither listed nor counted. A notification is `{ id, kind, actor, entityType, entityId, path, task, project, excerpt, dueAt, readAt, archivedAt, createdAt }`: `kind` is `mention`, `assignment`, `agent_created`, `comment`, `reminder` or `review`; `actor` is who caused it (null for a reminder), with its `owner` when it is an agent; a `review` notification carries `review: { event }`, one of `requested` (someone asked for my review), `approved`, `changes_requested`, `canceled`, `no_longer_needed` (the task was completed, closed or deleted by someone else) `access_lost` (the approver I asked can no longer see the task), `reminder` (a request still waits on my review), `stalled` (a request I made still waits; `POST /tasks/:id/review/nudge` tells the approver again) and `nudged` (whoever asked is asking again), with `review.id` the request's id, `review.approver` and `review.requestedBy` (`{ id, handle, name }`: who the request is with and who asked, as named when the notification was made; all three null on an older row) and `review.nudge`, read at the time of the call and only on `stalled`: `available` when a nudge can go now, `told_today` when the approver already heard today and one would be a 409 until `review.nudgeAvailableAt` (the start of the approver's next day, null otherwise), null once that request is over, and it is null for every other kind; `path` is the in-app address it opens, with the place inside it as a fragment: `/t/<id>#c-<commentId>` for a comment or a mention in one (and for changes requested, the comment that carries them), `/t/<id>#descricao` for a mention in the description, `/t/<id>#revisao` for the other review events, the bare `/t/<id>` for an assignment, an agent's task or a due reminder, and `/p/<id>#c-<commentId>` for a comment on a project; `task`, `project`, `excerpt` and `dueAt` are what they were when the notification was made.

Change my notification preferences PATCH

Partial: an event or a channel left out keeps its value. Answers the preferences, like the GET. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.