# Clanker sessions

A clanker session is one conversation in a clanker's app, such as a Claude Code session, on one of its computers. Each session works on one ticket: the one its person picked, else the one its clanker created or linked in it, else the one its branch is linked to, else the one its branch's name carries.

## The SessionView object

What Clanker Ship shows for a session: its ticket, where the ticket came from, the session's name and ticket line, and the person's other work. The Claude Code plugin draws its band and pane from it.

### Attributes

- `session` (object, required): The session.
  - `id` (string, required): Unique ID of the session.
  - `key` (string, required): The client's own ID for the session, such as a Claude Code session ID.
  - `client` (string, required): The clanker client, such as Claude Code.
  - `computer` (string, required): The computer it runs on.
  - `repository` (nullable string, required): The repository the session works in, as owner/name, or null.
  - `branch` (nullable string, required): The branch checked out in the session, or null.
  - `connected` (boolean, required): Whether the session holds a connection to Clanker Ship.
  - `live` (boolean, required): Whether the session is connected, or reported in the last minute.
- `ticket` (nullable object, required): The session's ticket, or null when it has none or you cannot see it.
  - `id` (string, required): Unique ID of the ticket.
  - `identifier` (string, required): The ticket's ID, such as WEB-31.
  - `title` (string, required): The ticket's title.
  - `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.
  - `url` (string, required): The ticket's page on the website.
  - `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.
  - `checklist` (object, required): The ticket's checklist items for its current stage, counted.
    - `done` (number, required): How many of the items are done.
    - `inProgress` (number, required): How many of the items are in progress: started and not done.
    - `total` (number, required): How many items there are.
  - `next` (nullable string, required): The first open Clanker item on the current status's checklist, or null.
  - `items` (array of objects, required): The checklist for the ticket's current status, in order.
    - `id` (string, required): Unique ID of the checklist item.
    - `title` (string, required): What the item asks for.
    - `doer` (string, one of: `human`, `clanker`, required): Who does it: a `human`, or the `clanker`.
    - `done` (boolean, required): Whether it is checked.
    - `inProgress` (boolean, required): Whether someone is working it: started, and not done yet.
  - `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.
  - `documents` (array of objects, required): The ticket's documents, in workflow order.
    - `name` (string, required): The document's name, such as Plan.
    - `slug` (string, required): The name in URLs and commands, such as plan.
    - `written` (boolean, required): Whether anyone has written it.
- `title` (nullable string, required): The session's name after its ticket, such as WEB-31: Add docs search, at most 36 characters; null without a ticket.
- `line` (string, required): The ticket line, at most 80 characters: the ticket, its stage and progress, and its next step or what it waits on you for, then how many of your other tickets need you. Without a ticket, the No ticket line.
- `work` (object, required): A summary of the session's person's other work.
  - `needsYou` (number, required): How many of your other open tickets wait on you.
  - `url` (string, required): Your My clankers page on the website, which the Claude Code band links its raised hand to.
  - `tickets` (array of objects, required): Your open tickets: those that wait on you first, then the session's, then the rest by stage.
    - `id` (string, required): Unique ID of the ticket.
    - `identifier` (string, required): The ticket's ID, such as WEB-28.
    - `title` (string, required): The ticket's title.
    - `url` (string, required): The ticket's page on the website.
    - `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.
    - `checklist` (object, required): The ticket's checklist items for its current stage, counted.
      - `done` (number, required): How many of the items are done.
      - `inProgress` (number, required): How many of the items are in progress: started and not done.
      - `total` (number, required): How many items there are.
    - `needsYou` (nullable string, required): What the ticket waits on the session's person for, such as Review approved, or null when it does not.
    - `here` (boolean, required): Whether it is this session's ticket.
    - `sessions` (array of objects, required): The other live sessions working on it.
      - `client` (string, required): The clanker client, such as Codex.
      - `computer` (string, required): The computer it runs on.

### Example

```json
{
  "session": {
    "id": "Ss1JtQ6wDm3X",
    "key": "0199f3a2-7c41-7d2e-9b1a-5e8c4d2f6a10",
    "client": "Claude Code",
    "computer": "maya-mbp",
    "repository": "acme/storefront",
    "branch": "web-31-docs-search",
    "connected": true,
    "live": true
  },
  "ticket": {
    "id": "Tk7BnC5xLp9M",
    "identifier": "WEB-31",
    "title": "Add docs search",
    "source": "linked",
    "url": "https://clankership.com/w/acme/tickets/WEB-31",
    "status": {
      "id": "St3BdV6nHs9D",
      "name": "Build",
      "category": "build",
      "position": 2,
      "isDefault": false
    },
    "checklist": {
      "done": 1,
      "inProgress": 1,
      "total": 3
    },
    "next": "Highlight matching headings",
    "items": [
      {
        "id": "Ci4FqW8rLm2N",
        "title": "Search box in the header",
        "doer": "clanker",
        "done": true,
        "inProgress": false
      },
      {
        "id": "Ci7HtX3vPn5R",
        "title": "Highlight matching headings",
        "doer": "clanker",
        "done": false,
        "inProgress": true
      },
      {
        "id": "Ci2KdY6wQs9T",
        "title": "Search result copy approved",
        "doer": "human",
        "done": false,
        "inProgress": false
      }
    ],
    "needsHuman": null,
    "documents": [
      {
        "name": "Plan",
        "slug": "plan",
        "written": true
      },
      {
        "name": "Build record",
        "slug": "build-record",
        "written": true
      }
    ]
  },
  "title": "WEB-31: Add docs search",
  "line": "◆ WEB-31 Add docs search · Build 1/3 · next: Highlight matching headings · 1 more needs you",
  "work": {
    "needsYou": 1,
    "url": "https://clankership.com/w/acme/clankers",
    "tickets": [
      {
        "id": "Tk3RmD8sVq1W",
        "identifier": "WEB-28",
        "title": "Fix login redirect",
        "url": "https://clankership.com/w/acme/tickets/WEB-28",
        "status": {
          "id": "St3BdV6nHs9D",
          "name": "Build",
          "category": "build",
          "position": 2,
          "isDefault": false
        },
        "checklist": {
          "done": 4,
          "inProgress": 0,
          "total": 5
        },
        "needsYou": "Review approved",
        "here": false,
        "sessions": [
          {
            "client": "Codex",
            "computer": "maya-mbp"
          }
        ]
      },
      {
        "id": "Tk7BnC5xLp9M",
        "identifier": "WEB-31",
        "title": "Add docs search",
        "url": "https://clankership.com/w/acme/tickets/WEB-31",
        "status": {
          "id": "St3BdV6nHs9D",
          "name": "Build",
          "category": "build",
          "position": 2,
          "isDefault": false
        },
        "checklist": {
          "done": 1,
          "inProgress": 1,
          "total": 3
        },
        "needsYou": null,
        "here": true,
        "sessions": []
      }
    ]
  }
}
```

## Get a session

`GET /v1/workspaces/{slug}/clanker-sessions/{session}`

Returns one of your clankers' sessions as Clanker Ship shows it: its ticket and where the ticket came from, its name and ticket line, and your other open tickets. A session of another member's clanker fails with Forbidden.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `session` (string, in path, required): The session's ID, from the sessions of your clankers' computers.

### Returns

Returns the [SessionView](https://docs.clankership.com/api/clanker-sessions/object.md) object. The status is 200.

### Request

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

### Response

```json
{
  "session": {
    "id": "Ss1JtQ6wDm3X",
    "key": "0199f3a2-7c41-7d2e-9b1a-5e8c4d2f6a10",
    "client": "Claude Code",
    "computer": "maya-mbp",
    "repository": "acme/storefront",
    "branch": "web-31-docs-search",
    "connected": true,
    "live": true
  },
  "ticket": {
    "id": "Tk7BnC5xLp9M",
    "identifier": "WEB-31",
    "title": "Add docs search",
    "source": "linked",
    "url": "https://clankership.com/w/acme/tickets/WEB-31",
    "status": {
      "id": "St3BdV6nHs9D",
      "name": "Build",
      "category": "build",
      "position": 2,
      "isDefault": false
    },
    "checklist": {
      "done": 1,
      "inProgress": 1,
      "total": 3
    },
    "next": "Highlight matching headings",
    "items": [
      {
        "id": "Ci4FqW8rLm2N",
        "title": "Search box in the header",
        "doer": "clanker",
        "done": true,
        "inProgress": false
      },
      {
        "id": "Ci7HtX3vPn5R",
        "title": "Highlight matching headings",
        "doer": "clanker",
        "done": false,
        "inProgress": true
      },
      {
        "id": "Ci2KdY6wQs9T",
        "title": "Search result copy approved",
        "doer": "human",
        "done": false,
        "inProgress": false
      }
    ],
    "needsHuman": null,
    "documents": [
      {
        "name": "Plan",
        "slug": "plan",
        "written": true
      },
      {
        "name": "Build record",
        "slug": "build-record",
        "written": true
      }
    ]
  },
  "title": "WEB-31: Add docs search",
  "line": "◆ WEB-31 Add docs search · Build 1/3 · next: Highlight matching headings · 1 more needs you",
  "work": {
    "needsYou": 1,
    "url": "https://clankership.com/w/acme/clankers",
    "tickets": [
      {
        "id": "Tk3RmD8sVq1W",
        "identifier": "WEB-28",
        "title": "Fix login redirect",
        "url": "https://clankership.com/w/acme/tickets/WEB-28",
        "status": {
          "id": "St3BdV6nHs9D",
          "name": "Build",
          "category": "build",
          "position": 2,
          "isDefault": false
        },
        "checklist": {
          "done": 4,
          "inProgress": 0,
          "total": 5
        },
        "needsYou": "Review approved",
        "here": false,
        "sessions": [
          {
            "client": "Codex",
            "computer": "maya-mbp"
          }
        ]
      },
      {
        "id": "Tk7BnC5xLp9M",
        "identifier": "WEB-31",
        "title": "Add docs search",
        "url": "https://clankership.com/w/acme/tickets/WEB-31",
        "status": {
          "id": "St3BdV6nHs9D",
          "name": "Build",
          "category": "build",
          "position": 2,
          "isDefault": false
        },
        "checklist": {
          "done": 1,
          "inProgress": 1,
          "total": 3
        },
        "needsYou": null,
        "here": true,
        "sessions": []
      }
    ]
  }
}
```

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

## Pick a session's ticket

`PUT /v1/workspaces/{slug}/clanker-sessions/{session}`

Makes the ticket the session's picked ticket. A pick wins over the ticket the session's clanker linked and the branch's ticket until you pick again, and the session's next prompt renames it after the ticket. A ticket you cannot see fails with NotFound; a session of another member's clanker fails with Forbidden.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `session` (string, in path, required): The session's ID, from the sessions of your clankers' computers.
- `ticket` (string, required): The ticket the session works on, by its ID, such as WEB-31.

### Returns

Returns the [SessionView](https://docs.clankership.com/api/clanker-sessions/object.md) object. The status is 200.

### Request

```bash
curl -X PUT https://api.clankership.com/v1/workspaces/{slug}/clanker-sessions/{session} \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ticket": "WEB-31"
  }'
```

### Response

```json
{
  "session": {
    "id": "Ss1JtQ6wDm3X",
    "key": "0199f3a2-7c41-7d2e-9b1a-5e8c4d2f6a10",
    "client": "Claude Code",
    "computer": "maya-mbp",
    "repository": "acme/storefront",
    "branch": "web-31-docs-search",
    "connected": true,
    "live": true
  },
  "ticket": {
    "id": "Tk7BnC5xLp9M",
    "identifier": "WEB-31",
    "title": "Add docs search",
    "source": "linked",
    "url": "https://clankership.com/w/acme/tickets/WEB-31",
    "status": {
      "id": "St3BdV6nHs9D",
      "name": "Build",
      "category": "build",
      "position": 2,
      "isDefault": false
    },
    "checklist": {
      "done": 1,
      "inProgress": 1,
      "total": 3
    },
    "next": "Highlight matching headings",
    "items": [
      {
        "id": "Ci4FqW8rLm2N",
        "title": "Search box in the header",
        "doer": "clanker",
        "done": true,
        "inProgress": false
      },
      {
        "id": "Ci7HtX3vPn5R",
        "title": "Highlight matching headings",
        "doer": "clanker",
        "done": false,
        "inProgress": true
      },
      {
        "id": "Ci2KdY6wQs9T",
        "title": "Search result copy approved",
        "doer": "human",
        "done": false,
        "inProgress": false
      }
    ],
    "needsHuman": null,
    "documents": [
      {
        "name": "Plan",
        "slug": "plan",
        "written": true
      },
      {
        "name": "Build record",
        "slug": "build-record",
        "written": true
      }
    ]
  },
  "title": "WEB-31: Add docs search",
  "line": "◆ WEB-31 Add docs search · Build 1/3 · next: Highlight matching headings · 1 more needs you",
  "work": {
    "needsYou": 1,
    "url": "https://clankership.com/w/acme/clankers",
    "tickets": [
      {
        "id": "Tk3RmD8sVq1W",
        "identifier": "WEB-28",
        "title": "Fix login redirect",
        "url": "https://clankership.com/w/acme/tickets/WEB-28",
        "status": {
          "id": "St3BdV6nHs9D",
          "name": "Build",
          "category": "build",
          "position": 2,
          "isDefault": false
        },
        "checklist": {
          "done": 4,
          "inProgress": 0,
          "total": 5
        },
        "needsYou": "Review approved",
        "here": false,
        "sessions": [
          {
            "client": "Codex",
            "computer": "maya-mbp"
          }
        ]
      },
      {
        "id": "Tk7BnC5xLp9M",
        "identifier": "WEB-31",
        "title": "Add docs search",
        "url": "https://clankership.com/w/acme/tickets/WEB-31",
        "status": {
          "id": "St3BdV6nHs9D",
          "name": "Build",
          "category": "build",
          "position": 2,
          "isDefault": false
        },
        "checklist": {
          "done": 1,
          "inProgress": 1,
          "total": 3
        },
        "needsYou": null,
        "here": true,
        "sessions": []
      }
    ]
  }
}
```

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