Nerve Kanban API Skill#

Use this skill to manage tasks on the Nerve Kanban board via its REST API.

Base URL#

All endpoints are relative to the Nerve server origin (e.g. http://localhost:3000). Prefix every path with /api/kanban.

Core Concepts#

• Tasks flow through columns: backlog → todo → in-progress → review → done (or cancelled).
• CAS versioning: Updates and reorders require the current version number. If it mismatches, you get a 409 version_conflict with the server's latest task. Re-read and retry.
• Workflow actions enforce valid transitions. You can't execute a task that's already in review.
• Proposals let agents suggest task creation or updates. The operator (or auto-policy) approves/rejects them.
• Actors are either "operator" or "agent:<name>".

Quick Reference#

ActionMethodPathList tasksGET/api/kanban/tasksCreate taskPOST/api/kanban/tasksUpdate taskPATCH/api/kanban/tasks/:idDelete taskDELETE/api/kanban/tasks/:idReorder/movePOST/api/kanban/tasks/:id/reorderExecute (spawn agent)POST/api/kanban/tasks/:id/executeApprove (review→done)POST/api/kanban/tasks/:id/approveReject (review→todo)POST/api/kanban/tasks/:id/rejectAbort (in-progress→todo)POST/api/kanban/tasks/:id/abortComplete run (webhook)POST/api/kanban/tasks/:id/completeList proposalsGET/api/kanban/proposalsCreate proposalPOST/api/kanban/proposalsApprove proposalPOST/api/kanban/proposals/:id/approveReject proposalPOST/api/kanban/proposals/:id/rejectGet configGET/api/kanban/configUpdate configPUT/api/kanban/config

Common Patterns#

Creating and executing a task#

1. POST /api/kanban/tasks with { "title": "...", "description": "..." } → returns task with id and version.
2. POST /api/kanban/tasks/:id/execute → moves to in-progress, spawns an agent session.
3. The agent session runs, and on completion the task moves to review automatically.
4. POST /api/kanban/tasks/:id/approve → moves to done.

Handling version conflicts#

Always send version in PATCH and reorder requests. On 409, read latest from the response and retry with the updated version.

Proposing changes (as an agent)#

Agents that can't directly modify the board should use proposals:

1. POST /api/kanban/proposals with { "type": "create", "payload": { "title": "..." }, "proposedBy": "agent:myname" }.
2. The operator approves or rejects via /api/kanban/proposals/:id/approve or /api/kanban/proposals/:id/reject.

Full API Reference#

See references/api.md for complete endpoint documentation, type definitions, error codes, and example requests.