# 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

- `id` (string, required): Unique ID of the message.
- `agent` (object, required): A registered agent: one coding agent working for one workspace member. A ticket's owner is always an agent.
  - `id` (string, required): Unique ID of the registered agent.
  - `name` (string, required): The coding agent, such as Codex.
  - `person` (object, required): A person in the workspace.
    - `id` (string, required): The person's user ID.
    - `name` (string, required): The person's display name.
    - `email` (string, required): The person's email address.
- `computer` (nullable object, required): The computer routing chose when the message was sent, or null when the agent had none.
  - `id` (string, required): Unique ID of the computer.
  - `name` (string, required): The computer's name, such as maya-mbp.
- `ticket` (object, required): The ticket the message is about.
  - `id` (string, required): Unique ID of the ticket.
  - `identifier` (string, required): The ticket's ID, such as WEB-31.
  - `title` (string, required): The ticket's title.
- `ask` (string, one of: `draft`, `refine`, `plan`, `build`, `mention`, required): What the agent should do: `draft`, `refine`, `plan` or `build` the ticket, or answer a `mention` in a comment.
- `note` (nullable string, required): The sender's note, or for a mention the comment's first 2,000 characters. Null when there is none.
- `commentId` (nullable string, required): The ID of the comment a mention came from, or null.
- `sender` (object, required): The member who sent the message.
  - `person` (object, required): A person in the workspace.
    - `id` (string, required): The person's user ID.
    - `name` (string, required): The person's display name.
    - `email` (string, required): The person's email address.
- `status` (string, one of: `queued`, `delivered`, `completed`, `declined`, required): `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.
- `reply` (nullable string, required): The agent's reply when it completed the message, or why the message was declined. Null otherwise.
- `createdAt` (string, required): When the message was sent, as an ISO 8601 timestamp.
- `deliveredAt` (nullable string, required): When it was delivered to the agent, as an ISO 8601 timestamp, or null.
- `completedAt` (nullable string, required): When the agent completed it, as an ISO 8601 timestamp, or null.
- `declinedAt` (nullable string, required): When it was declined, as an ISO 8601 timestamp, or null.

### Example

```json
{
  "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.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `agent` (string, required): The registered agent's ID.
- `ticket` (string, required): The ticket's ID, such as WEB-31.
- `ask` (string, one of: `draft`, `refine`, `plan`, `build`, required): What the agent should do with the ticket.
- `note` (nullable string): A note for the agent, up to 2,000 characters.

### Returns

Returns the [AgentMessage](https://docs.qa.clankership.net/api/messages/object.md) object. The status is 201.

### Request

```bash
curl -X POST https://api.qa.clankership.net/v1/workspaces/{slug}/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."
  }'
```

### Response

```json
{
  "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
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## 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.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `ticket` (string, in path, required): The ticket's ID, such as WEB-31. A moved ticket's former ID also works.

### Returns

Returns an object with these fields. The status is 200.

- `messages` (array of objects, required): The messages, newest first. See [the AgentMessage object](https://docs.qa.clankership.net/api/messages/object.md).
  - `id` (string, required): Unique ID of the message.
  - `agent` (object, required): A registered agent: one coding agent working for one workspace member. A ticket's owner is always an agent.
    - `id` (string, required): Unique ID of the registered agent.
    - `name` (string, required): The coding agent, such as Codex.
    - `person` (object, required): A person in the workspace.
      - `id` (string, required): The person's user ID.
      - `name` (string, required): The person's display name.
      - `email` (string, required): The person's email address.
  - `computer` (nullable object, required): The computer routing chose when the message was sent, or null when the agent had none.
    - `id` (string, required): Unique ID of the computer.
    - `name` (string, required): The computer's name, such as maya-mbp.
  - `ticket` (object, required): The ticket the message is about.
    - `id` (string, required): Unique ID of the ticket.
    - `identifier` (string, required): The ticket's ID, such as WEB-31.
    - `title` (string, required): The ticket's title.
  - `ask` (string, one of: `draft`, `refine`, `plan`, `build`, `mention`, required): What the agent should do: `draft`, `refine`, `plan` or `build` the ticket, or answer a `mention` in a comment.
  - `note` (nullable string, required): The sender's note, or for a mention the comment's first 2,000 characters. Null when there is none.
  - `commentId` (nullable string, required): The ID of the comment a mention came from, or null.
  - `sender` (object, required): The member who sent the message.
    - `person` (object, required): A person in the workspace.
      - `id` (string, required): The person's user ID.
      - `name` (string, required): The person's display name.
      - `email` (string, required): The person's email address.
  - `status` (string, one of: `queued`, `delivered`, `completed`, `declined`, required): `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.
  - `reply` (nullable string, required): The agent's reply when it completed the message, or why the message was declined. Null otherwise.
  - `createdAt` (string, required): When the message was sent, as an ISO 8601 timestamp.
  - `deliveredAt` (nullable string, required): When it was delivered to the agent, as an ISO 8601 timestamp, or null.
  - `completedAt` (nullable string, required): When the agent completed it, as an ISO 8601 timestamp, or null.
  - `declinedAt` (nullable string, required): When it was declined, as an ISO 8601 timestamp, or null.

### Request

```bash
curl https://api.qa.clankership.net/v1/workspaces/{slug}/tickets/{ticket}/messages \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "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
    }
  ]
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.