---
title: "Create or update a kanban column"
method: POST
path: "/api/boards/{boardId}/columns"
tags: ["Kanban"]
---

# Create or update a kanban column

`POST /api/boards/{boardId}/columns`

## Request

- Base URL: `https://cnvs.app`
- URL: `https://cnvs.app/api/boards/{boardId}/columns`
- Auth: none declared

Mirrors the MCP `create_column` / `update_column` tools. Only valid on a `todo`-mode board. Creates a NEW column with a fresh UUID, OR updates an existing column in place if you pass its `id`. Max 200 columns per board (≤ 20 per row, ≤ 10 rows).

## Request body

- AddColumnRequest
  - `id` string: Pass an existing id to UPDATE that column; omit to CREATE a new one.
  - `title` string, required
  - `sort` number: Left-to-right position. Defaults to the end if omitted on create.
  - `lane` integer: Optional row index for multi-lane layout. Defaults to 0 (top row).
  - `color` 'red' | 'blue' | 'green': Optional column title color — one of `red` / `blue` / `green`. Omit for the default.

## Response `200`

Column created or updated.

- Column: A kanban column on a `todo`-mode board.
  - `id` string, required
  - `title` string, required
  - `sort` number: Left-to-right order of the column.
  - `lane` integer: Row index for multi-lane layout. Defaults to 0 (top row).
  - `color` 'red' | 'blue' | 'green' | 'null', nullable: Column title color — one of `red` / `blue` / `green`, or null for the default.
  - `author` string, nullable
  - `last_updated` string: UTC timestamp.

## Other responses

- `400`: Invalid input (missing or malformed board id).
- `401`: Board is access-locked and the request did not carry a valid key. `lockMode` tells the client whether to prompt for a code or just disable write UI.
- `404`: Board does not exist or was deleted within the 30-day tombstone window.
- `413`: Per-board quota exceeded (too many texts, images, strokes, or total image bytes). Response body names the specific limit that was hit.
- `429`: Rate limit exceeded. Standard REST/MCP: 60 requests/10s/board; valid X-Import-Token infrastructure tier: 600/10s/board; browser WebSocket always 60/10s/board. REST/MCP enforcement is soft per-isolate; WebSocket enforcement is strong per Durable Object.

---

[API](https://skmtc.dev/cnvs/apis/cnvs-app-http-api.md) · [All operations](https://skmtc.dev/cnvs/apis/cnvs-app-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cnvs/apis/cnvs-app-http-api/revisions/c8f2c3b7ff90?raw)