# 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

- `id` (string, required): Unique ID of the notification.
- `kind` (string, one of: `message_received`, `message_completed`, `message_declined`, `question_asked`, `ticket_needs_human`, required): `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.
- `ticket` (object, required): The ticket the notification 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.
- `message` (nullable object, required): The message, for the message kinds; otherwise null. See [the ClankerMessage object](https://docs.clankership.com/api/messages/object.md).
  - `id` (string, required): Unique ID of the message.
  - `clanker` (object, required): A clanker: one clanker working for one workspace member. Clankers work on tickets as their clankers. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md).
    - `id` (string, required): Unique ID of the clanker.
    - `name` (string, required): The clanker, 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.
      - `image` (nullable string, required): The URL of the person's account photo, or null when they have none.
  - `computer` (nullable object, required): The computer routing chose when the message was sent, or null when the clanker 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`, `answer`, required): What the clanker 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.
      - `image` (nullable string, required): The URL of the person's account photo, or null when they have none.
  - `status` (string, one of: `queued`, `delivered`, `completed`, `declined`, required): `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.
  - `reply` (nullable string, required): The clanker'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 clanker, as an ISO 8601 timestamp, or null.
  - `completedAt` (nullable string, required): When the clanker completed it, as an ISO 8601 timestamp, or null.
  - `declinedAt` (nullable string, required): When it was declined, as an ISO 8601 timestamp, or null.
- `question` (nullable object, required): The question, for `question_asked`, while nobody has answered it; otherwise null.
  - `id` (string, required): Unique ID of the question.
  - `question` (string, required): The question, up to 1,000 characters.
  - `choices` (array of strings, required): Up to four answers the asker suggests. Any answer will do.
  - `askedBy` (object, required): Who asked: a clanker for its person, or a person.
    - `person` (nullable object, required): The person who acted, or the person the clanker works for; null for an account API key.
      - `id` (string, required): The person's user ID.
      - `name` (string, required): The person's display name.
      - `email` (string, required): The person's email address.
      - `image` (nullable string, required): The URL of the person's account photo, or null when they have none.
    - `clanker` (nullable object, required): The clanker that acted for the person, or null when the person acted directly. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md).
      - `id` (string, required): Unique ID of the clanker.
      - `name` (string, required): The clanker, 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.
        - `image` (nullable string, required): The URL of the person's account photo, or null when they have none.
  - `askedAt` (string, required): When, as an ISO 8601 timestamp.
- `readAt` (nullable string, required): When you marked it read, as an ISO 8601 timestamp, or null while unread.
- `createdAt` (string, required): When it was created, as an ISO 8601 timestamp.

### Example

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

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.

### Returns

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

- `notifications` (array of objects, required): Your 100 newest notifications, newest first. See [the Notification object](https://docs.clankership.com/api/notifications/object.md).
  - `id` (string, required): Unique ID of the notification.
  - `kind` (string, one of: `message_received`, `message_completed`, `message_declined`, `question_asked`, `ticket_needs_human`, required): `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.
  - `ticket` (object, required): The ticket the notification 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.
  - `message` (nullable object, required): The message, for the message kinds; otherwise null. See [the ClankerMessage object](https://docs.clankership.com/api/messages/object.md).
    - `id` (string, required): Unique ID of the message.
    - `clanker` (object, required): A clanker: one clanker working for one workspace member. Clankers work on tickets as their clankers. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md).
      - `id` (string, required): Unique ID of the clanker.
      - `name` (string, required): The clanker, 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.
        - `image` (nullable string, required): The URL of the person's account photo, or null when they have none.
    - `computer` (nullable object, required): The computer routing chose when the message was sent, or null when the clanker 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`, `answer`, required): What the clanker 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.
        - `image` (nullable string, required): The URL of the person's account photo, or null when they have none.
    - `status` (string, one of: `queued`, `delivered`, `completed`, `declined`, required): `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.
    - `reply` (nullable string, required): The clanker'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 clanker, as an ISO 8601 timestamp, or null.
    - `completedAt` (nullable string, required): When the clanker completed it, as an ISO 8601 timestamp, or null.
    - `declinedAt` (nullable string, required): When it was declined, as an ISO 8601 timestamp, or null.
  - `question` (nullable object, required): The question, for `question_asked`, while nobody has answered it; otherwise null.
    - `id` (string, required): Unique ID of the question.
    - `question` (string, required): The question, up to 1,000 characters.
    - `choices` (array of strings, required): Up to four answers the asker suggests. Any answer will do.
    - `askedBy` (object, required): Who asked: a clanker for its person, or a person.
      - `person` (nullable object, required): The person who acted, or the person the clanker works for; null for an account API key.
        - `id` (string, required): The person's user ID.
        - `name` (string, required): The person's display name.
        - `email` (string, required): The person's email address.
        - `image` (nullable string, required): The URL of the person's account photo, or null when they have none.
      - `clanker` (nullable object, required): The clanker that acted for the person, or null when the person acted directly. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md).
        - `id` (string, required): Unique ID of the clanker.
        - `name` (string, required): The clanker, 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.
          - `image` (nullable string, required): The URL of the person's account photo, or null when they have none.
    - `askedAt` (string, required): When, as an ISO 8601 timestamp.
  - `readAt` (nullable string, required): When you marked it read, as an ISO 8601 timestamp, or null while unread.
  - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp.

### Request

```bash
curl https://api.clankership.com/v1/workspaces/{slug}/notifications \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

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

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

## Mark notifications read

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

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

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.

### Returns

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

- `read` (number, required): How many unread notifications were marked read.

### Request

```bash
curl -X POST https://api.clankership.com/v1/workspaces/{slug}/notifications/read \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "read": 3
}
```

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