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/overview

Get boards overview

Returns aggregated card counts and notification summaries for all boards. Notification counts are null when the card.state plugin is not configured.

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, metadata, title, 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}/export

Export board settings

Exports the board configuration plus board-relevant workspace fragments (labels, forms, hook-related plugin config) as a versioned JSON archive. Card content, comments, attachments, and logs are not included.

Parameters

Responses

POST /api/boards/import

Import board settings

Imports a board-settings archive produced by the export endpoint. By default, importing a board whose ID already exists returns a 400 error. Pass overwrite: true in the request body to replace the existing board config. Workspace fragments (labels, forms, plugin config) are merged without touching unrelated global settings.

Request Body

Required: Yes

Schema: object

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 a server-owned permissions capability envelope plus 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. Active-task read models include server-owned permissions, resolved form descriptors in resolvedForms, and caller-scoped cardState 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 server-owned permissions, resolved form descriptors in resolvedForms, and side-effect-free cardState.unread / 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

GET /api/tasks/{id}/checklist

List checklist items

Returns the shared checklist read model for the task on the default board.

Parameters

Responses

POST /api/tasks/{id}/checklist

Add checklist item

Appends a new checklist item to the task on the default board and returns the refreshed checklist read model.

Parameters

Request Body

Required: Yes

Responses

PUT /api/tasks/{id}/checklist/{index}

Edit checklist item

Edits one checklist item on the task and returns the refreshed checklist read model. Supply expectedRaw to guard against stale concurrent edits.

Parameters

Request Body

Required: Yes

Responses

DELETE /api/tasks/{id}/checklist/{index}

Delete checklist item

Deletes one checklist item on the task and returns the refreshed checklist read model. Supply expectedRaw to guard against stale concurrent edits.

Parameters

Request Body

Required: No

Responses

POST /api/tasks/{id}/checklist/{index}/check

Check checklist item

Marks one checklist item complete and returns the refreshed checklist read model. Supply expectedRaw to guard against stale concurrent edits.

Parameters

Request Body

Required: No

Responses

POST /api/tasks/{id}/checklist/{index}/uncheck

Uncheck checklist item

Marks one checklist item incomplete and returns the refreshed checklist read model. Supply expectedRaw to guard against stale concurrent edits.

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 a server-owned permissions capability envelope plus 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. Active-task read models include server-owned permissions, resolved form descriptors in resolvedForms, and caller-scoped cardState 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 server-owned permissions, resolved form descriptors in resolvedForms, and side-effect-free cardState.unread / 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

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

List checklist items (board-scoped)

Returns the shared checklist read model for one task on the specified board.

Parameters

Responses

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

Add checklist item (board-scoped)

Appends a new checklist item to the task on the specified board and returns the refreshed checklist read model.

Parameters

Request Body

Required: Yes

Responses

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

Edit checklist item (board-scoped)

Edits one checklist item on the specified board and returns the refreshed checklist read model. Supply expectedRaw to guard against stale concurrent edits.

Parameters

Request Body

Required: Yes

Responses

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

Delete checklist item (board-scoped)

Deletes one checklist item on the specified board and returns the refreshed checklist read model. Supply expectedRaw to guard against stale concurrent edits.

Parameters

Request Body

Required: No

Responses

POST /api/boards/{boardId}/tasks/{id}/checklist/{index}/check

Check checklist item (board-scoped)

Marks one checklist item complete and returns the refreshed checklist read model. Supply expectedRaw to guard against stale concurrent edits.

Parameters

Request Body

Required: No

Responses

POST /api/boards/{boardId}/tasks/{id}/checklist/{index}/uncheck

Uncheck checklist item (board-scoped)

Marks one checklist item incomplete and returns the refreshed checklist read model. Supply expectedRaw to guard against stale concurrent edits.

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

Plugins

Plugin discovery, selection, options, and guarded installation

GET /api/plugin-settings

List plugin providers

Returns the capability-grouped plugin inventory with selected-provider state and shared redaction metadata. config.storage rows include configured-versus-effective resolution details, including explicit failure or degraded/read-only state when the SDK reports one. Secret values are never included in this list payload. When auth is active, callers must be authenticated and allowed to perform plugin-settings.read; redaction supplements authorization rather than replacing it.

Responses

GET /api/plugin-settings/{capability}/{providerId}

Read plugin settings

Returns the redacted plugin-settings read model for one provider. config.storage reads include configured-versus-effective resolution details so clients can distinguish explicit configured state from the current effective provider and any surfaced failure/degraded mode. Persisted secret fields are masked and surfaced only as write-only placeholders. When auth is active, callers must be authenticated and allowed to perform plugin-settings.read; allowed reads remain redacted.

Parameters

Responses

PUT /api/plugin-settings/{capability}/{providerId}/select

Select plugin provider

Persists the selected provider for one capability. Existing authorization wrappers remain in force for this privileged mutation. For config.storage, Worker topology-changing updates are rejected as explicit runtime-mutation errors instead of silently swapping the effective provider.

Parameters

Responses

PUT /api/plugin-settings/{capability}/{providerId}/options

Update plugin options

Persists provider options and returns the redacted provider read model. Secret placeholders may be submitted unchanged to preserve existing stored secrets. config.storage responses continue to surface configured-versus-effective resolution and any explicit failure/degraded state reported by the SDK.

Parameters

Request Body

Required: Yes

Responses

POST /api/plugin-settings/install

Install plugin package

Runs the guarded in-product installer for exact unscoped kl-* package names only. Responses surface redacted diagnostics and never expose raw installer stdout/stderr.

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 and the configured-versus-effective config.storage resolution state.

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 storage providers plus host-facing file/watch metadata and the configured-versus-effective config.storage resolution, including explicit failure or degraded/read-only state when present.

Responses

GET /api/events

List available events

Returns discoverable SDK events, including built-in before/after events and any plugin-declared additions. Supports filtering by phase and wildcard mask.

Parameters

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-plugin-storage-sqlite) 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

Mobile

Minimal mobile bootstrap and opaque local-session contract for the Expo field app.

POST /api/mobile/bootstrap

Resolve mobile workspace bootstrap

Normalizes a typed workspace origin, deep link, or QR payload into the canonical local-auth mobile bootstrap contract. When a one-time bootstrap token is present, the response keeps the client on the token-redemption branch instead of inventing a second login abstraction.

Request Body

Required: Yes

Responses

POST /api/mobile/session

Create a mobile opaque bearer session

Available when the local standalone auth provider is active. Exchanges local credentials or a validated one-time bootstrap token for a server-backed opaque mobile bearer session without reusing the browser cookie transport.

Request Body

Required: Yes

Responses

GET /api/mobile/session

Validate a stored mobile session

Validates a previously issued opaque mobile bearer token for cold-start and resume gating. Shared automation tokens and browser cookie sessions are not accepted here.

Parameters

Responses

DELETE /api/mobile/session

Revoke a stored mobile session

Revokes the current opaque mobile bearer token for mobile logout. Shared automation tokens and browser cookie sessions are not accepted here.

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