SectionBot API: address, authorization, errors

Bot API: address, authorization, errors

Learn the bot API's base address, how to send the bot's key, the request and response format, the error codes and how to make a first request.

The bot API is a set of HTTP requests your program uses to act in Syncra as a bot: post messages, read channels, work with tasks. Every request carries the bot’s 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 page Bots walks through it step by step.

Base address

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

Every path in this part of the docs is relative to this address: /messages means https://ai-syncra.ru/api/bot/v1/messages.

Requests and responses are JSON. Add the header Content-Type: application/json to a request that has a body.

Authorization

Send the key in the Authorization header of every request:

Authorization: Bearer skb_...

A key belongs to one bot and one workspace. Every request made with it reads and changes only that workspace. To the bot, channels, messages and tasks of other workspaces do not exist: a request for one gets 404.

A 401 response with the body {"error":"Unauthorized"} comes when:

  • the Authorization header is missing or its value does not start with Bearer skb_;
  • no such key exists or it was revoked;
  • the bot is turned off with the Bot enabled switch.

The bot key is the only way to authorize. The bot API does not accept a signed-in browser session, and it does not accept the access of an AI app such as Claude or ChatGPT that a person connected to the workspace.

First request

GET /me

Returns the bot that owns the key and its workspace. Use it to check quickly that the key works.

No parameters.

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

Response 200:

{
  "botId": "5f0c2a7e9b1d4c3a8e6f1a2b3c4d5e6f",
  "userId": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "name": "Deploy bot",
  "workspaceId": "0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "workspaceSlug": "acme"
}
Field Type Description
botId string The bot’s id
userId string The bot’s id as a member. Messages (authorId) and tasks (assigneeId) refer to the bot by this value
name string The bot’s name
workspaceId string The workspace id
workspaceSlug string The short address of the workspace, the same one as in /w/<slug>/... links

Next, post a first message. The bot must be a member of the channel you post to.

curl -X POST "https://ai-syncra.ru/api/bot/v1/messages" \
  -H "Authorization: Bearer skb_..." \
  -H "Content-Type: application/json" \
  -d '{"channelId":"<channel id>","text":"Build 142 passed"}'

Response 200:

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

To find a channel id, call GET /channels. Both requests are described in full on the page Messages and channels.

Data format

  • Ids are strings. Pass them exactly as you received them.
  • Dates in responses are ISO 8601 strings in UTC, for example 2026-11-10T09:30:00.000Z.
  • 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 successful response always has the code 200, including when a message or a comment is created.

Errors

An error is a response with a 4xx or 5xx code and JSON with an error field.

{ "error": "Channel not found" }
Code When it comes Body
400 The body of a message, channel, direct chat or upload request is not valid JSON, a required query parameter is missing, or a value makes no sense (for example, the project has no status with that name). Task requests read a body that is not valid JSON as an empty object {} {"error":"<text>"}
401 No key, a wrong or revoked key, or a disabled bot {"error":"Unauthorized"}
403 The bot is not a member of the channel; the channel is not public and cannot be joined; the Tasks module is turned off in this workspace {"error":"<text>"}
404 The channel, message, member or task does not exist in the key’s workspace {"error":"<text>"}
422 The request body failed validation: a required field is missing, a string is over its limit, or an extra field is sent where none is allowed {"error":"Validation error","details":{...}}, and {"error":"<text>"} for POST /uploads/presign
500 An unexpected error on the Syncra side {"error":"Internal server error","errId":"..."}

An example 422 response. Fields with a problem are named in details.fieldErrors, and problems with the body as a whole (such as an extra field) are in details.formErrors:

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

When the Tasks module is turned off for the workspace, requests to /tasks and /projects answer 403:

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

The text in error is meant for people to read. It is in English by default. If the request carries an Accept-Language header that starts with ru, many error texts come back in Russian. Make your program check the response code and the code field, not the text.

On a 500 response, save the errId value and pass it to the Syncra team: they use it to find the error in their logs.

Limits

  • The bot API has no limit on the number of requests. It sends no rate-limit headers and no 429 response.
  • A message is up to 4,000 characters, a task title up to 300, a task description and a comment up to 10,000.
  • A message can carry up to 10 files.
  • Lists come without a total count (total). The description of each list request says how to page through it.

The page What exists and what does not covers the other limits.

Retry without duplicates

If the network drops the response, your program cannot tell whether the message was posted. POST /messages has the clientNonce field for this case: generate a unique string of up to 100 characters for each message and send the same string on every attempt. A retry with the same string does not create a second message. It returns the id of the first one and "deduplicated": true.

All requests

Request What it does Page
GET /me The bot and its workspace this page
GET /channels Channels the bot can see Messages and channels
POST /channels/:channelId/join Join a public channel Messages and channels
POST /messages Post a message or a thread reply Messages and channels
PATCH /messages/:messageId Edit the bot’s own message Messages and channels
DELETE /messages/:messageId Delete the bot’s own message Messages and channels
GET /messages Read a channel’s history Messages and channels
POST /dms Open a direct chat with a member Messages and channels
POST /uploads/presign Get an address for uploading a file Messages and channels
GET /projects Projects and their statuses Tasks and projects
GET /tasks List tasks Tasks and projects
GET /tasks/:id One task Tasks and projects
PATCH /tasks/:id Change a task Tasks and projects
POST /tasks/:id/move Move a task to another status Tasks and projects
POST /tasks/:id/complete Complete or reopen a task Tasks and projects
GET /tasks/:id/comments Comments on a task Tasks and projects
POST /tasks/:id/comments Add a comment Tasks and projects