РазделAPI ботов: задачи и проекты

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 подключаются к внешнему сервису и вызывают его действия. Как подключить такое приложение, написано на странице «Подключить свой ИИ». Полный список ограничений — на странице «Что есть и чего нет».