> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```http theme={null}
GET /workflows
```

```json theme={null}
{ "workflows": [{ "name": "triage", "states": [...], "transitions": [...] }] }
```

```http theme={null}
GET /workflows/:name
```

Returns a single workflow definition.

## Save definition

```http theme={null}
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

```http theme={null}
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

```http theme={null}
POST /workflow/assign
Content-Type: application/json
```

```json theme={null}
{
  "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

```http theme={null}
POST /workflow/advance
Content-Type: application/json
```

```json theme={null}
{
  "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

```http theme={null}
POST /workflow/reorder
Content-Type: application/json
```

```json theme={null}
{
  "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

```http theme={null}
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](/concepts/mcp).