{"openapi":"3.1.0","info":{"title":"Yokka REST API","version":"0.1.0","description":"The same operations as Yokka's MCP server, over plain HTTP: for scripts, CI jobs and agents that\ndon't speak MCP. Each endpoint runs one MCP tool, with the same permissions and the same result.\n\n## Authentication\n\nSend a token from **Workspace settings → Agents** as `Authorization: Bearer <token>`. The token decides\nwhat you can do, exactly as over MCP:\n\n- **Read-only** tokens can call the `GET` endpoints only.\n- **Read-and-write** tokens can also work, file and edit cards.\n- The **Delete and restore cards** (`cards.delete`) and **Manage lanes, swimlanes and flows**\n  (`board.manage`) permissions unlock the Trash and Structure endpoints.\n- A token limited to some projects sees only those: everything else answers 404.\n- Archived projects are read-only: they answer reads when you name them, and refuse every change.\n\nTokens die with their creator's membership, and a creator who becomes a viewer leaves their tokens read-only.\n\n## Who you are on the board\n\nCalls act as an **agent**: the board shows who claimed, reported or commented, and the activity log records\nit as an agent. Name yours with `X-Client-Name` (for example `ci-bot`; the default is `api`). A card you\nclaim is held by that token *and* name together, across requests, so a script can claim a card in one call and\ncomplete it in another. Another name on the same token is another agent.\n\n## Requests and responses\n\n- Cards are addressed by their ref (`YK-12`), projects by slug, name or card prefix, and swimlanes, lanes,\n  epics and labels by name (URL-encode spaces: `Needs%20you`). A path segment can't be blank.\n- `GET` and `DELETE` take their arguments in the query string; `POST` and `PATCH` take a JSON body of at\n  most 1 MB.\n- Fields are **camelCase** (`wipLimit`, `addLabels`). The MCP tools take the same arguments in snake_case.\n- On a `PATCH`, leave a field out to keep it. `null` clears the fields that can be cleared: a card's\n  `epic`, a lane's `wipLimit` and `description`, a swimlane's `description`, and a flow rule's\n  `moveTo` and `setAttention`.\n- A success answers with the tool's result as JSON (its MCP `structuredContent`).\n- `GET /cards` answers a page at a time: when `more` is true, repeat the request with `cursor` set to the\n  `cursor` it returned.\n- Endpoints that create something (`201`) take an `Idempotency-Key` header. A retry with the same key and\n  the same request within 24 hours answers what the first one did, with `Idempotent-Replayed: true`, and\n  changes nothing. A failed request isn't remembered, so retrying it runs it again.\n\n## Errors\n\nFailures answer `{ \"error\": { \"code\": \"...\", \"message\": \"...\" } }`. The message is written to be shown to a\nperson as-is.\n\n| Status | Code | When |\n|---|---|---|\n| 400 | `invalid` | The arguments don't fit the schema, or the change isn't possible as asked |\n| 401 | `unauthenticated` | The token is missing, invalid, revoked or expired |\n| 403 | `forbidden` | The token can't do this (read-only, or without the permission) |\n| 403 | `limit` | A plan or board limit, like a free plan's custom flow rules, or a sandbox's 500 calls |\n| 404 | `not_found` | No such project, card, swimlane, lane, epic, label or rule for this token |\n| 405 | `method_not_allowed` | The path exists but not with this method (see `Allow`) |\n| 409 | `conflict` | Another agent holds the card, you don't hold the card you're working on, a name is taken, or an Idempotency-Key was used for another request |\n| 413 | `too_large` | The request body is over 1 MB |\n| 429 | `rate_limited` | Too many calls, or too many failed sign-ins from your address: wait for `Retry-After` seconds |\n| 503 | `unavailable` | A service the board depends on didn't answer; try again later |\n\n## Limits\n\nREST and MCP calls share one budget per token and count toward the same monthly allowance. On the free plan,\ncalls past the allowance are slowed to 10 a minute: a call over that answers 429 with `Retry-After`."},"servers":[{"url":"https://api.yokka.ai/api/v1"}],"security":[{"bearer":[]}],"tags":[{"name":"Board","description":"Read projects, boards and cards. Every token can."},{"name":"Card work","description":"The agent loop: find the next card, claim it, report progress, ask the human, attach proof and complete it. Claims belong to the token and X-Client-Name together."},{"name":"Planning","description":"File and edit cards, move them, and keep epics and labels in order. Read-and-write tokens."},{"name":"Archive","description":"Put cards away off the board and bring them back. Read-and-write tokens."},{"name":"Trash","description":"Delete and restore cards. Needs a token with the \"cards.delete\" permission."},{"name":"Structure","description":"Swimlanes, lanes and flow rules. Needs a token with the \"board.manage\" permission; custom flow rules also need a plan that includes them."}],"paths":{"/session/introduce":{"post":{"operationId":"introduce","summary":"Introduce yourself","description":"Tell the board who you are, once at the start of a session (and again if the human renames you). Use the name the human knows this session by in their CLI or app: its session or thread title, its terminal tab, or its worktree or branch, like \"auth-refactor\". The board shows it on the cards you hold and in its list of agents, so a human running many agents can tell which is which, and can ask any agent about you by that name. Leave the name out and the board picks one. Names are unique among live agents: when yours is taken you get a numbered one. Tell the human the name you got, and title your session with it if your client lets you. When the answer gives you an `as` name, other chats share your connection: pass it as `as` to claim_card from then on, so the board knows the cards are yours. Pass `project` to name the project you'll work in: tools then use it when you leave `project` out.\n\nNeeds a read-and-write token. Same as the MCP tool `introduce`.","tags":["Card work"],"parameters":[{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Optional: your name on the board, like this session's title, terminal tab or branch (\"auth-refactor\"). Leave it out and the board picks one.","minLength":1,"maxLength":40},"where":{"type":"string","description":"Optional one line on where you run, like \"kanban-app · feat/auth · work laptop\". Shown with your name.","maxLength":120},"as":{"type":"string","description":"Optional: the `as` name you already have, to rename yourself to `name`.","minLength":1,"maxLength":40},"project":{"type":"string","description":"Optional project slug, name or card prefix to work in: tools use it when you leave out `project`, until you claim or file a card in another one.","minLength":1,"maxLength":80}},"required":[],"additionalProperties":false},"example":{"name":"auth-refactor","where":"api · feat/auth"}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"where":{"type":["string","null"]},"as":{"type":["string","null"]},"project":{"type":["string","null"]}},"required":["name","where","as","project"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects":{"get":{"operationId":"list_projects","summary":"List projects","description":"List the projects in this workspace with their swimlanes, each swimlane's lanes and how many cards each lane holds (a done lane counts its latest cards; `more` says it holds more). Start here if you don't know which project to work in. Archived projects are read-only and left out unless includeArchived.\n\nAny token. Same as the MCP tool `list_projects`.","tags":["Board"],"parameters":[{"name":"includeArchived","in":"query","required":false,"description":"Also list archived (read-only) projects.","schema":{"type":"boolean","description":"Also list archived (read-only) projects."},"example":true}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"prefix":{"type":"string"},"archived":{"type":"boolean"},"swimlanes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"lanes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"cards":{"type":"integer"},"more":{"type":"boolean"}},"required":["name","cards","more"],"additionalProperties":false}},"backlog":{"type":["integer","null"]}},"required":["name","lanes","backlog"],"additionalProperties":false}}},"required":["name","slug","prefix","archived","swimlanes"],"additionalProperties":false}}},"required":["projects"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project}/board":{"get":{"operationId":"get_board","summary":"Read a board","description":"Read one project's board: every swimlane, its lanes and their cards (ref, title, who holds it, whether it needs the human, which cards it is blocked by). Swimlanes split the board by kind of work (Features, Bugs…) and each has its own lanes. A swimlane may also have a Backlog: parked work that isn't ready, which get_next_card skips. Done lanes (Shipped, Fixed…) show only their latest cards; find older ones with find_cards. Also lists the open epics (larger pieces of work that group cards across swimlanes) with their progress, each card's epic, and the project's labels. Use it to get oriented before picking work or planning.\n\nAny token. Same as the MCP tool `get_board`.","tags":["Board"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"string"},"archived":{"type":"boolean"},"epics":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"total":{"type":"integer"},"done":{"type":"integer"},"partial":{"type":"boolean"}},"required":["name","total","done","partial"],"additionalProperties":false}},"labels":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"color":{"type":"string"}},"required":["name","color"],"additionalProperties":false}},"swimlanes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"lanes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["active","done","backlog"]},"backlog":{"type":"boolean"},"more":{"type":"boolean"},"cards":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string"},"title":{"type":"string"},"epic":{"type":["string","null"]},"attention":{"type":["string","null"]},"holder":{"type":["string","null"]},"blocked":{"type":"boolean"}},"required":["ref","title","epic","attention","holder","blocked"],"additionalProperties":false}}},"required":["name","kind","backlog","more","cards"],"additionalProperties":false}}},"required":["name","lanes"],"additionalProperties":false}}},"required":["project","archived","epics","labels","swimlanes"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}":{"get":{"operationId":"get_card","summary":"Read a card","description":"Read a card in full: its brief (what, why, done-when), swimlane, lane, labels, epic, holder, checklist (items the human wrote are acceptance criteria), the cards it is blocked by and the cards it blocks, attached files (with download links: the human may attach screenshots or mockups), linked GitHub pull requests (with their checks), branches and commits, and recent activity. Read the brief before you start working on a card. Its cursor lets get_card_activity show only what's new. An archived card reads the same, but is read-only.\n\nAny token. Same as the MCP tool `get_card`.","tags":["Board"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"title":{"type":"string"},"archived":{"type":"boolean"},"swimlane":{"type":["string","null"]},"lane":{"type":["string","null"]},"backlog":{"type":"boolean"},"brief":{"type":"string"},"labels":{"type":"array","items":{"type":"string"}},"epic":{"type":["string","null"]},"attention":{"type":["string","null"]},"heldByYou":{"type":"boolean"},"blocked":{"type":"boolean"},"blockedBy":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string"},"title":{"type":"string"},"lane":{"type":["string","null"]},"done":{"type":"boolean"}},"required":["ref","title","lane","done"],"additionalProperties":false}},"blocks":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string"},"title":{"type":"string"},"lane":{"type":["string","null"]},"done":{"type":"boolean"}},"required":["ref","title","lane","done"],"additionalProperties":false}},"checklist":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer"},"text":{"type":"string"},"done":{"type":"boolean"},"from":{"type":"string","enum":["human","agent"]}},"required":["number","text","done","from"],"additionalProperties":false}},"attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"contentType":{"type":"string"},"size":{"type":"integer"},"caption":{"type":["string","null"]},"from":{"type":"string"},"url":{"type":["string","null"]}},"required":["filename","contentType","size","caption","from","url"],"additionalProperties":false}},"code":{"type":"object","properties":{"pullRequests":{"type":"array","items":{"type":"object","properties":{"repo":{"type":"string"},"number":{"type":"integer"},"title":{"type":"string"},"state":{"type":"string","enum":["open","draft","merged","closed"]},"ci":{"type":["string","null"]},"url":{"type":"string"}},"required":["repo","number","title","state","ci","url"],"additionalProperties":false}},"branches":{"type":"array","items":{"type":"object","properties":{"repo":{"type":"string"},"name":{"type":"string"},"deleted":{"type":"boolean"},"url":{"type":"string"}},"required":["repo","name","deleted","url"],"additionalProperties":false}},"commits":{"type":"array","items":{"type":"object","properties":{"repo":{"type":"string"},"sha":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"}},"required":["repo","sha","title","url"],"additionalProperties":false}}},"required":["pullRequests","branches","commits"],"additionalProperties":false},"cursor":{"type":["string","null"]}},"required":["ref","title","archived","swimlane","lane","backlog","brief","labels","epic","attention","heldByYou","blocked","blockedBy","blocks","checklist","attachments","code","cursor"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update_card","summary":"Edit a card","description":"Edit a card's title, brief, labels, epic or the cards it waits on: sharpen a brief you filed, fix labels, file it under an epic, or set what it's blocked by. `labels` replaces the whole list; addLabels and removeLabels change only those, and blockedBy, addBlockedBy and removeBlockedBy work the same way. Refuses a card another agent holds.\n\nNeeds a read-and-write token. Same as the MCP tool `update_card`.","tags":["Planning"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"New title.","minLength":1,"maxLength":200},"brief":{"type":"string","description":"New brief (markdown), replacing the old one.","maxLength":20000},"labels":{"type":"array","description":"The card's full new label list.","items":{"type":"string","maxLength":24},"maxItems":8},"addLabels":{"type":"array","description":"Labels to add.","items":{"type":"string","maxLength":24},"maxItems":8},"removeLabels":{"type":"array","description":"Labels to take off.","items":{"type":"string","maxLength":24},"maxItems":8},"epic":{"type":["string","null"],"description":"Open epic to move it into, by name. Pass \"\" to take it out of its epic.","maxLength":60},"blockedBy":{"type":"array","description":"The full list of cards of the same project it waits on, by ref. Pass [] to clear it.","items":{"type":"string","maxLength":80},"maxItems":20},"addBlockedBy":{"type":"array","description":"Cards it should also wait on, like [\"YK-3\"].","items":{"type":"string","maxLength":80},"maxItems":20},"removeBlockedBy":{"type":"array","description":"Cards it should stop waiting on.","items":{"type":"string","maxLength":80},"maxItems":20}},"required":[],"additionalProperties":false},"example":{"title":"Fix the flaky login test on CI","addLabels":["ci"],"epic":null,"addBlockedBy":["YK-3"]}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"changed":{"type":"array","items":{"type":"string"}}},"required":["ref","changed"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"delete_card","summary":"Delete a card","description":"Move a card to the trash: duplicates, or work the human decided against. It can be restored with restore_card until the trash is emptied. Refuses a card another agent holds.\n\nNeeds a token with the `cards.delete` permission. Without it: *This token can't delete or restore cards. Ask the human to do it, or to create a token with that permission turned on.* Same as the MCP tool `delete_card`.","tags":["Trash"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"}},"required":["ref"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/activity":{"get":{"operationId":"get_card_activity","summary":"Read a card's activity","description":"Read a card's activity oldest first: comments, questions, progress, moves and edits, with who did each. After request_input, pass the cursor it returned as `after` to see only what happened since, and look for a comment from a person: that's the human's answer. To wait for it, add waitSeconds (up to 50): the call answers as soon as a person or another agent adds something after the cursor, instead of you polling. Without `after`, returns the latest entries. Pass the returned cursor next time to keep reading forward.\n\nAny token. Same as the MCP tool `get_card_activity`.","tags":["Board"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"name":"after","in":"query","required":false,"description":"Optional cursor from request_input, comment_card, get_card or an earlier call.","schema":{"type":"string","description":"Optional cursor from request_input, comment_card, get_card or an earlier call.","minLength":1,"maxLength":80}},{"name":"limit","in":"query","required":false,"description":"Optional, 1–100 entries (default 30).","schema":{"type":"integer","description":"Optional, 1–100 entries (default 30).","minimum":1,"maximum":100},"example":10},{"name":"waitSeconds","in":"query","required":false,"description":"Optional, with `after`: wait up to this many seconds (1–50) for a person or another agent to add something, and answer as soon as they do. Counts as one call.","schema":{"type":"integer","description":"Optional, with `after`: wait up to this many seconds (1–50) for a person or another agent to add something, and answer as soon as they do. Counts as one call.","minimum":1,"maximum":50}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"actor":{"type":"string","enum":["user","agent","system"]},"by":{"type":["string","null"]},"kind":{"type":"string"},"message":{"type":["string","null"]},"options":{"type":"array","items":{"type":"object","properties":{"option":{"type":"integer"},"label":{"type":"string"},"attachment":{"type":["string","null"]},"detail":{"type":["string","null"]}},"required":["option","label","attachment","detail"],"additionalProperties":false}},"picked":{"type":["integer","null"]}},"required":["id","at","actor","by","kind","message","options","picked"],"additionalProperties":false}},"cursor":{"type":["string","null"]},"more":{"type":"boolean"},"waitingOnHuman":{"type":"boolean"}},"required":["ref","events","cursor","more","waitingOnHuman"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards":{"get":{"operationId":"find_cards","summary":"Find cards","description":"Search cards by text in the title or brief, label, epic, swimlane or lane, across every active project unless you name one (name an archived project to search it). heldByMe lists the cards you hold (useful after a restart); heldBy lists another agent's, by the name it introduced itself with, when the human asks about it (\"what is auth-refactor doing?\"). needsHuman lists cards waiting on the human. inTrash searches deleted cards instead, and archived the cards put away off the board. Backlogs are included. Results come a page at a time: when `more` is true, pass the returned `cursor` with the same filters for the next page (a page can be short when a search reads many cards).\n\nAny token. Same as the MCP tool `find_cards`.","tags":["Board"],"parameters":[{"name":"project","in":"query","required":false,"description":"Optional project slug, name or card prefix. Omit to search every active project.","schema":{"type":"string","description":"Optional project slug, name or card prefix. Omit to search every active project.","minLength":1,"maxLength":80}},{"name":"text","in":"query","required":false,"description":"Words to look for in the title or brief.","schema":{"type":"string","description":"Words to look for in the title or brief.","minLength":1,"maxLength":200},"example":"login"},{"name":"label","in":"query","required":false,"description":"Only cards with this label.","schema":{"type":"string","description":"Only cards with this label.","minLength":1,"maxLength":24},"example":"bug"},{"name":"epic","in":"query","required":false,"description":"Only cards in this epic.","schema":{"type":"string","description":"Only cards in this epic.","minLength":1,"maxLength":60}},{"name":"swimlane","in":"query","required":false,"description":"Only cards in this swimlane.","schema":{"type":"string","description":"Only cards in this swimlane.","minLength":1,"maxLength":40}},{"name":"lane","in":"query","required":false,"description":"Only cards in lanes with this name, like \"Ready\".","schema":{"type":"string","description":"Only cards in lanes with this name, like \"Ready\".","minLength":1,"maxLength":40}},{"name":"heldByMe","in":"query","required":false,"description":"Only cards you hold, and your helpers' (agents that claimed with `as`).","schema":{"type":"boolean","description":"Only cards you hold, and your helpers' (agents that claimed with `as`)."}},{"name":"as","in":"query","required":false,"description":"Optional: the name you claim with (`as` on claim_card), so held_by_me lists only your cards.","schema":{"type":"string","description":"Optional: the name you claim with (`as` on claim_card), so held_by_me lists only your cards.","minLength":1,"maxLength":40}},{"name":"heldBy","in":"query","required":false,"description":"Only cards held by this agent, including ones it finished: its name (\"auth-refactor\") or its client's (\"codex\"). Agents seen today only.","schema":{"type":"string","description":"Only cards held by this agent, including ones it finished: its name (\"auth-refactor\") or its client's (\"codex\"). Agents seen today only.","minLength":1,"maxLength":40}},{"name":"needsHuman","in":"query","required":false,"description":"Only cards flagged for the human.","schema":{"type":"boolean","description":"Only cards flagged for the human."}},{"name":"inTrash","in":"query","required":false,"description":"Search deleted cards instead of live ones.","schema":{"type":"boolean","description":"Search deleted cards instead of live ones."}},{"name":"archived","in":"query","required":false,"description":"Search archived cards instead of live ones.","schema":{"type":"boolean","description":"Search archived cards instead of live ones."}},{"name":"limit","in":"query","required":false,"description":"Optional, 1–100 cards a page (default 30).","schema":{"type":"integer","description":"Optional, 1–100 cards a page (default 30).","minimum":1,"maximum":100},"example":20},{"name":"cursor","in":"query","required":false,"description":"Optional: the cursor a previous page returned, to read the next one.","schema":{"type":"string","description":"Optional: the cursor a previous page returned, to read the next one.","minLength":1,"maxLength":1000}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"cards":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string"},"title":{"type":"string"},"project":{"type":"string"},"swimlane":{"type":["string","null"]},"lane":{"type":["string","null"]},"backlog":{"type":"boolean"},"labels":{"type":"array","items":{"type":"string"}},"epic":{"type":["string","null"]},"attention":{"type":["string","null"]},"holder":{"type":["string","null"]},"heldByYou":{"type":"boolean"},"blocked":{"type":"boolean"},"deletedAt":{"type":["string","null"]},"archivedAt":{"type":["string","null"]}},"required":["ref","title","project","swimlane","lane","backlog","labels","epic","attention","holder","heldByYou","blocked","deletedAt","archivedAt"],"additionalProperties":false}},"more":{"type":"boolean"},"cursor":{"type":["string","null"]}},"required":["cards","more","cursor"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project}/next-card":{"get":{"operationId":"get_next_card","summary":"Find the next card","description":"Find the top unclaimed card waiting to be picked up: in each swimlane, the lane just before the one claimed cards move to (usually Ready or Triage). Swimlanes are searched top to bottom unless you name one. Backlogs are never searched, and cards blocked by work that isn't done yet are skipped. Name an epic to only pick up that epic's cards. It only looks: claim the card with claim_card before starting, or call claim_card without a card to find and claim the next one in one step, so no other agent takes it in between. To keep working until your human stops you, add waitSeconds (up to 50) once you run out: the call answers as soon as a card is ready (one filed or moved in, a blocker done, a claim let go) instead of you polling.\n\nAny token. Same as the MCP tool `get_next_card`.","tags":["Card work"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"name":"swimlane","in":"query","required":false,"description":"Swimlane name, like \"Bugs\". Optional; leave it out to look in every swimlane.","schema":{"type":"string","description":"Swimlane name, like \"Bugs\". Optional; leave it out to look in every swimlane.","minLength":1,"maxLength":40}},{"name":"epic","in":"query","required":false,"description":"Epic name, like \"Checkout v2\". get_board lists the open epics.","schema":{"type":"string","description":"Epic name, like \"Checkout v2\". get_board lists the open epics.","minLength":1,"maxLength":60}},{"name":"waitSeconds","in":"query","required":false,"description":"Optional: when nothing is waiting, wait up to this many seconds (1–50) for a card to be ready, and answer as soon as one is. Counts as one call.","schema":{"type":"integer","description":"Optional: when nothing is waiting, wait up to this many seconds (1–50) for a card to be ready, and answer as soon as one is. Counts as one call.","minimum":1,"maximum":50}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"card":{"type":["object","null"],"properties":{"ref":{"type":"string"},"title":{"type":"string"},"swimlane":{"type":"string"},"lane":{"type":"string"},"epic":{"type":["string","null"]},"brief":{"type":"string"}},"required":["ref","title","swimlane","lane","epic","brief"],"additionalProperties":false}},"required":["card"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"claim_next_card","summary":"Claim the next card","description":"Claim a card when you start working on it, not a batch ahead of time. The board moves it (usually to Working) and shows you as its agent. Refuses a card another agent holds, including another running session on your token. Leave out `card` to take the next card waiting to be picked up, exactly as get_next_card would find it (same project, swimlane and epic filters), in one step: cards other agents hold are skipped, and no other agent can take it in between. Add waitSeconds to wait for one when none is ready yet: it claims the first card that becomes ready, and two waiting agents never get the same one. A card blocked by other cards (they aren't done yet) is refused with what it waits on; pass force: true only if the human asked you to work on it anyway. A claim lapses once its holder has been quiet for the project's stale time (30 minutes by default); then any agent may claim the card. It doesn't lapse while a question you asked with request_input waits on the human. If you are one of several agents on one connection (a subagent, or a helper another agent started), pass `as` with your own short name, like \"setup-copy\": the board shows you as your own agent under the one that started you, and every tool you call on this card acts as you.\n\nNeeds a read-and-write token. Same as the MCP tool `claim_card`, without `card`, `force`.","tags":["Card work"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"as":{"type":"string","description":"Optional: your own name, when you share a connection with other agents (a subagent), like \"setup-copy\". Use the same one for every card you claim.","minLength":1,"maxLength":40},"swimlane":{"type":"string","description":"Without a card: only look in this swimlane, like \"Bugs\". Leave it out to look in every swimlane.","minLength":1,"maxLength":40},"epic":{"type":"string","description":"Without a card: only take a card of this epic, like \"Checkout v2\".","minLength":1,"maxLength":60},"waitSeconds":{"type":"integer","description":"Without a card: when nothing is waiting, wait up to this many seconds (1–50) for a card to be ready, and claim it as soon as one is. Counts as one call.","minimum":1,"maximum":50},"note":{"type":"string","description":"Optional one-line note on your plan.","maxLength":280},"launch":{"type":"string","description":"The launch code from your start prompt (like \"r_7f3k2a\"), when you were given one. It links your session to the run the person started.","maxLength":20}},"required":[],"additionalProperties":false},"example":{"swimlane":"Bugs","note":"Starting with the top bug"}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":["string","null"]},"title":{"type":["string","null"]},"lane":{"type":["string","null"]}},"required":["ref","title","lane"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/claim":{"post":{"operationId":"claim_card","summary":"Claim a card","description":"Claim a card when you start working on it, not a batch ahead of time. The board moves it (usually to Working) and shows you as its agent. Refuses a card another agent holds, including another running session on your token. Leave out `card` to take the next card waiting to be picked up, exactly as get_next_card would find it (same project, swimlane and epic filters), in one step: cards other agents hold are skipped, and no other agent can take it in between. Add waitSeconds to wait for one when none is ready yet: it claims the first card that becomes ready, and two waiting agents never get the same one. A card blocked by other cards (they aren't done yet) is refused with what it waits on; pass force: true only if the human asked you to work on it anyway. A claim lapses once its holder has been quiet for the project's stale time (30 minutes by default); then any agent may claim the card. It doesn't lapse while a question you asked with request_input waits on the human. If you are one of several agents on one connection (a subagent, or a helper another agent started), pass `as` with your own short name, like \"setup-copy\": the board shows you as your own agent under the one that started you, and every tool you call on this card acts as you.\n\nNeeds a read-and-write token. Same as the MCP tool `claim_card`, without `project`, `swimlane`, `epic`, `waitSeconds`.","tags":["Card work"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"as":{"type":"string","description":"Optional: your own name, when you share a connection with other agents (a subagent), like \"setup-copy\". Use the same one for every card you claim.","minLength":1,"maxLength":40},"note":{"type":"string","description":"Optional one-line note on your plan.","maxLength":280},"launch":{"type":"string","description":"The launch code from your start prompt (like \"r_7f3k2a\"), when you were given one. It links your session to the run the person started.","maxLength":20},"force":{"type":"boolean","description":"Optional: claim the card even though it is blocked by cards that aren't done. Only when the human asked for it."}},"required":[],"additionalProperties":false},"example":{"note":"Starting with the API"}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":["string","null"]},"title":{"type":["string","null"]},"lane":{"type":["string","null"]}},"required":["ref","title","lane"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/progress":{"post":{"operationId":"report_progress","summary":"Report progress","description":"Report progress on a card you hold, at real milestones only. The human watches the board live, so keep each message to one short line (\"Added the Stripe session endpoint\"). Say when a long step starts (tests, a build) and how it ended, and have subagents working on the card report here too. Never report work you haven't done.\n\nNeeds a read-and-write token. Same as the MCP tool `report_progress`.","tags":["Card work"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"One line on what just happened.","minLength":1,"maxLength":280},"percent":{"type":"number","description":"Optional rough completion, 0–100 (rounded to a whole number). Leave it out on a card with a checklist: its bar follows the items.","minimum":0,"maximum":100},"step":{"type":"string","description":"Optional short step name, like \"Tests\".","maxLength":60}},"required":["message"],"additionalProperties":false},"example":{"message":"Added the Stripe session endpoint","percent":60,"step":"Backend"}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"percent":{"type":["integer","null"]}},"required":["ref","percent"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/session/stop-check":{"get":{"operationId":"stop_check","summary":"Check your cards before you stop","description":"Call it before you end your turn. It lists the cards you hold that the board shows as in progress although you haven't said anything about them for 10 minutes or more: not done, not released and not waiting on the human. Answers `{}` when there are none. Otherwise it answers with `{\"decision\": \"block\", \"reason\": ...}` naming each card: complete, release, request_input or report_progress on it before you stop. The reply is Claude Code hook output, so a Stop hook can call this tool directly.\n\nAny token. Same as the MCP tool `stop_check`.","tags":["Card work"],"parameters":[{"name":"stopHookActive","in":"query","required":false,"description":"Claude Code's stop_hook_active: true once a Stop hook already sent you back this turn, and then this check lets the turn end rather than blocking again. \"true\" and \"false\" are accepted as well.","schema":{"type":"boolean","description":"Claude Code's stop_hook_active: true once a Stop hook already sent you back this turn, and then this check lets the turn end rather than blocking again. \"true\" and \"false\" are accepted as well."}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":["string","null"]},"reason":{"type":["string","null"]},"cards":{"type":"array","items":{"type":"string"}}},"required":["decision","reason","cards"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/checklist":{"post":{"operationId":"set_checklist","summary":"Write a card's checklist","description":"Write your plan for a card as a checklist the human can follow on the board: 3–10 concrete steps, in order, each one short line. Call it again to revise the plan; pass the full list each time. Items whose text is unchanged keep their number and ticked state; your other items are dropped. Items the human wrote (acceptance criteria) always stay: work through them, you can't reword or remove them. Call it before you change anything; only a one-line fix may skip it. Refuses a card another agent holds.\n\nNeeds a read-and-write token. Same as the MCP tool `set_checklist`.","tags":["Card work"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"The whole checklist in order, like [\"Add the endpoint\", \"Write tests\", \"Update the docs\"].","items":{"type":"string","maxLength":200},"maxItems":50}},"required":["items"],"additionalProperties":false},"example":{"items":["Add the Stripe session endpoint","Show the receipt","Write tests"]}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"done":{"type":"integer"},"total":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer"},"text":{"type":"string"},"done":{"type":"boolean"},"from":{"type":"string","enum":["human","agent"]}},"required":["number","text","done","from"],"additionalProperties":false}}},"required":["ref","done","total","items"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/checklist/check":{"post":{"operationId":"check_items","summary":"Tick checklist items","description":"Tick checklist items off as you finish them, by the numbers get_card and set_checklist show (#3 is 3). The board's progress bar follows the checklist, so tick each item when it's really done, not ahead of time. Pass done: false to untick. Refuses a card another agent holds.\n\nNeeds a read-and-write token. Same as the MCP tool `check_items`.","tags":["Card work"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","description":"Item numbers, like [1, 2].","items":{"type":"integer","minimum":1,"maximum":1000000},"maxItems":50},"done":{"type":"boolean","description":"Optional; false unticks them. Defaults to true."}},"required":["items"],"additionalProperties":false},"example":{"items":[1,2]}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"done":{"type":"integer"},"total":{"type":"integer"},"changed":{"type":"integer"}},"required":["ref","done","total","changed"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/attachments":{"post":{"operationId":"attach_file","summary":"Attach proof","description":"Attach proof to a card you hold: a screenshot of the change, a screen recording, a test report or a log, so the human can see it worked without running it. Returns a single-use upload link: PUT the file's raw bytes to it (the reply shows the curl command) within 15 minutes and it appears on the card. Images, MP4/WebM/MOV videos, PDFs and text files, up to 20 MB each (less on some plans: the reply gives the cap). Prefer a cropped screenshot or a short, trimmed recording. Attach before complete_card. If you can't reach the network (a sandbox) and a Yokka runner started you, pass `path` instead and the runner uploads the file from your working folder.\n\nNeeds a read-and-write token. Same as the MCP tool `attach_file`.","tags":["Card work"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","description":"The file's name, like \"checkout-after.png\". Its extension sets the type.","minLength":1,"maxLength":200},"caption":{"type":"string","description":"Optional one line on what it shows (\"Checkout page with the new totals\").","maxLength":280},"contentType":{"type":"string","description":"Optional MIME type, like \"image/png\", when the extension doesn't say.","minLength":1,"maxLength":100},"path":{"type":"string","description":"Optional, runner runs only: the file's path relative to your working folder (screenshots/after.png). The runner uploads it; you don't PUT anything.","minLength":1,"maxLength":500}},"required":["filename"],"additionalProperties":false},"example":{"filename":"checkout-after.png","caption":"Checkout with the new totals"}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"uploadUrl":{"type":"string"},"method":{"type":"string"},"contentType":{"type":"string"},"maxBytes":{"type":"integer"},"expiresAt":{"type":"string"}},"required":["ref","uploadUrl","method","contentType","maxBytes","expiresAt"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/request-input":{"post":{"operationId":"request_input","summary":"Ask the human","description":"Ask the human a question when you're blocked on a decision only they can make. The card is flagged \"your turn\" (and usually moves to Needs you). Ask one clear question, then wait for their reply with get_card_activity, passing the returned cursor as `after` and wait_seconds so it answers as soon as they reply, before continuing. When the human should pick between a few choices, pass them as `options` so they can answer with one tap (on their phone too); for visual choices (designs, screenshots, charts), attach each with attach_file first and name the files in `optionFiles`, in the same order. Their reply says which option they picked (`picked`, from 1), or has no `picked` when they chose Other and wrote their own answer. If they answer you somewhere else instead (like your chat), note their answer with comment_card and `answers_question` before carrying on: that closes the question on the board.\n\nNeeds a read-and-write token. Same as the MCP tool `request_input`.","tags":["Card work"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","description":"One clear question.","minLength":1,"maxLength":4000},"options":{"type":"array","description":"Optional: 2 to 6 short choices, like [\"Rounded\", \"Geometric\", \"Wordmark only\"].","items":{"type":"string","maxLength":80},"maxItems":6},"optionFiles":{"type":"array","description":"Optional: for each option in order, the file name of an attachment on this card to show with it (\"logo-a.png\"), or \"-\" for none.","items":{"type":"string","maxLength":200},"maxItems":6}},"required":["question"],"additionalProperties":false},"example":{"question":"Should the receipt email be plain text or HTML?"}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"lane":{"type":["string","null"]},"cursor":{"type":"string"}},"required":["ref","lane","cursor"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/comments":{"post":{"operationId":"comment_card","summary":"Comment on a card","description":"Leave a comment on a card: answer something the human wrote, note a decision, or leave context for whoever picks it up next. Unlike request_input it doesn't flag the card for the human or move it. With `answersQuestion`, it records the answer to your open question that the human gave you elsewhere (like your chat) and takes the flag off. Use report_progress for milestones on work you hold.\n\nNeeds a read-and-write token. Same as the MCP tool `comment_card`.","tags":["Card work"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"The comment. Markdown is fine.","minLength":1,"maxLength":4000},"answersQuestion":{"type":"boolean","description":"Optional: true when the comment is the human's answer to your open request_input question, given outside the board. Closes the question, so the card stops waiting on them."}},"required":["message"],"additionalProperties":false},"example":{"message":"Going with HTML; the template is in emails/receipt.tsx."}}}},"responses":{"201":{"description":"Created. The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"cursor":{"type":"string"},"closed_question":{"type":"boolean"}},"required":["ref","cursor","closed_question"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/complete":{"post":{"operationId":"complete_card","summary":"Complete a card","description":"Mark a card you hold as done, with a one or two sentence summary of what changed. The board moves it on (usually to Review, for the human to check). Add links to pull requests or docs if you have them.\n\nNeeds a read-and-write token. Same as the MCP tool `complete_card`.","tags":["Card work"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string","description":"What changed, in one or two sentences.","minLength":1,"maxLength":4000},"links":{"type":"array","description":"Optional http(s) URLs (pull request, preview, docs). Anything else is left out.","items":{"type":"string","maxLength":2000},"maxItems":10}},"required":["summary"],"additionalProperties":false},"example":{"summary":"Checkout now creates a Stripe session and shows the receipt.","links":["https://github.com/acme/shop/pull/42"]}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"lane":{"type":["string","null"]}},"required":["ref","lane"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/release":{"post":{"operationId":"release_card","summary":"Release a card","description":"Give back a card you hold when you can't or shouldn't finish it. It is unassigned and usually returns to Ready. Say why in one line. Refuses a card you don't hold.\n\nNeeds a read-and-write token. Same as the MCP tool `release_card`.","tags":["Card work"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Why you're letting go.","maxLength":280}},"required":[],"additionalProperties":false},"example":{"reason":"Blocked on API keys"}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"lane":{"type":["string","null"]}},"required":["ref","lane"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/usage":{"post":{"operationId":"report_usage","summary":"Report usage","description":"Report what your work on a card cost, when your app shows it: tokens, cost in US dollars, model and active time. Send your running totals for this card so far, not just the latest step: each report replaces your last one for the card, so report as often as you like (before complete_card is a good time) and nothing is counted twice. Optional, and skip any number you don't know; runs a runner started report their usage on their own.\n\nNeeds a read-and-write token. Same as the MCP tool `report_usage`.","tags":["Card work"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"Optional: the model you ran on, like \"claude-opus-4-5\" or \"gpt-5-codex\".","maxLength":80},"inputTokens":{"type":"integer","description":"Optional: input tokens, not counting cache reads.","minimum":0,"maximum":1000000000000},"outputTokens":{"type":"integer","description":"Optional: output tokens, thinking included.","minimum":0,"maximum":1000000000000},"cacheReadTokens":{"type":"integer","description":"Optional: input tokens read from the prompt cache.","minimum":0,"maximum":1000000000000},"cacheWriteTokens":{"type":"integer","description":"Optional: input tokens written to the prompt cache.","minimum":0,"maximum":1000000000000},"costUsd":{"type":"number","description":"Optional: what it cost in US dollars, as your app reports it (like 1.42).","minimum":0,"maximum":1000000},"durationMs":{"type":"integer","description":"Optional: how long you were actively working on it, in milliseconds.","minimum":0,"maximum":2592000000}},"required":[],"additionalProperties":false},"example":{"model":"claude-opus-4-5","inputTokens":1200,"outputTokens":48000,"cacheReadTokens":2100000,"cacheWriteTokens":96000,"costUsd":3.81,"durationMs":1260000}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"recorded":{"type":"boolean"},"cost_usd":{"type":["number","null"]},"tokens":{"type":["integer","null"]},"card_cost_usd":{"type":["number","null"]},"card_tokens":{"type":["integer","null"]}},"required":["ref","recorded","cost_usd","tokens","card_cost_usd","card_tokens"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project}/cards":{"post":{"operationId":"add_card","summary":"Add a card","description":"File a new card: for work your human asks for that isn't on the board yet (claim it with claim_card before you start), for follow-up work you discover, or when planning. Give it a clear title and a brief covering what, why and done-when, plus optional labels (new ones join the project). Goes to the first lane of the first swimlane unless you name a swimlane and/or lane. Name the lane \"Backlog\" to park an idea that isn't ready, on swimlanes that have a backlog.\n\nNeeds a read-and-write token. Same as the MCP tool `add_card`.","tags":["Planning"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Short, specific title.","minLength":1,"maxLength":200},"brief":{"type":"string","description":"Markdown: what, why, done-when.","maxLength":20000},"swimlane":{"type":"string","description":"Swimlane name, like \"Bugs\". Optional; defaults to the first swimlane.","minLength":1,"maxLength":40},"lane":{"type":"string","description":"Lane name within the swimlane, or \"Backlog\". Defaults to the swimlane's first lane.","minLength":1,"maxLength":40},"labels":{"type":"array","description":"Optional labels, like \"bug\" or \"frontend\". Reuse existing labels where they fit.","items":{"type":"string","maxLength":24},"maxItems":8},"epic":{"type":"string","description":"Optional open epic to file it under, by name. Create one first with add_epic if it doesn't exist.","minLength":1,"maxLength":60},"checklist":{"type":"array","description":"Optional checklist: the steps, or what done means, one short line each. Whoever works the card ticks them off.","items":{"type":"string","maxLength":200},"maxItems":50},"blockedBy":{"type":"array","description":"Optional cards of the same project this one waits on, like [\"YK-3\"]. Until they reach a done lane, get_next_card skips it and claim_card refuses it.","items":{"type":"string","maxLength":80},"maxItems":20}},"required":["title"],"additionalProperties":false},"example":{"title":"Fix the flaky login test","brief":"**What:** login.spec fails one run in ten.\n**Done when:** 50 green runs in a row.","swimlane":"Bugs","labels":["bug","tests"]}}}},"responses":{"201":{"description":"Created. The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"swimlane":{"type":["string","null"]},"lane":{"type":"string"},"epic":{"type":["string","null"]}},"required":["ref","swimlane","lane","epic"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/move":{"post":{"operationId":"move_card","summary":"Move a card","description":"Move a card to another lane, like a person dragging it: promote it out of the Backlog, park it, or send it to another swimlane. Agent-event flow rules don't run, but an auto-start rule on the target lane may queue a run for it. Don't use it to claim, ship or release work: claim_card, complete_card and release_card do that. Refuses a card another agent holds.\n\nNeeds a read-and-write token. Same as the MCP tool `move_card`.","tags":["Planning"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lane":{"type":"string","description":"Target lane, like \"Ready\" or \"Backlog\".","minLength":1,"maxLength":40},"swimlane":{"type":"string","description":"Target swimlane. Defaults to the card's own swimlane.","minLength":1,"maxLength":40},"position":{"type":"string","description":"Top (default) or bottom of the lane.","enum":["top","bottom"]}},"required":["lane"],"additionalProperties":false},"example":{"lane":"Ready","swimlane":"Features","position":"top"}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"swimlane":{"type":["string","null"]},"lane":{"type":"string"}},"required":["ref","swimlane","lane"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project}/epics":{"post":{"operationId":"add_epic","summary":"Add an epic","description":"Create an epic: a larger piece of work (a feature, a migration) whose cards can sit in any swimlane. Use it when planning something that needs several cards, then file them with add_card and its epic argument. Check get_board first so you don't duplicate an existing epic.\n\nNeeds a read-and-write token. Same as the MCP tool `add_epic`.","tags":["Planning"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Short name, like \"Checkout v2\".","minLength":1,"maxLength":60},"brief":{"type":"string","description":"Optional markdown: the goal and what done means.","maxLength":4000}},"required":["name"],"additionalProperties":false},"example":{"name":"Checkout v2","brief":"One-page checkout with saved cards."}}}},"responses":{"201":{"description":"Created. The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"epic":{"type":"string"}},"required":["epic"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project}/epics/{epic}":{"patch":{"operationId":"update_epic","summary":"Edit an epic","description":"Rename an epic, rewrite its brief, or close it when its work has shipped (closed epics keep their cards but take no new ones). closed: false reopens it.\n\nNeeds a read-and-write token. Same as the MCP tool `update_epic`.","tags":["Planning"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"name":"epic","in":"path","required":true,"description":"Epic name, like \"Checkout v2\".","schema":{"type":"string","description":"Epic name, like \"Checkout v2\".","minLength":1,"maxLength":60}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New name.","minLength":1,"maxLength":60},"brief":{"type":"string","description":"New brief (markdown).","maxLength":4000},"closed":{"type":"boolean","description":"true closes the epic, false reopens it."}},"required":[],"additionalProperties":false},"example":{"closed":true}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"epic":{"type":"string"},"closed":{"type":"boolean"}},"required":["epic","closed"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project}/labels":{"post":{"operationId":"add_label","summary":"Add a label","description":"Add a label to a project's palette, or recolor an existing one. Labels are lowercase. add_card and update_card also create labels as needed; use this to pick a color.\n\nNeeds a read-and-write token. Same as the MCP tool `add_label`.","tags":["Planning"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Label name, like \"frontend\".","minLength":1,"maxLength":24},"color":{"type":"string","description":"Optional color.","enum":["slate","blue","violet","pink","orange","amber","green","teal"]}},"required":["name"],"additionalProperties":false},"example":{"name":"frontend","color":"violet"}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"color":{"type":"string"}},"required":["label","color"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project}/labels/{label}":{"patch":{"operationId":"update_label","summary":"Edit a label","description":"Rename or recolor a label. A rename updates every card that has it; renaming onto another existing label merges the two.\n\nNeeds a read-and-write token. Same as the MCP tool `update_label`.","tags":["Planning"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"name":"label","in":"path","required":true,"description":"Label name, like \"frontend\".","schema":{"type":"string","description":"Label name, like \"frontend\".","minLength":1,"maxLength":24}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New name.","minLength":1,"maxLength":24},"color":{"type":"string","description":"Optional color.","enum":["slate","blue","violet","pink","orange","amber","green","teal"]}},"required":[],"additionalProperties":false},"example":{"name":"ui"}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"color":{"type":"string"},"merged":{"type":"boolean"}},"required":["label","color","merged"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"remove_label","summary":"Remove a label","description":"Delete a label from the project and take it off every card that has it.\n\nNeeds a read-and-write token. Same as the MCP tool `remove_label`.","tags":["Planning"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"name":"label","in":"path","required":true,"description":"Label name, like \"frontend\".","schema":{"type":"string","description":"Label name, like \"frontend\".","minLength":1,"maxLength":24}},{"$ref":"#/components/parameters/ClientName"}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"}},"required":["label"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/archive":{"post":{"operationId":"archive_card","summary":"Archive a card","description":"Put a card away off the board without deleting it: finished work the human wants out of sight, or work set aside for later. It keeps everything, becomes read-only, and unarchive_card brings it back. Refuses a card another agent holds.\n\nNeeds a read-and-write token. Same as the MCP tool `archive_card`.","tags":["Archive"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"}},"required":["ref"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/unarchive":{"post":{"operationId":"unarchive_card","summary":"Unarchive a card","description":"Bring an archived card back to its lane on the board. find_cards with archived lists the archive.\n\nNeeds a read-and-write token. Same as the MCP tool `unarchive_card`.","tags":["Archive"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"lane":{"type":["string","null"]}},"required":["ref","lane"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cards/{card}/restore":{"post":{"operationId":"restore_card","summary":"Restore a card","description":"Bring a deleted card back from the trash to its lane. find_cards with in_trash lists the trash.\n\nNeeds a token with the `cards.delete` permission. Without it: *This token can't delete or restore cards. Ask the human to do it, or to create a token with that permission turned on.* Same as the MCP tool `restore_card`.","tags":["Trash"],"parameters":[{"name":"card","in":"path","required":true,"description":"The card's ref, like \"GS-12\".","schema":{"type":"string","description":"The card's ref, like \"GS-12\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string"},"lane":{"type":["string","null"]}},"required":["ref","lane"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project}/flow-rules":{"get":{"operationId":"get_flow_rules","summary":"Read flow rules","description":"Read each swimlane's flow rules: what the board does when an agent claims, reports, asks, completes or releases a card (move it to a lane, flag it for the human), and auto-start rules (on entered: start an agent on a runner when a card enters `lane`; set up in the app). Rules run in order. Their ids are what update_flow_rule and remove_flow_rule take.\n\nNeeds a token with the `board.manage` permission. Without it: *This token can't change lanes, swimlanes or flow rules. Ask the human to do it, or to create a token with that permission turned on.* Same as the MCP tool `get_flow_rules`.","tags":["Structure"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"name":"swimlane","in":"query","required":false,"description":"Swimlane name, like \"Bugs\". Optional; leave it out to look in every swimlane.","schema":{"type":"string","description":"Swimlane name, like \"Bugs\". Optional; leave it out to look in every swimlane.","minLength":1,"maxLength":40}}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"swimlanes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"on":{"type":"string"},"moveTo":{"type":["string","null"]},"setAttention":{"type":["string","null"]},"lane":{"type":["string","null"]},"start":{"type":["string","null"]},"enabled":{"type":"boolean"}},"required":["id","on","moveTo","setAttention","lane","start","enabled"],"additionalProperties":false}}},"required":["name","rules"],"additionalProperties":false}}},"required":["swimlanes"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"add_flow_rule","summary":"Add a flow rule","description":"Add a rule to a swimlane: when an event happens to one of its cards (claimed, progress, needs_input, completed, released, stale), move the card to a lane of the same swimlane and/or flag it (owner: the human's turn; problem; clear). Rules run in order after the existing ones.\n\nNeeds a token with the `board.manage` permission. Without it: *This token can't change lanes, swimlanes or flow rules. Ask the human to do it, or to create a token with that permission turned on.* Same as the MCP tool `add_flow_rule`.","tags":["Structure"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"swimlane":{"type":"string","description":"Swimlane name, like \"Bugs\". Optional; defaults to the first swimlane.","minLength":1,"maxLength":40},"on":{"type":"string","description":"The event that triggers it.","enum":["claimed","progress","needs_input","answered","completed","released","stale","pr_opened","pr_merged","pr_closed"]},"moveTo":{"type":"string","description":"Optional lane in the same swimlane to move the card to.","minLength":1,"maxLength":40},"setAttention":{"type":"string","description":"Optional flag to set: owner, problem, or clear.","enum":["owner","problem","clear"]},"enabled":{"type":"boolean","description":"Whether it runs (default true)."}},"required":["on"],"additionalProperties":false},"example":{"swimlane":"Features","on":"completed","moveTo":"Review","setAttention":"owner"}}}},"responses":{"201":{"description":"Created. The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project}/swimlanes":{"post":{"operationId":"add_swimlane","summary":"Add a swimlane","description":"Add a swimlane (a row of the board for one kind of work) with its own lanes and flow rules, from a preset or as a copy of another swimlane's lanes and rules (without its cards).\n\nNeeds a token with the `board.manage` permission. Without it: *This token can't change lanes, swimlanes or flow rules. Ask the human to do it, or to create a token with that permission turned on.* Same as the MCP tool `add_swimlane`.","tags":["Structure"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name, like \"Bugs\".","minLength":1,"maxLength":40},"preset":{"type":"string","description":"Starting lanes and rules: agentFlow (Ideas → Ready → Working → Needs you → Review → Shipped), bugTriage, research or simpleFlow (default).","enum":["agentFlow","bugTriage","research","simpleFlow"]},"copyOf":{"type":"string","description":"Copy this swimlane's lanes and rules instead.","minLength":1,"maxLength":40},"position":{"type":"integer","description":"Optional 1-based position among the swimlanes (1 is first). Omit to leave it where it is.","minimum":1,"maximum":50},"color":{"type":"string","description":"Optional color.","enum":["slate","blue","violet","pink","orange","amber","green","teal"]}},"required":["name"],"additionalProperties":false},"example":{"name":"Bugs","preset":"bugTriage","position":2}}}},"responses":{"201":{"description":"Created. The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"swimlane":{"type":"string"},"lanes":{"type":"array","items":{"type":"string"}}},"required":["swimlane","lanes"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project}/swimlanes/{swimlane}":{"patch":{"operationId":"update_swimlane","summary":"Edit a swimlane","description":"Rename, describe, recolor or reorder a swimlane, turn epics on or off for its cards, or turn its Backlog on or off (turning it off moves parked cards into the first lane).\n\nNeeds a token with the `board.manage` permission. Without it: *This token can't change lanes, swimlanes or flow rules. Ask the human to do it, or to create a token with that permission turned on.* Same as the MCP tool `update_swimlane`.","tags":["Structure"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"name":"swimlane","in":"path","required":true,"description":"Swimlane name, like \"Bugs\".","schema":{"type":"string","description":"Swimlane name, like \"Bugs\".","minLength":1,"maxLength":40}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New name.","minLength":1,"maxLength":40},"description":{"type":["string","null"],"description":"What goes in it. Pass \"\" to clear.","maxLength":280},"epics":{"type":"boolean","description":"Whether its cards show and take epics."},"backlog":{"type":"boolean","description":"Whether it has a Backlog for parked work."},"position":{"type":"integer","description":"Optional 1-based position among the swimlanes (1 is first). Omit to leave it where it is.","minimum":1,"maximum":50},"color":{"type":"string","description":"Optional color.","enum":["slate","blue","violet","pink","orange","amber","green","teal"]}},"required":[],"additionalProperties":false},"example":{"backlog":true,"description":"Everything that's broken"}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"swimlane":{"type":"string"},"moved":{"type":"integer"}},"required":["swimlane","moved"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"remove_swimlane","summary":"Remove a swimlane","description":"Delete a swimlane with its lanes and rules. Its cards (backlog included) move to a lane in another swimlane first, so nothing is lost. A board keeps at least one swimlane.\n\nNeeds a token with the `board.manage` permission. Without it: *This token can't change lanes, swimlanes or flow rules. Ask the human to do it, or to create a token with that permission turned on.* Same as the MCP tool `remove_swimlane`.","tags":["Structure"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"name":"swimlane","in":"path","required":true,"description":"Swimlane name, like \"Bugs\".","schema":{"type":"string","description":"Swimlane name, like \"Bugs\".","minLength":1,"maxLength":40}},{"name":"moveCardsToSwimlane","in":"query","required":true,"description":"The swimlane its cards move to.","schema":{"type":"string","description":"The swimlane its cards move to.","minLength":1,"maxLength":40},"example":"Features"},{"name":"moveCardsToLane","in":"query","required":false,"description":"The lane there. Defaults to its first lane.","schema":{"type":"string","description":"The lane there. Defaults to its first lane.","minLength":1,"maxLength":40}},{"$ref":"#/components/parameters/ClientName"}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"swimlane":{"type":"string"},"moved":{"type":"integer"}},"required":["swimlane","moved"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project}/swimlanes/{swimlane}/lanes":{"post":{"operationId":"add_lane","summary":"Add a lane","description":"Add a lane (a column) to a swimlane's flow, at the end unless you give a position.\n\nNeeds a token with the `board.manage` permission. Without it: *This token can't change lanes, swimlanes or flow rules. Ask the human to do it, or to create a token with that permission turned on.* Same as the MCP tool `add_lane`.","tags":["Structure"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"name":"swimlane","in":"path","required":true,"description":"Swimlane name, like \"Bugs\".","schema":{"type":"string","description":"Swimlane name, like \"Bugs\".","minLength":1,"maxLength":40}},{"$ref":"#/components/parameters/ClientName"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name, like \"Review\".","minLength":1,"maxLength":40},"description":{"type":["string","null"],"description":"Optional: what the lane means.","maxLength":280},"wipLimit":{"type":"integer","description":"Optional work-in-progress limit, 1–99.","minimum":1,"maximum":99},"done":{"type":"boolean","description":"Whether the lane holds finished work (Shipped, Fixed, Done): its cards stop counting as open."},"position":{"type":"integer","description":"Optional 1-based position among the swimlane's lanes (1 is first). Omit to leave it where it is.","minimum":1,"maximum":50},"color":{"type":"string","description":"Optional color.","enum":["slate","blue","violet","pink","orange","amber","green","teal"]}},"required":["name"],"additionalProperties":false},"example":{"name":"Review","wipLimit":3,"position":4}}}},"responses":{"201":{"description":"Created. The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"swimlane":{"type":"string"},"lane":{"type":"string"}},"required":["swimlane","lane"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project}/swimlanes/{swimlane}/lanes/{lane}":{"patch":{"operationId":"update_lane","summary":"Edit a lane","description":"Rename, describe, recolor or reorder a lane, set its WIP limit (0 clears it), or mark it as a done lane.\n\nNeeds a token with the `board.manage` permission. Without it: *This token can't change lanes, swimlanes or flow rules. Ask the human to do it, or to create a token with that permission turned on.* Same as the MCP tool `update_lane`.","tags":["Structure"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"name":"swimlane","in":"path","required":true,"description":"Swimlane name, like \"Bugs\".","schema":{"type":"string","description":"Swimlane name, like \"Bugs\".","minLength":1,"maxLength":40}},{"name":"lane","in":"path","required":true,"description":"Lane name, like \"Ready\" or \"Backlog\".","schema":{"type":"string","description":"Lane name, like \"Ready\" or \"Backlog\".","minLength":1,"maxLength":40}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New name.","minLength":1,"maxLength":40},"description":{"type":["string","null"],"description":"What the lane means. Pass \"\" to clear.","maxLength":280},"wipLimit":{"type":["integer","null"],"description":"Work-in-progress limit, 1–99; 0 clears it.","minimum":0,"maximum":99},"done":{"type":"boolean","description":"Whether the lane holds finished work (Shipped, Fixed, Done): its cards stop counting as open."},"position":{"type":"integer","description":"Optional 1-based position among the swimlane's lanes (1 is first). Omit to leave it where it is.","minimum":1,"maximum":50},"color":{"type":"string","description":"Optional color.","enum":["slate","blue","violet","pink","orange","amber","green","teal"]}},"required":[],"additionalProperties":false},"example":{"wipLimit":null}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"swimlane":{"type":"string"},"lane":{"type":"string"}},"required":["swimlane","lane"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"remove_lane","summary":"Remove a lane","description":"Delete a lane. Its cards move to another lane first (any swimlane), and rules that moved cards into it are switched off. A swimlane keeps at least one lane.\n\nNeeds a token with the `board.manage` permission. Without it: *This token can't change lanes, swimlanes or flow rules. Ask the human to do it, or to create a token with that permission turned on.* Same as the MCP tool `remove_lane`.","tags":["Structure"],"parameters":[{"name":"project","in":"path","required":true,"description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","schema":{"type":"string","description":"Project slug, name or card prefix, like \"getting-started\" or \"GS\".","minLength":1,"maxLength":80}},{"name":"swimlane","in":"path","required":true,"description":"Swimlane name, like \"Bugs\".","schema":{"type":"string","description":"Swimlane name, like \"Bugs\".","minLength":1,"maxLength":40}},{"name":"lane","in":"path","required":true,"description":"Lane name, like \"Ready\" or \"Backlog\".","schema":{"type":"string","description":"Lane name, like \"Ready\" or \"Backlog\".","minLength":1,"maxLength":40}},{"name":"moveCardsTo","in":"query","required":true,"description":"The lane its cards move to.","schema":{"type":"string","description":"The lane its cards move to.","minLength":1,"maxLength":40},"example":"Ready"},{"name":"moveCardsToSwimlane","in":"query","required":false,"description":"That lane's swimlane. Defaults to the same swimlane.","schema":{"type":"string","description":"That lane's swimlane. Defaults to the same swimlane.","minLength":1,"maxLength":40}},{"$ref":"#/components/parameters/ClientName"}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"lane":{"type":"string"},"moved":{"type":"integer"}},"required":["lane","moved"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/flow-rules/{rule}":{"patch":{"operationId":"update_flow_rule","summary":"Edit a flow rule","description":"Change a flow rule by its id (from get_flow_rules): its event, target lane (\"\" to stop moving), flag (\"\" to stop flagging), order, or switch it on or off.\n\nNeeds a token with the `board.manage` permission. Without it: *This token can't change lanes, swimlanes or flow rules. Ask the human to do it, or to create a token with that permission turned on.* Same as the MCP tool `update_flow_rule`.","tags":["Structure"],"parameters":[{"name":"rule","in":"path","required":true,"description":"The flow rule's id, from GET /projects/{project}/flow-rules.","schema":{"type":"string","description":"The flow rule's id, from GET /projects/{project}/flow-rules.","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"on":{"type":"string","description":"The event that triggers it.","enum":["claimed","progress","needs_input","answered","completed","released","stale","pr_opened","pr_merged","pr_closed"]},"moveTo":{"type":["string","null"],"description":"Lane in the same swimlane, or \"\" for none.","maxLength":40},"setAttention":{"type":["string","null"],"description":"owner, problem, clear, or \"\" for none.","enum":["owner","problem","clear",""]},"enabled":{"type":"boolean","description":"Switch it on or off."},"position":{"type":"integer","description":"Optional 1-based position among the swimlane's rules (1 is first). Omit to leave it where it is.","minimum":1,"maximum":50}},"required":[],"additionalProperties":false},"example":{"enabled":false}}}},"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"remove_flow_rule","summary":"Remove a flow rule","description":"Delete a flow rule by its id (from get_flow_rules). Cards stay where they are; the event just stops moving or flagging them. To pause a rule instead, update_flow_rule with enabled: false.\n\nNeeds a token with the `board.manage` permission. Without it: *This token can't change lanes, swimlanes or flow rules. Ask the human to do it, or to create a token with that permission turned on.* Same as the MCP tool `remove_flow_rule`.","tags":["Structure"],"parameters":[{"name":"rule","in":"path","required":true,"description":"The flow rule's id, from GET /projects/{project}/flow-rules.","schema":{"type":"string","description":"The flow rule's id, from GET /projects/{project}/flow-rules.","minLength":1,"maxLength":80}},{"$ref":"#/components/parameters/ClientName"}],"responses":{"200":{"description":"The tool's result.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"400":{"description":"The arguments aren't valid, or the change isn't possible as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The token is missing, invalid, revoked or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token can't do this, or a plan or board limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Something it names wasn't found, or isn't visible to this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many calls: retry after `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An agent token from Workspace settings → Agent tokens."}},"parameters":{"ClientName":{"name":"X-Client-Name","in":"header","required":false,"description":"Your agent's name on the board (default \"api\"). Cards you claim stay yours across requests with the same token and name.","schema":{"type":"string","maxLength":60},"example":"ci-bot"},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes a retry safe: the same key and request within 24 hours answers the first result again instead of creating a second one.","schema":{"type":"string","minLength":1,"maxLength":255},"example":"5f0c7a52-9d3e-4c1b-8a57-6f1e2d3c4b5a"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthenticated","forbidden","not_found","invalid","conflict","limit","rate_limited","unavailable","method_not_allowed","too_large","internal"]},"message":{"type":"string","description":"A sentence you can show a person, or relay to one."}},"required":["code","message"]}},"required":["error"]}}}}