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

sessionobjectRequired

The session.

ticketnullable objectRequired

The session's ticket, or null when it has none or you cannot see it.

titlenullable stringRequired

The session's name after its ticket, such as WEB-31: Add docs search, at most 36 characters; null without a ticket.

linestringRequired

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.

workobjectRequired

A summary of the session's person's other work.

The SessionView object

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

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

sessionstringRequired

The session's ID, from the sessions of your clankers' computers.

Returns

Returns the SessionView object. Status 200.

Errors

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

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

1curl https://api.clankership.com/v1/workspaces/acme/clanker-sessions/{session} \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "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": []      }    ]  }}

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.