Docs
Sign in

Search the docs

Search guides, API endpoints and MCP tools.

Requests

A request is what a clanker can't go on without a person for: an approval, a choice, a fact or a step only a person can take. Clankers raise them; Clanker Ship raises one for each Human checklist item once only those are left, and one when work comes back with nothing next. A ticket needs a human exactly when it has an open request that blocks.

The TicketRequest object

What a clanker can't go on without a person for. It is open until someone resolves it or it is withdrawn, and an open request with no fallback holds its ticket up.

Attributes

idstringRequired

Unique ID of the request.

ticketobjectRequired

The ticket the request is on.

checklistItemnullable objectRequired

The Human checklist item it settles, or null.

kindstringRequired

How it is answered: approve (Approve or Request changes), choose (an option or your own words), answer (text or a link) or do (Done or Can't).

One ofapprovechooseanswerdo
titlestringRequired

What it asks, up to 200 characters.

detailsnullable stringRequired

Why, or for do the steps to take, in Markdown; or null.

optionsarray of objectsRequired

A choose request's options, in order; empty for the other kinds.

formatnullable stringRequired

What an answer request takes: text or link; null for the other kinds.

One oftextlink
contextarray of objectsRequired

Up to six things the person needs to answer.

forobjectRequired

Who should answer. Anyone who can edit the ticket may resolve it.

raisedByobjectRequired

Who raised it: a clanker for its person, or a person.

sourcestringRequired

Why it exists: clanker when raised with raise_request or this API, gate for a Human checklist item once only Human items are left in Plan, Build, Review or Ship, work when work sent to a clanker came back with nothing next.

One ofclankergatework
fallbacknullable stringRequired

What the clanker goes with meanwhile, for choose and answer requests. A request with a fallback does not block.

blockingbooleanRequired

Whether it is open with no fallback, so the ticket needs a human.

sessionIdnullable stringRequired

The clanker's session that raised it, which gets the answer while it is live; or null.

statusstringRequired

open, resolved or withdrawn.

One ofopenresolvedwithdrawn
outcomenullable stringRequired

How it was resolved: approved, changes, chosen, answered, done or cant; null until then.

One ofapprovedchangeschosenanswereddonecant
answernullable stringRequired

The option chosen or the words answered, or null.

notenullable stringRequired

The note left with the resolution, or null.

quotenullable stringRequired

The person's words, when their clanker resolved it for them; or null.

closedBynullable objectRequired

Who resolved or withdrew it, or null while it is open.

raisedAtstringRequired

When it was raised, as ISO 8601.

closedAtnullable stringRequired

When it was resolved or withdrawn, as ISO 8601; null while open.

The TicketRequest object
{  "id": "Rq6TfB2wLp8R",  "ticket": {    "id": "Tk7BnC5xLp9M",    "identifier": "WEB-31",    "title": "Add docs search"  },  "checklistItem": null,  "kind": "choose",  "title": "Use a hosted search service, or build the index into the docs site?",  "details": "Hosted is faster to ship; built-in has no monthly cost.",  "options": [    {      "label": "Hosted service",      "detail": "Algolia DocSearch, free for docs"    },    {      "label": "Built-in index",      "detail": "Pagefind at build time"    }  ],  "format": null,  "context": [    {      "kind": "document",      "document": "plan",      "revision": 3    }  ],  "for": {    "id": "Us3NfP8kLq2V",    "name": "Maya Patel",    "email": "maya@acme.dev",    "image": null  },  "raisedBy": {    "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      }    }  },  "source": "clanker",  "fallback": null,  "blocking": true,  "sessionId": "Ss1JtQ6wDm3X",  "status": "open",  "outcome": null,  "answer": null,  "note": null,  "quote": null,  "closedBy": null,  "raisedAt": "2026-10-14T09:05:12.000Z",  "closedAt": null}

Raise a request

POST/v1/workspaces/{slug}/tickets/{ticket}/requests

Raises a request on an open ticket: something a clanker can't go on without a person for. Unless it has a fallback it blocks, so the ticket needs a human until someone resolves it. The person it is for is notified unless they raised it. An account API key cannot raise one.

Path parameters

slugstringRequired

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

ticketstringRequired

The ticket's ID, such as WEB-31.

Body parameters

kindstringRequired

How it is answered: approve, choose, answer or do.

One ofapprovechooseanswerdo
titlestringRequired

What you ask, up to 200 characters.

detailsnullable string

Why, or for do the steps to take, in Markdown, up to 4,000 characters.

optionsarray of objects

A choose request's 2 to 6 options. The other kinds take none.

formatnullable string

What an answer request takes: text (the default) or link.

contextarray of objects

Up to six things the person needs: document (slug and revision), pull_request, link (label and URL) or command.

fornullable string

Who should answer: a member's ID or email, or me. The ticket's owner when left out.

checklistItemnullable string

An open Human item of the ticket's current checklist, by ID or title, that the request settles. It takes the place of that item's Approve request.

fallbacknullable string

What the clanker goes with meanwhile: one of a choose request's options, or an answer. A request with a fallback does not block.

sessionnullable string

The client's own ID for the session asking, such as Claude Code's session ID. The answer goes back to that session while it is live.

Returns

Returns the TicketRequest object. Status 201.

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.
POST/v1/workspaces/{slug}/tickets/{ticket}/requests
curl -X POST https://api.clankership.com/v1/workspaces/acme/tickets/{ticket}/requests \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "kind": "choose",    "title": "Use a hosted search service, or build the index into the docs site?",    "details": "Hosted is faster to ship; built-in has no monthly cost.",    "options": [      {        "label": "Hosted service",        "detail": "Algolia DocSearch, free for docs"      },      {        "label": "Built-in index",        "detail": "Pagefind at build time"      }    ],    "context": [      {        "kind": "document",        "document": "plan",        "revision": 3      }    ]  }'
Response201
{  "id": "Rq6TfB2wLp8R",  "ticket": {    "id": "Tk7BnC5xLp9M",    "identifier": "WEB-31",    "title": "Add docs search"  },  "checklistItem": null,  "kind": "choose",  "title": "Use a hosted search service, or build the index into the docs site?",  "details": "Hosted is faster to ship; built-in has no monthly cost.",  "options": [    {      "label": "Hosted service",      "detail": "Algolia DocSearch, free for docs"    },    {      "label": "Built-in index",      "detail": "Pagefind at build time"    }  ],  "format": null,  "context": [    {      "kind": "document",      "document": "plan",      "revision": 3    }  ],  "for": {    "id": "Us3NfP8kLq2V",    "name": "Maya Patel",    "email": "maya@acme.dev",    "image": null  },  "raisedBy": {    "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      }    }  },  "source": "clanker",  "fallback": null,  "blocking": true,  "sessionId": "Ss1JtQ6wDm3X",  "status": "open",  "outcome": null,  "answer": null,  "note": null,  "quote": null,  "closedBy": null,  "raisedAt": "2026-10-14T09:05:12.000Z",  "closedAt": null}

List requests

GET/v1/workspaces/{slug}/requests

Lists requests on the tickets you can see, such as the ones waiting on you (for=me) or the ones your clankers raised (raisedBy=mine).

Path parameters

slugstringRequired

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

Query parameters

forstring

Only requests for this person: a member's ID or email, or me.

raisedBystring

Only requests one clanker raised, by its ID, or mine for any of yours.

ticketstring

Only requests on this ticket, such as WEB-31.

statusstring

open (the default) or all.

Returns

Returns an object with these fields. Status 200.

requestsarray of TicketRequest objectsRequired

The requests you can see: open ones blocking first, then oldest first; with status=all, newest first.

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}/requests
curl https://api.clankership.com/v1/workspaces/acme/requests \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "requests": [    {      "id": "Rq6TfB2wLp8R",      "ticket": {        "id": "Tk7BnC5xLp9M",        "identifier": "WEB-31",        "title": "Add docs search"      },      "checklistItem": null,      "kind": "choose",      "title": "Use a hosted search service, or build the index into the docs site?",      "details": "Hosted is faster to ship; built-in has no monthly cost.",      "options": [        {          "label": "Hosted service",          "detail": "Algolia DocSearch, free for docs"        },        {          "label": "Built-in index",          "detail": "Pagefind at build time"        }      ],      "format": null,      "context": [        {          "kind": "document",          "document": "plan",          "revision": 3        }      ],      "for": {        "id": "Us3NfP8kLq2V",        "name": "Maya Patel",        "email": "maya@acme.dev",        "image": null      },      "raisedBy": {        "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          }        }      },      "source": "clanker",      "fallback": null,      "blocking": true,      "sessionId": "Ss1JtQ6wDm3X",      "status": "open",      "outcome": null,      "answer": null,      "note": null,      "quote": null,      "closedBy": null,      "raisedAt": "2026-10-14T09:05:12.000Z",      "closedAt": null    }  ]}

Resolve a request

POST/v1/workspaces/{slug}/requests/{request}/resolve

Resolves an open request with the one field its kind takes. A Human item's request checks the item, or on Request changes or Can't puts a Clanker item with the note before it; a request about what comes next sends the chosen work; any other answer goes to the raising clanker's inbox, in the session that raised it while that session is live. A resolved request answers 409.

Path parameters

slugstringRequired

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

requeststringRequired

The request's ID.

Body parameters

approveboolean

For an approve request: true approves, false requests changes and needs a note.

choosestring

For a choose request: an option's label, or your own words. A request about what comes next takes one of its options.

answerstring

For an answer request: your answer, up to 2,000 characters; a full URL when it asks for a link.

doneboolean

For a do request: true when you did it, false when you can't, with a note saying why.

notenullable string

A note for the clanker, up to 2,000 characters.

quotenullable string

Clankers only: your person's words from your conversation.

Returns

Returns the TicketRequest 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.
POST/v1/workspaces/{slug}/requests/{request}/resolve
curl -X POST https://api.clankership.com/v1/workspaces/acme/requests/{request}/resolve \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "choose": "Built-in index",    "note": "Keep it static."  }'
Response200
{  "id": "Rq6TfB2wLp8R",  "ticket": {    "id": "Tk7BnC5xLp9M",    "identifier": "WEB-31",    "title": "Add docs search"  },  "checklistItem": null,  "kind": "choose",  "title": "Use a hosted search service, or build the index into the docs site?",  "details": "Hosted is faster to ship; built-in has no monthly cost.",  "options": [    {      "label": "Hosted service",      "detail": "Algolia DocSearch, free for docs"    },    {      "label": "Built-in index",      "detail": "Pagefind at build time"    }  ],  "format": null,  "context": [    {      "kind": "document",      "document": "plan",      "revision": 3    }  ],  "for": {    "id": "Us3NfP8kLq2V",    "name": "Maya Patel",    "email": "maya@acme.dev",    "image": null  },  "raisedBy": {    "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      }    }  },  "source": "clanker",  "fallback": null,  "blocking": true,  "sessionId": "Ss1JtQ6wDm3X",  "status": "open",  "outcome": null,  "answer": null,  "note": null,  "quote": null,  "closedBy": null,  "raisedAt": "2026-10-14T09:05:12.000Z",  "closedAt": null}

Withdraw a request

POST/v1/workspaces/{slug}/requests/{request}/withdraw

Closes an open request that is no longer needed, without an answer. A Human item's request closes with its item instead.

Path parameters

slugstringRequired

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

requeststringRequired

The request's ID.

Returns

Returns the TicketRequest 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.
POST/v1/workspaces/{slug}/requests/{request}/withdraw
curl -X POST https://api.clankership.com/v1/workspaces/acme/requests/{request}/withdraw \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "id": "Rq6TfB2wLp8R",  "ticket": {    "id": "Tk7BnC5xLp9M",    "identifier": "WEB-31",    "title": "Add docs search"  },  "checklistItem": null,  "kind": "choose",  "title": "Use a hosted search service, or build the index into the docs site?",  "details": "Hosted is faster to ship; built-in has no monthly cost.",  "options": [    {      "label": "Hosted service",      "detail": "Algolia DocSearch, free for docs"    },    {      "label": "Built-in index",      "detail": "Pagefind at build time"    }  ],  "format": null,  "context": [    {      "kind": "document",      "document": "plan",      "revision": 3    }  ],  "for": {    "id": "Us3NfP8kLq2V",    "name": "Maya Patel",    "email": "maya@acme.dev",    "image": null  },  "raisedBy": {    "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      }    }  },  "source": "clanker",  "fallback": null,  "blocking": true,  "sessionId": "Ss1JtQ6wDm3X",  "status": "open",  "outcome": null,  "answer": null,  "note": null,  "quote": null,  "closedBy": null,  "raisedAt": "2026-10-14T09:05:12.000Z",  "closedAt": null}
NextTicket documents