API ботов: задачи и проекты
Какими запросами бот читает проекты и задачи, оставляет комментарии, меняет исполнителя, срок, приоритет и статус и завершает задачи.
Эта страница описывает запросы, которыми бот работает с задачами: читает проекты и задачи, пишет комментарии, меняет поля, переносит задачу в другой статус и завершает её. Для них нужен ключ бота. Его выпускает владелец или администратор рабочего пространства: настройки пространства, вкладка «Боты», раздел «API-токены» на странице бота. Адрес API, заголовок с ключом и общие коды ошибок описаны на странице «API ботов».
Все пути записаны от адреса https://ai-syncra.ru/api/bot/v1.
Что нужно знать заранее
- Бот видит задачи всего рабочего пространства, к которому привязан ключ. Состоять в каналах для этого не нужно.
- Проект, который виден только своему создателю, боту недоступен. Запрос к задаче такого проекта отвечает
404, как к несуществующей. - Задачу в пути запроса можно указать идентификатором или коротким номером вида
SYN-42. Это номер, который участники видят в карточке задачи. - Статус задачи — это столбец доски проекта. В API он называется секцией: поля
sectionIdиsectionName. - Всё, что бот меняет, участники видят сразу и без перезагрузки страницы. В истории задачи автором изменения записан бот.
- Если модуль «Задачи» выключен для рабочего пространства, все запросы этой страницы отвечают
403с"code": "module_disabled". - Если тело запроса — некорректный JSON, Syncra не отвечает ошибкой, а считает тело пустым объектом
{}. ДляPOST /tasks/:id/moveэто значит «убрать статус»,PATCH /tasks/:idничего не меняет, остальные отвечают422. Проверяйте JSON до отправки.
Проекты
GET /projects
Возвращает действующие проекты рабочего пространства и статусы каждого. Архивных и удалённых проектов в ответе нет, как и проектов, которые видны только своему создателю. Отсюда берут projectId и sectionId для остальных запросов.
Параметров нет.
curl "https://ai-syncra.ru/api/bot/v1/projects" \
-H "Authorization: Bearer skb_..."
Ответ 200:
{
"items": [
{
"id": "e5f60718293a4b5c6d7e8f90a1b2c3d4",
"name": "Сайт",
"sections": [
{ "id": "f60718293a4b5c6d7e8f90a1b2c3d4e5", "name": "К выполнению" },
{ "id": "0718293a4b5c6d7e8f90a1b2c3d4e5f6", "name": "В работе" },
{ "id": "18293a4b5c6d7e8f90a1b2c3d4e5f607", "name": "Готово" }
]
}
]
}
Задачи
GET /tasks
Возвращает задачи рабочего пространства. Без параметров отдаёт открытые задачи, не больше 50.
| Параметр | Где | Тип | Обязателен | Описание |
|---|---|---|---|---|
assignee |
строка запроса | string | нет | me — задачи, назначенные на бота. Идентификатор участника — задачи этого участника |
projectId |
строка запроса | string | нет | Только задачи этого проекта |
sectionId |
строка запроса | string | нет | Только задачи в этом статусе |
status |
строка запроса | string | нет | open — открытые (по умолчанию), completed — завершённые, all — все |
limit |
строка запроса | number | нет | Сколько задач вернуть, от 1 до 100. По умолчанию 50 |
curl "https://ai-syncra.ru/api/bot/v1/tasks?assignee=me&status=open" \
-H "Authorization: Bearer skb_..."
Ответ 200. В примере показаны основные поля задачи, в настоящем ответе у объекта есть и другие:
{
"items": [
{
"id": "293a4b5c6d7e8f90a1b2c3d4e5f60718",
"projectId": "e5f60718293a4b5c6d7e8f90a1b2c3d4",
"sectionId": "0718293a4b5c6d7e8f90a1b2c3d4e5f6",
"title": "Обновить страницу тарифов",
"description": "Добавить пример расчёта для девяти человек",
"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": "сайт", "color": null }
],
"key": "SYN",
"number": 42,
"ref": "SYN-42"
}
]
}
| Поле | Тип | Описание |
|---|---|---|
id |
string | Идентификатор задачи |
projectId |
string | Проект задачи |
sectionId |
string или null | Статус задачи. null — задача без статуса |
title |
string | Название |
description |
string или null | Описание |
priority |
string | none, low, medium, high или urgent |
assigneeId |
string или null | Исполнитель |
dueDate |
string или null | Срок, ISO 8601 по UTC |
isCompleted |
boolean | Завершена ли задача |
completedAt |
string или null | Когда завершена |
createdBy |
string | Кто создал задачу |
createdAt |
string | Когда создана |
labels |
array | Метки задачи: id, name, color |
key, number, ref |
string, number, string | Короткий номер задачи по частям и целиком: SYN, 42, SYN-42 |
Как листать. Общего числа задач и смещения у запроса нет. Если задач больше 100, сужайте выборку параметрами projectId, sectionId, assignee и status.
GET /tasks/:id
Возвращает одну задачу. К полям из списка добавляет название статуса и проекта и файлы задачи.
| Параметр | Где | Тип | Обязателен | Описание |
|---|---|---|---|---|
id |
путь | string | да | Идентификатор задачи или её короткий номер, например SYN-42 |
curl "https://ai-syncra.ru/api/bot/v1/tasks/SYN-42" \
-H "Authorization: Bearer skb_..."
Ответ 200 — объект задачи с теми же полями, что в списке, и тремя дополнительными:
| Поле | Тип | Описание |
|---|---|---|
sectionName |
string или null | Название статуса |
projectName |
string или null | Название проекта |
attachments |
array | Файлы, приложенные к задаче: id, name, contentType, size, url |
Ошибка: 404 с телом {"error":"Not found"}, если задачи нет, она удалена или её проект боту недоступен.
PATCH /tasks/:id
Меняет поля задачи. Передавайте только те поля, которые хотите изменить: остальные останутся как были. Лишнее поле в теле запроса — ошибка 422.
| Параметр | Где | Тип | Обязателен | Описание |
|---|---|---|---|---|
id |
путь | string | да | Идентификатор задачи или её короткий номер |
assigneeId |
тело | string или null | нет | Новый исполнитель: идентификатор участника рабочего пространства. null снимает исполнителя |
title |
тело | string | нет | Новое название, от 1 до 300 символов |
description |
тело | string | нет | Новое описание, до 10 000 символов. Пустая строка стирает описание |
priority |
тело | string | нет | none, low, medium, high или urgent |
dueDate |
тело | string или null | нет | Новый срок: дата и время со смещением от UTC, например 2026-11-14T18:00:00+03:00 или 2026-11-14T15:00:00Z. null снимает срок |
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"}'
Ответ 200 — задача после изменения. В этом ответе нет полей labels, key, number, ref, sectionName, projectName и attachments: за ними обратитесь к GET /tasks/:id.
Срок без смещения API не принимает. Значения вроде 2026-11-14 или 2026-11-14T18:00:00 возвращают 400: у программы нет часового пояса, и Syncra не угадывает, какой день вы имели в виду.
Новый исполнитель получает уведомление о назначении и начинает следить за задачей.
Ошибки:
| Код | Тело | Причина |
|---|---|---|
400 |
{"error":"Assignee is not a member"} |
assigneeId не принадлежит участнику рабочего пространства |
400 |
{"error":"Invalid due date ..."} |
В dueDate нет смещения от UTC или значение не похоже на дату |
400 |
{"error":"Invalid task title"} |
Название состоит из одних пробелов |
404 |
{"error":"Not found"} |
Задачи нет, она удалена или её проект боту недоступен |
422 |
{"error":"Validation error","details":{...}} |
Лишнее поле, неизвестный приоритет, строка длиннее лимита |
POST /tasks/:id/move
Переносит задачу в другой статус того же проекта. Статус указывают идентификатором или названием. Задача встаёт в конец столбца.
| Параметр | Где | Тип | Обязателен | Описание |
|---|---|---|---|---|
id |
путь | string | да | Идентификатор задачи или её короткий номер |
sectionId |
тело | string | нет | Идентификатор статуса из GET /projects |
sectionName |
тело | string | нет | Название статуса. Регистр букв не важен |
Передайте одно из двух полей. Если переданы оба, работает sectionId. Если не передано ни одно, задача уходит из своего статуса и остаётся без статуса, а в ответе sectionId равен null.
Перенос меняет и отметку о завершении. Перенос в статус, который в проекте означает «готово», завершает задачу. Перенос из него в любой другой статус открывает задачу заново.
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":"В работе"}'
Ответ 200:
{ "ok": true, "sectionId": "0718293a4b5c6d7e8f90a1b2c3d4e5f6" }
Ошибки:
| Код | Тело | Причина |
|---|---|---|
400 |
{"error":"Invalid section"} |
Статуса с таким идентификатором или названием нет в проекте задачи |
404 |
{"error":"Not found"} |
Задачи нет, она удалена или её проект боту недоступен |
422 |
{"error":"Validation error","details":{...}} |
В теле есть поле кроме sectionId и sectionName |
POST /tasks/:id/complete
Завершает задачу или открывает её заново.
| Параметр | Где | Тип | Обязателен | Описание |
|---|---|---|---|---|
id |
путь | string | да | Идентификатор задачи или её короткий номер |
completed |
тело | boolean | да | true — завершить, false — открыть заново |
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}'
Ответ 200 — задача после изменения, в том же виде, что у PATCH /tasks/:id. У завершённой задачи isCompleted равно true и заполнено completedAt.
Завершённая задача переходит в статус, который в проекте означает «готово». Задача, открытая заново, из этого статуса уходит и остаётся без статуса.
Ошибки: 404 с телом {"error":"Not found"}, если задачи нет; 422, если в теле нет completed или это не true и не false.
Комментарии
GET /tasks/:id/comments
Возвращает комментарии к задаче от старых к новым. Если комментариев больше, чем limit, в ответ попадают самые свежие.
| Параметр | Где | Тип | Обязателен | Описание |
|---|---|---|---|---|
id |
путь | string | да | Идентификатор задачи или её короткий номер |
limit |
строка запроса | number | нет | Сколько комментариев вернуть, от 1 до 200. По умолчанию 50 |
curl "https://ai-syncra.ru/api/bot/v1/tasks/SYN-42/comments?limit=20" \
-H "Authorization: Bearer skb_..."
Ответ 200. В примере показаны основные поля комментария, в настоящем ответе у объекта есть и другие:
{
"items": [
{
"id": "4b5c6d7e8f90a1b2c3d4e5f60718293a",
"taskId": "293a4b5c6d7e8f90a1b2c3d4e5f60718",
"authorId": "b2c3d4e5f60718293a4b5c6d7e8f90a1",
"body": "Пример расчёта добавила, посмотрите",
"createdAt": "2026-11-10T08:05:11.220Z",
"editedAt": null
}
]
}
Ошибка: 404 с телом {"error":"Not found"}, если задачи нет, она удалена или её проект боту недоступен.
POST /tasks/:id/comments
Оставляет комментарий к задаче от имени бота. После этого бот начинает следить за задачей.
| Параметр | Где | Тип | Обязателен | Описание |
|---|---|---|---|---|
id |
путь | string | да | Идентификатор задачи или её короткий номер |
body |
тело | string | да | Текст комментария, от 1 до 10 000 символов |
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":"Сборка с этой задачей выкачена"}'
Ответ 200:
{ "ok": true, "commentId": "5c6d7e8f90a1b2c3d4e5f60718293a4b" }
Ошибки: 404 с телом {"error":"Not found"}, если задачи нет; 422, если body пустой или длиннее 10 000 символов.
Как узнавать о новых задачах
API не присылает изменения сам. Чтобы бот узнавал, что задачу создали, назначили или перенесли, настройте подписки на события: Syncra будет отправлять запрос на ваш адрес. События о действиях самих ботов не приходят, поэтому бот не получит уведомление о собственном изменении.
Чего здесь нет
- Создать или удалить задачу через API ботов нельзя.
- Нет запросов для меток, подзадач, эпиков и файлов задачи.
- Нет запросов для страниц базы знаний.
Создавать задачи и страницы базы знаний умеют ИИ-приложения, которые человек подключил к рабочему пространству от своего имени. Для этого служит MCP — протокол, по которому Claude, ChatGPT и Cursor подключаются к внешнему сервису и вызывают его действия. Как подключить такое приложение, написано на странице «Подключить свой ИИ». Полный список ограничений — на странице «Что есть и чего нет».