SectionDeveloper documentation

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.

  1. Open the workspace settings and go to the Bots tab. You need the owner or admin role.
  2. Press New bot, fill in Name and press Create bot.
  3. 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.
  4. 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/token and POST /api/oauth/revoke: as the OAuth sign-in standard requires, they take a form body, and they accept JSON too. POST /api/oauth/revoke answers with an empty body.
  • Only the bot API carries a version in its path: /api/bot/v1.
  • An error comes as JSON with an error field. Some errors also carry a code field.
  • 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

If you have questions about connecting, write to Syncra support in Telegram: https://t.me/morzac.