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
Authorizationheader is missing or its value does not start withBearer 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
429response. - 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 |