docs
Notifications

List my notifications

GET
/v1/notifications

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.

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".

Query Parameters

unread?boolean|
kind?string
Lengthlength <= 200
archived?boolean|
unreadFirst?boolean|
ids?string
Lengthlength <= 8200
limit?|
Multiple Of1
Range1 <= value <= 200
offset?|
Multiple Of1
Range0 <= value <= 9007199254740991

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'
Example Response
{  "error": "string"}