Skip to content
DocumentationAPI ReferenceChangelog
API ReferenceTalon Studio v1.0.2-beta

Workboard

Read and create workboard (kanban) cards.

List workboard cards

GET/api/v1/kanban/cardskanban:read

List a workspace's workboard cards, flattened with their column, in board order.

Query parameters
workspaceIdstring (UUID)
Required with an org-scoped token; a workspace-bound token uses its own workspace.
Response
idstring (UUID)
columnIdstring (UUID)
columnTitlestring
columnStatusstring
in_progress | blocked | review | completed — the board's four fixed lanes (In Progress, Blocked, Review, Done).
titlestring
typestring
epic | task | investigation | bug | incident | improvement | hardening
prioritystring
High | Medium | Low
progressinteger
sourcestring
human | agent
agentNamestring · nullable
Set on cards an agent owns.
assigneesstring[]
dueDatestring (ISO 8601) · nullable
Returned as { data: [...] }. Reading the board repairs its lanes first: a missing lane is created, a duplicate lane is merged into the first, and a leftover Backlog lane from older versions is removed.
No columns endpoint
There is no /kanban/columns endpoint in v1. The only way to learn a valid columnId for creating a card is to read it off an existing card in this response — an empty lane contributes nothing, so a workspace with no cards has no way to discover a columnId through the API.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/kanban/cards?workspaceId=…"
Response
{
  "data": [
    {
      "id": "b2d7e441-3c9a-4f10-8e6b-5a1c2d0f7e93",
      "columnId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "columnTitle": "In Progress",
      "columnStatus": "in_progress",
      "title": "Tune brute-force rule",
      "type": "task",
      "priority": "High",
      "progress": 40,
      "source": "human",
      "agentName": null,
      "assignees": [],
      "dueDate": null
    }
  ]
}

Create workboard card

POST/api/v1/kanban/cardskanban:write

Create a workboard card in a lane. Not available on the Community Edition: kanban:write is a write scope and needs an Enterprise licence.

Request body
columnIdstring (UUID)required
A lane in the target workspace — read one from GET /kanban/cards.
titlestringrequired
1–200 characters.
descriptionstring · optional
Up to 4,000 characters.
typestring · optional
epic | task | investigation | bug | incident | improvement | hardening — defaults to task.
prioritystring · optional
High | Medium | Low — defaults to Medium.
workspaceIdstring (UUID) · optional
Required with an org-scoped token; a workspace-bound token uses its own workspace.
Response
dataobject
{ id, title, columnId }
Returns 201 Created. The card goes to the bottom of its lane, is logged on the card as created by the token's owner (or "API token" for a service token), fires any Flow listening for new cards, and is recorded in the audit log as api.card.created.
Column must belong to the workspace
If columnId isn't a lane in the resolved workspace, the API returns 400 "Column not found in this workspace".
Request
curl -X POST -H "Authorization: Bearer tlk_…" \
  -H "Content-Type: application/json" \
  -d '{"columnId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "title": "Tune brute-force rule", "priority": "High"}' \
  "https://<your-instance>/api/v1/kanban/cards"
Response
{
  "data": {
    "id": "c9f0a123-6d54-4b2e-9a71-0e3f8c5d1b62",
    "title": "Tune brute-force rule",
    "columnId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  }
}