Esta página se publica en inglés y en ucraniano; abajo está la versión en inglés.
API overview: the runtime and the management API
For developers, in code: the two APIs — the runtime the widget speaks to, and the management API the panel speaks to — what each is for, how each is authenticated, and every limit in one table.
Two APIs
| The runtime | The management API | |
|---|---|---|
| base | the data-agent-base of your snippet |
your panel’s host, /api/ |
| speaks to | the widget (and a custom front end) | the panel (and your scripts) |
| auth | the site’s widget key — public by design, restricted to the origins listed on it | a management key — secret, shown once, owner-scoped |
| what it does | the conversation (WS /ws, POST /message), the widget’s configuration, speech and recognition, two beacons |
everything the panel does: sites, sources, agents, widgets, tools, events, keys, conversations, analytics, billing |
| reference | the pages of this section | generated from /api/schema/ — Swagger at /api/docs/, ReDoc at /api/redoc/ |
You need the runtime API only to build a front end of your own; the widget already speaks it. You need the management API to automate the panel — create sources from your CMS, read conversations into your warehouse, rotate a key.
Effectively public
Because the widget key is public, every runtime endpoint it authenticates is reachable by anyone
on an allowed origin — and by a non-browser client that forges the Origin header. The runtime is
built for that: nothing it serves is more than a visitor could see, every write is rate-limited
and bounded (a follow may only increment an existing offer; a handoff only files a lead), and the
beacons answer 204 to every failure so they reveal nothing. A conversation id is a bearer
capability — whoever holds it can resume the chat — so it is never put in a URL that can be
shared.
So the limits that matter are counted where a script cannot change them: per visitor (one address on one site), so one client cannot take the whole allowance, and per owner, so an account with no plan can only try the assistant. Switching a widget off in the panel stops the chat itself, not only the button: a turn that names a switched-off widget, or any turn on a site whose widgets are all off, is refused with 403. Revoking the widget key stops everything at once.
The management key is the real secret. Keep it on a server.
Every limit, in one table
| Limit | Value | Applies to |
|---|---|---|
| chat, per account per minute | 30 · 60 · 180 · 360 · 900 (before a plan · Starter · Growth · Pro · Business) | /message, /ws messages |
| chat, per visitor | 20 / min, 300 / day (a visitor is one address on one site) | /message, /ws messages |
| before a plan | 50 credits a day, 300 a month; 20,000 speech characters and 100 recognition streams a day | every request of the owner’s key |
| credits per month | 3,000 · 7,000 · 18,000 · 52,000 by plan, plus top-ups | every answered turn |
| speech | 120 / min; 1,200 characters per request; 60 / min and 30,000 characters a day per visitor; per account, 20,000 a day plus 2,500 for each answered turn | POST /tts |
| recognition | 60 streams / min; 120 s per stream; 20 / min and 300 / day per visitor; per account, 200 a day plus 6 for each answered turn | WS /ws/stt |
| handoff | 30 / min | POST /handoff, /handoff/opened |
| followed beacon | 120 / min | POST /followed |
| voice timing | 120 / min | the voice_timing frame |
| tool test | 30 / min per owner | the panel’s Test |
| custom tool | 3 calls per turn; 10 s cap; 256 KB; 600 s cache cap; 8 concurrent | every tool call |
| tools and events bound | 12 tools and 12 events per turn among those bound on the screen, by name; the rest dropped with only a server log | every turn |
| page actions | 40 round trips per turn; 40 steps per call; 5 s per bridge round trip; 1.5 s prefetch | page-actionable turns |
| conversation handoff token | 90 s, single use | GET /conversation |
| widget config cache | 1 h | GET /widget/config |
| onboarding analysis | 20 / min per owner | POST /api/onboarding/analyze/ |
Every burst limit is a fixed window per minute, for the account and, where the table says so,
for each visitor. Over it: HTTP 429, or an error frame with code: "rate_limited" on the
socket, and no credit is spent. At the monthly cap the turn is answered with a limit message, the
widget goes inactive from the next load, and the owner is emailed; before a plan the allowance
runs out the same way, without the email.
Versions and stability
There is one version of each API. The frame protocol is additive — a new server frame is advisory to an older widget — and a key leaving a response is announced on the changelog. The widget bundle is served from a CDN and updated in place; a page never pins a bundle version.