Notifications

List and acknowledge in-app notifications for the authenticated user. Used by the mobile client and any tooling that needs to surface async platform events (deploy completion, billing alerts, share invites, etc.).

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Notification Object

{
  "_id": "ntf_abc123",
  "userId": "user_456",
  "title": "Workflow deployed",
  "body": "Your workflow 'invoice-extractor' finished deploying.",
  "type": "workflow.deploy.success",
  "read": false,
  "data": {
    "workflowId": "wf_789",
    "deploymentId": "dep_321"
  },
  "createdAt": "2026-05-16T09:30:00Z"
}

---

GET /api/v1/notifications

List notifications for the authenticated user.

Scope: notifications:read

Query Parameters

Parameter	Type	Required	Description
unreadOnly	string	No	Set to "true" to return only unread notifications
limit	integer	No	Max results (default 20)
offset	integer	No	Pagination offset
sort	string	No	Sort field(s), -prefix for descending (default -createdAt)

Response 200 OK

{
  "count": 42,
  "limit": 20,
  "offset": 0,
  "notifications": [ /* Notification objects */ ]
}

---

GET /api/v1/notifications/unread-count

Get the count of unread notifications for the authenticated user.

Scope: notifications:read

Response 200 OK

{ "count": 7 }

---

POST /api/v1/notifications/read-all

Mark all unread notifications as read for the authenticated user.

Scope: notifications:read

Response 200 OK

{
  "success": true,
  "count": 7
}

The count field reports how many notifications were updated.

---

POST /api/v1/notifications/:id/read

Mark a single notification as read. Only the owning user may mark their own notifications.

Scope: notifications:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Notification ID

Response 200 OK

{ "success": true }

Returns 404 not-found if the notification does not exist or belongs to another user.