# 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 - `id` (string, required): Unique ID of the request. - `ticket` (object, required): The ticket the request is on. - `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. - `checklistItem` (nullable object, required): The Human checklist item it settles, or null. - `id` (string, required): Unique ID of the checklist item. - `title` (string, required): The item's title. - `kind` (string, one of: `approve`, `choose`, `answer`, `do`, required): 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). - `title` (string, required): What it asks, up to 200 characters. - `details` (nullable string, required): Why, or for `do` the steps to take, in Markdown; or null. - `options` (array of objects, required): A `choose` request's options, in order; empty for the other kinds. - `label` (string, required): The option, up to 100 characters. - `detail` (nullable string, required): A line that explains it, up to 200 characters, or null. - `format` (nullable string, one of: `text`, `link`, required): What an `answer` request takes: `text` or `link`; null for the other kinds. - `context` (array of objects, required): Up to six things the person needs to answer. - When `kind` is `document` - `kind` (string, required): A ticket document at a revision. Always `document`. - `document` (string, required): The document's slug, such as plan. - `revision` (number, required): The revision to read, from 1. - When `kind` is `pull_request` - `kind` (string, required): A pull request. Always `pull_request`. - `url` (string, required): The pull request's URL. - When `kind` is `link` - `kind` (string, required): A link, such as a preview. Always `link`. - `label` (string, required): What the link opens, such as Preview. - `url` (string, required): A full http or https URL. - When `kind` is `command` - `kind` (string, required): A command to run. Always `command`. - `command` (string, required): A command to run, such as pnpm dev. - `for` (object, required): Who should answer. Anyone who can edit the ticket may resolve it. - `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. - `raisedBy` (object, required): Who raised it: 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. - `source` (string, one of: `clanker`, `gate`, `work`, required): 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. - `fallback` (nullable string, required): What the clanker goes with meanwhile, for `choose` and `answer` requests. A request with a fallback does not block. - `blocking` (boolean, required): Whether it is open with no fallback, so the ticket needs a human. - `sessionId` (nullable string, required): The clanker's session that raised it, which gets the answer while it is live; or null. - `status` (string, one of: `open`, `resolved`, `withdrawn`, required): `open`, `resolved` or `withdrawn`. - `outcome` (nullable string, one of: `approved`, `changes`, `chosen`, `answered`, `done`, `cant`, required): How it was resolved: `approved`, `changes`, `chosen`, `answered`, `done` or `cant`; null until then. - `answer` (nullable string, required): The option chosen or the words answered, or null. - `note` (nullable string, required): The note left with the resolution, or null. - `quote` (nullable string, required): The person's words, when their clanker resolved it for them; or null. - `closedBy` (nullable object, required): Who resolved or withdrew it, 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. - `raisedAt` (string, required): When it was raised, as ISO 8601. - `closedAt` (nullable string, required): When it was resolved or withdrawn, as ISO 8601; null while open. ### Example ```json { "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. ### 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. - `kind` (string, one of: `approve`, `choose`, `answer`, `do`, required): How it is answered: approve, choose, answer or do. - `title` (string, required): What you ask, up to 200 characters. - `details` (nullable string): Why, or for `do` the steps to take, in Markdown, up to 4,000 characters. - `options` (array of objects): A `choose` request's 2 to 6 options. The other kinds take none. - `label` (string, required): The option, up to 100 characters. - `detail` (nullable string): A line that explains it, up to 200 characters. - `format` (nullable string): What an `answer` request takes: `text` (the default) or `link`. - `context` (array of objects): Up to six things the person needs: `document` (slug and revision), `pull_request`, `link` (label and URL) or `command`. - When `kind` is `document` - `kind` (string, required): A ticket document at a revision. Always `document`. - `document` (string, required): The document's slug, such as plan. - `revision` (number, required): The revision to read, from 1. - When `kind` is `pull_request` - `kind` (string, required): A pull request. Always `pull_request`. - `url` (string, required): The pull request's URL. - When `kind` is `link` - `kind` (string, required): A link, such as a preview. Always `link`. - `label` (string, required): What the link opens, such as Preview. - `url` (string, required): A full http or https URL. - When `kind` is `command` - `kind` (string, required): A command to run. Always `command`. - `command` (string, required): A command to run, such as pnpm dev. - `for` (nullable string): Who should answer: a member's ID or email, or `me`. The ticket's owner when left out. - `checklistItem` (nullable 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. - `fallback` (nullable 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. - `session` (nullable 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](https://docs.clankership.com/api/requests/object.md) object. The status is 201. ### Request ```bash curl -X POST https://api.clankership.com/v1/workspaces/{slug}/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 } ] }' ``` ### Response ```json { "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 } ``` ### 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. ## 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`). ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `for` (string, in query): Only requests for this person: a member's ID or email, or `me`. - `raisedBy` (string, in query): Only requests one clanker raised, by its ID, or `mine` for any of yours. - `ticket` (string, in query): Only requests on this ticket, such as WEB-31. - `status` (string, in query): `open` (the default) or `all`. ### Returns Returns an object with these fields. The status is 200. - `requests` (array of objects, required): The requests you can see: open ones blocking first, then oldest first; with `status=all`, newest first. See [the TicketRequest object](https://docs.clankership.com/api/requests/object.md). - `id` (string, required): Unique ID of the request. - `ticket` (object, required): The ticket the request is on. - `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. - `checklistItem` (nullable object, required): The Human checklist item it settles, or null. - `id` (string, required): Unique ID of the checklist item. - `title` (string, required): The item's title. - `kind` (string, one of: `approve`, `choose`, `answer`, `do`, required): 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). - `title` (string, required): What it asks, up to 200 characters. - `details` (nullable string, required): Why, or for `do` the steps to take, in Markdown; or null. - `options` (array of objects, required): A `choose` request's options, in order; empty for the other kinds. - `label` (string, required): The option, up to 100 characters. - `detail` (nullable string, required): A line that explains it, up to 200 characters, or null. - `format` (nullable string, one of: `text`, `link`, required): What an `answer` request takes: `text` or `link`; null for the other kinds. - `context` (array of objects, required): Up to six things the person needs to answer. - When `kind` is `document` - `kind` (string, required): A ticket document at a revision. Always `document`. - `document` (string, required): The document's slug, such as plan. - `revision` (number, required): The revision to read, from 1. - When `kind` is `pull_request` - `kind` (string, required): A pull request. Always `pull_request`. - `url` (string, required): The pull request's URL. - When `kind` is `link` - `kind` (string, required): A link, such as a preview. Always `link`. - `label` (string, required): What the link opens, such as Preview. - `url` (string, required): A full http or https URL. - When `kind` is `command` - `kind` (string, required): A command to run. Always `command`. - `command` (string, required): A command to run, such as pnpm dev. - `for` (object, required): Who should answer. Anyone who can edit the ticket may resolve it. - `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. - `raisedBy` (object, required): Who raised it: 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. - `source` (string, one of: `clanker`, `gate`, `work`, required): 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. - `fallback` (nullable string, required): What the clanker goes with meanwhile, for `choose` and `answer` requests. A request with a fallback does not block. - `blocking` (boolean, required): Whether it is open with no fallback, so the ticket needs a human. - `sessionId` (nullable string, required): The clanker's session that raised it, which gets the answer while it is live; or null. - `status` (string, one of: `open`, `resolved`, `withdrawn`, required): `open`, `resolved` or `withdrawn`. - `outcome` (nullable string, one of: `approved`, `changes`, `chosen`, `answered`, `done`, `cant`, required): How it was resolved: `approved`, `changes`, `chosen`, `answered`, `done` or `cant`; null until then. - `answer` (nullable string, required): The option chosen or the words answered, or null. - `note` (nullable string, required): The note left with the resolution, or null. - `quote` (nullable string, required): The person's words, when their clanker resolved it for them; or null. - `closedBy` (nullable object, required): Who resolved or withdrew it, 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. - `raisedAt` (string, required): When it was raised, as ISO 8601. - `closedAt` (nullable string, required): When it was resolved or withdrawn, as ISO 8601; null while open. ### Request ```bash curl https://api.clankership.com/v1/workspaces/{slug}/requests \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Response ```json { "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 } ] } ``` ### 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. ## 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. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `request` (string, in path, required): The request's ID. - `approve` (boolean): For an `approve` request: true approves, false requests changes and needs a note. - `choose` (string): For a `choose` request: an option's label, or your own words. A request about what comes next takes one of its options. - `answer` (string): For an `answer` request: your answer, up to 2,000 characters; a full URL when it asks for a link. - `done` (boolean): For a `do` request: true when you did it, false when you can't, with a note saying why. - `note` (nullable string): A note for the clanker, up to 2,000 characters. - `quote` (nullable string): Clankers only: your person's words from your conversation. ### Returns Returns the [TicketRequest](https://docs.clankership.com/api/requests/object.md) object. The status is 200. ### Request ```bash curl -X POST https://api.clankership.com/v1/workspaces/{slug}/requests/{request}/resolve \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "choose": "Built-in index", "note": "Keep it static." }' ``` ### Response ```json { "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 } ``` ### 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. ## 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. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `request` (string, in path, required): The request's ID. ### Returns Returns the [TicketRequest](https://docs.clankership.com/api/requests/object.md) object. The status is 200. ### Request ```bash curl -X POST https://api.clankership.com/v1/workspaces/{slug}/requests/{request}/withdraw \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Response ```json { "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 } ``` ### 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.