Boards

Kanban-Boards: ein Dokumentwurzel-Block wie eine Seite, der seine Spalten- und Lane-Konfiguration mitführt. Die Karten sind Zeilen einer impliziten Datenbank dahinter — Seiten mit Spalte, Lane und Position je Board.

10 Operationen. Jeder Pfad ist relativ zum Ursprung der Instanz; jeder Antwortkörper ist JSON, sofern nicht anders vermerkt. Die Endpunktbeschreibungen unten stammen unverändert aus der Routentabelle des Servers und bleiben englisch. Authentifizierung, Fehler und seitenweise Abfrage stehen unter API.

GET /api/v1/workspaces/{workspaceId}/boards

List the boards of a collection (flat, newest first). Requires read on the collection.

listBoards · token scope: content:read

Path parameters

• workspaceId · string (uuid) — required

Query parameters

• collectionId · string (uuid) — required

Response 200 — application/json

• items · object[] — required
  • id · string (uuid) — required
  • workspaceId · string (uuid) — required
  • collectionId · string (uuid) — required
  • title · string — required
  • icon · string | null — required
  • targetDatabaseId · string (uuid) — required
  • columns · object[] — required
    • id · string (uuid) — required
    • label · string — required, length 1–200
    • icon · string — length 0–2048
    • collapsed · boolean
  • lanes · object[] — required
    • id · string (uuid) — required
    • label · string — required, length 1–200
    • collapsed · boolean
  • noLaneCollapsed · boolean — required
  • cardFields · string (uuid)[] — required
  • configVersion · string — required
  • createdAt · string (date-time) — required
  • updatedAt · string (date-time) — required
  • deletedAt · string (date-time) | null — required

Response default — application/json

• error · object — required
  • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
  • message · string — required
  • reason · string — length 1–64

POST /api/v1/workspaces/{workspaceId}/boards

Create a board at the collection root. Requires edit on the collection. Implicitly creates the 1:1 backing database and stores its id as targetDatabaseId (ADR-0025 D2); the body doc is created lazily on first collab connect. Starts with empty columns and lanes.

createBoard · token scope: content:write

Path parameters

• workspaceId · string (uuid) — required

Request body — application/json, required

• collectionId · string (uuid) — required
• title · string — required, length 1–500
• icon · string — length 0–2048

Response 200 — application/json

• id · string (uuid) — required
• workspaceId · string (uuid) — required
• collectionId · string (uuid) — required
• title · string — required
• icon · string | null — required
• targetDatabaseId · string (uuid) — required
• columns · object[] — required
  • id · string (uuid) — required
  • label · string — required, length 1–200
  • icon · string — length 0–2048
  • collapsed · boolean
• lanes · object[] — required
  • id · string (uuid) — required
  • label · string — required, length 1–200
  • collapsed · boolean
• noLaneCollapsed · boolean — required
• cardFields · string (uuid)[] — required
• configVersion · string — required
• createdAt · string (date-time) — required
• updatedAt · string (date-time) — required
• deletedAt · string (date-time) | null — required

Response default — application/json

• error · object — required
  • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
  • message · string — required
  • reason · string — length 1–64

GET /api/v1/workspaces/{workspaceId}/boards/{boardId}

Fetch one board (structure plane only — config, not cards). Requires read.

getBoard · token scope: content:read

Path parameters

• workspaceId · string (uuid) — required
• boardId · string (uuid) — required

Response 200 — application/json

• id · string (uuid) — required
• workspaceId · string (uuid) — required
• collectionId · string (uuid) — required
• title · string — required
• icon · string | null — required
• targetDatabaseId · string (uuid) — required
• columns · object[] — required
  • id · string (uuid) — required
  • label · string — required, length 1–200
  • icon · string — length 0–2048
  • collapsed · boolean
• lanes · object[] — required
  • id · string (uuid) — required
  • label · string — required, length 1–200
  • collapsed · boolean
• noLaneCollapsed · boolean — required
• cardFields · string (uuid)[] — required
• configVersion · string — required
• createdAt · string (date-time) — required
• updatedAt · string (date-time) — required
• deletedAt · string (date-time) | null — required

Response default — application/json

• error · object — required
  • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
  • message · string — required
  • reason · string — length 1–64

PATCH /api/v1/workspaces/{workspaceId}/boards/{boardId}

Rename a board, change its icon, replace its column/lane config (whole lists, board-local), fold or unfold the implicit no-lane row, and/or replace the field list its cards show. Because those lists are replaced whole, pass expectedConfigVersion — the board’s configVersion the patch was computed from — for optimistic concurrency: a board that has changed since answers 409 instead of silently dropping what the caller had not seen yet. Cards of a column the patch removes are UNPLACED (they surface in the grouped read’s columnId: null group) rather than left pointing at an id no list contains. Requires edit.

updateBoard · token scope: content:write

Path parameters

• workspaceId · string (uuid) — required
• boardId · string (uuid) — required

Request body — application/json, required

• title · string — length 1–500
• icon · string | null
• columns · object[]
  • id · string (uuid) — required
  • label · string — required, length 1–200
  • icon · string — length 0–2048
  • collapsed · boolean
• lanes · object[]
  • id · string (uuid) — required
  • label · string — required, length 1–200
  • collapsed · boolean
• noLaneCollapsed · boolean
• cardFields · string (uuid)[]
• expectedConfigVersion · string — length 1–64

Response 200 — application/json

• id · string (uuid) — required
• workspaceId · string (uuid) — required
• collectionId · string (uuid) — required
• title · string — required
• icon · string | null — required
• targetDatabaseId · string (uuid) — required
• columns · object[] — required
  • id · string (uuid) — required
  • label · string — required, length 1–200
  • icon · string — length 0–2048
  • collapsed · boolean
• lanes · object[] — required
  • id · string (uuid) — required
  • label · string — required, length 1–200
  • collapsed · boolean
• noLaneCollapsed · boolean — required
• cardFields · string (uuid)[] — required
• configVersion · string — required
• createdAt · string (date-time) — required
• updatedAt · string (date-time) — required
• deletedAt · string (date-time) | null — required

Response default — application/json

• error · object — required
  • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
  • message · string — required
  • reason · string — length 1–64

DELETE /api/v1/workspaces/{workspaceId}/boards/{boardId}

Move a board to the trash (soft delete). Requires full.

trashBoard · token scope: content:write

Path parameters

• workspaceId · string (uuid) — required
• boardId · string (uuid) — required

Response 200 — application/json

• ok · true — required

Response default — application/json

• error · object — required
  • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
  • message · string — required
  • reason · string — length 1–64

POST /api/v1/workspaces/{workspaceId}/boards/{boardId}/move

Reorder a board among its collection’s boards — beforeId/afterId name the siblings it lands between, neither appends. Boards stay at the collection root. Requires edit.

moveBoard · token scope: content:write

Path parameters

• workspaceId · string (uuid) — required
• boardId · string (uuid) — required

Request body — application/json, required

• beforeId · string (uuid)
• afterId · string (uuid)

Response 200 — application/json

• id · string (uuid) — required
• workspaceId · string (uuid) — required
• collectionId · string (uuid) — required
• title · string — required
• icon · string | null — required
• targetDatabaseId · string (uuid) — required
• columns · object[] — required
  • id · string (uuid) — required
  • label · string — required, length 1–200
  • icon · string — length 0–2048
  • collapsed · boolean
• lanes · object[] — required
  • id · string (uuid) — required
  • label · string — required, length 1–200
  • collapsed · boolean
• noLaneCollapsed · boolean — required
• cardFields · string (uuid)[] — required
• configVersion · string — required
• createdAt · string (date-time) — required
• updatedAt · string (date-time) — required
• deletedAt · string (date-time) | null — required

Response default — application/json

• error · object — required
  • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
  • message · string — required
  • reason · string — length 1–64

GET /api/v1/workspaces/{workspaceId}/boards/{boardId}/cards

The board read path (ADR-0025 D4): cards grouped by (column × lane) in ONE grouped query — a window per group, a per-group cursor, and per-group total counts. Without a cursor, every group answers its first window; with one, only that group answers its next. Requires read on the board; card pages the caller may not read are omitted, not stubbed (ADR-0016 D9), so group counts and cursors are viewer-dependent.

getBoardCards · token scope: content:read

Path parameters

• workspaceId · string (uuid) — required
• boardId · string (uuid) — required

Query parameters

• cursor · string — length 1–∞
• windowSize · integer — 1–100

Response 200 — application/json

• groups · object[] — required
  • columnId · string (uuid) | null — required
  • laneId · string (uuid) | null — required
  • cards · object[] — required
    • pageId · string (uuid) — required
    • workspaceId · string (uuid) — required
    • databaseId · string (uuid) — required
    • position · string — required
    • title · string — required
    • icon · string | null — required
    • cells · object — required
    • createdAt · string (date-time) — required
    • checklist · object | null — required
      • done · integer — required, 0–9007199254740991
      • total · integer — required, −∞–9007199254740991
    • columnId · string (uuid) | null — required
    • laneId · string (uuid) | null — required
    • boardPosition · string — required
  • nextCursor · string | null — required
  • totalCount · integer — required, 0–9007199254740991

Response default — application/json

• error · object — required
  • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
  • message · string — required
  • reason · string — length 1–64

POST /api/v1/workspaces/{workspaceId}/boards/{boardId}/cards

Add a card: create a new page as a row of the backing database, or attach an existing page by id — either way a membership carrying columnId, an optional laneId, and a position (omit the neighbours for the end of the column). Requires edit on the board.

addBoardCard · token scope: content:write

Path parameters

• workspaceId · string (uuid) — required
• boardId · string (uuid) — required

Request body — application/json, required

• pageId · string (uuid)
• title · string — length 0–1000
• icon · string — length 0–2048
• columnId · string (uuid) — required
• laneId · string (uuid)
• beforeId · string (uuid)
• afterId · string (uuid)

Response 200 — application/json

• pageId · string (uuid) — required
• workspaceId · string (uuid) — required
• databaseId · string (uuid) — required
• position · string — required
• title · string — required
• icon · string | null — required
• cells · object — required
• createdAt · string (date-time) — required
• checklist · object | null — required
  • done · integer — required, 0–9007199254740991
  • total · integer — required, −∞–9007199254740991
• columnId · string (uuid) | null — required
• laneId · string (uuid) | null — required
• boardPosition · string — required

Response default — application/json

• error · object — required
  • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
  • message · string — required
  • reason · string — length 1–64

POST /api/v1/workspaces/{workspaceId}/boards/{boardId}/cards/{pageId}/move

Move a card to a (column × lane) and position on THIS board — one transaction over the membership's override columns (ADR-0025 D5). The permission subject is the board, at edit; the card's page is not consulted and not touched. The response redacts title/icon/cells to empty when the caller may not read the page (ADR-0016 D9): D5 authorizes the move, not a content read.

moveBoardCard · token scope: content:write

Path parameters

• workspaceId · string (uuid) — required
• boardId · string (uuid) — required
• pageId · string (uuid) — required

Request body — application/json, required

• columnId · string (uuid) — required
• laneId · string (uuid)
• beforeId · string (uuid)
• afterId · string (uuid)

Response 200 — application/json

• pageId · string (uuid) — required
• workspaceId · string (uuid) — required
• databaseId · string (uuid) — required
• position · string — required
• title · string — required
• icon · string | null — required
• cells · object — required
• createdAt · string (date-time) — required
• checklist · object | null — required
  • done · integer — required, 0–9007199254740991
  • total · integer — required, −∞–9007199254740991
• columnId · string (uuid) | null — required
• laneId · string (uuid) | null — required
• boardPosition · string — required

Response default — application/json

• error · object — required
  • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
  • message · string — required
  • reason · string — length 1–64

DELETE /api/v1/workspaces/{workspaceId}/boards/{boardId}/cards/{pageId}

Remove a card from this board (drops the backing-database membership; the page is kept). Requires edit on the board; like the move, the response redacts title/icon/cells the caller may not read (ADR-0016 D9). 409 with a needs-new-home code when this is the page's home database (ADR-0006, the same rule removeRow enforces) — name newHomeBoardId to hand the card to another board of the same collection it is already on, which re-homes and removes in one transaction, or let the UI offer trash / another board (ADR-0025 D6). That parameter needs edit on the named board and is ignored when this board is not the card's home.

removeBoardCard · token scope: content:write

Path parameters

• workspaceId · string (uuid) — required
• boardId · string (uuid) — required
• pageId · string (uuid) — required

Query parameters

• newHomeBoardId · string (uuid)

Response 200 — application/json

• pageId · string (uuid) — required
• workspaceId · string (uuid) — required
• databaseId · string (uuid) — required
• position · string — required
• title · string — required
• icon · string | null — required
• cells · object — required
• createdAt · string (date-time) — required
• checklist · object | null — required
  • done · integer — required, 0–9007199254740991
  • total · integer — required, −∞–9007199254740991
• columnId · string (uuid) | null — required
• laneId · string (uuid) | null — required
• boardPosition · string — required

Response default — application/json

• error · object — required
  • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" — required
  • message · string — required
  • reason · string — length 1–64