Tecto docs
tectoapp.io

Boards

Kanban boards: a doc-root block like a page, carrying its column and lane configuration, whose cards are rows of an implicit backing database: pages with a per-board column, lane and position. Every card has a number per workspace, and a card can be looked up by it. Board templates give a board its shape in one step: columns, lanes and fields. Automations are rules on a board that create cards on a schedule. Questions on a card are answered with one of their options, which can move the card to a column. A card whose person fields name a bot has a chat with that agent.

37 operations. Every path is relative to the instance origin; every response body is JSON unless stated. The endpoint descriptions below come straight from the server’s own route table. See API for authentication, errors and pagination.

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[] · required
    • questionId · string (uuid) · required
    • pageId · string (uuid) · required
    • title · string · required
    • question · string · required
    • answer · string · required
    • answeredBy · string · required
    • answeredAt · string (date-time) · 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
    • params · 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) · required
  • pageId · string (uuid) · required

Query parameters

  • status · "open" | "all"

Response 200 · application/json

  • items · object[] · required
    • id · string (uuid) · required
    • pageId · string (uuid) · required
    • question · string · required
    • context · string | null · required
    • options · object[] · required
      • label · string · required, length 1–300
      • columnId · string (uuid) | null · required
    • recommended · integer | null · required
    • allowText · boolean · required
    • boardId · string (uuid) | null · required
    • askedBy · object · required
      • id · string (uuid) · required
      • name · string · required
    • addressee · object | null · required
      • id · string (uuid) · required
      • name · string · required
    • status · "open" | "answered" | "withdrawn" · required
    • answerOption · integer | null · required
    • answerText · string | null · required
    • closedBy · object | null · required
      • id · string (uuid) · required
      • name · string · required
    • closedAt · string (date-time) | null · required
    • createdAt · string (date-time) · 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
    • params · 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) · required
  • pageId · string (uuid) · required

Request body · application/json, required

  • question · string · required, length 1–1000
  • context · string | null
  • options · object[] · required, 2–6 items
    • label · string · required, length 1–300
    • columnId · string (uuid) | null · required
  • recommended · integer | null
  • allowText · boolean
  • boardId · string (uuid) | null
  • addresseeId · string (uuid) | null

Response 200 · application/json

  • id · string (uuid) · required
  • pageId · string (uuid) · required
  • question · string · required
  • context · string | null · required
  • options · object[] · required
    • label · string · required, length 1–300
    • columnId · string (uuid) | null · required
  • recommended · integer | null · required
  • allowText · boolean · required
  • boardId · string (uuid) | null · required
  • askedBy · object · required
    • id · string (uuid) · required
    • name · string · required
  • addressee · object | null · required
    • id · string (uuid) · required
    • name · string · required
  • status · "open" | "answered" | "withdrawn" · required
  • answerOption · integer | null · required
  • answerText · string | null · required
  • closedBy · object | null · required
    • id · string (uuid) · required
    • name · string · required
  • closedAt · string (date-time) | null · required
  • createdAt · string (date-time) · 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
    • params · 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) · required
  • questionId · string (uuid) · required

Request body · application/json, required

  • option · integer · 0–9007199254740991
  • text · string · length 1–5000

Response 200 · application/json

  • id · string (uuid) · required
  • pageId · string (uuid) · required
  • question · string · required
  • context · string | null · required
  • options · object[] · required
    • label · string · required, length 1–300
    • columnId · string (uuid) | null · required
  • recommended · integer | null · required
  • allowText · boolean · required
  • boardId · string (uuid) | null · required
  • askedBy · object · required
    • id · string (uuid) · required
    • name · string · required
  • addressee · object | null · required
    • id · string (uuid) · required
    • name · string · required
  • status · "open" | "answered" | "withdrawn" · required
  • answerOption · integer | null · required
  • answerText · string | null · required
  • closedBy · object | null · required
    • id · string (uuid) · required
    • name · string · required
  • closedAt · string (date-time) | null · required
  • createdAt · string (date-time) · 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
    • params · 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) · required
  • questionId · string (uuid) · required

Response 200 · application/json

  • id · string (uuid) · required
  • pageId · string (uuid) · required
  • question · string · required
  • context · string | null · required
  • options · object[] · required
    • label · string · required, length 1–300
    • columnId · string (uuid) | null · required
  • recommended · integer | null · required
  • allowText · boolean · required
  • boardId · string (uuid) | null · required
  • askedBy · object · required
    • id · string (uuid) · required
    • name · string · required
  • addressee · object | null · required
    • id · string (uuid) · required
    • name · string · required
  • status · "open" | "answered" | "withdrawn" · required
  • answerOption · integer | null · required
  • answerText · string | null · required
  • closedBy · object | null · required
    • id · string (uuid) · required
    • name · string · required
  • closedAt · string (date-time) | null · required
  • createdAt · string (date-time) · 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
    • params · 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[] · required
    • id · string (uuid) · required
    • pageId · string (uuid) · required
    • cardTitle · string · required
    • text · string · required
    • author · object · required
      • id · string (uuid) · required
      • name · string · required
    • createdAt · string (date-time) · 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
    • params · 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) · required
  • pageId · string (uuid) · required

Response 200 · application/json

  • agent · object | null · required
    • id · string (uuid) · required
    • name · string · required
  • canWrite · boolean · required
  • waiting · boolean · required
  • items · object[] · required
    • id · string (uuid) · required
    • author · object · required
      • id · string (uuid) · required
      • name · string · required
      • bot · boolean · required
    • text · string · required
    • state · "waiting" | "answered" | "failed" | null · required
    • replyTo · string (uuid) | null · required
    • createdAt · string (date-time) · 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
    • params · 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) · required
  • pageId · string (uuid) · required

Request body · application/json, required

  • text · string · required, length 1–8000
  • replyTo · string (uuid)
  • failed · boolean

Response 200 · application/json

  • id · string (uuid) · required
  • author · object · required
    • id · string (uuid) · required
    • name · string · required
    • bot · boolean · required
  • text · string · required
  • state · "waiting" | "answered" | "failed" | null · required
  • replyTo · string (uuid) | null · required
  • createdAt · string (date-time) · 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
    • params · 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[] · 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
      • icon · string · length 0–2048
      • collapsed · boolean
    • noLaneCollapsed · boolean · required
    • noLaneLabel · string | null · required
    • cardFields · string (uuid)[] · required
    • showCardNumbers · boolean · required
    • template · object
      • id · string · required, length 1–100
      • version · integer · required, 1–9007199254740991
      • offerSeen · integer · 1–9007199254740991
    • 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
    • params · 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) · 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
    • icon · string · length 0–2048
    • collapsed · boolean
  • noLaneCollapsed · boolean · required
  • noLaneLabel · string | null · required
  • cardFields · string (uuid)[] · required
  • showCardNumbers · boolean · required
  • template · object
    • id · string · required, length 1–100
    • version · integer · required, 1–9007199254740991
    • offerSeen · integer · 1–9007199254740991
  • 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
    • params · 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) · 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
    • icon · string · length 0–2048
    • collapsed · boolean
  • noLaneCollapsed · boolean · required
  • noLaneLabel · string | null · required
  • cardFields · string (uuid)[] · required
  • showCardNumbers · boolean · required
  • template · object
    • id · string · required, length 1–100
    • version · integer · required, 1–9007199254740991
    • offerSeen · integer · 1–9007199254740991
  • 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
    • params · 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) · 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
    • icon · string · length 0–2048
    • collapsed · boolean
  • noLaneCollapsed · boolean
  • noLaneLabel · string | null
  • cardFields · string (uuid)[]
  • showCardNumbers · boolean
  • templateOfferSeen · integer · 1–9007199254740991
  • expectedConfigVersion · string · length 1–64
  • removedColumns · object
  • removedLanes · object

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
    • icon · string · length 0–2048
    • collapsed · boolean
  • noLaneCollapsed · boolean · required
  • noLaneLabel · string | null · required
  • cardFields · string (uuid)[] · required
  • showCardNumbers · boolean · required
  • template · object
    • id · string · required, length 1–100
    • version · integer · required, 1–9007199254740991
    • offerSeen · integer · 1–9007199254740991
  • 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
    • params · 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) · 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
    • params · 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) · required
  • boardId · string (uuid) · required

Response 200 · application/json

  • string

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
    • params · 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) · required
  • boardId · string (uuid) · required

Request body · application/json, required

  • string

Response 200 · application/json

  • string

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
    • params · 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) · required
  • boardId · string (uuid) · required

Request body · application/json, required

  • beforeId · string (uuid)
  • afterId · string (uuid)
  • collectionId · 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
    • icon · string · length 0–2048
    • collapsed · boolean
  • noLaneCollapsed · boolean · required
  • noLaneLabel · string | null · required
  • cardFields · string (uuid)[] · required
  • showCardNumbers · boolean · required
  • template · object
    • id · string · required, length 1–100
    • version · integer · required, 1–9007199254740991
    • offerSeen · integer · 1–9007199254740991
  • configVersion · string · required
  • createdAt · string (date-time) · required
  • updatedAt · string (date-time) · required
  • deletedAt · string (date-time) | null · required
  • accessDiff · object · required
    • gained · object[] · required
      • subjectType · "user" | "group" · required
      • subjectId · string (uuid) · required
      • name · string · required
      • image · string | null · required
      • bot · boolean
      • agentUrl · string | null
    • lost · object[] · required
      • subjectType · "user" | "group" · required
      • subjectId · string (uuid) · required
      • name · string · required
      • image · string | null · required
      • bot · boolean
      • agentUrl · string | null

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
    • params · 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) · required
  • boardId · string (uuid) · required

Query parameters

  • cursor · string · length 1–∞
  • windowSize · integer · 1–100
  • filters · string · length 0–8000
  • match · "all" | "any"
  • archived · "include" | "only"

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
      • number · integer | null · required
      • columnId · string (uuid) | null · required
      • laneId · string (uuid) | null · required
      • boardPosition · string · required
      • archivedAt · string (date-time) | null
      • unseen · boolean
      • openQuestions · integer · 0–9007199254740991
    • nextCursor · string | null · required
    • totalCount · integer · required, 0–9007199254740991
  • archivedCount · integer · 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
    • params · 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) · 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
  • number · integer | null · required
  • columnId · string (uuid) | null · required
  • laneId · string (uuid) | null · required
  • boardPosition · string · required
  • archivedAt · string (date-time) | null
  • unseen · boolean
  • openQuestions · integer · 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
    • params · 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) · 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
  • number · integer | null · required
  • columnId · string (uuid) | null · required
  • laneId · string (uuid) | null · required
  • boardPosition · string · required
  • archivedAt · string (date-time) | null
  • unseen · boolean
  • openQuestions · integer · 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
    • params · 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) · 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
  • number · integer | null · required
  • columnId · string (uuid) | null · required
  • laneId · string (uuid) | null · required
  • boardPosition · string · required
  • archivedAt · string (date-time) | null
  • unseen · boolean
  • openQuestions · integer · 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
    • params · 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) · required
  • number · integer · required, −∞–9007199254740991

Response 200 · application/json

  • pageId · string (uuid) · required
  • number · integer · required, −∞–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
    • params · 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) · required
  • boardId · string (uuid) · required

Request body · application/json, required

  • pageIds · string (uuid)[] · 1–500 items
  • columnId · string (uuid)
  • archived · boolean
  • allBoards · boolean
  • dryRun · boolean

Response 200 · application/json

  • changed · integer · required, 0–9007199254740991
  • otherBoardCards · integer · required, 0–9007199254740991
  • otherBoards · integer · required, 0–9007199254740991
  • skippedBoards · 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
    • params · 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[] · required
    • id · string · required
    • builtin · boolean · required
    • readOnly · boolean · required
    • template · object · required
      • name · string · required, length 1–200
      • description · string · required, length 0–500
      • version · integer · required, 1–9007199254740991
      • columns · object[] · required, 0–50 items
        • label · string · required, length 1–200
        • icon · string · length 0–2048
      • lanes · object[] · required, 0–20 items
        • label · string · required, length 1–200
        • icon · string · length 0–2048
      • fields · object[] · required, 0–30 items
        • key · string · required, length 1–100
        • name · string · required, length 1–200
        • type · "select" | "multi_select" | "checkbox" | "number" | "text" | "date" | "person" | "url" · required
        • options · object[] · required, 0–50 items, default []
          • …
      • cardFields · string[] · required, 0–30 items
      • showCardNumbers · boolean
    • createdAt · string (date-time) | null · required
    • updatedAt · 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
    • params · 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) · required
  • name · string · required, length 1–200
  • description · string · length 0–500

Response 200 · application/json

  • template · object · required
    • id · string · required
    • builtin · boolean · required
    • readOnly · boolean · required
    • template · object · required
      • name · string · required, length 1–200
      • description · string · required, length 0–500
      • version · integer · required, 1–9007199254740991
      • columns · object[] · required, 0–50 items
        • label · string · required, length 1–200
        • icon · string · length 0–2048
      • lanes · object[] · required, 0–20 items
        • label · string · required, length 1–200
        • icon · string · length 0–2048
      • fields · object[] · required, 0–30 items
        • key · string · required, length 1–100
        • name · string · required, length 1–200
        • type · "select" | "multi_select" | "checkbox" | "number" | "text" | "date" | "person" | "url" · required
        • options · object[] · required, 0–50 items, default []
          • …
      • cardFields · string[] · required, 0–30 items
      • showCardNumbers · boolean
    • createdAt · string (date-time) | null · required
    • updatedAt · string (date-time) | null · required
  • skipped · object[] · required
    • kind · "lane" | "field" | "option" | "card_field" · required
    • name · string · required
    • reason · "conflict" | "needs_admin" | "options_need_admin" | "missing_builtin" | "lane_name_taken" | "unsupported_type" | "status" · 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
    • params · 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) · required
  • templateId · string · required, length 1–∞

Request body · application/json, required

  • name · string · length 1–200
  • description · string · length 0–500
  • fromBoardId · string (uuid)

Response 200 · application/json

  • template · object · required
    • id · string · required
    • builtin · boolean · required
    • readOnly · boolean · required
    • template · object · required
      • name · string · required, length 1–200
      • description · string · required, length 0–500
      • version · integer · required, 1–9007199254740991
      • columns · object[] · required, 0–50 items
        • label · string · required, length 1–200
        • icon · string · length 0–2048
      • lanes · object[] · required, 0–20 items
        • label · string · required, length 1–200
        • icon · string · length 0–2048
      • fields · object[] · required, 0–30 items
        • key · string · required, length 1–100
        • name · string · required, length 1–200
        • type · "select" | "multi_select" | "checkbox" | "number" | "text" | "date" | "person" | "url" · required
        • options · object[] · required, 0–50 items, default []
          • …
      • cardFields · string[] · required, 0–30 items
      • showCardNumbers · boolean
    • createdAt · string (date-time) | null · required
    • updatedAt · string (date-time) | null · required
  • skipped · object[] · required
    • kind · "lane" | "field" | "option" | "card_field" · required
    • name · string · required
    • reason · "conflict" | "needs_admin" | "options_need_admin" | "missing_builtin" | "lane_name_taken" | "unsupported_type" | "status" · 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
    • params · 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) · required
  • templateId · string · required, length 1–∞

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
    • params · 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) · required
  • templateId · string · required, length 1–∞

Request body · application/json, required

  • name · string · length 1–200

Response 200 · application/json

  • id · string · required
  • builtin · boolean · required
  • readOnly · boolean · required
  • template · object · required
    • name · string · required, length 1–200
    • description · string · required, length 0–500
    • version · integer · required, 1–9007199254740991
    • columns · object[] · required, 0–50 items
      • label · string · required, length 1–200
      • icon · string · length 0–2048
    • lanes · object[] · required, 0–20 items
      • label · string · required, length 1–200
      • icon · string · length 0–2048
    • fields · object[] · required, 0–30 items
      • key · string · required, length 1–100
      • name · string · required, length 1–200
      • type · "select" | "multi_select" | "checkbox" | "number" | "text" | "date" | "person" | "url" · required
      • options · object[] · required, 0–50 items, default []
        • label · string · required, length 1–200
        • color · "#94a3b8" | "#f59e0b" | "#22c55e" | "#3b82f6" | "#ec4899" | "#a855f7" · required
    • cardFields · string[] · required, 0–30 items
    • showCardNumbers · boolean
  • createdAt · string (date-time) | null · required
  • updatedAt · 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
    • params · 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) · required
  • templateId · string · required, length 1–∞

Request body · application/json, required

  • collectionId · string (uuid) · required
  • title · string · required, length 1–500

Response 200 · application/json

  • board · 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
      • icon · string · length 0–2048
      • collapsed · boolean
    • noLaneCollapsed · boolean · required
    • noLaneLabel · string | null · required
    • cardFields · string (uuid)[] · required
    • showCardNumbers · boolean · required
    • template · object
      • id · string · required, length 1–100
      • version · integer · required, 1–9007199254740991
      • offerSeen · integer · 1–9007199254740991
    • configVersion · string · required
    • createdAt · string (date-time) · required
    • updatedAt · string (date-time) · required
    • deletedAt · string (date-time) | null · required
  • made · object[] · required
    • kind · "column" | "lane" | "field" | "binding" | "option" | "card_field" · required
    • name · string · required
  • skipped · object[] · required
    • kind · "lane" | "field" | "option" | "card_field" · required
    • name · string · required
    • reason · "conflict" | "needs_admin" | "options_need_admin" | "missing_builtin" | "lane_name_taken" | "unsupported_type" | "status" · 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
    • params · 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) · required
  • boardId · string (uuid) · required

Request body · application/json, required

  • templateId · string · required, length 1–∞

Response 200 · application/json

  • configVersion · string · required
  • template · object · required
    • id · string · required
    • name · string · required
    • version · integer · required, -9007199254740991–9007199254740991
  • plan · object · required
    • columnsToAdd · object[] · required
      • label · string · required
      • icon · string · length 0–2048
    • lanesToAdd · object[] · required
      • label · string · required
      • icon · string · length 0–2048
    • fieldsToBind · object[] · required
      • fieldId · string (uuid) · required
      • key · string · required
    • fieldsToCreate · object[] · required
      • field · object · required
        • key · string · required
        • name · string · required
        • type · "select" | "multi_select" | "checkbox" | "number" | "text" | "date" | "person" | "url" · required
        • options · object[] · required
          • …
      • needsAdmin · boolean · required
    • optionsToAdd · object[] · required
      • key · string · required
      • options · object[] · required
        • label · string · required
        • color · string · required
      • needsAdmin · boolean · required
    • cardFieldsToShow · string[] · required
    • showCardNumbersToSet · boolean · required
    • conflicts · object[] · required
      • key · string · required
      • templateType · string · required
      • existingType · string · required
    • notes · object[] · required
      • code · "conflict" | "needs_admin" | "options_need_admin" | "missing_builtin" | "lane_name_taken" · required
      • key · string · required
    • empty · boolean · 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
    • params · 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) · required
  • boardId · string (uuid) · required

Request body · application/json, required

  • templateId · string · required, length 1–∞
  • expectedConfigVersion · string · required

Response 200 · application/json

  • board · 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
      • icon · string · length 0–2048
      • collapsed · boolean
    • noLaneCollapsed · boolean · required
    • noLaneLabel · string | null · required
    • cardFields · string (uuid)[] · required
    • showCardNumbers · boolean · required
    • template · object
      • id · string · required, length 1–100
      • version · integer · required, 1–9007199254740991
      • offerSeen · integer · 1–9007199254740991
    • configVersion · string · required
    • createdAt · string (date-time) · required
    • updatedAt · string (date-time) · required
    • deletedAt · string (date-time) | null · required
  • made · object[] · required
    • kind · "column" | "lane" | "field" | "binding" | "option" | "card_field" · required
    • name · string · required
  • skipped · object[] · required
    • kind · "lane" | "field" | "option" | "card_field" · required
    • name · string · required
    • reason · "conflict" | "needs_admin" | "options_need_admin" | "missing_builtin" | "lane_name_taken" | "unsupported_type" | "status" · 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
    • params · 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) · required
  • boardId · string (uuid) · required

Response 200 · application/json

  • items · object[] · required
    • id · string (uuid) · required
    • boardId · string (uuid) · required
    • name · string · required
    • status · "active" | "paused" · required
    • pauseReason · "target_missing" | "board_missing" | "creator_no_access" | null · required
    • trigger · object · required
      • type · "schedule" · required
      • frequency · "daily" | "weekly" | "monthly" · required
      • weekdays · integer[] · 1–7 items
      • monthDay · integer · 1–31
      • time · string · required
      • timeZone · string · required, length 1–64
    • action · object · required
      • type · "create_card" · required
      • title · string · required, length 1–500
      • markdown · string · length 0–50000
      • cells · object
      • columnId · string (uuid) · required
      • laneId · string (uuid) | null · required, default null
      • onlyIfPreviousDone · boolean · required, default false
    • nextRunAt · string (date-time) | null · required
    • lastRunAt · string (date-time) | null · required
    • createdBy · string (uuid) · required
    • createdAt · string (date-time) · required
    • updatedAt · string (date-time) · 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
    • params · 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) · required
  • boardId · string (uuid) · required

Request body · application/json, required

  • name · string · required, length 1–200
  • trigger · object · required
    • type · "schedule" · required
    • frequency · "daily" | "weekly" | "monthly" · required
    • weekdays · integer[] · 1–7 items
    • monthDay · integer · 1–31
    • time · string · required
    • timeZone · string · required, length 1–64
  • action · object · required
    • type · "create_card" · required
    • title · string · required, length 1–500
    • markdown · string · length 0–50000
    • cells · object
    • columnId · string (uuid) · required
    • laneId · string (uuid) | null · default null
    • onlyIfPreviousDone · boolean · default false
  • paused · boolean

Response 200 · application/json

  • id · string (uuid) · required
  • boardId · string (uuid) · required
  • name · string · required
  • status · "active" | "paused" · required
  • pauseReason · "target_missing" | "board_missing" | "creator_no_access" | null · required
  • trigger · object · required
    • type · "schedule" · required
    • frequency · "daily" | "weekly" | "monthly" · required
    • weekdays · integer[] · 1–7 items
    • monthDay · integer · 1–31
    • time · string · required
    • timeZone · string · required, length 1–64
  • action · object · required
    • type · "create_card" · required
    • title · string · required, length 1–500
    • markdown · string · length 0–50000
    • cells · object
    • columnId · string (uuid) · required
    • laneId · string (uuid) | null · required, default null
    • onlyIfPreviousDone · boolean · required, default false
  • nextRunAt · string (date-time) | null · required
  • lastRunAt · string (date-time) | null · required
  • createdBy · string (uuid) · required
  • createdAt · string (date-time) · required
  • updatedAt · string (date-time) · 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
    • params · 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) · required
  • automationId · string (uuid) · required

Request body · application/json, required

  • name · string · length 1–200
  • status · "active" | "paused"
  • trigger · object
    • type · "schedule" · required
    • frequency · "daily" | "weekly" | "monthly" · required
    • weekdays · integer[] · 1–7 items
    • monthDay · integer · 1–31
    • time · string · required
    • timeZone · string · required, length 1–64
  • action · object
    • type · "create_card" · required
    • title · string · required, length 1–500
    • markdown · string · length 0–50000
    • cells · object
    • columnId · string (uuid) · required
    • laneId · string (uuid) | null · default null
    • onlyIfPreviousDone · boolean · default false

Response 200 · application/json

  • id · string (uuid) · required
  • boardId · string (uuid) · required
  • name · string · required
  • status · "active" | "paused" · required
  • pauseReason · "target_missing" | "board_missing" | "creator_no_access" | null · required
  • trigger · object · required
    • type · "schedule" · required
    • frequency · "daily" | "weekly" | "monthly" · required
    • weekdays · integer[] · 1–7 items
    • monthDay · integer · 1–31
    • time · string · required
    • timeZone · string · required, length 1–64
  • action · object · required
    • type · "create_card" · required
    • title · string · required, length 1–500
    • markdown · string · length 0–50000
    • cells · object
    • columnId · string (uuid) · required
    • laneId · string (uuid) | null · required, default null
    • onlyIfPreviousDone · boolean · required, default false
  • nextRunAt · string (date-time) | null · required
  • lastRunAt · string (date-time) | null · required
  • createdBy · string (uuid) · required
  • createdAt · string (date-time) · required
  • updatedAt · string (date-time) · 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
    • params · 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) · required
  • automationId · 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
    • params · 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) · required
  • automationId · string (uuid) · required

Response 200 · application/json

  • id · string (uuid) · required
  • automationId · string (uuid) · required
  • occurrenceKey · string · required
  • scheduledFor · string (date-time) | null · required
  • ranAt · string (date-time) · required
  • outcome · "created" | "skipped" | "paused" | "failed" · required
  • pageId · string (uuid) | null · required
  • message · string | 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
    • params · 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) · required
  • automationId · string (uuid) · required

Response 200 · application/json

  • items · object[] · required
    • id · string (uuid) · required
    • automationId · string (uuid) · required
    • occurrenceKey · string · required
    • scheduledFor · string (date-time) | null · required
    • ranAt · string (date-time) · required
    • outcome · "created" | "skipped" | "paused" | "failed" · required
    • pageId · string (uuid) | null · required
    • message · string | 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
    • params · 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 · required
    • type · "schedule" · required
    • frequency · "daily" | "weekly" | "monthly" · required
    • weekdays · integer[] · 1–7 items
    • monthDay · integer · 1–31
    • time · string · required
    • timeZone · string · required, length 1–64

Response 200 · application/json

  • occurrences · string (date-time)[] · 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
    • params · object