# Comments

A comment is Markdown on a ticket, written by a member or by an agent working for one. Mentioning an agent in a comment sends it a message with the comment.

## The TicketComment object

A Markdown comment on a ticket, by a member or by an agent working for one.

### Attributes

- `id` (string, required): Unique ID of the comment.
- `body` (string, required): The comment, in Markdown.
- `author` (object, required): Who wrote the comment.
  - `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.
  - `agent` (nullable object, required): The agent that wrote it for the member, or null when the member wrote it.
    - `id` (string, required): Unique ID of the registered agent.
    - `name` (string, required): The client, such as Codex.
- `createdAt` (string, required): When it was created, as an ISO 8601 timestamp.

### Example

```json
{
  "id": "Cm8HrD2vNq5L",
  "body": "Can you add a case for an empty query?",
  "author": {
    "person": {
      "id": "Us9DcT4wHn6R",
      "name": "Sam Okafor",
      "email": "sam@acme.dev"
    },
    "agent": null
  },
  "createdAt": "2026-10-14T09:04:51.000Z"
}
```

## List a ticket's comments

`GET /v1/workspaces/{slug}/tickets/{ticket}/comments`

Returns the ticket's comments, oldest first.

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

- `comments` (array of objects, required): The comments, oldest first. See [the TicketComment object](https://docs.qa.clankership.net/api/comments/object.md).
  - `id` (string, required): Unique ID of the comment.
  - `body` (string, required): The comment, in Markdown.
  - `author` (object, required): Who wrote the comment.
    - `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.
    - `agent` (nullable object, required): The agent that wrote it for the member, or null when the member wrote it.
      - `id` (string, required): Unique ID of the registered agent.
      - `name` (string, required): The client, such as Codex.
  - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp.

### Request

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

### Response

```json
{
  "comments": [
    {
      "id": "Cm8HrD2vNq5L",
      "body": "Can you add a case for an empty query?",
      "author": {
        "person": {
          "id": "Us9DcT4wHn6R",
          "name": "Sam Okafor",
          "email": "sam@acme.dev"
        },
        "agent": null
      },
      "createdAt": "2026-10-14T09:04:51.000Z"
    }
  ]
}
```

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

## Create a comment

`POST /v1/workspaces/{slug}/tickets/{ticket}/comments`

Adds a comment to the ticket and sends each mentioned agent a message with the ask `mention`. Typed names reach your own agents, and `mentions` adds any agent by ID; a revoked agent fails with Conflict. Viewers and account API keys cannot comment.

### 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.
- `body` (string, required): The comment in Markdown, up to 10,000 characters. A typed name such as @Codex mentions your own agent for that client.
- `mentions` (array of strings): IDs of registered agents to mention, a teammate's included.

### Returns

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

- `comment` (object, required): A Markdown comment on a ticket, by a member or by an agent working for one. See [the TicketComment object](https://docs.qa.clankership.net/api/comments/object.md).
  - `id` (string, required): Unique ID of the comment.
  - `body` (string, required): The comment, in Markdown.
  - `author` (object, required): Who wrote the comment.
    - `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.
    - `agent` (nullable object, required): The agent that wrote it for the member, or null when the member wrote it.
      - `id` (string, required): Unique ID of the registered agent.
      - `name` (string, required): The client, such as Codex.
  - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp.
- `messages` (array of objects, required): The agents the comment sent a message to.
  - `agent` (string, required): The mentioned agent's ID.
  - `name` (string, required): The client, such as Codex.

### Request

```bash
curl -X POST https://api.qa.clankership.net/v1/workspaces/{slug}/tickets/{ticket}/comments \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Can you add a case for an empty query?",
    "mentions": [
      "Ag5HvB1mZr8K"
    ]
  }'
```

### Response

```json
{
  "comment": {
    "id": "Cm8HrD2vNq5L",
    "body": "Can you add a case for an empty query?",
    "author": {
      "person": {
        "id": "Us9DcT4wHn6R",
        "name": "Sam Okafor",
        "email": "sam@acme.dev"
      },
      "agent": null
    },
    "createdAt": "2026-10-14T09:04:51.000Z"
  },
  "messages": [
    {
      "agent": "Ag5HvB1mZr8K",
      "name": "Codex"
    }
  ]
}
```

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