Workflows

CRUD workflow definitions and advance page state with validation.

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.