Introduction
Base URL: https://<ringmaster-host>/v1 (local: http://localhost:8085/v1)
Short Description: Ringmaster is an engine for intelligent call centres. Services build their calling features on it (they are its client apps): the engine does the telephony, the call logic, the AI and the agents; the service owns its users, its screens and its business rules. A business on such a service (an account) gets phone numbers; each number plays a call flow (a script of blocks: greet, menu, collect a number, voicemail, AI agent, connect to a person…). Ringmaster also calls people (reminders, campaigns, callbacks, OTP codes), rings the business's agents in their browser, records and transcribes calls, and tells the client app what happened through signed webhooks. This book is for developers of a client app: every endpoint, every event the engine sends, every value.
Hints:
- Every
/v1request carries the client app's API key:Authorization: Bearer <key>. Keep it on your server; never ship it to a browser or phone. - Ringmaster knows nothing about the client app's users, contacts, money or messages. It stores what it needs to ring and play: account settings, numbers, call flows, agents (a ref and a name), calls and their reports.
- Phone numbers are always E.164 (
+255745051250). Times in responses are UTC ISO 8601 (2026-11-13T14:41:00Z); times inside an account (opening hours, quiet hours, "call me at 9") are in the account's time zone (defaultAfrica/Dar_es_Salaam). - Refusals you should handle in code come with a stable
code(SCRIPT_IN_USE,VERSION_NOT_RUNNABLE…); switch on the code, show the message. Full list in Part 4. - How a call flow is written (all blocks, their settings and exits) is in
SCRIPTS.mdPart 5.;Thishowbooktocoversbuild the editor, calls, reports and live screens on top of the APIaroundisit.in Part 6. - A working sample client to try everything by hand: the demo console (
console/,python3 console/serve.py); its "API calls" bar shows the exact request for each click.
Contents
| Page | What's in it |
|---|---|
| Part 1 — How Ringmaster works | Read first: the objects, a call step by step, call-outs, flows and versions, agents, webhooks, app actions, recordings, costs, formats |
| Part 2A — Setup: basics, accounts, numbers | ping, script schema and check · accounts · numbers |
| Part 2B — Call flows, media, knowledge | scripts and versions · audio files · knowledge base for the AI |
| Part 2C — Calls, call-outs, OTP, reports | call history, timeline, recording, transcript · quick calls and call-outs · OTP · stats and exports |
| Part 2D — Agents and live calls | departments, agents, the browser desk · accept, hold, transfer, hang up |
| Part 2E — App actions and opt-outs | registering the client app's actions and answering them · the do-not-call list |
| Part 3 — What the engine sends you | webhooks: envelope, signature, retries, every event · agent desk signals |
| Part 4 — Reference | every status and value · every error code · limits and defaults · glossary |
| Part 5 — Call flow reference | the flow document · messages · variables · all 18 blocks with every setting and exit · Waiting Room · AI Agent · check codes and fixes |
| Part 6 — Building the screens | flow editor · calls page and call log · reports · agent desk and queue · which webhook updates what · the don't list |
| Appendix — Not for client apps | engine-internal routes · what the Ringmaster owner sets up with ringmaster-admin |
Standard Response Format
Every response uses the Globe envelope.
Success
{
"success": true,
"httpStatus": "OK",
"message": "Script",
"action": null,
"action_time": "2026-11-13T17:44:40.645991261",
"data": { }
}
Error
{
"success": false,
"httpStatus": "CONFLICT",
"message": "The script is still in use: move these to another script first",
"code": "SCRIPT_IN_USE",
"action_time": "2026-11-13T18:09:38.582694597",
"data": { "numbers": ["+255677000003"] }
}
| Field | Type | Description |
|---|---|---|
success |
boolean | true for success, false for errors |
httpStatus |
string | HTTP status, e.g. "200 OK", "409 CONFLICT" |
message |
string | Human-readable result; safe to show |
code |
string | Errors only: stable machine code to switch on (NOT_FOUND, VALIDATION_FAILED, SCRIPT_IN_USE…) |
action_time |
string | Server time of the response (local, no zone) |
data |
any | The payload; on errors, details (field messages, what is in the way) or null |
| HTTP | code |
When |
|---|---|---|
| 400 | BAD_REQUEST |
Body is not valid JSON, a query parameter is missing or not the right type, a value is not allowed |
| 401 | UNAUTHORIZED |
Missing or wrong API key |
| 403 | CLIENT_SUSPENDED, FEATURE_OFF, CAN_CALL_REFUSED |
The app is suspended, the feature is not enabled for it, or its can-call check said no |
| 404 | NOT_FOUND |
No such object, or it belongs to another client app |
| 409 | a specific code | A rule says no (in use, wrong state, already answered); data says what is in the way |
| 422 | VALIDATION_FAILED |
Field errors in data ({"field": "message"}), or a script's error list |
| 429 | RATE_LIMITED |
More requests per second than the app's limit |
| 500 | INTERNAL_ERROR |
A bug on our side; the message is generic |
HTTP Method Badge Standards
- GET - GET - read only
- POST - POST - create / act
- PUT - PUT - create or replace
- PATCH - PATCH - change some fields
- DELETE - DELETE - remove
Every endpoint at a glance
| Group | Method | Path | Page |
|---|---|---|---|
| Basics | GET | /v1/ping |
2A |
| GET | /v1/scripts/schema |
2A | |
| POST | /v1/scripts/validate |
2A | |
| Accounts | POST · GET | /v1/accounts |
2A |
| GET · PATCH | /v1/accounts/{accountId} |
2A | |
| Numbers | GET · POST | /v1/numbers |
2A |
| DELETE | /v1/numbers/{numberId} |
2A | |
| POST | /v1/numbers/{numberId}/assign · /release · /transfer |
2A | |
| PUT | /v1/numbers/{numberId}/script · /ring-mode |
2A | |
| Scripts | GET | /v1/accounts/{accountId}/scripts |
2B |
| PUT · GET · DELETE | /v1/accounts/{accountId}/scripts/{ref} |
2B | |
| POST | /v1/accounts/{accountId}/scripts/{ref}/versions |
2B | |
| GET | /v1/accounts/{accountId}/scripts/{ref}/versions/{version} |
2B | |
| POST | …/versions/{version}/runnable · …/versions/{version}/revoke |
2B | |
| GET | …/versions/{version}/stats |
2B | |
| Media | POST · GET | /v1/accounts/{accountId}/media |
2B |
| GET · DELETE | /v1/media/{mediaId} |
2B | |
| Knowledge | POST · GET | /v1/accounts/{accountId}/kb-docs |
2B |
| DELETE | /v1/accounts/{accountId}/kb-docs/{documentId} |
2B | |
| Calls | GET | /v1/calls · /v1/calls/{callId} · /timeline · /recording · /transcript |
2C |
| GET | /v1/calls/export.csv |
2C | |
| POST | /v1/calls (quick call) · /v1/calls/agent |
2C | |
| Call-outs | POST · GET | /v1/callouts |
2C |
| GET | /v1/callouts/{id} · /recipients · /stats · /export.csv |
2C | |
| POST | /v1/callouts/{id}/recipients · /v1/callouts/{id}/{action} |
2C | |
| OTP | POST | /v1/otp |
2C |
| Stats | GET | /v1/accounts/{accountId}/stats |
2C |
| Agents | GET | /v1/accounts/{accountId}/agents · /agents/stats |
2D |
| PUT · DELETE | /v1/accounts/{accountId}/agents/{ref} |
2D | |
| PUT · POST · POST | …/agents/{ref}/status · /ready · /lobby-token |
2D | |
| Departments | POST · GET | /v1/accounts/{accountId}/departments |
2D |
| PUT · DELETE | …/departments/{departmentId} |
2D | |
| PUT · GET | …/departments/{departmentId}/members · /queue |
2D | |
| Live calls | POST | /v1/calls/{callId}/accept · /decline · /hold · /unhold · /transfer · /hangup |
2D |
| App actions | PUT · GET | /v1/actions |
2E |
| POST | /v1/calls/{callId}/action-result |
2E | |
| Opt-outs | POST · GET | /v1/accounts/{accountId}/opt-outs |
2E |
| DELETE | /v1/accounts/{accountId}/opt-outs/{e164} |
2E |