Skip to main content
Workflow JSON files live in .kiwi/workflows/. Pages reference them with frontmatter keys workflow and state. Base path: http://localhost:3333/api/kiwi.

​
List and read

GET /workflows

{ "workflows": [{ "name": "triage", "states": [...], "transitions": [...] }] }

GET /workflows/:name
Returns a single workflow definition.

​
Save definition

PUT /workflows/:name
Content-Type: application/json
Body is the full workflow JSON. The server sets name from the URL segment and validates structure.

​
Delete a workflow

DELETE /workflows/:name
Removes a workflow definition. Pages referencing this workflow keep their current state but can no longer be advanced.

​
Assign a page to a workflow

POST /workflow/assign
Content-Type: application/json

{
  "path": "tasks/t-42.md",
  "workflow": "triage",
  "state": "open",
  "actor": "agent:bot"
}
Sets the workflow and state frontmatter fields on the page. Use this to onboard a page into a workflow for the first time.

​
Advance a page

POST /workflow/advance
Content-Type: application/json

{
  "path": "tasks/t-42.md",
  "target_state": "done",
  "actor": "agent:bot"
}
  • Requires the page to have workflow and state in frontmatter.
  • Validates (state → target_state) against the workflow’s transitions.
  • Writes the page with updated state via the normal pipeline.
Returns 409 when the transition is not allowed.

​
Reorder items on the board

POST /workflow/reorder
Content-Type: application/json

{
  "workflow": "triage",
  "state": "in_progress",
  "paths": ["tasks/t-42.md", "tasks/t-15.md", "tasks/t-99.md"]
}
Sets the display order of pages within a workflow state column. The paths array defines the new order top-to-bottom.

​
Kanban board

GET /workflow/board/:workflow
Returns { "workflow": { ... }, "board": { "<state>": [ { "path", "title", ... } ] } } grouping markdown pages that declare the given workflow name.

​
MCP parity

kiwi_workflow_list, kiwi_workflow_get, kiwi_workflow_save, kiwi_workflow_advance, kiwi_workflow_board — see MCP.
Last modified on May 31, 2026