API quickstart
From a new key to a Bot's reply, with commands you can paste into a terminal. You need curl and a group conversation in your workspace with at least one Bot in it.
1. Create a keyCopy link to this section
In the workspace open Settings › API keys, name the key and give it these three scopes: read:profile, read:channels and write:messages. Copy the key when it is shown; it is shown once.
Put it in your shell without writing it into a command or a file: the first line below waits for you to paste the key and does not echo it. Then set the address of your deployment.
read -rs api_key && export api_key
export workspace="https://<your-deployment>"2. Check who the key isCopy link to this section
curl -sS -H "Authorization: Bearer $api_key" \
"$workspace/api/me"The answer is the person the key belongs to, with their role. A 401 means the key is missing, mistyped, revoked or expired.
3. Pick a group conversationCopy link to this section
Open the group conversation in the workspace: its id is the last part of the address, after /group/. Your conversations are also listed by the call below. Keep the id in a variable.
curl -sS -H "Authorization: Bearer $api_key" \
"$workspace/api/channels?limit=20"
export channel_id="<the conversation id>"4. Send a messageCopy link to this section
curl -sS -X POST \
-H "Authorization: Bearer $api_key" \
-H "content-type: application/json" \
-d '{"id":"quickstart-1","text":"Hello. What can you help me with?"}' \
"$workspace/api/groups/$channel_id"The server answers 202: the message is in, and the Bots in the conversation answer as they would in the app. id is yours to choose, and sending the same id twice is one message, so a retry is safe. Add "agentId" to address one Bot.
5. Read the replyCopy link to this section
curl -sS -H "Authorization: Bearer $api_key" \
"$workspace/api/groups/$channel_id"The answer holds the conversation's messages. A Bot's reply is a message with its agentId set. Its status is queued or running while it is being written, waiting, with a reason, when it needs an answer from someone, then completed or failed. Run the call again until it is done.
Plugin manifestsCopy link to this section
A plugin ships one JSON manifest. Version 1 names the plugin (id, name, version, publisher), its MCP address (server.url), the tools Bots are offered, a settings form, its permissions (hosts, access and the data it reads), lifecycle hooks and what it requires. Administrators install it under Admin › Plugins › Plugin manifests after reading what it asks for.
{
"manifestVersion": 1,
"id": "ticket-desk",
"name": "Ticket desk",
"version": "1.2.0",
"publisher": "Example Ltd",
"server": { "url": "https://mcp.tickets.example/mcp" },
"tools": [{ "name": "search_tickets" }],
"settings": [{ "key": "apiKey", "label": "API key", "type": "secret", "header": "X-Desk-Key", "required": true }],
"permissions": { "hosts": ["mcp.tickets.example"], "access": "read", "data": ["Ticket titles and status"] },
"hooks": { "url": "https://mcp.tickets.example/events", "events": ["approval.decided"] },
"requires": { "apiVersion": "2026-10-15", "plugins": [] }
}Every address must use https and sit on a listed host. A tool the manifest does not declare is not offered to Bots, and "access": "read" keeps the connection read-only. Each setting reaches the plugin as the request header it names; secret settings are kept in the vault and never shown again. Hooks receive approval.requested, approval.decided or run.finished as signed webhooks, with the signing secret shown once at install.
requires.apiVersion and requires.plugins (versions such as 1.2.0, >=1.2.0 or ^1.2.0) are checked before install, and a plugin another one requires stays until that one is uninstalled. Every installed version is kept, with the API versions it works with, for a rollback.
Sign a manifest so it installs as verified: synthia plugin keygen makes an Ed25519 key pair and synthia plugin sign manifest.json --key publisher-key.pem adds the signature. It covers the manifest without signature, written as JSON with every object's keys sorted and no whitespace. Administrators trust the public key under the publisher's name; a manifest nobody trusted signed needs their explicit confirmation.
Last updated