Docs
Sign in

Search the docs

Search guides, API endpoints and MCP tools.

Messages

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

The AgentMessage object

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

Attributes

idstringRequired

Unique ID of the message.

agentobjectRequired

A registered agent: one coding agent working for one workspace member. A ticket's owner is always an agent.

computernullable objectRequired

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

ticketobjectRequired

The ticket the message is about.

askstringRequired

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

One ofdraftrefineplanbuildmention
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 agent, then delivered, then completed when the agent finishes it. declined when the agent was revoked first.

One ofqueueddeliveredcompleteddeclined
replynullable stringRequired

The agent'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 agent, as an ISO 8601 timestamp, or null.

completedAtnullable stringRequired

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

declinedAtnullable stringRequired

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

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

Send a message

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

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

Path parameters

slugstringRequired

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

Body parameters

agentstringRequired

The registered agent's ID.

ticketstringRequired

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

askstringRequired

What the agent should do with the ticket.

One ofdraftrefineplanbuild
notenullable string

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

Returns

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

List a ticket's messages

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

Returns every message sent about the ticket, with its status and the agent'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 AgentMessage 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.qa.clankership.net/v1/workspaces/acme/tickets/{ticket}/messages \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "messages": [    {      "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    }  ]}
NextComments