AI Platform

API

The API lets your own software talk to your workspace: chat with an assistant, start an agent task, or run a workflow, and read the result. It is separate from the website widget and Telegram, and it acts as the workspace rather than as a person.

Create a key

Workspace owners and admins create keys under Settings → API keys. Give the key a name so you can tell it apart, choose its scopes, and optionally set an expiry date.

  • Chat lets the key message assistants.
  • Runs lets the key start agent tasks and workflow runs and read their results.

The full key is shown once, when you create it. Copy it then; if you lose it, create another and revoke the old one. A key can't be edited. To change its scopes, create a new one. A workspace can have up to 20 active keys, and a revoked key stays in the list so you can see when it was last used.

Turn on API access for what you want to expose

A key does not reach anything by itself. Each assistant, agent and workflow has an API access switch, off by default. Turn it on, from the Configure page of an assistant or agent or the page of a workflow, for the ones you want a key to reach. An item with the switch off looks to a key as if it doesn't exist. A resource showing the API badge has the switch on.

Turning the switch off takes effect on the next call. A conversation or run already started carries on.

Call it

Send the key as a bearer token to /api/v1. List what a key can reach, then message an assistant:

curl https://YOUR-API-HOST/api/v1/assistants \
  -H "Authorization: Bearer YOUR_KEY"

curl https://YOUR-API-HOST/api/v1/assistants/ASSISTANT_ID/messages \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

The reply carries a conversationId; send it back with the next message to continue the conversation. Agents and workflows are started with POST /agents/ID/tasks and POST /workflows/ID/runs, and read with GET /runs/ID.

Limits and cost

Each key is limited to 60 requests a minute. Usage counts against your workspace's credits and plan like the same call made in the app, and the number of tasks and runs started through the API in a day is capped.

Where to see it

Conversations started through the API appear on the Conversations page with an API label, and you can filter by it. An assistant called through the API has no signed-in person behind it, so it behaves as it does in a widget: no file tools, and a tool that needs approval can't be approved mid-chat.

Anything a caller sends is treated as untrusted input, like a webhook payload.