curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"content": "# My task", "status": "todo", "priority": "high"}'

Kanban Lite REST API

This file is generated from packages/kanban-lite/src/standalone/internal/openapi-spec.ts plus active standalone plugin API metadata via scripts/generate-api-docs.ts.

Version: 1.0.0

• Authoritative source: Swagger/OpenAPI in packages/kanban-lite/src/standalone/internal/openapi-spec.ts plus standalone plugin API metadata discovered during docs generation
• Interactive docs: http://localhost:3000/api/docs
• OpenAPI JSON: http://localhost:3000/api/docs/json
• Base API URL: http://localhost:3000/api

The standalone server exposes a full REST API for managing kanban boards programmatically.

Base URL: http://localhost:3000/api

Start the server with kl serve or kanban-md. Use --port <number> to change the port.

Response envelope:

{ "ok": true, "data": { ... } }   // success
{ "ok": false, "error": "..." }    // error

CORS is enabled for all origins.

Conventions: Card/task IDs support partial matching within a board. /api/tasks/* operates on the default board; /api/boards/:boardId/tasks/* targets a specific board explicitly.

Boards

Board CRUD and board-level actions

GET /api/boards

List boards

Returns all boards in the workspace.

Responses

POST /api/boards

Create board

Creates a new board and persists it to .kanban.json. When columns is omitted, the board inherits the default board's columns (or built-in standard columns when the default board has none).

Request Body

Required: Yes

Responses

GET /api/boards/{boardId}

Get board

Returns the full configuration for a board.

Parameters

Responses

PUT /api/boards/{boardId}

Update board

Updates an existing board in place. Only provided fields are changed; omitted properties keep their current values.

Parameters

Request Body

Required: Yes

Any subset of board config fields: name, description, columns, defaultStatus, defaultPriority.

Responses

DELETE /api/boards/{boardId}

Delete board

Deletes a board. The board must be empty (no cards) and cannot be the default board.

Parameters

Responses

GET /api/boards/{boardId}/actions

Get board actions

Returns the defined actions for the board as a map of key → title.

Parameters

Responses

POST /api/boards/{boardId}/actions

Set board actions

Replaces all board actions with the provided set. Keys present in the existing set but absent from the new set are removed.

Parameters

Request Body

Required: Yes

Responses

PUT /api/boards/{boardId}/actions/{key}

Add/update board action

Adds a new board action or updates the title of an existing one.

Parameters

Request Body

Required: Yes

Responses

DELETE /api/boards/{boardId}/actions/{key}

Delete board action

Removes a board action by key.

Parameters

Responses

POST /api/boards/{boardId}/actions/{key}/trigger

Trigger board action

Fires the configured webhook for the named board action.

Parameters

Responses

GET /api/boards/{boardId}/columns

List board columns

Returns the ordered column definitions for the specified board, including each column's id, display name, and color.

Parameters

Responses

Tasks

Task operations on the default board

GET /api/tasks

List tasks

Returns tasks on the default board. Supports exact free-text search via q, optional fuzzy matching via fuzzy=true, and field-scoped metadata filters via meta.<field>=value. Read models include side-effect-free cardState.unread and cardState.open metadata for the current actor; this is separate from active-task UI state.

Parameters

Responses

POST /api/tasks

Create task

Creates a task on the default board. Title is derived from the first Markdown # heading. Omitted status/priority fall back to board defaults.

Request Body

Required: Yes

Responses

GET /api/tasks/active

Get active task

Returns the currently active/open task on the default board, or null when no task is active. This is separate from actor-scoped card.state open/unread metadata.

Responses

GET /api/tasks/{id}

Get task

Returns a single task from the default board. The :id segment supports partial ID matching. Read models include side-effect-free cardState.unread and cardState.open metadata for the current actor; this is separate from active-task UI state.

Parameters

Responses

PUT /api/tasks/{id}

Update task

Updates an existing task. Only the supplied fields are modified; omitted fields remain unchanged.

Parameters

Request Body

Required: Yes

Any subset of task fields: content, status, priority, assignee, dueDate, labels, metadata, forms, formData, actions.

Responses

DELETE /api/tasks/{id}

Delete task

Soft-deletes a task by moving it into the hidden deleted column.

Parameters

Responses

POST /api/tasks/{id}/open

Mark task opened

Persists an explicit actor-scoped open mutation through the shared SDK card.state APIs. This does not modify active-card UI state.

Parameters

Responses

POST /api/tasks/{id}/read

Mark task read

Persists an explicit actor-scoped unread acknowledgement through the shared SDK card.state APIs. Read-only GET routes never invoke this mutation implicitly.

Parameters

Request Body

Required: No

Responses

POST /api/tasks/{id}/forms/{formId}/submit

Submit task form

Validates and persists a card form submission. Merge order: config defaults → card attachment defaults / existing formData → matching card metadata → submitted data. Emits the form.submit webhook event.

Parameters

Request Body

Required: Yes

Responses

PATCH /api/tasks/{id}/move

Move task

Moves a task to a different column and/or position on the default board.

Parameters

Request Body

Required: Yes

Responses

DELETE /api/tasks/{id}/permanent

Permanently delete task

Permanently and irreversibly deletes a task from the default board. This cannot be undone.

Parameters

Responses

POST /api/tasks/{id}/actions/{action}

Trigger task action

Fires the configured webhook for the named card-level action.

Parameters

Responses

Board Tasks

Board-scoped task operations

GET /api/boards/{boardId}/tasks

List tasks (board-scoped)

Returns tasks for the specified board. Supports the same q, fuzzy, meta.*, and field filters as /api/tasks. Read models include side-effect-free cardState.unread and cardState.open metadata for the current actor; this is separate from active-task UI state.

Parameters

Responses

POST /api/boards/{boardId}/tasks

Create task (board-scoped)

Creates a task on the specified board. Title is derived from the first Markdown # heading. Omitted status/priority fall back to the board defaults.

Parameters

Request Body

Required: Yes

Responses

GET /api/boards/{boardId}/tasks/active

Get active task (board-scoped)

Returns the currently active/open task for the board, or null when none is active. This is separate from actor-scoped card.state open/unread metadata.

Parameters

Responses

GET /api/boards/{boardId}/tasks/{id}

Get task (board-scoped)

Returns a single task from the specified board. The :id segment supports partial ID matching. Read models include side-effect-free cardState.unread and cardState.open metadata for the current actor; this is separate from active-task UI state.

Parameters

Responses

PUT /api/boards/{boardId}/tasks/{id}

Update task (board-scoped)

Updates fields of a task. Only supplied fields are modified; omitted fields remain unchanged.

Parameters

Request Body

Required: Yes

Any subset of task fields: content, status, priority, assignee, dueDate, labels, metadata, forms, formData, actions.

Responses

DELETE /api/boards/{boardId}/tasks/{id}

Delete task (board-scoped)

Soft-deletes the task by moving it to the hidden deleted column.

Parameters

Responses

POST /api/boards/{boardId}/tasks/{id}/open

Mark task opened (board-scoped)

Persists an explicit actor-scoped open mutation through the shared SDK card.state APIs. This does not modify active-card UI state.

Parameters

Responses

POST /api/boards/{boardId}/tasks/{id}/read

Mark task read (board-scoped)

Persists an explicit actor-scoped unread acknowledgement through the shared SDK card.state APIs. Read-only GET routes never invoke this mutation implicitly.

Parameters

Request Body

Required: No

Responses

PATCH /api/boards/{boardId}/tasks/{id}/move

Move task (board-scoped)

Moves a task to a different column and/or position within the board.

Parameters

Request Body

Required: Yes

Responses

POST /api/boards/{boardId}/tasks/{id}/forms/{formId}/submit

Submit task form (board-scoped)

Validates and persists a card form submission. Merge order: config defaults → card attachment defaults / existing formData → matching card metadata → submitted data. Emits the form.submit webhook event.

Parameters

Request Body

Required: Yes

Responses

POST /api/boards/{boardId}/tasks/{id}/actions/{action}

Trigger task action (board-scoped)

Fires the configured webhook for the named card-level action.

Parameters

Responses

DELETE /api/boards/{boardId}/tasks/{id}/permanent

Permanently delete task (board-scoped)

Permanently and irreversibly removes the task. This cannot be undone.

Parameters

Responses

POST /api/boards/{boardId}/tasks/{id}/transfer

Transfer task to another board

Moves a task from the current board context to the specified destination board. The :boardId path segment is the destination board. The source board is the server's currently active board context.

Parameters

Request Body

Required: No

Responses

Columns

Column management for the default board

GET /api/columns

List columns

Returns the ordered column definitions for the default board.

Responses

POST /api/columns

Add column

Creates a new column on the default board. New columns are appended to the end of the board's current column order.

Request Body

Required: Yes

Responses

PUT /api/columns/reorder

Reorder columns

Reorders the columns for the specified board (or default board if boardId is omitted).

Parameters

Request Body

Required: Yes

Responses

PUT /api/columns/minimized

Set minimized columns

Sets which columns are minimized for the specified board (or default board if boardId is omitted).

Parameters

Request Body

Required: Yes

Responses

PUT /api/columns/{id}

Update column

Updates a column's display name and/or color on the default board.

Parameters

Request Body

Required: Yes

Responses

DELETE /api/columns/{id}

Delete column

Deletes a column on the default board. Fails if the column still contains tasks.

Parameters

Responses

Comments

Task comment threads

GET /api/tasks/{id}/comments

List comments

Returns all comments currently attached to the task, in stored order.

Parameters

Responses

POST /api/tasks/{id}/comments

Add comment

Adds a new comment to the task and emits the comment.created webhook event.

Parameters

Request Body

Required: Yes

Responses

PUT /api/tasks/{id}/comments/{commentId}

Update comment

Updates the Markdown content of an existing comment.

Parameters

Request Body

Required: Yes

Responses

DELETE /api/tasks/{id}/comments/{commentId}

Delete comment

Deletes the specified comment from the task.

Parameters

Responses

Attachments

File attachments on tasks

POST /api/tasks/{id}/attachments

Upload attachments

Uploads one or more files as task attachments. Files are sent as base64-encoded strings in a JSON body and stored through the active attachment-storage provider.

Parameters

Request Body

Required: Yes

Responses

GET /api/tasks/{id}/attachments/{filename}

Download attachment

Materializes and streams the named attachment back to the client. Most browsers render known types (PDFs, images) inline unless ?download=1 is set.

Parameters

Responses

DELETE /api/tasks/{id}/attachments/{filename}

Delete attachment

Removes the named attachment from the task and deletes the provider-backed payload when supported.

Parameters

Responses

Logs

Append-only log entries on tasks and boards

GET /api/boards/{boardId}/logs

List board logs

Returns all board-level log entries.

Parameters

Responses

POST /api/boards/{boardId}/logs

Add board log

Appends a log entry to the board.

Parameters

Request Body

Required: Yes

Responses

DELETE /api/boards/{boardId}/logs

Clear board logs

Removes all board-level log entries.

Parameters

Responses

GET /api/tasks/{id}/logs

List task logs

Returns all log entries for the task.

Parameters

Responses

POST /api/tasks/{id}/logs

Add task log

Appends a log entry to the task.

Parameters

Request Body

Required: Yes

Responses

DELETE /api/tasks/{id}/logs

Clear task logs

Removes all log entries for the task.

Parameters

Responses

Settings

Workspace display settings

GET /api/settings

Get settings

Returns the workspace's current display and behavior settings used by the UI surfaces.

Responses

PUT /api/settings

Update settings

Updates workspace display settings and immediately broadcasts the change to connected WebSocket clients.

Request Body

Required: Yes

Responses

Labels

Label definitions and cascading renames

GET /api/labels

List labels

Returns all label definitions with their colors and groups.

Responses

PUT /api/labels/{name}

Set label

Creates or updates a label definition (color and optional group).

Parameters

Request Body

Required: Yes

Responses

PATCH /api/labels/{name}

Rename label

Renames a label and cascades the change to all cards that use it.

Parameters

Request Body

Required: Yes

Responses

DELETE /api/labels/{name}

Delete label

Deletes a label definition and removes it from all cards that reference it.

Parameters

Responses

Workspace

Workspace metadata, storage, and auth status

GET /api/card-state/status

Get card-state status

Returns the active card.state provider status for the standalone runtime, including backend family, availability, the stable auth-absent default actor contract, and whether a configured auth.identity provider is currently causing identity-unavailable failures.

Responses

GET /api/workspace

Get workspace info

Returns workspace-level connection metadata plus resolved storage, auth, webhook, and card.state provider information, including filesystem watcher support.

Responses

GET /api/auth

Get auth status

Returns auth provider metadata plus safe request-scoped token diagnostics for the current standalone HTTP request.

Responses

GET /api/storage

Get storage status

Returns the active card, attachment, webhook, and card.state provider IDs plus host-facing file/watch metadata.

Responses

POST /api/storage/migrate-to-sqlite

Migrate to SQLite

Migrates cards from the built-in markdown provider to the first-party sqlite compatibility provider (kl-sqlite-storage) and updates compatibility config fields in .kanban.json. This endpoint does not migrate into arbitrary external providers.

Request Body

Required: No

Responses

POST /api/storage/migrate-to-markdown

Migrate to Markdown

Migrates cards from the built-in SQLite provider back to markdown files and updates compatibility config fields. Existing source data is left in place as a manual backup.

Responses

GET /api/resolve-path

Resolve path

Resolves a workspace-relative, absolute, or ~-prefixed path to its canonical absolute filesystem path.

Parameters

Responses

Webhooks

Webhook registration endpoints. These routes are registered by the active standalone webhook plugin while preserving the public /api/webhooks contract.

GET /api/webhooks

List webhooks

Returns all registered webhooks. Runtime ownership stays on the active standalone webhook plugin, which preserves this public path.

Responses

POST /api/webhooks

Create webhook

Registers a new webhook endpoint through the active standalone webhook plugin.

Request Body

Required: Yes

Responses

PUT /api/webhooks/{id}

Update webhook

Updates an existing webhook by id through the active standalone webhook plugin.

Parameters

Request Body

Required: Yes

Responses

DELETE /api/webhooks/{id}

Delete webhook

Deletes a webhook by id through the active standalone webhook plugin.

Parameters

Responses