Boards and tasks

A bot works with task boards like a person, within the permissions of its roles and the overrides on the board. It creates and runs tasks, assigns people, comments, keeps checklists and milestones, and reads the journal and automation rules. A bot can be a task's assignee, and it can be let into a private board personally.

Routes#

Not available to bots#

These routes answer a bot with 403 BOT_NOT_ALLOWED, whatever permissions it has:

• board access PUT /api/boards/{id}/permissions and the final delete DELETE /api/boards/{id}?purge=1;
• voting on an approval POST /api/tasks/{id}/approval — a bot never approves tasks;
• the board webhook /api/boards/{id}/webhook… — it holds a secret and exports data (people set it up, see Webhooks);
• creating, changing, deleting and testing automation rules: POST /api/boards/{id}/rules, PATCH · DELETE /api/rules/{id}, POST /api/rules/{id}/test;
• connecting a Git repository to a board /api/boards/{id}/git.

Create a task#

CreateTaskRequest: title (1..200), description (≤ 20,000, markdown-lite), statusId (empty = the default status), priority (TASK_PRIORITY_NONE…TASK_PRIORITY_URGENT), assignees, labelIds, startOn / dueOn (YYYY-MM-DD), estimate, parentId, milestoneId, attachmentIds, approverIds, approvalRequired, fromMessageId (create from a message the bot can see).

curl -s -X POST $CALAB/api/boards/$BOARD/tasks \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d "{\"title\": \"Renew certificates\", \"priority\": \"TASK_PRIORITY_HIGH\", \"dueOn\": \"2026-10-20\",
       \"assignees\": [{\"userId\": \"$USER\", \"isLead\": true}]}"

import { TaskPriority } from '@calaba/protocol';

const task = await bot.tasks.create(boardId, {
  title: 'Renew certificates',
  priority: TaskPriority.HIGH,
  dueOn: '2026-10-20',
  assignees: [{ userId, isLead: true }],
});
await bot.tasks.comment(task, 'On it. I will remind you a day before the due date.');

r = requests.post(f"{CALAB}/api/boards/{board_id}/tasks", headers=H, json={
    "title": "Renew certificates", "priority": "TASK_PRIORITY_HIGH", "dueOn": "2026-10-20",
    "assignees": [{"userId": user_id, "isLead": True}],
})
task = r.json()["task"]

Response 201 is a TaskResponse {task, subtasks, related, parent, room}:

{
  "task": {
    "id": "0192b7e0-0000-7000-8000-0000000000dd",
    "boardId": "0192a000-0000-7000-8000-0000000000bb",
    "number": 42,
    "key": "OPS-42",
    "title": "Renew certificates",
    "description": "",
    "statusId": "0192a000-0000-7000-8000-0000000000c1",
    "priority": "TASK_PRIORITY_HIGH",
    "assignees": [{"userId": "0191c2d3-0000-7000-8000-000000000042", "isLead": true, "note": "", "assignedBy": "0192a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b", "assignedAt": "2026-10-14T10:00:00Z"}],
    "createdBy": "0192a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
    "dueOn": "2026-10-20",
    "roomId": "0192b7e0-0000-7000-8000-0000000000ee",
    "checklistTotal": 0,
    "checklistDone": 0,
    "milestones": [],
    "taskMilestoneId": "",
    "watcherIds": [],
    "createdAt": "2026-10-14T10:00:00Z"
  },
  "subtasks": [],
  "related": []
}

A task comment is an ordinary message in the task's hidden room task.roomId: the same message routes and reactions; files go through POST /api/boards/{id}/files. The SDK's bot.tasks.comment(task, text) does this for you.

Update and find#

await bot.tasks.update(task.id, { statusId: doneStatusId });
await bot.tasks.setAssignees(task.id, [{ userId, isLead: true, note: 'owns the renewal' }]);
const found = await bot.tasks.search(wsId, 'OPS-42');
const { task: t, subtasks } = await bot.tasks.get(task.id);
const all = await bot.tasks.list(boardId);   // every page

curl -s -X PATCH $CALAB/api/tasks/$TASK -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d "{\"statusId\": \"$DONE\"}"
curl -s "$CALAB/api/workspaces/$WS/tasks/search?q=OPS-42" -H "Authorization: Bearer $TOKEN"
curl -s $CALAB/api/t/OPS-42 -H "Authorization: Bearer $TOKEN"

GET /api/boards/{id}/tasks returns up to 500 tasks per page (by status, then position); an empty nextCursor means the last page. filter is a JSON TaskFilter {conditions, any} (≤ 30 conditions). Archived tasks come only with archived=1 or an “archived” condition.

Assignees, approvers, watchers#

Any human member who is not a guest can be an assignee, approver or watcher — even without access to the board, on a private board too (they then see the board only through their tasks: Board.taskScoped). A bot qualifies only if it sees the board, and never as an approver; otherwise 422. A bot itself never sees a board through its tasks — it needs VIEW_BOARD. Up to 50 watchers (409).

Checklists#

Checklists are edited like task fields: EDIT_TASKS, or CREATE_TASKS for the bot's own tasks and those it is assigned to. They need the Team plan (409 PLAN_LIMIT). Limits: ≤ 10 checklists per task (CHECKLIST_LIMIT), ≤ 100 items per checklist (CHECKLIST_ITEM_LIMIT), ≤ 50 board categories per workspace (BOARD_CATEGORY_LIMIT); all are 409 CONFLICT with used/limit.

const { checklist } = await bot.tasks.checklists.create(task.id, 'Before release');
await bot.tasks.checklists.addItem(checklist.id, 'Update the gateway certificate');
await bot.tasks.checklists.updateItem(itemId, { done: true });
const { task: subtask } = await bot.tasks.checklists.convertItem(itemId);   // item → subtask

Task milestones#

Milestones inside a task are stages with their own dates: POST /api/tasks/{id}/milestones {name, dueOn?}. The answer is {milestone, task}; milestones and progress (milestones, milestoneProgress, taskMilestoneId) are in every task and in the TASK_UPDATE event. A subtask is linked to its parent's milestone with PATCH /api/tasks/{id} {taskMilestoneId}.

• ≤ 20 milestones per task (409 TASK_MILESTONE_LIMIT); subtasks have none (422); a subtask links only its parent's milestone (422).
• While subtasks are linked, the server keeps the milestone's completion: a manual completed is 409 TASK_MILESTONE_AUTO.
• The “Milestones” feature is off on the board — 409 FEATURE_DISABLED.

const { milestone } = await bot.tasks.milestones.create(task.id, 'Testing', '2026-10-18');
await bot.tasks.milestones.update(milestone.id, { completed: true });

Board features and categories#

PATCH /api/boards/{id} {setDisabledFeatures, disabledFeatures, estimateScale} (MANAGE_BOARD) switches board features on and off. With a feature off, a request that changes its field to a non-empty value gets 409 CONFLICT, reason: "FEATURE_DISABLED", with field set to the field name (estimate, dueOn, approverIds…). Clearing the field and repeating the current value pass.

import { BoardFeature } from '@calaba/bot-sdk';

await bot.boards.setFeatures(boardId, { disabledFeatures: [BoardFeature.MILESTONES] });
const cat = await bot.boards.categories.create(wsId, 'Operations');
await bot.boards.setOrder(wsId, { boards: [{ boardId, categoryId: cat.id, position: 0 }] });

Automations#

A bot reads a board's rules (GET /api/boards/{id}/rules) and their run log (GET /api/rules/{id}/runs). Task changes made by a bot run the board's rules just like people's changes. Changes made by rules appear in the journal with an empty actorId and a ruleId.

Gotchas#