# Tickets

A ticket is one unit of work on a team. Its ID is the team key and number, such as WEB-31. Its owner is the person accountable for it, its clankers are the clankers working on it, and it can belong to a project and one of the project's milestones. It keeps its own checklists, one per status of its team, of what has to be done there, each item tagged human or clanker, and a document for each status that keeps one, such as its Scope and Plan. Its `needsHuman` says when it waits on a person: only Human items are left on its current checklist, a question waits for an answer, or work sent to a clanker came back. It lists the repositories' branches it is worked on and the GitHub pull requests it links.

## The Ticket object

One unit of work on a team, with its checklists and documents.

### Attributes

- `id` (string, required): Unique ID of the ticket.
- `identifier` (string, required): The team key and number, such as WEB-31. Paths take this ID.
- `number` (number, required): The ticket's number within its team.
- `team` (object, required): A team as tickets and projects show it.
  - `id` (string, required): Unique ID of the team.
  - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB.
  - `name` (string, required): The team's display name.
  - `visibility` (string, one of: `open`, `private`, required): Who sees the team: open teams are listed for everyone in the workspace, private teams only for their members and for owners and admins.
- `title` (string, required): A short name for the work.
- `status` (object, required): A step in a team's workflow, such as Plan or Build. See [the TicketStatus object](https://docs.clankership.com/api/ticket-statuses/object.md).
  - `id` (string, required): Unique ID of the ticket status.
  - `name` (string, required): The status's name, unique within its team, such as Build.
  - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change.
  - `position` (number, required): Orders the status within its category; lower comes first.
  - `isDefault` (boolean, required): Whether new tickets get this status when none is named.
- `owner` (nullable object, required): The person accountable for the ticket, or null.
  - `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.
- `clankers` (array of objects, required): The clankers working on the ticket, in the order they were added. 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.
- `project` (nullable object, required): The project the ticket belongs to, or null.
  - `id` (string, required): Unique ID of the project.
  - `slug` (string, required): Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch.
  - `name` (string, required): The project's display name.
- `milestone` (nullable object, required): The milestone of its project the ticket belongs to, or null.
  - `id` (string, required): Unique ID of the milestone.
  - `number` (number, required): The milestone's number within the project: 2 is M2.
  - `name` (string, required): The milestone's name.
- `tags` (array of objects, required): The ticket's tags, sorted by name. See [the Tag object](https://docs.clankership.com/api/tags/object.md).
  - `id` (string, required): Unique ID of the tag.
  - `name` (string, required): The tag's name, such as bug.
  - `color` (string, one of: `gray`, `red`, `orange`, `amber`, `green`, `teal`, `cobalt`, `iris`, `pink`, required): The tag's color.
  - `team` (nullable object, required): The team a team tag belongs to; null for a workspace tag.
    - `id` (string, required): Unique ID of the team.
    - `key` (string, required): The team's key, such as WEB.
- `checklist` (object, required): The ticket's checklist items for the statuses of its current stage, counted. The Work layout fills the stage's stretch of the track by this share.
  - `done` (number, required): How many of those items are done.
  - `inProgress` (number, required): How many of those items are in progress: started and not done.
  - `total` (number, required): How many items there are.
- `needsHuman` (nullable object, required): Why the ticket waits on a person, or null when it does not.
  - `reasons` (array of strings, one of: `human-items`, `question`, `work-returned`, required): Why: `human-items` when only Human items are left on the current status's checklist in Plan, Build, Review or Ship; `question` while a question waits for an answer; `work-returned` when work sent to a clanker came back finished (a draft, refinement or plan) or declined.
  - `items` (array of strings, required): The open Human items, for `human-items`; otherwise empty.
  - `questions` (array of objects, required): The open questions, oldest first.
    - `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.
  - `work` (nullable object, required): The work that came back, for `work-returned`; otherwise null.
    - `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.
    - `ask` (string, one of: `draft`, `refine`, `plan`, `build`, `mention`, `answer`, required): What was asked.
    - `status` (string, one of: `queued`, `delivered`, `completed`, `declined`, required): Where the work is: queued, delivered, completed or declined.
    - `reply` (nullable string, required): What the clanker said when it finished or declined, or null.
- `rank` (number, required): The ticket's place in the one workspace-wide order that views ordered by hand follow; lower comes first.
- `createdAt` (string, required): When it was created, as an ISO 8601 timestamp.
- `updatedAt` (string, required): When it last changed, as an ISO 8601 timestamp.
- `createdBy` (object, required): Who created the ticket.
  - `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.
- `formerIdentifiers` (array of strings, required): IDs the ticket had on other teams, oldest first. Each still finds it.
- `checklists` (array of objects, required): The ticket's own checklists, one per status of its team that has one, in board order. A ticket gets a status's checklist, copied from the status's template, when it first enters the status.
  - `id` (string, required): Unique ID of the checklist.
  - `status` (object, required): The status the checklist is for.
    - `id` (string, required): Unique ID of the ticket status.
    - `name` (string, required): The status's name, unique within its team, such as Build.
    - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change.
    - `position` (number, required): Orders the status within its category; lower comes first.
    - `isDefault` (boolean, required): Whether new tickets get this status when none is named.
  - `items` (array of objects, required): The checklist's items, in order.
    - `id` (string, required): Unique ID of the checklist item.
    - `title` (string, required): What has to be done, up to 120 characters, unique within its checklist.
    - `position` (number, required): Orders the item within its checklist, from 0.
    - `doer` (string, one of: `human`, `clanker`, required): Who does the item: `human` for a person, such as an approval, or `clanker`. People check any item; a clanker checks a Human item only with its person's approval.
    - `done` (boolean, required): Whether the item is checked.
    - `doneBy` (nullable object, required): Who checked the item, or null while it is open.
      - `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.
    - `doneAt` (nullable string, required): When the item was checked, as an ISO 8601 timestamp, or null while it is open.
    - `inProgress` (boolean, required): Whether someone is working the item: started and not checked yet.
    - `startedBy` (nullable object, required): Who started the item, or null unless it is in progress.
      - `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.
    - `startedAt` (nullable string, required): When the item was started, as an ISO 8601 timestamp, or null unless it is in progress.
    - `approval` (nullable string, required): The person's words approving the item in a conversation with their clanker, when the clanker checked a Human item for them; null otherwise.
- `documents` (array of objects, required): The ticket's documents in workflow order: one for each of its team's statuses that keeps a document, written or not, then any it kept from statuses that are gone.
  - `name` (string, required): The document's name, such as Plan.
  - `slug` (string, required): The name as paths take it, such as build-record.
  - `stage` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change.
  - `status` (nullable object, required): The status that keeps the document; null once that status is gone. See [the TicketStatus object](https://docs.clankership.com/api/ticket-statuses/object.md).
    - `id` (string, required): Unique ID of the ticket status.
    - `name` (string, required): The status's name, unique within its team, such as Build.
    - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change.
    - `position` (number, required): Orders the status within its category; lower comes first.
    - `isDefault` (boolean, required): Whether new tickets get this status when none is named.
  - `revision` (number, required): The document's latest revision; 0 until anyone writes it.
  - `updatedAt` (nullable string, required): When the document was last written, as an ISO 8601 timestamp, or null.
- `branches` (array of objects, required): The repositories' branches the ticket is worked on, oldest link first.
  - `repository` (string, required): The repository as owner/name.
  - `branch` (string, required): The branch, such as web-31-docs-search.
  - `linkedBy` (object, required): Who linked it.
    - `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.
  - `linkedAt` (string, required): When, as an ISO 8601 timestamp.
- `pullRequests` (array of objects, required): The GitHub pull requests the ticket links, oldest link first, up to 10.
  - `url` (string, required): The pull request's page on GitHub.
  - `repository` (string, required): The repository as owner/name.
  - `number` (number, required): The pull request's number, such as 142.
  - `linkedBy` (object, required): Who linked it.
    - `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.
  - `linkedAt` (string, required): When, as an ISO 8601 timestamp.
- `sessions` (array of objects, required): The live sessions working on the ticket, most recently seen first.
  - `id` (string, required): Unique ID of the session.
  - `client` (string, required): The clanker client, such as Claude Code.
  - `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` (string, required): The name of the computer the session runs on, such as maya-mbp.
  - `repository` (nullable string, required): The repository the session works in, as owner/name, or null outside one.
  - `branch` (nullable string, required): The branch checked out in the session, or null.
  - `source` (string, one of: `picked`, `linked`, `branch`, `name`, required): Where the session's ticket came from, strongest first: `picked` by its person, `linked` by its clanker in the session, the ticket its branch is `branch`-linked to, or the ticket whose ID the branch's `name` carries.
  - `connected` (boolean, required): Whether the session holds a connection to Clanker Ship, so it hears changes at once.
  - `lastSeenAt` (string, required): When the session last reported, as an ISO 8601 timestamp.

### Example

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.000Z"
    }
  ]
}
```

## List tickets

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

Returns the tickets the caller can read, without their documents and checklists: tickets of the teams the caller sees, and tickets in the projects the caller can open.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `team` (string, in query): Only this team's tickets, by key, such as WEB.
- `project` (string, in query): Only this project's tickets, by slug, such as docs-launch.
- `owner` (string, in query): Only tickets this person owns, by user ID, or me for tickets the caller owns.
- `clanker` (string, in query): Only tickets this clanker works on, by clanker ID, or mine for tickets any of the caller's clankers work on.
- `category` (string, in query): Only tickets whose status is in these categories, comma-separated, such as plan,build,review. The categories are backlog, plan, build, review, ship, done, canceled.
- `query` (string, in query): Only tickets whose title or Scope holds these words, or whose ID starts with them.
- `needsHuman` (string, in query): `true` for only the tickets that wait on a person. Always `true`.

### Returns

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

- `tickets` (array of objects, required): The tickets, sorted by status category, then status position, then rank, so open tickets come first.
  - `id` (string, required): Unique ID of the ticket.
  - `identifier` (string, required): The team key and number, such as WEB-31. Paths take this ID.
  - `number` (number, required): The ticket's number within its team.
  - `team` (object, required): A team as tickets and projects show it.
    - `id` (string, required): Unique ID of the team.
    - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB.
    - `name` (string, required): The team's display name.
    - `visibility` (string, one of: `open`, `private`, required): Who sees the team: open teams are listed for everyone in the workspace, private teams only for their members and for owners and admins.
  - `title` (string, required): A short name for the work.
  - `status` (object, required): A step in a team's workflow, such as Plan or Build. See [the TicketStatus object](https://docs.clankership.com/api/ticket-statuses/object.md).
    - `id` (string, required): Unique ID of the ticket status.
    - `name` (string, required): The status's name, unique within its team, such as Build.
    - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change.
    - `position` (number, required): Orders the status within its category; lower comes first.
    - `isDefault` (boolean, required): Whether new tickets get this status when none is named.
  - `owner` (nullable object, required): The person accountable for the ticket, or null.
    - `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.
  - `clankers` (array of objects, required): The clankers working on the ticket, in the order they were added. 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.
  - `project` (nullable object, required): The project the ticket belongs to, or null.
    - `id` (string, required): Unique ID of the project.
    - `slug` (string, required): Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch.
    - `name` (string, required): The project's display name.
  - `milestone` (nullable object, required): The milestone of its project the ticket belongs to, or null.
    - `id` (string, required): Unique ID of the milestone.
    - `number` (number, required): The milestone's number within the project: 2 is M2.
    - `name` (string, required): The milestone's name.
  - `tags` (array of objects, required): The ticket's tags, sorted by name. See [the Tag object](https://docs.clankership.com/api/tags/object.md).
    - `id` (string, required): Unique ID of the tag.
    - `name` (string, required): The tag's name, such as bug.
    - `color` (string, one of: `gray`, `red`, `orange`, `amber`, `green`, `teal`, `cobalt`, `iris`, `pink`, required): The tag's color.
    - `team` (nullable object, required): The team a team tag belongs to; null for a workspace tag.
      - `id` (string, required): Unique ID of the team.
      - `key` (string, required): The team's key, such as WEB.
  - `checklist` (object, required): The ticket's checklist items for the statuses of its current stage, counted. The Work layout fills the stage's stretch of the track by this share.
    - `done` (number, required): How many of those items are done.
    - `inProgress` (number, required): How many of those items are in progress: started and not done.
    - `total` (number, required): How many items there are.
  - `needsHuman` (nullable object, required): Why the ticket waits on a person, or null when it does not.
    - `reasons` (array of strings, one of: `human-items`, `question`, `work-returned`, required): Why: `human-items` when only Human items are left on the current status's checklist in Plan, Build, Review or Ship; `question` while a question waits for an answer; `work-returned` when work sent to a clanker came back finished (a draft, refinement or plan) or declined.
    - `items` (array of strings, required): The open Human items, for `human-items`; otherwise empty.
    - `questions` (array of objects, required): The open questions, oldest first.
      - `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.
    - `work` (nullable object, required): The work that came back, for `work-returned`; otherwise null.
      - `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.
      - `ask` (string, one of: `draft`, `refine`, `plan`, `build`, `mention`, `answer`, required): What was asked.
      - `status` (string, one of: `queued`, `delivered`, `completed`, `declined`, required): Where the work is: queued, delivered, completed or declined.
      - `reply` (nullable string, required): What the clanker said when it finished or declined, or null.
  - `rank` (number, required): The ticket's place in the one workspace-wide order that views ordered by hand follow; lower comes first.
  - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp.
  - `updatedAt` (string, required): When it last changed, as an ISO 8601 timestamp.

### Request

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

### Response

```json
{
  "tickets": [
    {
      "id": "Tk7BnC5xLp9M",
      "identifier": "WEB-31",
      "number": 31,
      "team": {
        "id": "Tm6PzN3kWq1J",
        "key": "WEB",
        "name": "Web",
        "visibility": "open"
      },
      "title": "Add docs search",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "owner": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "clankers": [
        {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      ],
      "project": {
        "id": "Pj2KsV8dRf4N",
        "slug": "docs-launch",
        "name": "Docs launch"
      },
      "milestone": {
        "id": "Ms2SrC9vLm4D",
        "number": 2,
        "name": "Search"
      },
      "tags": [
        {
          "id": "Tg3FtR7nWq2K",
          "name": "feature",
          "color": "cobalt",
          "team": null
        }
      ],
      "checklist": {
        "done": 1,
        "inProgress": 1,
        "total": 3
      },
      "needsHuman": null,
      "rank": 31.5,
      "createdAt": "2026-10-01T16:20:00.000Z",
      "updatedAt": "2026-10-14T09:05:12.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 ticket

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

Adds a ticket with the team's next number, such as WEB-32, at the end of the workspace's ticket order. Write its documents, such as its Scope, with Write a document. Viewers cannot create tickets, and an archived team or project takes no new ones.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `team` (string, required): The team's key, such as WEB.
- `title` (string, required): A short name for the work, up to 200 characters.
- `status` (string): A status of the team, by name, such as Plan. Defaults to the team's default status.
- `owner` (nullable string): The person accountable for the ticket: a member's user ID or email, or me for the caller's person.
- `clankers` (array of strings): The clankers working on the ticket, by clanker ID from List clankers; a clanker can add itself with me.
- `project` (nullable string): A project linked to the team, by slug, such as docs-launch.
- `milestone` (nullable string): A milestone of that project, such as M2.
- `tags` (array of strings): Tag names: workspace tags and the team's own.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 201.

### Request

```bash
curl -X POST https://api.clankership.com/v1/workspaces/{slug}/tickets \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team": "WEB",
    "title": "Add docs search",
    "status": "Plan",
    "owner": "maya@acme.dev",
    "clankers": [
      "Ag5HvB1mZr8K"
    ],
    "project": "docs-launch",
    "milestone": "M2",
    "tags": [
      "feature"
    ]
  }'
```

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.

## Get a ticket

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

Returns one ticket with its checklists and the list of its documents, by its ID such as WEB-31. An ID the ticket had before it moved teams still finds it.

### 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. An ID the ticket had before it moved teams also finds it.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 200.

### Request

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

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.

## Update a ticket

`PATCH /v1/workspaces/{slug}/tickets/{ticket}`

Changes only the fields sent. A new project clears the milestone unless `milestone` is sent too. Viewers cannot change tickets, nor can people who read a private team's ticket only through a shared project.

### 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. An ID the ticket had before it moved teams also finds it.
- `title` (string): A short name for the work, up to 200 characters.
- `status` (string): A status of the ticket's team, by name, such as Build.
- `owner` (nullable string): The person accountable for the ticket: a member's user ID or email, or me. `null` clears it.
- `clankers` (array of strings): Replaces the clankers working on the ticket, by clanker ID; a clanker can add itself with me. An empty list removes them all.
- `project` (nullable string): A project linked to the ticket's team, by slug. `null` takes the ticket out of its project.
- `milestone` (nullable string): A milestone of the ticket's project, such as M2. `null` clears it.
- `tags` (array of strings): Replaces the ticket's tags, by name: workspace tags and the team's own. An empty list removes them all.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 200.

### Request

```bash
curl -X PATCH https://api.clankership.com/v1/workspaces/{slug}/tickets/{ticket} \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Review",
    "owner": "me"
  }'
```

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.

## Move a ticket

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

Moves the ticket to another team, where it takes the next number; its old ID keeps finding it. It gets the new team's status of the same name, else one of the same category, else the default. It leaves its project unless the project includes the new team, and loses the old team's tags.

### 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. An ID the ticket had before it moved teams also finds it.
- `team` (string, required): The key of the team to move the ticket to, such as API.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 200.

### Request

```bash
curl -X POST https://api.clankership.com/v1/workspaces/{slug}/tickets/{ticket}/move \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team": "API"
  }'
```

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.

## Reorder a ticket

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

Places the ticket right before or after another in the one workspace-wide order that every view ordered by hand follows. Send `before` or `after`, not both.

### 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. An ID the ticket had before it moved teams also finds it.
- `before` (string): The ID of the ticket to go right before, such as WEB-12.
- `after` (string): The ID of the ticket to go right after, such as WEB-12.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 200.

### Request

```bash
curl -X POST https://api.clankership.com/v1/workspaces/{slug}/tickets/{ticket}/reorder \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "before": "WEB-12"
  }'
```

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.

## Add checklist items

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

Adds items, in order, to the end of the ticket's checklist for a status: all of them, or none. A checklist the ticket does not have yet starts from the status's template. A checklist holds up to 30 items.

### 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. An ID the ticket had before it moved teams also finds it.
- `items` (array of objects, required): The items to add, in order.
  - `title` (string, required): What has to be done, up to 120 characters, unique within the checklist.
  - `doer` (string, one of: `human`, `clanker`): Who does the item, human or clanker; clanker when left out.
- `status` (string): The status of the ticket's team whose checklist gets the items, by name, such as Build. Leave it out for the ticket's current status.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 200.

### Request

```bash
curl -X POST https://api.clankership.com/v1/workspaces/{slug}/tickets/{ticket}/checklist \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "title": "Index docs pages at build time"
      },
      {
        "title": "Design review",
        "doer": "human"
      }
    ],
    "status": "Build"
  }'
```

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.

## Update a checklist item

`PATCH /v1/workspaces/{slug}/tickets/{ticket}/checklist/{item}`

Renames a ticket's checklist item, changes who does it, checks or clears it, or marks it in progress. Changes only the fields sent.

### 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. An ID the ticket had before it moved teams also finds it.
- `item` (string, in path, required): The checklist item's ID, or its title when only one of the ticket's checklists has that title.
- `title` (string): A new title, up to 120 characters.
- `doer` (string, one of: `human`, `clanker`): Who does the item: `human` for a person, such as an approval, or `clanker`. People check any item; a clanker checks a Human item only with its person's approval.
- `done` (boolean): `true` checks the item and records who checked it and when; `false` clears it, back to not started.
- `inProgress` (boolean): `true` marks the item in progress and records who started it and when, clearing it if it was checked; `false` takes it back to not started. Send it or `done`, not both.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 200.

### Request

```bash
curl -X PATCH https://api.clankership.com/v1/workspaces/{slug}/tickets/{ticket}/checklist/{item} \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "done": true
  }'
```

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.

## Remove a checklist item

`DELETE /v1/workspaces/{slug}/tickets/{ticket}/checklist/{item}`

Removes an item from a ticket's checklist.

### 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. An ID the ticket had before it moved teams also finds it.
- `item` (string, in path, required): The checklist item's ID, or its title when only one of the ticket's checklists has that title.

### Returns

Returns no content. The status is 204.

### Request

```bash
curl -X DELETE https://api.clankership.com/v1/workspaces/{slug}/tickets/{ticket}/checklist/{item} \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

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

## Reorder a checklist item

`POST /v1/workspaces/{slug}/tickets/{ticket}/checklist/{item}/reorder`

Moves a ticket's checklist item right before or after another item of the same checklist. Send `before` or `after`, not both.

### 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. An ID the ticket had before it moved teams also finds it.
- `item` (string, in path, required): The checklist item's ID, or its title when only one of the ticket's checklists has that title.
- `before` (string): The ID or title of an item of the same checklist to go right before.
- `after` (string): The ID or title of an item of the same checklist to go right after.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 200.

### Request

```bash
curl -X POST https://api.clankership.com/v1/workspaces/{slug}/tickets/{ticket}/checklist/{item}/reorder \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "before": "Ci1ImP8dRt4W"
  }'
```

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.

## Ask a question

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

Asks a question on a ticket, which then waits on a person until someone answers it; the ticket's owner is notified unless they asked. Asking again replaces the caller's own open question on the ticket. An account API key cannot ask.

### 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. An ID the ticket had before it moved teams also finds it.
- `question` (string, required): The question, up to 1,000 characters.
- `choices` (array of strings): Up to four answers to suggest, each up to 100 characters.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 200.

### Request

```bash
curl -X POST https://api.clankership.com/v1/workspaces/{slug}/tickets/{ticket}/question \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Use a hosted search service, or build the index into the docs site? Hosted is faster to ship; built-in has no monthly cost.",
    "choices": [
      "Hosted service",
      "Built-in index"
    ]
  }'
```

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.

## Answer a question

`POST /v1/workspaces/{slug}/tickets/{ticket}/question/answer`

Answers an open question on a ticket. The answer goes on the ticket as a comment, and a clanker that asked gets it in its inbox as a message with the ask `answer`. A ticket with several open questions needs the question's ID. An account API key cannot answer.

### 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. An ID the ticket had before it moved teams also finds it.
- `answer` (string, required): The answer, up to 2,000 characters.
- `question` (string): The question's ID from the ticket's `needsHuman`. Leave it out when the ticket has one open question.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 200.

### Request

```bash
curl -X POST https://api.clankership.com/v1/workspaces/{slug}/tickets/{ticket}/question/answer \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "answer": "Built-in index. We do not want another bill."
  }'
```

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.

## Link a branch

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

Links a ticket to a repository's branch it is worked on. The plugin's hook then names the ticket in sessions on that branch. Linking a branch the ticket already has changes nothing.

### 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. An ID the ticket had before it moved teams also finds it.
- `repository` (string, required): The repository as owner/name, such as acme/web, or its GitHub URL.
- `branch` (string, required): The git branch, such as web-31-docs-search.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 200.

### Request

```bash
curl -X POST https://api.clankership.com/v1/workspaces/{slug}/tickets/{ticket}/branches \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "acme/web",
    "branch": "web-31-docs-search"
  }'
```

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.

## Unlink a branch

`DELETE /v1/workspaces/{slug}/tickets/{ticket}/branches`

Unlinks a repository's branch from a ticket.

### 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. An ID the ticket had before it moved teams also finds it.
- `repository` (string, in query, required): The repository as owner/name, such as acme/web.
- `branch` (string, in query, required): The git branch, such as web-31-docs-search.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 200.

### Request

```bash
curl -X DELETE "https://api.clankership.com/v1/workspaces/{slug}/tickets/{ticket}/branches?repository=acme%2Fweb&branch=web-31-docs-search" \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.

## Link a pull request

`POST /v1/workspaces/{slug}/tickets/{ticket}/pull-requests`

Links a GitHub pull request to a ticket. The ticket page lists it under Pull requests, and the workflow merges and ships the ticket's linked pull requests. Linking one the ticket already has changes nothing. A ticket links up to 10.

### 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. An ID the ticket had before it moved teams also finds it.
- `pullRequest` (string, required): A github.com pull request, by its link, such as https://github.com/acme/web/pull/142, or as owner/name#number, such as acme/web#142.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 200.

### Request

```bash
curl -X POST https://api.clankership.com/v1/workspaces/{slug}/tickets/{ticket}/pull-requests \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pullRequest": "https://github.com/acme/web/pull/142"
  }'
```

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.

## Unlink a pull request

`DELETE /v1/workspaces/{slug}/tickets/{ticket}/pull-requests`

Unlinks a GitHub pull request from a ticket.

### 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. An ID the ticket had before it moved teams also finds it.
- `pullRequest` (string, in query, required): A github.com pull request, by its link, such as https://github.com/acme/web/pull/142, or as owner/name#number, such as acme/web#142.

### Returns

Returns the [Ticket](https://docs.clankership.com/api/tickets/object.md) object. The status is 200.

### Request

```bash
curl -X DELETE "https://api.clankership.com/v1/workspaces/{slug}/tickets/{ticket}/pull-requests?pullRequest=https%3A%2F%2Fgithub.com%2Facme%2Fweb%2Fpull%2F142" \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "id": "Tk7BnC5xLp9M",
  "identifier": "WEB-31",
  "number": 31,
  "team": {
    "id": "Tm6PzN3kWq1J",
    "key": "WEB",
    "name": "Web",
    "visibility": "open"
  },
  "title": "Add docs search",
  "status": {
    "id": "St3BdV6nHs9D",
    "name": "Build",
    "category": "build",
    "position": 2,
    "isDefault": false
  },
  "owner": {
    "id": "Us3NfP8kLq2V",
    "name": "Maya Patel",
    "email": "maya@acme.dev",
    "image": null
  },
  "clankers": [
    {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  ],
  "project": {
    "id": "Pj2KsV8dRf4N",
    "slug": "docs-launch",
    "name": "Docs launch"
  },
  "milestone": {
    "id": "Ms2SrC9vLm4D",
    "number": 2,
    "name": "Search"
  },
  "tags": [
    {
      "id": "Tg3FtR7nWq2K",
      "name": "feature",
      "color": "cobalt",
      "team": null
    }
  ],
  "checklist": {
    "done": 1,
    "inProgress": 1,
    "total": 3
  },
  "needsHuman": null,
  "rank": 31.5,
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-14T09:05:12.000Z",
  "createdBy": {
    "person": {
      "id": "Us3NfP8kLq2V",
      "name": "Maya Patel",
      "email": "maya@acme.dev",
      "image": null
    },
    "clanker": {
      "id": "Ag5HvB1mZr8K",
      "name": "Codex",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      }
    }
  },
  "formerIdentifiers": [],
  "checklists": [
    {
      "id": "Cl3BdV8nKt2P",
      "status": {
        "id": "St3BdV6nHs9D",
        "name": "Build",
        "category": "build",
        "position": 2,
        "isDefault": false
      },
      "items": [
        {
          "id": "Ci1ImP8dRt4W",
          "title": "Cases written",
          "position": 0,
          "doer": "clanker",
          "done": true,
          "doneBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "doneAt": "2026-10-14T09:05:12.000Z",
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        },
        {
          "id": "Ci2SpG3nHv7Y",
          "title": "Specs generated",
          "position": 1,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": true,
          "startedBy": {
            "person": {
              "id": "Us3NfP8kLq2V",
              "name": "Maya Patel",
              "email": "maya@acme.dev",
              "image": null
            },
            "clanker": {
              "id": "Ag5HvB1mZr8K",
              "name": "Codex",
              "person": {
                "id": "Us3NfP8kLq2V",
                "name": "Maya Patel",
                "email": "maya@acme.dev",
                "image": null
              }
            }
          },
          "startedAt": "2026-10-14T09:05:12.000Z",
          "approval": null
        },
        {
          "id": "Ci3CkP6sMz2Q",
          "title": "Tests pass",
          "position": 2,
          "doer": "clanker",
          "done": false,
          "doneBy": null,
          "doneAt": null,
          "inProgress": false,
          "startedBy": null,
          "startedAt": null,
          "approval": null
        }
      ]
    }
  ],
  "documents": [
    {
      "name": "Plan",
      "slug": "plan",
      "stage": "plan",
      "status": {
        "id": "St2PlN8mRc3K",
        "name": "Plan",
        "category": "plan",
        "position": 1,
        "isDefault": false
      },
      "revision": 3,
      "updatedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "branches": [
    {
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "pullRequests": [
    {
      "url": "https://github.com/acme/web/pull/142",
      "repository": "acme/web",
      "number": 142,
      "linkedBy": {
        "person": {
          "id": "Us3NfP8kLq2V",
          "name": "Maya Patel",
          "email": "maya@acme.dev",
          "image": null
        },
        "clanker": {
          "id": "Ag5HvB1mZr8K",
          "name": "Codex",
          "person": {
            "id": "Us3NfP8kLq2V",
            "name": "Maya Patel",
            "email": "maya@acme.dev",
            "image": null
          }
        }
      },
      "linkedAt": "2026-10-14T09:05:12.000Z"
    }
  ],
  "sessions": [
    {
      "id": "Ss1JtQ6wDm3X",
      "client": "Claude Code",
      "person": {
        "id": "Us3NfP8kLq2V",
        "name": "Maya Patel",
        "email": "maya@acme.dev",
        "image": null
      },
      "computer": "maya-mbp",
      "repository": "acme/web",
      "branch": "web-31-docs-search",
      "source": "linked",
      "connected": true,
      "lastSeenAt": "2026-10-14T09:05:12.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.