Workflows

A workflow is a state machine stored as JSON in .kiwi/workflows/<name>.json. A page joins a workflow through its workflow and state frontmatter fields. These endpoints edit definitions, move pages between states with transition checks, and return the kanban board the web UI renders. See Workflows for the model. Page updates (assign, advance, reorder) go through the write pipeline with an internal If-Match check, so a page edited between the server’s read and write returns 409. Retry the request.

List workflows

Return every workflow definition.

GET /api/kiwi/workflows

curl 'http://localhost:3333/api/kiwi/workflows'

object[]

Valid workflow definitions. See Workflow definition for the shape.

string[]

One message per workflow file that failed to parse or validate. Omitted when every file loaded.

{
  "workflows": [
    {
      "name": "triage",
      "states": [
        { "name": "open", "color": "#6b7280" },
        { "name": "in_progress", "wip_limit": 3 },
        { "name": "done", "terminal": true }
      ],
      "transitions": [
        { "from": "open", "to": "in_progress" },
        { "from": "in_progress", "to": "done" }
      ]
    }
  ],
  "errors": [".kiwi/workflows/broken.json: invalid character '}' looking for beginning of value"]
}

Get a workflow

Return one workflow definition.

GET /api/kiwi/workflows/:name

string

required

Workflow name (the file name without .json).

curl 'http://localhost:3333/api/kiwi/workflows/triage'

Returns 404 if the workflow does not exist. The response is a workflow definition.

Save a workflow

Create or replace a workflow definition. The name in the URL wins over any name in the body.

PUT /api/kiwi/workflows/:name

string

required

Workflow name. Must not contain / or \, or leading or trailing spaces.

object[]

required

At least one state. Names must be unique.

object[]

required

Allowed moves. Every from and to must name a defined state, and terminal states can’t have outbound transitions.

curl -X PUT 'http://localhost:3333/api/kiwi/workflows/triage' \
  -H "Content-Type: application/json" \
  -d '{
    "states": [
      {"name": "open"},
      {"name": "in_progress", "wip_limit": 3},
      {"name": "done", "terminal": true}
    ],
    "transitions": [
      {"from": "open", "to": "in_progress"},
      {"from": "in_progress", "to": "done"}
    ]
  }'

Returns 400 for invalid JSON or a definition that fails validation. The body limit is 1 MB.

string

Always saved.

object

The saved definition.

{ "status": "saved", "workflow": { "name": "triage", "states": [/* ... */], "transitions": [/* ... */] } }

Workflow definition

string

Workflow name.

object[]

Board columns, in display order.

Show properties

string

State name, stored in the page’s state field.

string

Hex color for the web UI.

boolean

Pages in this state can’t move out.

integer

Maximum pages in this state. 0 or omitted means unlimited.

object[]

Allowed moves.

Show properties

string

Source state.

string

Target state.

string

Optional role label stored with the transition.

Delete a workflow

Delete a workflow definition file.

DELETE /api/kiwi/workflows/:name

string

required

Workflow name.

curl -X DELETE 'http://localhost:3333/api/kiwi/workflows/triage'

Returns 404 if the workflow does not exist. Pages that reference it keep their workflow and state fields but can no longer be advanced.

{ "status": "deleted", "name": "triage" }

Assign a page to a workflow

Set a page’s workflow and state frontmatter, either to add it to a workflow or to place it in a column directly. Assignment does not check transitions.

POST /api/kiwi/workflow/assign

string

required

Markdown page path. Must end in .md.

string

required

Workflow name.

string

required

Target state. Matched case-insensitively and stored with the workflow’s spelling.

integer

Position within the column. Lower values sort first.

string

Commit author. Falls back to the X-Actor header, then system.

curl -X POST 'http://localhost:3333/api/kiwi/workflow/assign' \
  -H "Content-Type: application/json" \
  -d '{"path": "tasks/t-42.md", "workflow": "triage", "state": "open", "actor": "agent:bot"}'

Returns 400 for a missing field, a non-markdown path, or an unknown state, and 404 if the workflow or page does not exist.

string

Page path.

string

Workflow name.

string

Stored state name.

string

Git blob hash of the page after the call.

boolean

true when the page already had this workflow and state and no ordinal was given, so nothing was written.

{ "path": "tasks/t-42.md", "workflow": "triage", "state": "open", "etag": "5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d" }

Advance a page

Move a page to another state, enforcing the workflow’s rules. The server also sets modified to the current UTC time and, if the page has a status field that mirrored the old state, updates status too.

POST /api/kiwi/workflow/advance

string

required

Markdown page path. The page must have workflow and state frontmatter.

string

required

State to move to.

string

Expected workflow. If set and it differs from the page’s workflow, the call fails with 409.

string

Commit author. Falls back to the X-Actor header, then system.

curl -X POST 'http://localhost:3333/api/kiwi/workflow/advance' \
  -H "Content-Type: application/json" \
  -d '{"path": "tasks/t-42.md", "target_state": "in_progress", "actor": "agent:bot"}'

The call returns 409 when:

the target state does not exist in the workflow
the current state is terminal
no transition goes from the current state to the target
the target column is at its wip_limit
the target is in_progress and the page is blocked (a blocked_by page isn’t finished, or blocked: true)
the page changed during the request

It returns 400 when the page has no frontmatter, workflow, or state, and 404 when the page or workflow does not exist.

string

Page path.

string

State before the call.

string

State after the call.

string

Git blob hash of the page after the call.

boolean

true when the page was already in target_state.

{ "path": "tasks/t-42.md", "from_state": "open", "to_state": "in_progress", "etag": "7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b" }

Reorder a card

Set a page’s ordinal frontmatter field, which controls its position within its board column.

POST /api/kiwi/workflow/reorder

string

required

Page path.

integer

required

New position. Cards sort by ascending ordinal; cards without one sort last. Leave gaps (the web UI uses steps of 1000) so you can insert between cards.

string

Commit author. Falls back to the X-Actor header, then system.

curl -X POST 'http://localhost:3333/api/kiwi/workflow/reorder' \
  -H "Content-Type: application/json" \
  -d '{"path": "tasks/t-42.md", "ordinal": 1500}'

Returns 404 if the page does not exist.

string

Page path.

integer

Stored ordinal.

string

Git blob hash of the page after the call.

boolean

true when the page already had this ordinal.

{ "path": "tasks/t-42.md", "ordinal": 1500, "etag": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b" }

Get the kanban board

Return the workflow definition and every markdown page in it, grouped by state.

GET /api/kiwi/workflow/board/:workflow

string

required

Workflow name.

curl 'http://localhost:3333/api/kiwi/workflow/board/triage'

Returns 404 if the workflow does not exist.

object

The workflow definition.

object

Map from state name to an array of cards. Every state has a key, even when empty. Pages whose state isn’t in the workflow appear under __unmatched__.

Show card properties

string

Page path.

string

Page’s state value.

string

Frontmatter title, or the file name.

any

Frontmatter priority, if set.

string[]

Frontmatter tags, if set.

string

Frontmatter due, if set.

string

Frontmatter author, if set.

integer

Column position, if set.

string[]

Frontmatter depends_on, if set.

boolean

true if the card is blocked.

string

Why the card is blocked.

string

Short excerpt of the page body.

string

Frontmatter modified, or the file’s modification time (RFC 3339).

{
  "workflow": { "name": "triage", "states": [/* ... */], "transitions": [/* ... */] },
  "board": {
    "open": [
      { "path": "tasks/t-15.md", "state": "open", "title": "Fix login redirect", "priority": "high", "ordinal": 1000 }
    ],
    "in_progress": [
      { "path": "tasks/t-42.md", "state": "in_progress", "title": "Rotate API keys", "modified": "2026-10-18T09:12:00Z" }
    ],
    "done": []
  }
}

MCP equivalents

kiwi_workflow_list, kiwi_workflow_get, kiwi_workflow_save, kiwi_workflow_advance, and kiwi_workflow_board. Assign, reorder, and delete are REST-only.

Workflows concepts

States, transitions, WIP limits, and blocked cards.

Claims

Lease a page before an agent works on it.

REST API

CLI

List workflows

Get a workflow

Save a workflow

Workflow definition

Delete a workflow

Assign a page to a workflow

Advance a page

Reorder a card

Get the kanban board

MCP equivalents

Workflows concepts

Claims

​List workflows

​Get a workflow

​Save a workflow

​Workflow definition

​Delete a workflow

​Assign a page to a workflow

​Advance a page

​Reorder a card

​Get the kanban board

​MCP equivalents

​Related

Workflows concepts

Claims

List workflows

Get a workflow

Save a workflow

Workflow definition

Delete a workflow

Assign a page to a workflow

Advance a page

Reorder a card

Get the kanban board

MCP equivalents

Related