SectionBot API: tasks and projects

Bot API: tasks and projects

Learn the requests a bot uses to read projects and tasks, add comments, change a task's assignee, due date, priority and status, and complete tasks.

This page describes the requests a bot uses for tasks: reading projects and tasks, writing comments, changing fields, moving a task to another status and completing it. Every request needs a bot key. A workspace owner or admin issues the key in the workspace settings: on the Bots tab, open the bot’s page and find the API tokens section. The API address, the header that carries the key and the common error codes are on the page Bot API.

Every path is relative to the address https://ai-syncra.ru/api/bot/v1.

What to know first

  • A bot sees the tasks of the whole workspace its key belongs to. It does not need to be a member of any channel for that.
  • A project that only its creator can see is closed to the bot. A request for a task in such a project gets 404, as if the task did not exist.
  • In a request path you can refer to a task by its id or by its short number such as SYN-42. Members see this number on the task card.
  • A task’s status is the column it sits in on the project board. The API calls a column a section, hence the fields sectionId and sectionName.
  • Members see every change a bot makes right away, without reloading the page. The task history names the bot as the author of the change.
  • When the Tasks module is turned off for the workspace, every request on this page gets 403 with "code": "module_disabled".
  • If a request body is not valid JSON, these requests treat it as an empty object {} instead of returning an error. For POST /tasks/:id/move that means “clear the status”, PATCH /tasks/:id changes nothing, and the others answer 422. Check your JSON before you send it.

Projects

GET /projects

Returns the active projects of the workspace and the statuses of each. Archived and deleted projects are left out, and so are projects that only their creator can see. Take projectId and sectionId for the other requests from this response.

No parameters.

curl "https://ai-syncra.ru/api/bot/v1/projects" \
  -H "Authorization: Bearer skb_..."

Response 200:

{
  "items": [
    {
      "id": "e5f60718293a4b5c6d7e8f90a1b2c3d4",
      "name": "Website",
      "sections": [
        { "id": "f60718293a4b5c6d7e8f90a1b2c3d4e5", "name": "To do" },
        { "id": "0718293a4b5c6d7e8f90a1b2c3d4e5f6", "name": "In progress" },
        { "id": "18293a4b5c6d7e8f90a1b2c3d4e5f607", "name": "Done" }
      ]
    }
  ]
}

Tasks

GET /tasks

Returns tasks of the workspace. With no parameters it returns open tasks, 50 at most.

Parameter In Type Required Description
assignee query string no me for tasks assigned to the bot. A member’s id for that member’s tasks
projectId query string no Only tasks of this project
sectionId query string no Only tasks in this status
status query string no open for open tasks (the default), completed for completed ones, all for both
limit query number no How many tasks to return, 1 to 100. The default is 50
curl "https://ai-syncra.ru/api/bot/v1/tasks?assignee=me&status=open" \
  -H "Authorization: Bearer skb_..."

Response 200. The example shows the main fields of a task. In a real response the object has other fields too:

{
  "items": [
    {
      "id": "293a4b5c6d7e8f90a1b2c3d4e5f60718",
      "projectId": "e5f60718293a4b5c6d7e8f90a1b2c3d4",
      "sectionId": "0718293a4b5c6d7e8f90a1b2c3d4e5f6",
      "title": "Update the pricing page",
      "description": "Add a worked example for nine people",
      "priority": "high",
      "assigneeId": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
      "dueDate": "2026-11-14T15:00:00.000Z",
      "isCompleted": false,
      "completedAt": null,
      "createdBy": "b2c3d4e5f60718293a4b5c6d7e8f90a1",
      "createdAt": "2026-11-07T08:12:45.103Z",
      "labels": [
        { "id": "3a4b5c6d7e8f90a1b2c3d4e5f6071829", "name": "website", "color": null }
      ],
      "key": "SYN",
      "number": 42,
      "ref": "SYN-42"
    }
  ]
}
Field Type Description
id string The task id
projectId string The task’s project
sectionId string or null The task’s status. null means the task has no status
title string The title
description string or null The description
priority string none, low, medium, high or urgent
assigneeId string or null The assignee
dueDate string or null The due date, ISO 8601 in UTC
isCompleted boolean Whether the task is completed
completedAt string or null When it was completed
createdBy string Who created the task
createdAt string When it was created
labels array The task’s labels: id, name, color
key, number, ref string, number, string The short number of the task in parts and whole: SYN, 42, SYN-42

How to page. The request has no total count and no offset. If there are more than 100 tasks, narrow the selection with projectId, sectionId, assignee and status.

GET /tasks/:id

Returns one task. Besides the fields from the list, it returns the status name, the project name and the task’s files.

Parameter In Type Required Description
id path string yes The task id or its short number, for example SYN-42
curl "https://ai-syncra.ru/api/bot/v1/tasks/SYN-42" \
  -H "Authorization: Bearer skb_..."

Response 200 is a task object with the same fields as in the list and three more:

Field Type Description
sectionName string or null The name of the status
projectName string or null The name of the project
attachments array Files attached to the task: id, name, contentType, size, url

Error: 404 with the body {"error":"Not found"} when the task does not exist, is deleted, or its project is closed to the bot.

PATCH /tasks/:id

Changes fields of a task. Send only the fields you want to change. The rest stay as they were. An extra field in the request body is a 422 error.

Parameter In Type Required Description
id path string yes The task id or its short number
assigneeId body string or null no The new assignee: the id of a workspace member. null removes the assignee
title body string no The new title, 1 to 300 characters
description body string no The new description, up to 10,000 characters. An empty string erases the description
priority body string no none, low, medium, high or urgent
dueDate body string or null no The new due date: a date and time with a UTC offset, for example 2026-11-14T18:00:00+03:00 or 2026-11-14T15:00:00Z. null removes the due date
curl -X PATCH "https://ai-syncra.ru/api/bot/v1/tasks/SYN-42" \
  -H "Authorization: Bearer skb_..." \
  -H "Content-Type: application/json" \
  -d '{"priority":"urgent","dueDate":"2026-11-14T18:00:00+03:00"}'

Response 200 is the task after the change. This response has no labels, key, number, ref, sectionName, projectName or attachments fields. Call GET /tasks/:id for those.

The API does not accept a due date without an offset. Values such as 2026-11-14 or 2026-11-14T18:00:00 get 400: Syncra does not know your program’s time zone and does not guess which day you meant.

The new assignee gets a notification about the assignment and starts following the task.

Errors:

Code Body Reason
400 {"error":"Assignee is not a member"} assigneeId does not belong to a member of the workspace
400 {"error":"Invalid due date ..."} dueDate has no UTC offset or cannot be read as a date
400 {"error":"Invalid task title"} The title is only spaces
404 {"error":"Not found"} The task does not exist, is deleted, or its project is closed to the bot
422 {"error":"Validation error","details":{...}} An extra field, an unknown priority, or a string over its limit

POST /tasks/:id/move

Moves a task to another status of the same project. Name the status by its id or by its name. The task goes to the end of the column.

Parameter In Type Required Description
id path string yes The task id or its short number
sectionId body string no A status id from GET /projects
sectionName body string no The name of the status. Letter case does not matter

Send one of the two fields. If both are sent, sectionId wins. If neither is sent, the task leaves its status and stays with none, and sectionId in the response is null.

A move can also complete or reopen the task. Moving a task into the status that means “done” in the project completes it. Moving it from there to any other status reopens it.

curl -X POST "https://ai-syncra.ru/api/bot/v1/tasks/SYN-42/move" \
  -H "Authorization: Bearer skb_..." \
  -H "Content-Type: application/json" \
  -d '{"sectionName":"In progress"}'

Response 200:

{ "ok": true, "sectionId": "0718293a4b5c6d7e8f90a1b2c3d4e5f6" }

Errors:

Code Body Reason
400 {"error":"Invalid section"} The task’s project has no status with this id or name
404 {"error":"Not found"} The task does not exist, is deleted, or its project is closed to the bot
422 {"error":"Validation error","details":{...}} The body has a field other than sectionId and sectionName

POST /tasks/:id/complete

Completes a task or reopens it.

Parameter In Type Required Description
id path string yes The task id or its short number
completed body boolean yes true to complete, false to reopen
curl -X POST "https://ai-syncra.ru/api/bot/v1/tasks/SYN-42/complete" \
  -H "Authorization: Bearer skb_..." \
  -H "Content-Type: application/json" \
  -d '{"completed":true}'

Response 200 is the task after the change, in the same shape as for PATCH /tasks/:id. A completed task has isCompleted set to true and completedAt filled in.

A completed task moves to the status that means “done” in the project. A reopened task leaves that status and stays with none.

Errors: 404 with the body {"error":"Not found"} when the task does not exist; 422 when the body has no completed or it is neither true nor false.

Comments

GET /tasks/:id/comments

Returns the comments on a task, oldest first. If the task has more comments than limit, the response contains the most recent ones.

Parameter In Type Required Description
id path string yes The task id or its short number
limit query number no How many comments to return, 1 to 200. The default is 50
curl "https://ai-syncra.ru/api/bot/v1/tasks/SYN-42/comments?limit=20" \
  -H "Authorization: Bearer skb_..."

Response 200. The example shows the main fields of a comment. In a real response the object has other fields too:

{
  "items": [
    {
      "id": "4b5c6d7e8f90a1b2c3d4e5f60718293a",
      "taskId": "293a4b5c6d7e8f90a1b2c3d4e5f60718",
      "authorId": "b2c3d4e5f60718293a4b5c6d7e8f90a1",
      "body": "I added the worked example, please take a look",
      "createdAt": "2026-11-10T08:05:11.220Z",
      "editedAt": null
    }
  ]
}

Error: 404 with the body {"error":"Not found"} when the task does not exist, is deleted, or its project is closed to the bot.

POST /tasks/:id/comments

Adds a comment to a task as the bot. The bot then starts following the task.

Parameter In Type Required Description
id path string yes The task id or its short number
body body string yes The comment text, 1 to 10,000 characters
curl -X POST "https://ai-syncra.ru/api/bot/v1/tasks/SYN-42/comments" \
  -H "Authorization: Bearer skb_..." \
  -H "Content-Type: application/json" \
  -d '{"body":"The build with this task is deployed"}'

Response 200:

{ "ok": true, "commentId": "5c6d7e8f90a1b2c3d4e5f60718293a4b" }

Errors: 404 with the body {"error":"Not found"} when the task does not exist; 422 when body is empty or longer than 10,000 characters.

How to learn about new tasks

The bot API does not push changes to your program. For a bot to learn that a task was created, assigned or moved, set up event subscriptions: Syncra then sends a request to your server’s address. Syncra sends no events for actions that bots make, so a bot gets no notice about its own changes.

What is not here

  • The bot API cannot create or delete a task.
  • There are no requests for labels, subtasks, epics or task files.
  • There are no requests for knowledge base pages.

An AI app that a person connects to the workspace under their own account can create tasks and pages. It connects through MCP, a protocol that lets Claude, ChatGPT and Cursor connect to an outside service and call its actions. The page Connect your AI explains how to connect such an app. The full list of limits is on the page What exists and what does not.