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. Jede Karte hat eine Nummer je Workspace, über die sie sich abrufen lässt. Board-Vorlagen geben einem Board seine Form in einem Schritt: Spalten, Lanes und Felder. Automationen sind Regeln an einem Board, die nach Zeitplan Karten anlegen. Rückfragen an einer Karte werden mit einer ihrer Optionen beantwortet, die die Karte in eine Spalte verschieben kann. Nennt ein Personenfeld einer Karte einen Bot, hat die Karte einen Chat mit diesem Agenten.
37 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}/questions/answered
The caller's own questions that were answered in the last 14 days, newest first, on cards the caller may still read (ADR-0095): the card, the question, the answer as text, who gave it and when.
listAnswersToMe · token scope: content:read
Path parameters
workspaceId· string (uuid) · required
Response 200 · application/json
items· object[] · requiredquestionId· string (uuid) · requiredpageId· string (uuid) · requiredtitle· string · requiredquestion· string · requiredanswer· string · requiredansweredBy· string · requiredansweredAt· string (date-time) · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
GET /api/v1/workspaces/{workspaceId}/pages/{pageId}/questions
The questions on a card (ADR-0095), oldest first: open ones by default, status: all adds the answered and withdrawn ones. Requires read on the page.
listCardQuestions · token scope: content:read
Path parameters
workspaceId· string (uuid) · requiredpageId· string (uuid) · required
Query parameters
status·"open"|"all"
Response 200 · application/json
items· object[] · requiredid· string (uuid) · requiredpageId· string (uuid) · requiredquestion· string · requiredcontext· string | null · requiredoptions· object[] · requiredlabel· string · required, length 1–300columnId· string (uuid) | null · required
recommended· integer | null · requiredallowText· boolean · requiredboardId· string (uuid) | null · requiredaskedBy· object · requiredid· string (uuid) · requiredname· string · required
addressee· object | null · requiredid· string (uuid) · requiredname· string · required
status·"open"|"answered"|"withdrawn"· requiredanswerOption· integer | null · requiredanswerText· string | null · requiredclosedBy· object | null · requiredid· string (uuid) · requiredname· string · required
closedAt· string (date-time) | null · requiredcreatedAt· string (date-time) · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/pages/{pageId}/questions
Ask a question on a card with two to six options, optionally a recommended one, and whether an own text may answer it. An option may name a column of boardId; answering with it moves the card there. Requires comment on the page.
askCardQuestion · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredpageId· string (uuid) · required
Request body · application/json, required
question· string · required, length 1–1000context· string | nulloptions· object[] · required, 2–6 itemslabel· string · required, length 1–300columnId· string (uuid) | null · required
recommended· integer | nullallowText· booleanboardId· string (uuid) | nulladdresseeId· string (uuid) | null
Response 200 · application/json
id· string (uuid) · requiredpageId· string (uuid) · requiredquestion· string · requiredcontext· string | null · requiredoptions· object[] · requiredlabel· string · required, length 1–300columnId· string (uuid) | null · required
recommended· integer | null · requiredallowText· boolean · requiredboardId· string (uuid) | null · requiredaskedBy· object · requiredid· string (uuid) · requiredname· string · required
addressee· object | null · requiredid· string (uuid) · requiredname· string · required
status·"open"|"answered"|"withdrawn"· requiredanswerOption· integer | null · requiredanswerText· string | null · requiredclosedBy· object | null · requiredid· string (uuid) · requiredname· string · required
closedAt· string (date-time) | null · requiredcreatedAt· string (date-time) · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/questions/{questionId}/answer
Answer an open question with an option (its index) or an own text. An option that names a column moves the card there in the same transaction, keeping its lane, and then also requires edit on the board. Requires edit on the page; a question that is no longer open answers 409.
answerCardQuestion · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredquestionId· string (uuid) · required
Request body · application/json, required
option· integer · 0–9007199254740991text· string · length 1–5000
Response 200 · application/json
id· string (uuid) · requiredpageId· string (uuid) · requiredquestion· string · requiredcontext· string | null · requiredoptions· object[] · requiredlabel· string · required, length 1–300columnId· string (uuid) | null · required
recommended· integer | null · requiredallowText· boolean · requiredboardId· string (uuid) | null · requiredaskedBy· object · requiredid· string (uuid) · requiredname· string · required
addressee· object | null · requiredid· string (uuid) · requiredname· string · required
status·"open"|"answered"|"withdrawn"· requiredanswerOption· integer | null · requiredanswerText· string | null · requiredclosedBy· object | null · requiredid· string (uuid) · requiredname· string · required
closedAt· string (date-time) | null · requiredcreatedAt· string (date-time) · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/questions/{questionId}/withdraw
Withdraw an open question. Allowed to whoever asked it and to anyone with edit on the page; a question that is no longer open answers 409.
withdrawCardQuestion · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredquestionId· string (uuid) · required
Response 200 · application/json
id· string (uuid) · requiredpageId· string (uuid) · requiredquestion· string · requiredcontext· string | null · requiredoptions· object[] · requiredlabel· string · required, length 1–300columnId· string (uuid) | null · required
recommended· integer | null · requiredallowText· boolean · requiredboardId· string (uuid) | null · requiredaskedBy· object · requiredid· string (uuid) · requiredname· string · required
addressee· object | null · requiredid· string (uuid) · requiredname· string · required
status·"open"|"answered"|"withdrawn"· requiredanswerOption· integer | null · requiredanswerText· string | null · requiredclosedBy· object | null · requiredid· string (uuid) · requiredname· string · required
closedAt· string (date-time) | null · requiredcreatedAt· string (date-time) · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
GET /api/v1/workspaces/{workspaceId}/chat/waiting
The messages that wait for the caller in the chats of cards it is the agent of (ADR-0096 D8), oldest first, on cards it may still read: the card, the text, who wrote it and when. Empty for a person; meant for a bot's token.
listWaitingChatMessages · token scope: content:read
Path parameters
workspaceId· string (uuid) · required
Response 200 · application/json
items· object[] · requiredid· string (uuid) · requiredpageId· string (uuid) · requiredcardTitle· string · requiredtext· string · requiredauthor· object · requiredid· string (uuid) · requiredname· string · required
createdAt· string (date-time) · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
GET /api/v1/workspaces/{workspaceId}/pages/{pageId}/chat
The chat of a card with its agent (ADR-0096): the agent (the first bot in the card's person fields, or null), and the newest 200 messages oldest first, a person's with its state (waiting, answered, failed). Requires read on the page.
getCardChat · token scope: content:read
Path parameters
workspaceId· string (uuid) · requiredpageId· string (uuid) · required
Response 200 · application/json
agent· object | null · requiredid· string (uuid) · requiredname· string · required
canWrite· boolean · requiredwaiting· boolean · requireditems· object[] · requiredid· string (uuid) · requiredauthor· object · requiredid· string (uuid) · requiredname· string · requiredbot· boolean · required
text· string · requiredstate·"waiting"|"answered"|"failed"| null · requiredreplyTo· string (uuid) | null · requiredcreatedAt· string (date-time) · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/pages/{pageId}/chat
Write into the chat of a card. A person writes a message that waits for the agent; it requires edit on the page, and a card without an agent refuses with no_agent. The card's bot replies with replyTo (the message is answered), says with failed and replyTo that it could not (the text is the reason), or writes a short notice with neither; another bot is refused.
postCardChatMessage · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredpageId· string (uuid) · required
Request body · application/json, required
text· string · required, length 1–8000replyTo· string (uuid)failed· boolean
Response 200 · application/json
id· string (uuid) · requiredauthor· object · requiredid· string (uuid) · requiredname· string · requiredbot· boolean · required
text· string · requiredstate·"waiting"|"answered"|"failed"| null · requiredreplyTo· string (uuid) | null · requiredcreatedAt· string (date-time) · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
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[] · requiredid· string (uuid) · requiredworkspaceId· string (uuid) · requiredcollectionId· string (uuid) · requiredtitle· string · requiredicon· string | null · requiredtargetDatabaseId· string (uuid) · requiredcolumns· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
lanes· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
noLaneCollapsed· boolean · requirednoLaneLabel· string | null · requiredcardFields· string (uuid)[] · requiredshowCardNumbers· boolean · requiredtemplate· objectid· string · required, length 1–100version· integer · required, 1–9007199254740991offerSeen· integer · 1–9007199254740991
configVersion· string · requiredcreatedAt· string (date-time) · requiredupdatedAt· string (date-time) · requireddeletedAt· string (date-time) | null · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
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) · requiredtitle· string · required, length 1–500icon· string · length 0–2048
Response 200 · application/json
id· string (uuid) · requiredworkspaceId· string (uuid) · requiredcollectionId· string (uuid) · requiredtitle· string · requiredicon· string | null · requiredtargetDatabaseId· string (uuid) · requiredcolumns· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
lanes· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
noLaneCollapsed· boolean · requirednoLaneLabel· string | null · requiredcardFields· string (uuid)[] · requiredshowCardNumbers· boolean · requiredtemplate· objectid· string · required, length 1–100version· integer · required, 1–9007199254740991offerSeen· integer · 1–9007199254740991
configVersion· string · requiredcreatedAt· string (date-time) · requiredupdatedAt· string (date-time) · requireddeletedAt· string (date-time) | null · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
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) · requiredboardId· string (uuid) · required
Response 200 · application/json
id· string (uuid) · requiredworkspaceId· string (uuid) · requiredcollectionId· string (uuid) · requiredtitle· string · requiredicon· string | null · requiredtargetDatabaseId· string (uuid) · requiredcolumns· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
lanes· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
noLaneCollapsed· boolean · requirednoLaneLabel· string | null · requiredcardFields· string (uuid)[] · requiredshowCardNumbers· boolean · requiredtemplate· objectid· string · required, length 1–100version· integer · required, 1–9007199254740991offerSeen· integer · 1–9007199254740991
configVersion· string · requiredcreatedAt· string (date-time) · requiredupdatedAt· string (date-time) · requireddeletedAt· string (date-time) | null · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
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. Removing a column or lane that still holds cards needs removedColumns / removedLanes to say where they go, keyed by the removed id: { moveTo } appends them to another column (or lane) of the new list; 'unplace' for a column leaves them in the grouped read’s columnId: null group, { moveTo: null } for a lane puts them in their column’s no-lane row. Without it the server answers 409 conflict with reason board_column_not_empty / board_lane_not_empty and the card count in params (cards the caller cannot read included); an empty column or lane needs no entry. Requires edit.
updateBoard · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredboardId· string (uuid) · required
Request body · application/json, required
title· string · length 1–500icon· string | nullcolumns· object[]id· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
lanes· object[]id· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
noLaneCollapsed· booleannoLaneLabel· string | nullcardFields· string (uuid)[]showCardNumbers· booleantemplateOfferSeen· integer · 1–9007199254740991expectedConfigVersion· string · length 1–64removedColumns· objectremovedLanes· object
Response 200 · application/json
id· string (uuid) · requiredworkspaceId· string (uuid) · requiredcollectionId· string (uuid) · requiredtitle· string · requiredicon· string | null · requiredtargetDatabaseId· string (uuid) · requiredcolumns· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
lanes· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
noLaneCollapsed· boolean · requirednoLaneLabel· string | null · requiredcardFields· string (uuid)[] · requiredshowCardNumbers· boolean · requiredtemplate· objectid· string · required, length 1–100version· integer · required, 1–9007199254740991offerSeen· integer · 1–9007199254740991
configVersion· string · requiredcreatedAt· string (date-time) · requiredupdatedAt· string (date-time) · requireddeletedAt· string (date-time) | null · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
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) · requiredboardId· string (uuid) · required
Response 200 · application/json
ok·true· required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
GET /api/v1/workspaces/{workspaceId}/boards/{boardId}/markdown
Fetch the board's own document body (“About this board”) as canonical Markdown (text/markdown with a strong ETag over the canonical bytes; ADR-0025, mirroring the ADR-0012 page surface). A pinned card appears as a basalt-card fenced block. Requires read on the board.
getBoardMarkdown · token scope: content:read
Path parameters
workspaceId· string (uuid) · requiredboardId· string (uuid) · required
Response 200 · application/json
- string
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
PUT /api/v1/workspaces/{workspaceId}/boards/{boardId}/markdown
Replace the board's own document body (“About this board”) from canonical Markdown (text/markdown; ADR-0025 amendment, mirroring the ADR-0012 page surface). Applied to the live document in one Yjs transaction, so an open board sees it immediately; a basalt-card fenced block is kept as a pinned card. Supports If-Match/ETag optimistic concurrency (412 on mismatch); returns the stored canonical Markdown. Requires edit on the board.
updateBoardMarkdown · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredboardId· string (uuid) · required
Request body · application/json, required
- string
Response 200 · application/json
- string
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
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) · requiredboardId· string (uuid) · required
Request body · application/json, required
beforeId· string (uuid)afterId· string (uuid)collectionId· string (uuid)
Response 200 · application/json
id· string (uuid) · requiredworkspaceId· string (uuid) · requiredcollectionId· string (uuid) · requiredtitle· string · requiredicon· string | null · requiredtargetDatabaseId· string (uuid) · requiredcolumns· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
lanes· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
noLaneCollapsed· boolean · requirednoLaneLabel· string | null · requiredcardFields· string (uuid)[] · requiredshowCardNumbers· boolean · requiredtemplate· objectid· string · required, length 1–100version· integer · required, 1–9007199254740991offerSeen· integer · 1–9007199254740991
configVersion· string · requiredcreatedAt· string (date-time) · requiredupdatedAt· string (date-time) · requireddeletedAt· string (date-time) | null · requiredaccessDiff· object · requiredgained· object[] · requiredsubjectType·"user"|"group"· requiredsubjectId· string (uuid) · requiredname· string · requiredimage· string | null · requiredbot· booleanagentUrl· string | null
lost· object[] · requiredsubjectType·"user"|"group"· requiredsubjectId· string (uuid) · requiredname· string · requiredimage· string | null · requiredbot· booleanagentUrl· string | null
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
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) · requiredboardId· string (uuid) · required
Query parameters
cursor· string · length 1–∞windowSize· integer · 1–100filters· string · length 0–8000match·"all"|"any"archived·"include"|"only"
Response 200 · application/json
groups· object[] · requiredcolumnId· string (uuid) | null · requiredlaneId· string (uuid) | null · requiredcards· object[] · requiredpageId· string (uuid) · requiredworkspaceId· string (uuid) · requireddatabaseId· string (uuid) · requiredposition· string · requiredtitle· string · requiredicon· string | null · requiredcells· object · requiredcreatedAt· string (date-time) · requiredchecklist· object | null · requireddone· integer · required, 0–9007199254740991total· integer · required, −∞–9007199254740991
number· integer | null · requiredcolumnId· string (uuid) | null · requiredlaneId· string (uuid) | null · requiredboardPosition· string · requiredarchivedAt· string (date-time) | nullunseen· booleanopenQuestions· integer · 0–9007199254740991
nextCursor· string | null · requiredtotalCount· integer · required, 0–9007199254740991
archivedCount· integer · 0–9007199254740991
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
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) · requiredboardId· string (uuid) · required
Request body · application/json, required
pageId· string (uuid)title· string · length 0–1000icon· string · length 0–2048columnId· string (uuid) · requiredlaneId· string (uuid)beforeId· string (uuid)afterId· string (uuid)
Response 200 · application/json
pageId· string (uuid) · requiredworkspaceId· string (uuid) · requireddatabaseId· string (uuid) · requiredposition· string · requiredtitle· string · requiredicon· string | null · requiredcells· object · requiredcreatedAt· string (date-time) · requiredchecklist· object | null · requireddone· integer · required, 0–9007199254740991total· integer · required, −∞–9007199254740991
number· integer | null · requiredcolumnId· string (uuid) | null · requiredlaneId· string (uuid) | null · requiredboardPosition· string · requiredarchivedAt· string (date-time) | nullunseen· booleanopenQuestions· integer · 0–9007199254740991
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/boards/{boardId}/cards/{pageId}/move
Move a card to a (column × lane) and position on THIS board, in 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) · requiredboardId· string (uuid) · requiredpageId· string (uuid) · required
Request body · application/json, required
columnId· string (uuid) · requiredlaneId· string (uuid)beforeId· string (uuid)afterId· string (uuid)
Response 200 · application/json
pageId· string (uuid) · requiredworkspaceId· string (uuid) · requireddatabaseId· string (uuid) · requiredposition· string · requiredtitle· string · requiredicon· string | null · requiredcells· object · requiredcreatedAt· string (date-time) · requiredchecklist· object | null · requireddone· integer · required, 0–9007199254740991total· integer · required, −∞–9007199254740991
number· integer | null · requiredcolumnId· string (uuid) | null · requiredlaneId· string (uuid) | null · requiredboardPosition· string · requiredarchivedAt· string (date-time) | nullunseen· booleanopenQuestions· integer · 0–9007199254740991
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
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) · requiredboardId· string (uuid) · requiredpageId· string (uuid) · required
Query parameters
newHomeBoardId· string (uuid)
Response 200 · application/json
pageId· string (uuid) · requiredworkspaceId· string (uuid) · requireddatabaseId· string (uuid) · requiredposition· string · requiredtitle· string · requiredicon· string | null · requiredcells· object · requiredcreatedAt· string (date-time) · requiredchecklist· object | null · requireddone· integer · required, 0–9007199254740991total· integer · required, −∞–9007199254740991
number· integer | null · requiredcolumnId· string (uuid) | null · requiredlaneId· string (uuid) | null · requiredboardPosition· string · requiredarchivedAt· string (date-time) | nullunseen· booleanopenQuestions· integer · 0–9007199254740991
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
GET /api/v1/workspaces/{workspaceId}/cards/{number}
The card a number names (ADR-0057): #42 is /cards/42. Card numbers count up per workspace and never change. Requires read on the card; a missing number, a trashed card and one the caller may not read all answer the same 404.
getCardByNumber · token scope: content:read
Path parameters
workspaceId· string (uuid) · requirednumber· integer · required, −∞–9007199254740991
Response 200 · application/json
pageId· string (uuid) · requirednumber· integer · required, −∞–9007199254740991
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/boards/{boardId}/archive
Archive cards on this board, or bring them back (archived: false). An archived card keeps its membership, column, lane and position but leaves the grouped read unless it asks for archived. Name the cards by pageIds or a whole columnId. allBoards also archives them on every other board they sit on where the caller has edit; the others are counted as skipped. dryRun writes nothing and returns the same counts. Requires edit on the board.
archiveBoardCards · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredboardId· string (uuid) · required
Request body · application/json, required
pageIds· string (uuid)[] · 1–500 itemscolumnId· string (uuid)archived· booleanallBoards· booleandryRun· boolean
Response 200 · application/json
changed· integer · required, 0–9007199254740991otherBoardCards· integer · required, 0–9007199254740991otherBoards· integer · required, 0–9007199254740991skippedBoards· integer · required, 0–9007199254740991
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
GET /api/v1/workspaces/{workspaceId}/board-templates
The workspace's board templates (ADR-0110): the built-in ones first (readOnly, ids like builtin:agent-board), then the workspace's own, oldest first. A template is a board's shape: columns, lanes, fields and the fields the cards show. Any member; a guest is refused.
listBoardTemplates · token scope: content:read
Path parameters
workspaceId· string (uuid) · required
Response 200 · application/json
items· object[] · requiredid· string · requiredbuiltin· boolean · requiredreadOnly· boolean · requiredtemplate· object · requiredname· string · required, length 1–200description· string · required, length 0–500version· integer · required, 1–9007199254740991columns· object[] · required, 0–50 itemslabel· string · required, length 1–200icon· string · length 0–2048
lanes· object[] · required, 0–20 itemslabel· string · required, length 1–200icon· string · length 0–2048
fields· object[] · required, 0–30 itemskey· string · required, length 1–100name· string · required, length 1–200type·"select"|"multi_select"|"checkbox"|"number"|"text"|"date"|"person"|"url"· requiredoptions· object[] · required, 0–50 items, default[]- …
cardFields· string[] · required, 0–30 itemsshowCardNumbers· boolean
createdAt· string (date-time) | null · requiredupdatedAt· string (date-time) | null · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/board-templates
Save a board's current shape as a workspace template. Columns, lanes, the fields its cards show (select options with colours included) are taken over; a field type a template cannot carry (formula, relation) is left out and named in skipped. Workspace admins and owners only; at most 100 templates per workspace. Requires read on the board.
createBoardTemplate · token scope: content:write
Path parameters
workspaceId· string (uuid) · required
Request body · application/json, required
boardId· string (uuid) · requiredname· string · required, length 1–200description· string · length 0–500
Response 200 · application/json
template· object · requiredid· string · requiredbuiltin· boolean · requiredreadOnly· boolean · requiredtemplate· object · requiredname· string · required, length 1–200description· string · required, length 0–500version· integer · required, 1–9007199254740991columns· object[] · required, 0–50 itemslabel· string · required, length 1–200icon· string · length 0–2048
lanes· object[] · required, 0–20 itemslabel· string · required, length 1–200icon· string · length 0–2048
fields· object[] · required, 0–30 itemskey· string · required, length 1–100name· string · required, length 1–200type·"select"|"multi_select"|"checkbox"|"number"|"text"|"date"|"person"|"url"· requiredoptions· object[] · required, 0–50 items, default[]- …
cardFields· string[] · required, 0–30 itemsshowCardNumbers· boolean
createdAt· string (date-time) | null · requiredupdatedAt· string (date-time) | null · required
skipped· object[] · requiredkind·"lane"|"field"|"option"|"card_field"· requiredname· string · requiredreason·"conflict"|"needs_admin"|"options_need_admin"|"missing_builtin"|"lane_name_taken"|"unsupported_type"|"status"· required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
PATCH /api/v1/workspaces/{workspaceId}/board-templates/{templateId}
Rename a workspace template, change its description, and/or replace its content with the current shape of a board (fromBoardId; the version rises by one). Built-in templates are fixed (409). Workspace admins and owners only.
updateBoardTemplate · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredtemplateId· string · required, length 1–∞
Request body · application/json, required
name· string · length 1–200description· string · length 0–500fromBoardId· string (uuid)
Response 200 · application/json
template· object · requiredid· string · requiredbuiltin· boolean · requiredreadOnly· boolean · requiredtemplate· object · requiredname· string · required, length 1–200description· string · required, length 0–500version· integer · required, 1–9007199254740991columns· object[] · required, 0–50 itemslabel· string · required, length 1–200icon· string · length 0–2048
lanes· object[] · required, 0–20 itemslabel· string · required, length 1–200icon· string · length 0–2048
fields· object[] · required, 0–30 itemskey· string · required, length 1–100name· string · required, length 1–200type·"select"|"multi_select"|"checkbox"|"number"|"text"|"date"|"person"|"url"· requiredoptions· object[] · required, 0–50 items, default[]- …
cardFields· string[] · required, 0–30 itemsshowCardNumbers· boolean
createdAt· string (date-time) | null · requiredupdatedAt· string (date-time) | null · required
skipped· object[] · requiredkind·"lane"|"field"|"option"|"card_field"· requiredname· string · requiredreason·"conflict"|"needs_admin"|"options_need_admin"|"missing_builtin"|"lane_name_taken"|"unsupported_type"|"status"· required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
DELETE /api/v1/workspaces/{workspaceId}/board-templates/{templateId}
Delete a workspace template. Boards made from it keep what they got and lose nothing. Built-in templates cannot be deleted (409). Workspace admins and owners only.
deleteBoardTemplate · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredtemplateId· string · required, length 1–∞
Response 200 · application/json
ok·true· required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/board-templates/{templateId}/duplicate
Make an editable workspace copy of a built-in or workspace template, named name or " (copy)". Workspace admins and owners only.
duplicateBoardTemplate · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredtemplateId· string · required, length 1–∞
Request body · application/json, required
name· string · length 1–200
Response 200 · application/json
id· string · requiredbuiltin· boolean · requiredreadOnly· boolean · requiredtemplate· object · requiredname· string · required, length 1–200description· string · required, length 0–500version· integer · required, 1–9007199254740991columns· object[] · required, 0–50 itemslabel· string · required, length 1–200icon· string · length 0–2048
lanes· object[] · required, 0–20 itemslabel· string · required, length 1–200icon· string · length 0–2048
fields· object[] · required, 0–30 itemskey· string · required, length 1–100name· string · required, length 1–200type·"select"|"multi_select"|"checkbox"|"number"|"text"|"date"|"person"|"url"· requiredoptions· object[] · required, 0–50 items, default[]label· string · required, length 1–200color·"#94a3b8"|"#f59e0b"|"#22c55e"|"#3b82f6"|"#ec4899"|"#a855f7"· required
cardFields· string[] · required, 0–30 itemsshowCardNumbers· boolean
createdAt· string (date-time) | null · requiredupdatedAt· string (date-time) | null · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/board-templates/{templateId}/create-board
Create a board in a collection with the template's columns, lanes, field bindings and shown fields in one step. A field the template needs and the caller may not create (workspace admin) is skipped and named in skipped; everything else is made. The board remembers the template and its version. Needs the same as createBoard: edit on the collection, Tecto origin.
createBoardFromTemplate · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredtemplateId· string · required, length 1–∞
Request body · application/json, required
collectionId· string (uuid) · requiredtitle· string · required, length 1–500
Response 200 · application/json
board· object · requiredid· string (uuid) · requiredworkspaceId· string (uuid) · requiredcollectionId· string (uuid) · requiredtitle· string · requiredicon· string | null · requiredtargetDatabaseId· string (uuid) · requiredcolumns· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
lanes· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
noLaneCollapsed· boolean · requirednoLaneLabel· string | null · requiredcardFields· string (uuid)[] · requiredshowCardNumbers· boolean · requiredtemplate· objectid· string · required, length 1–100version· integer · required, 1–9007199254740991offerSeen· integer · 1–9007199254740991
configVersion· string · requiredcreatedAt· string (date-time) · requiredupdatedAt· string (date-time) · requireddeletedAt· string (date-time) | null · required
made· object[] · requiredkind·"column"|"lane"|"field"|"binding"|"option"|"card_field"· requiredname· string · required
skipped· object[] · requiredkind·"lane"|"field"|"option"|"card_field"· requiredname· string · requiredreason·"conflict"|"needs_admin"|"options_need_admin"|"missing_builtin"|"lane_name_taken"|"unsupported_type"|"status"· required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/boards/{boardId}/template-preview
What applying a template to the board would add: the columns, lanes, fields, options and shown fields it lacks, the fields whose key exists with another type (left alone), and the parts only an admin may make. Changes nothing. Returns the board's configVersion; echo it to applyBoardTemplate. Requires edit on the board.
previewBoardTemplate · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredboardId· string (uuid) · required
Request body · application/json, required
templateId· string · required, length 1–∞
Response 200 · application/json
configVersion· string · requiredtemplate· object · requiredid· string · requiredname· string · requiredversion· integer · required, -9007199254740991–9007199254740991
plan· object · requiredcolumnsToAdd· object[] · requiredlabel· string · requiredicon· string · length 0–2048
lanesToAdd· object[] · requiredlabel· string · requiredicon· string · length 0–2048
fieldsToBind· object[] · requiredfieldId· string (uuid) · requiredkey· string · required
fieldsToCreate· object[] · requiredfield· object · requiredkey· string · requiredname· string · requiredtype·"select"|"multi_select"|"checkbox"|"number"|"text"|"date"|"person"|"url"· requiredoptions· object[] · required- …
needsAdmin· boolean · required
optionsToAdd· object[] · requiredkey· string · requiredoptions· object[] · requiredlabel· string · requiredcolor· string · required
needsAdmin· boolean · required
cardFieldsToShow· string[] · requiredshowCardNumbersToSet· boolean · requiredconflicts· object[] · requiredkey· string · requiredtemplateType· string · requiredexistingType· string · required
notes· object[] · requiredcode·"conflict"|"needs_admin"|"options_need_admin"|"missing_builtin"|"lane_name_taken"· requiredkey· string · required
empty· boolean · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/boards/{boardId}/apply-template
Add what previewBoardTemplate listed, in one transaction: it renames, moves and removes nothing and hides no field a card shows today. Fields are bound at the board's own database, so other boards are untouched. Parts that need an admin are skipped and named in skipped, not refused. 409 when the board changed since the preview (expectedConfigVersion). Requires edit on the board.
applyBoardTemplate · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredboardId· string (uuid) · required
Request body · application/json, required
templateId· string · required, length 1–∞expectedConfigVersion· string · required
Response 200 · application/json
board· object · requiredid· string (uuid) · requiredworkspaceId· string (uuid) · requiredcollectionId· string (uuid) · requiredtitle· string · requiredicon· string | null · requiredtargetDatabaseId· string (uuid) · requiredcolumns· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
lanes· object[] · requiredid· string (uuid) · requiredlabel· string · required, length 1–200icon· string · length 0–2048collapsed· boolean
noLaneCollapsed· boolean · requirednoLaneLabel· string | null · requiredcardFields· string (uuid)[] · requiredshowCardNumbers· boolean · requiredtemplate· objectid· string · required, length 1–100version· integer · required, 1–9007199254740991offerSeen· integer · 1–9007199254740991
configVersion· string · requiredcreatedAt· string (date-time) · requiredupdatedAt· string (date-time) · requireddeletedAt· string (date-time) | null · required
made· object[] · requiredkind·"column"|"lane"|"field"|"binding"|"option"|"card_field"· requiredname· string · required
skipped· object[] · requiredkind·"lane"|"field"|"option"|"card_field"· requiredname· string · requiredreason·"conflict"|"needs_admin"|"options_need_admin"|"missing_builtin"|"lane_name_taken"|"unsupported_type"|"status"· required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
GET /api/v1/workspaces/{workspaceId}/boards/{boardId}/automations
The board's automation rules (ADR-0055), oldest first. Requires edit on the board.
listAutomations · token scope: content:read
Path parameters
workspaceId· string (uuid) · requiredboardId· string (uuid) · required
Response 200 · application/json
items· object[] · requiredid· string (uuid) · requiredboardId· string (uuid) · requiredname· string · requiredstatus·"active"|"paused"· requiredpauseReason·"target_missing"|"board_missing"|"creator_no_access"| null · requiredtrigger· object · requiredtype·"schedule"· requiredfrequency·"daily"|"weekly"|"monthly"· requiredweekdays· integer[] · 1–7 itemsmonthDay· integer · 1–31time· string · requiredtimeZone· string · required, length 1–64
action· object · requiredtype·"create_card"· requiredtitle· string · required, length 1–500markdown· string · length 0–50000cells· objectcolumnId· string (uuid) · requiredlaneId· string (uuid) | null · required, defaultnullonlyIfPreviousDone· boolean · required, defaultfalse
nextRunAt· string (date-time) | null · requiredlastRunAt· string (date-time) | null · requiredcreatedBy· string (uuid) · requiredcreatedAt· string (date-time) · requiredupdatedAt· string (date-time) · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/boards/{boardId}/automations
Create a rule on the board: a schedule (daily, weekly or monthly at a wall-clock time in a named zone) that creates a card from a template. The rule acts as its creator. At most 20 per board. Requires edit on the board.
createAutomation · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredboardId· string (uuid) · required
Request body · application/json, required
name· string · required, length 1–200trigger· object · requiredtype·"schedule"· requiredfrequency·"daily"|"weekly"|"monthly"· requiredweekdays· integer[] · 1–7 itemsmonthDay· integer · 1–31time· string · requiredtimeZone· string · required, length 1–64
action· object · requiredtype·"create_card"· requiredtitle· string · required, length 1–500markdown· string · length 0–50000cells· objectcolumnId· string (uuid) · requiredlaneId· string (uuid) | null · defaultnullonlyIfPreviousDone· boolean · defaultfalse
paused· boolean
Response 200 · application/json
id· string (uuid) · requiredboardId· string (uuid) · requiredname· string · requiredstatus·"active"|"paused"· requiredpauseReason·"target_missing"|"board_missing"|"creator_no_access"| null · requiredtrigger· object · requiredtype·"schedule"· requiredfrequency·"daily"|"weekly"|"monthly"· requiredweekdays· integer[] · 1–7 itemsmonthDay· integer · 1–31time· string · requiredtimeZone· string · required, length 1–64
action· object · requiredtype·"create_card"· requiredtitle· string · required, length 1–500markdown· string · length 0–50000cells· objectcolumnId· string (uuid) · requiredlaneId· string (uuid) | null · required, defaultnullonlyIfPreviousDone· boolean · required, defaultfalse
nextRunAt· string (date-time) | null · requiredlastRunAt· string (date-time) | null · requiredcreatedBy· string (uuid) · requiredcreatedAt· string (date-time) · requiredupdatedAt· string (date-time) · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
PATCH /api/v1/workspaces/{workspaceId}/automations/{automationId}
Change a rule's name, schedule or template, or pause and resume it. Resuming clears the reason the rule paused itself and schedules the next occurrence from now. Requires edit on the rule's board.
updateAutomation · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredautomationId· string (uuid) · required
Request body · application/json, required
name· string · length 1–200status·"active"|"paused"trigger· objecttype·"schedule"· requiredfrequency·"daily"|"weekly"|"monthly"· requiredweekdays· integer[] · 1–7 itemsmonthDay· integer · 1–31time· string · requiredtimeZone· string · required, length 1–64
action· objecttype·"create_card"· requiredtitle· string · required, length 1–500markdown· string · length 0–50000cells· objectcolumnId· string (uuid) · requiredlaneId· string (uuid) | null · defaultnullonlyIfPreviousDone· boolean · defaultfalse
Response 200 · application/json
id· string (uuid) · requiredboardId· string (uuid) · requiredname· string · requiredstatus·"active"|"paused"· requiredpauseReason·"target_missing"|"board_missing"|"creator_no_access"| null · requiredtrigger· object · requiredtype·"schedule"· requiredfrequency·"daily"|"weekly"|"monthly"· requiredweekdays· integer[] · 1–7 itemsmonthDay· integer · 1–31time· string · requiredtimeZone· string · required, length 1–64
action· object · requiredtype·"create_card"· requiredtitle· string · required, length 1–500markdown· string · length 0–50000cells· objectcolumnId· string (uuid) · requiredlaneId· string (uuid) | null · required, defaultnullonlyIfPreviousDone· boolean · required, defaultfalse
nextRunAt· string (date-time) | null · requiredlastRunAt· string (date-time) | null · requiredcreatedBy· string (uuid) · requiredcreatedAt· string (date-time) · requiredupdatedAt· string (date-time) · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
DELETE /api/v1/workspaces/{workspaceId}/automations/{automationId}
Delete a rule and its run history. Cards it created stay. Requires edit on the rule's board.
deleteAutomation · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredautomationId· string (uuid) · required
Response 200 · application/json
ok·true· required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/automations/{automationId}/run
Run the rule now, once, independent of its schedule; placeholders resolve for the current moment. Answers the recorded run, which may be skipped or paused. Requires edit on the rule's board.
runAutomation · token scope: content:write
Path parameters
workspaceId· string (uuid) · requiredautomationId· string (uuid) · required
Response 200 · application/json
id· string (uuid) · requiredautomationId· string (uuid) · requiredoccurrenceKey· string · requiredscheduledFor· string (date-time) | null · requiredranAt· string (date-time) · requiredoutcome·"created"|"skipped"|"paused"|"failed"· requiredpageId· string (uuid) | null · requiredmessage· string | null · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
GET /api/v1/workspaces/{workspaceId}/automations/{automationId}/runs
The rule's last 50 runs, newest first: what each did and which card it created. Requires edit on the rule's board.
listAutomationRuns · token scope: content:read
Path parameters
workspaceId· string (uuid) · requiredautomationId· string (uuid) · required
Response 200 · application/json
items· object[] · requiredid· string (uuid) · requiredautomationId· string (uuid) · requiredoccurrenceKey· string · requiredscheduledFor· string (date-time) | null · requiredranAt· string (date-time) · requiredoutcome·"created"|"skipped"|"paused"|"failed"· requiredpageId· string (uuid) | null · requiredmessage· string | null · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object
POST /api/v1/workspaces/{workspaceId}/automations/preview
The next five occurrences of a schedule, as instants. Stores nothing; for checking a schedule before saving it.
previewAutomation · token scope: content:write
Path parameters
workspaceId· string (uuid) · required
Request body · application/json, required
trigger· object · requiredtype·"schedule"· requiredfrequency·"daily"|"weekly"|"monthly"· requiredweekdays· integer[] · 1–7 itemsmonthDay· integer · 1–31time· string · requiredtimeZone· string · required, length 1–64
Response 200 · application/json
occurrences· string (date-time)[] · required
Response default · application/json
error· object · requiredcode·"bad_request"|"validation_failed"|"unauthorized"|"forbidden"|"not_found"|"conflict"|"rate_limited"|"internal"· requiredmessage· string · requiredreason· string · length 1–64params· object