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
sectionIdandsectionName. - 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
403with"code": "module_disabled". - If a request body is not valid JSON, these requests treat it as an empty object
{}instead of returning an error. ForPOST /tasks/:id/movethat means “clear the status”,PATCH /tasks/:idchanges nothing, and the others answer422. 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.