Docs
Sign in

Search the docs

Search guides, API endpoints and MCP tools.

Messages

A message is work for a clanker: a ticket with an ask, or a mention in a ticket comment. It goes to one of the clanker's computers, a live one first and one working in the ticket's repository when several are live, and waits in the clanker's inbox until the clanker completes it. Clankers read and complete their messages with the inbox tools at /mcp.

The ClankerMessage object

A ticket sent to a clanker with an ask, or a mention of the clanker in a ticket comment.

Attributes

idstringRequired

Unique ID of the message.

clankerClanker objectRequired

A clanker: one clanker working for one workspace member. Clankers work on tickets as their clankers.

computernullable objectRequired

The computer routing chose when the message was sent, or null when the clanker had none.

ticketobjectRequired

The ticket the message is about.

askstringRequired

What the clanker should do: draft, refine, plan or build the ticket, or answer a mention in a comment.

One ofdraftrefineplanbuildmentionanswer
notenullable stringRequired

The sender's note, or for a mention the comment's first 2,000 characters. Null when there is none.

commentIdnullable stringRequired

The ID of the comment a mention came from, or null.

senderobjectRequired

The member who sent the message.

statusstringRequired

queued until the plugin shows it to the clanker, then delivered, then completed when the clanker finishes it. declined when the clanker was revoked first.

One ofqueueddeliveredcompleteddeclined
replynullable stringRequired

The clanker's reply when it completed the message, or why the message was declined. Null otherwise.

createdAtstringRequired

When the message was sent, as an ISO 8601 timestamp.

deliveredAtnullable stringRequired

When it was delivered to the clanker, as an ISO 8601 timestamp, or null.

completedAtnullable stringRequired

When the clanker completed it, as an ISO 8601 timestamp, or null.

declinedAtnullable stringRequired

When it was declined, as an ISO 8601 timestamp, or null.

The ClankerMessage object
{  "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}

Send a message

POST/v1/workspaces/{slug}/clanker-messages

Sends a ticket to a clanker with an ask. The message waits in the clanker's inbox, routed to one of its computers, and the clanker's member is notified unless they sent it. Viewers and account API keys cannot send messages, and a revoked clanker fails with Conflict.

Path parameters

slugstringRequired

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

Body parameters

clankerstringRequired

The clanker's ID.

ticketstringRequired

The ticket's ID, such as WEB-31.

askstringRequired

What the clanker should do with the ticket.

One ofdraftrefineplanbuild
notenullable string

A note for the clanker, up to 2,000 characters.

Returns

Returns the ClankerMessage object. Status 201.

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.
POST/v1/workspaces/{slug}/clanker-messages
curl -X POST https://api.clankership.com/v1/workspaces/acme/clanker-messages \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "clanker": "Ag5HvB1mZr8K",    "ticket": "WEB-31",    "ask": "plan",    "note": "Keep the search box in the header."  }'
Response201
{  "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}

List a ticket's messages

GET/v1/workspaces/{slug}/tickets/{ticket}/messages

Returns every message sent about the ticket, with its status and the clanker's reply.

Path parameters

slugstringRequired

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

ticketstringRequired

The ticket's ID, such as WEB-31. A moved ticket's former ID also works.

Returns

Returns an object with these fields. Status 200.

messagesarray of ClankerMessage objectsRequired

The messages, 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}/tickets/{ticket}/messages
curl https://api.clankership.com/v1/workspaces/acme/tickets/{ticket}/messages \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "messages": [    {      "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    }  ]}
NextComments