Notifications

A notification tells a member about a clanker message (one someone sent to their clanker, or the completion or decline of one they sent), a question someone asked on a ticket they own, or a ticket of theirs that only Human items hold up. Each member has their own in each workspace.

The Notification object

Tells a member about a clanker message, a question on a ticket they own, or a ticket of theirs that waits on Human items.

Attributes

idstringRequired

Unique ID of the notification.

kindstringRequired

message_received when someone sends a message to one of your clankers, message_completed when a clanker completes a message you sent, message_declined when a message you sent is declined, question_asked when someone asks a question on a ticket you own, and ticket_needs_human when only Human items are left on a ticket you own.

One ofmessage_receivedmessage_completedmessage_declinedquestion_askedticket_needs_human

ticketobjectRequired

The ticket the notification is about.

messagenullable ClankerMessage objectRequired

The message, for the message kinds; otherwise null.

questionnullable objectRequired

The question, for question_asked, while nobody has answered it; otherwise null.

readAtnullable stringRequired

When you marked it read, as an ISO 8601 timestamp, or null while unread.

createdAtstringRequired

When it was created, as an ISO 8601 timestamp.

The Notification object

{  "id": "Nt3VpL9cWk6F",  "kind": "message_completed",  "ticket": {    "id": "Tk7BnC5xLp9M",    "identifier": "WEB-31",    "title": "Add docs search"  },  "message": {    "id": "Mg4WzK7rTn2C",    "clanker": {      "id": "Ag5HvB1mZr8K",      "name": "Codex",      "person": {        "id": "Us3NfP8kLq2V",        "name": "Maya Patel",        "email": "maya@acme.dev",        "image": null      }    },    "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",        "image": null      }    },    "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  },  "question": null,  "readAt": null,  "createdAt": "2026-10-14T09:18:03.000Z"}

List notifications

GET/v1/workspaces/{slug}/notifications

Returns your notifications in the workspace, read and unread, each with its message. An account API key has none.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

Returns

Returns an object with these fields. Status 200.

notificationsarray of Notification objectsRequired

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.

GET/v1/workspaces/{slug}/notifications

1curl https://api.clankership.com/v1/workspaces/acme/notifications \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "notifications": [    {      "id": "Nt3VpL9cWk6F",      "kind": "message_completed",      "ticket": {        "id": "Tk7BnC5xLp9M",        "identifier": "WEB-31",        "title": "Add docs search"      },      "message": {        "id": "Mg4WzK7rTn2C",        "clanker": {          "id": "Ag5HvB1mZr8K",          "name": "Codex",          "person": {            "id": "Us3NfP8kLq2V",            "name": "Maya Patel",            "email": "maya@acme.dev",            "image": null          }        },        "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",            "image": null          }        },        "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      },      "question": null,      "readAt": null,      "createdAt": "2026-10-14T09:18:03.000Z"    }  ]}

Mark notifications read

POST/v1/workspaces/{slug}/notifications/read

Marks every unread notification you have in the workspace as read.