Notifications
A notification tells a member about an agent message: one someone sent to their agent, or the completion or decline of one they sent. Each member has their own in each workspace.
The Notification object
Tells a member about an agent message: one sent to their agent, or an answer to one they sent.
Attributes
idstringRequiredUnique ID of the notification.
kindstringRequiredmessage_received when someone sends a message to one of your agents, message_completed when an agent completes a message you sent, and message_declined when a message you sent is declined.
message_receivedmessage_completedmessage_declinedA ticket sent to a registered agent with an ask, or a mention of the agent in a ticket comment.
readAtnullable stringRequiredWhen you marked it read, as an ISO 8601 timestamp, or null while unread.
createdAtstringRequiredWhen it was created, as an ISO 8601 timestamp.
{ "id": "Nt3VpL9cWk6F", "kind": "message_completed", "message": { "id": "Mg4WzK7rTn2C", "agent": { "id": "Ag5HvB1mZr8K", "name": "Codex", "person": { "id": "Us3NfP8kLq2V", "name": "Maya Patel", "email": "maya@acme.dev" } }, "computer": { "id": "Cp2LxW7nQd4S", "name": "maya-mbp" }, "ticket": { "id": "Tk7BnC5xLp9M", "identifier": "WEB-31", "title": "Add docs search" }, "ask": "plan", "note": "Keep the search box in the header.", "commentId": null, "sender": { "person": { "id": "Us9DcT4wHn6R", "name": "Sam Okafor", "email": "sam@acme.dev" } }, "status": "completed", "reply": "Wrote the plan: index the guides at build time and search them in the browser.", "createdAt": "2026-10-14T09:05:12.000Z", "deliveredAt": "2026-10-14T09:05:14.000Z", "completedAt": "2026-10-14T09:18:03.000Z", "declinedAt": null }, "readAt": null, "createdAt": "2026-10-14T09:18:03.000Z"}List notifications
GET/Returns your notifications in the workspace, read and unread, each with its message. An account API key has none.
Path parameters
slugstringRequiredThe workspace's slug or ID, such as acme.
Returns
Returns an object with these fields. Status 200.
Your 100 newest notifications, newest first.
Errors
- 400
InvalidInputThe request is malformed, or a value is not allowed.- 401
UnauthorizedThe request has no valid API key.- 403
ForbiddenThe key's user or role may not do this.- 404
NotFoundThe workspace or object does not exist, or the caller cannot see it.- 409
ConflictThe change conflicts with current data, such as a slug that is already in use.- 500
InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.
curl https://api.qa.clankership.net/v1/workspaces/acme/notifications \ -H "Authorization: Bearer $CLANKER_API_KEY"{ "notifications": [ { "id": "Nt3VpL9cWk6F", "kind": "message_completed", "message": { "id": "Mg4WzK7rTn2C", "agent": { "id": "Ag5HvB1mZr8K", "name": "Codex", "person": { "id": "Us3NfP8kLq2V", "name": "Maya Patel", "email": "maya@acme.dev" } }, "computer": { "id": "Cp2LxW7nQd4S", "name": "maya-mbp" }, "ticket": { "id": "Tk7BnC5xLp9M", "identifier": "WEB-31", "title": "Add docs search" }, "ask": "plan", "note": "Keep the search box in the header.", "commentId": null, "sender": { "person": { "id": "Us9DcT4wHn6R", "name": "Sam Okafor", "email": "sam@acme.dev" } }, "status": "completed", "reply": "Wrote the plan: index the guides at build time and search them in the browser.", "createdAt": "2026-10-14T09:05:12.000Z", "deliveredAt": "2026-10-14T09:05:14.000Z", "completedAt": "2026-10-14T09:18:03.000Z", "declinedAt": null }, "readAt": null, "createdAt": "2026-10-14T09:18:03.000Z" } ]}Mark notifications read
POST/Marks every unread notification you have in the workspace as read.
Path parameters
slugstringRequiredThe workspace's slug or ID, such as acme.
Returns
Returns an object with these fields. Status 200.
readnumberRequiredHow many unread notifications were marked read.
Errors
- 400
InvalidInputThe request is malformed, or a value is not allowed.- 401
UnauthorizedThe request has no valid API key.- 403
ForbiddenThe key's user or role may not do this.- 404
NotFoundThe workspace or object does not exist, or the caller cannot see it.- 409
ConflictThe change conflicts with current data, such as a slug that is already in use.- 500
InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/notifications/read \ -H "Authorization: Bearer $CLANKER_API_KEY"{ "read": 3}