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 |
Оставить комментарий | Задачи и проекты |