РазделAPI ботов: адрес, авторизация, ошибки

API ботов: адрес, авторизация, ошибки

По какому адресу работает API ботов, как передать ключ бота в запросе, какие ошибки возвращает API и как сделать первый запрос.

API ботов — это HTTP-запросы, которыми ваша программа действует в Syncra от имени бота: пишет сообщения, читает каналы, работает с задачами. Каждый запрос подписан ключом бота. Ключ выпускает владелец или администратор рабочего пространства: настройки пространства, вкладка «Боты», страница бота, раздел «API-токены». Как это сделать по шагам, написано на странице «Боты».

Базовый адрес

https://ai-syncra.ru/api/bot/v1

Все пути на страницах этого раздела записаны от этого адреса: /messages значит https://ai-syncra.ru/api/bot/v1/messages.

Запросы и ответы — JSON. К запросам с телом добавляйте заголовок Content-Type: application/json.

Авторизация

Ключ передаётся в заголовке Authorization каждого запроса:

Authorization: Bearer skb_...

Ключ привязан к одному боту и одному рабочему пространству. Все запросы с ним читают и меняют только это пространство. Канал, сообщение или задача из другого пространства для бота не существуют: запрос вернёт 404.

Ответ 401 с телом {"error":"Unauthorized"} приходит, когда:

  • заголовка Authorization нет или значение не начинается с Bearer skb_;
  • такого ключа нет или его отозвали;
  • бот выключен переключателем «Бот включён».

Других способов авторизации у этого API нет: сессия браузера и токен подключённого ИИ-приложения здесь не принимаются.

Первый запрос

GET /me

Возвращает бота, которому принадлежит ключ, и его рабочее пространство. Этим запросом проверяют, что ключ работает.

Параметров нет.

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

Ответ 200:

{
  "botId": "5f0c2a7e9b1d4c3a8e6f1a2b3c4d5e6f",
  "userId": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "name": "Deploy bot",
  "workspaceId": "0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "workspaceSlug": "acme"
}
Поле Тип Описание
botId string Идентификатор бота
userId string Идентификатор бота как участника. Этим значением бот подписан в сообщениях (authorId) и задачах (assigneeId)
name string Имя бота
workspaceId string Идентификатор рабочего пространства
workspaceSlug string Короткий адрес пространства, тот же, что в ссылках /w/<адрес>/...

Затем отправьте первое сообщение. Бот должен состоять в канале, куда пишет: как его добавить, написано на странице «Боты».

curl -X POST "https://ai-syncra.ru/api/bot/v1/messages" \
  -H "Authorization: Bearer skb_..." \
  -H "Content-Type: application/json" \
  -d '{"channelId":"<id канала>","text":"Сборка 142 прошла"}'

Ответ 200:

{ "ok": true, "messageId": "9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a40", "deduplicated": false }

Идентификатор канала возвращает запрос GET /channels. Оба запроса подробно описаны на странице «Сообщения и каналы».

Формат данных

  • Идентификаторы — строки. Передавайте их так, как получили из ответа.
  • Даты в ответах — строки в формате ISO 8601 по UTC, например 2026-11-10T09:30:00.000Z.
  • Задачу можно указать идентификатором или коротким номером вида SYN-42: это номер, который участники видят в карточке задачи.
  • Успешный ответ всегда приходит с кодом 200, в том числе на создание сообщения или комментария.

Ошибки

Ошибка — это ответ с кодом 4xx или 5xx и JSON с полем error.

{ "error": "Channel not found" }
Код Когда приходит Тело
400 Тело запроса к сообщениям, каналам, личным чатам или загрузке файлов — некорректный JSON; не хватает обязательного параметра в адресе; значение не подошло по смыслу (например, статуса с таким именем нет в проекте). Некорректное тело запроса к задачам Syncra считает пустым объектом {} {"error":"<текст>"}
401 Нет ключа, ключ неверный или отозван, бот выключен {"error":"Unauthorized"}
403 Бот не состоит в канале; канал закрытый и вступить в него нельзя; модуль «Задачи» выключен в этом рабочем пространстве {"error":"<текст>"}
404 Канала, сообщения, участника или задачи нет в рабочем пространстве ключа {"error":"<текст>"}
422 Тело запроса не прошло проверку: нет обязательного поля, строка длиннее лимита, лишнее поле там, где оно запрещено {"error":"Validation error","details":{...}}, у POST /uploads/presign — {"error":"<текст>"}
500 Непредвиденная ошибка на стороне Syncra {"error":"Internal server error","errId":"..."}

Пример ответа 422. Имена полей с ошибкой лежат в details.fieldErrors, ошибки всего тела (например, лишнее поле) — в details.formErrors:

{
  "error": "Validation error",
  "details": {
    "formErrors": [],
    "fieldErrors": { "text": ["..."] }
  }
}

Если модуль «Задачи» выключен для рабочего пространства, запросы к /tasks и /projects отвечают 403:

{ "error": "This module is turned off in this workspace", "code": "module_disabled", "module": "tasks" }

Текст в поле error написан для человека. По умолчанию он английский. Если запрос несёт заголовок Accept-Language, который начинается с ru, текст многих ошибок придёт на русском. В программе опирайтесь на код ответа и поле code, а не на текст.

При ответе 500 сохраните значение errId: по нему команда Syncra найдёт ошибку в журнале.

Лимиты

  • Ограничения на число запросов у API ботов нет. Заголовков с остатком лимита и ответа 429 тоже нет.
  • Текст сообщения — до 4000 символов, название задачи — до 300, описание задачи и комментарий — до 10 000.
  • К сообщению можно приложить до 10 файлов.
  • Списки отдаются без общего числа записей (total). Как листать каждый список, написано в описании его запроса.

Что ещё есть и чего нет, собрано на странице «Что есть и чего нет».

Повтор запроса без дублей

Сеть может оборвать ответ, и программа не узнает, дошло ли сообщение. На этот случай у POST /messages есть поле clientNonce: придумайте для каждого сообщения свою строку длиной до 100 символов и передавайте её при каждой попытке. Повтор с той же строкой не создаст второе сообщение, а вернёт идентификатор первого и "deduplicated": true.

Все запросы

Запрос Что делает Страница
GET /me Бот и его рабочее пространство эта страница
GET /channels Каналы, которые видит бот Сообщения и каналы
POST /channels/:channelId/join Вступить в открытый канал Сообщения и каналы
POST /messages Написать сообщение или ответ в ветке Сообщения и каналы
PATCH /messages/:messageId Изменить своё сообщение Сообщения и каналы
DELETE /messages/:messageId Удалить своё сообщение Сообщения и каналы
GET /messages Прочитать историю канала Сообщения и каналы
POST /dms Открыть личный чат с участником Сообщения и каналы
POST /uploads/presign Получить адрес для загрузки файла Сообщения и каналы
GET /projects Проекты и их статусы Задачи и проекты
GET /tasks Список задач Задачи и проекты
GET /tasks/:id Одна задача Задачи и проекты
PATCH /tasks/:id Изменить задачу Задачи и проекты
POST /tasks/:id/move Перенести задачу в другой статус Задачи и проекты
POST /tasks/:id/complete Завершить или открыть задачу заново Задачи и проекты
GET /tasks/:id/comments Комментарии к задаче Задачи и проекты
POST /tasks/:id/comments Оставить комментарий Задачи и проекты