Developer documentation
The ways a program can work with Syncra, from your own AI to bots and webhooks, and how to send a first request with one command.
Syncra is a work app where a team has chat, tasks, a knowledge base and calls in one place. These docs are for a developer who wants a program to read and write in a workspace: post alerts to a channel, create tasks, answer commands, or give an AI app access to the chats. Any member can connect their own AI app in the Preferences window, in the Connected apps section. Bots, keys and webhooks are for a workspace owner or admin, who creates them on the Bots tab of the workspace settings.
Ways to connect
| Way | What happens | What proves the request | Use it when |
|---|---|---|---|
| Your AI | The app works as the person who connected it | The person signs in through a browser and presses Allow. There is no key to create | Claude, ChatGPT, Cursor or your own agent should work with chats, tasks and the knowledge base |
| A bot and its API | Your program works as a bot. A bot is a separate member of the workspace | The key skb_... in the Authorization header |
The program posts and reads messages and changes tasks |
| Incoming webhook | A bot posts your text in one chosen channel | The secret whk_... inside the address |
You need to send text to a channel with one request |
| Event subscriptions | Syncra sends a request to your address when something happens | A signature made with the secret whsec_... |
The program has to learn about new messages, tasks and pages |
| Slash commands | A person types a command in a channel, Syncra sends a request to your address | A signature made with the secret whsec_... |
A command such as /deploy should run your code |
Your AI connects over MCP. MCP (Model Context Protocol) is an open standard that AI apps use to call actions in outside services. Syncra has one address for it, https://ai-syncra.ru/api/mcp. The page Tools for your AI lists what a connected app can do.
First request
The quickest way to see a result is an incoming webhook. You get a secret address, send text to it, and a bot posts that text in a channel.
- Open the workspace settings and go to the Bots tab. You need the owner or admin role.
- Press New bot, fill in Name and press Create bot.
- On the bot’s page find the Incoming webhooks section. Pick a channel in the Channel field and press Create webhook. The bot joins that channel on its own.
- Copy the webhook address and put it into the request below.
POST /api/webhooks/:token
Posts a message as the bot in the channel the webhook is bound to.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
token |
path | string | yes | The webhook secret, starts with whk_. No Authorization header is needed |
text |
body | string | yes | The message text, 1 to 4000 characters |
curl -X POST "https://ai-syncra.ru/api/webhooks/whk_..." \
-H "Content-Type: application/json" \
-d '{"text":"Build 142 passed"}'
Response 200:
{
"ok": true,
"messageId": "..."
}
The message appears for everyone in the channel right away, without reloading the page.
| Status | Response body | What happened |
|---|---|---|
400 |
{"error":"Invalid JSON"} |
The request body is not valid JSON |
404 |
{"error":"Not found"} |
There is no such webhook, or the webhook or its bot is switched off |
422 |
{"error":"Validation error","details":{...}} |
text is missing, empty or longer than 4000 characters |
429 |
{"error":"Too many requests"} |
More than 60 requests in 60 seconds for one webhook |
The webhook address is a secret: anyone who knows it can write to the channel. Keep it out of public code. Details and limits are on the page Incoming webhooks.
Keys and secrets
Each way to connect has its own key or secret. The first letters of the string tell you which one it is.
| Starts with | What it is | Where you get it | Where it goes |
|---|---|---|---|
skb_ |
A bot key | The bot’s page, section API tokens, button Create token. The full key is shown once | The header Authorization: Bearer skb_... on requests to /api/bot/v1 |
whk_ |
The secret of an incoming webhook | The bot’s page, section Incoming webhooks | Inside the request address |
whsec_ |
A signing secret | Each event subscription and each slash command has its own | You never send it. You use it to check the signature of requests Syncra sends you |
syncat_ |
The access key of an AI app | The app gets it automatically after the person presses Allow | The header Authorization: Bearer syncat_... on requests to /api/mcp |
Common rules
- The address for every request is
https://ai-syncra.ru. - Request and response bodies are JSON. The exceptions are
POST /api/oauth/tokenandPOST /api/oauth/revoke: as the OAuth sign-in standard requires, they take a form body, and they accept JSON too.POST /api/oauth/revokeanswers with an empty body. - Only the bot API carries a version in its path:
/api/bot/v1. - An error comes as JSON with an
errorfield. Some errors also carry acodefield. - A bot works in one workspace: the one it was created in.
What does not exist
- There are no personal API tokens. An outside program acts as a person through an MCP connection, after the person has pressed Allow.
- There is no published SDK and no npm package. The examples in these docs use cURL.
- There is no separate live event stream for outside programs. A bot learns about events through subscriptions.
The full list is on the page What exists and what does not.
Where to go next
- Connect your AI: the server address, sign-in, steps for Claude, ChatGPT and Cursor.
- Tools for your AI: what a connected app can do in Syncra.
- Bots: what a bot is, how to create one and get its key.
- Bot API: base address, authorization, errors, first call.
- Messages and tasks in the bot API.
- Incoming webhooks, event subscriptions, slash commands.
If you have questions about connecting, write to Syncra support in Telegram: https://t.me/morzac.