What exists and what does not
What a developer can use in Syncra today, which request limits and token lifetimes apply, and which tools, such as personal API tokens or an SDK, do not exist.
This page answers “can I do this” before you start writing code. It lists every way to connect to Syncra, the limits and lifetimes in force, the error format, and the things that do not exist. Bot keys, webhooks, subscriptions and commands are created by a workspace owner or admin: workspace settings, the Bots tab. Each person connects their own AI app themselves: the Preferences window, the Connected apps section.
What works today
There are five ways in. The first one uses MCP. MCP (Model Context Protocol) is an open protocol that lets an AI app find out which actions another service offers and run them.
| Way in | What it gives you | How access is proven |
|---|---|---|
| Connect your AI | Claude, ChatGPT or Cursor reads and writes in Syncra as a person, with that person’s rights. The server address is https://ai-syncra.ru/api/mcp. |
Sign-in through OAuth, the standard flow where the AI app opens a Syncra page and the person presses Allow themselves. |
| Bot API | A bot posts and reads messages, opens direct messages and works with tasks. The paths start with /api/bot/v1. |
A bot key skb_... in the Authorization header. |
| Incoming webhooks | One POST request posts text in a channel. | The secret whk_... is part of the address. |
| Event subscriptions | Syncra sends a request to your address when something happens. | Syncra signs the request with a secret whsec_.... |
| Slash commands | A command typed in the message field sends a request to your address. | Syncra signs the request with a secret whsec_.... |
Where to read the details:
- Connect your AI and what a connected app can do
- Bots and the bot API
- Incoming webhooks
- Event subscriptions
- Slash commands
Service addresses
Two addresses are open without a key. They are handy for checking that the server answers.
GET /api/health
Tells you the server is up. It takes no parameters.
curl "https://ai-syncra.ru/api/health"
Response 200 OK:
{
"ok": true
}
GET /api/version
Returns the build that is running now. It takes no parameters.
curl "https://ai-syncra.ru/api/version"
Response 200 OK:
{
"sha": "...",
"builtAt": "..."
}
sha is the id of the code version, builtAt is the build time.
Request limits
Syncra counts each limit separately for each address. There is no overall limit for the whole API. Each counting window starts with the first request and lasts the stated time.
| Address | Limit | Counted per |
|---|---|---|
POST /api/webhooks/:token |
60 requests per 60 seconds | Webhook |
POST /api/oauth/register |
20 requests per hour | IP address |
GET /api/oauth/authorize |
60 requests per minute | IP address |
POST /api/oauth/token |
120 requests per minute | IP address |
POST /api/oauth/revoke |
60 requests per minute | IP address |
/api/bot/v1/* |
No limit | |
POST /api/mcp |
No limit of its own |
When a limit is exceeded, the server answers 429 with the body {"error":"Too many requests"}. The response carries no Retry-After or X-RateLimit-* headers. Wait until the window ends and send the request again.
Sizes and lifetimes
| What | Value |
|---|---|
| Message text in the bot API and in an incoming webhook | 1 to 4000 characters |
| Your service’s answer to a slash command | Cut to 4000 characters |
| Attachments in one bot message | Up to 10 |
Messages in one history request, GET /api/bot/v1/messages |
1 to 100, 30 by default |
| Slash command name | 1 to 32 characters: a-z, 0-9, -, _ |
| Slash command description | Up to 200 characters |
| Address of an event subscription or a slash command | Up to 2048 characters |
| Time your service has to answer an event or a command | 5 seconds |
| Attempts to deliver an event | Up to 5 |
| Attempts to send a slash command | 1 |
| Lifetime of an AI app’s access token | 1 hour |
| Lifetime of an AI app’s refresh token | 90 days |
| Lifetime of the link to the page where the person allows access | 15 minutes |
| Lifetime of an OAuth authorization code | 10 minutes |
Syncra shows a bot key in full only once, when it is created. The secrets of event subscriptions and slash commands stay visible in the workspace settings, so you can copy them again later.
Error format
An error body is JSON with an error field. Some errors also carry a code field with a fixed value that your code can check. The error text is English by default. If the request carries an Accept-Language: ru header, the standard error texts come back in Russian, so build your logic on the status and code, not on the text.
| Status | Body | When |
|---|---|---|
| 401 | {"error":"Unauthorized"} |
The bot key is missing or revoked, or the bot is turned off. |
| 422 | {"error":"Validation error","details":{...}} |
The request body failed validation. details.fieldErrors lists the fields and the reasons. |
| 429 | {"error":"Too many requests"} |
A request limit is exceeded. |
| 500 | {"error":"Internal server error","errId":"..."} |
An unexpected server error. |
If you get a 500, send its errId value to the Syncra team in Telegram, https://t.me/morzac, and they can find the error by it. The errors of each address are listed on its own page.
What does not exist
Keys and access
- There are no personal API tokens and no API keys for a user. Only a bot has a key.
- There is no key access to the app’s internal API. The paths under
/apithat the Syncra app itself uses accept a browser session only. They have no version and change together with the app. The only API with a version in its path is/api/bot/v1. - There is no address that creates bots, keys, webhooks, subscriptions or commands with a bot key. That is done in the workspace settings.
- There is no bot directory and no way to install one bot into several workspaces. A bot belongs to one workspace.
Connecting your AI
- There is one access level (OAuth scope),
mcp. There is no read-only access and no access to a single workspace. The app gets everything the person can do, in all of that person’s workspaces. - Of the OAuth flows, only the authorization code with PKCE and the token refresh work. There are no client credentials, implicit or device flows.
- There is no developer console for registering apps. An app registers itself with a
POST /api/oauth/registerrequest. - A token obtained through OAuth opens
/api/mcponly. Other addresses do not accept it. - The server offers tools only. There are no MCP resources or prompts. There is no event stream from the server, no sessions, and no server-initiated notifications.
Bot API
- There is no request limit and there are no limit headers.
- There is no pagination with a total count,
total. - A bot does not create tasks, work with knowledge base pages, add reactions, pin messages, take part in calls, read files, list members or search the workspace. A connected AI app can do most of this on a person’s behalf: what a connected app can do.
Webhooks, events and commands
- An incoming webhook posts text only. There are no attachments, no replies in a thread and no custom author name.
- There are no events for reactions, channel membership, calls, meetings or CRM.
- There is no manual redelivery of an event and no guaranteed order of events.
- There are no interactive messages: buttons, forms or modal windows.
- There are no delayed answers to a slash command and no answers that only the caller sees.
- There is no realtime (WebSocket) API for outside services. A bot learns about events through subscriptions only.
Developer tooling
- There is no published SDK and no npm package.
- There is no OpenAPI or Swagger file.
- No address sends
Retry-AfterorX-RateLimit-*headers.