Introduction Author : Josh S. Sakweli, Backend Lead Team Last Updated : 2026-11-13 Version : v1.0 Base URL : https:///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 /v1 request carries the client app's API key: Authorization: Bearer . 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 (default Africa/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 Part 5 ; how to build the editor, calls, reports, live screens and the screens around Agent Phone on top of the API is 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 2F — Agent Phone connecting an agent's desktop app (pairing codes, devices, remove) · the app's own /v1/agent API 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 · screens for Agent Phone (connect, devices, shared computers, shifts, settings, notices) 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 GET /v1/accounts/{accountId}/agents/{ref}/desk · /desk/search 2D Agent calls POST /v1/calls/{callId}/join · /call-back 2D Devices POST · GET · DELETE /v1/accounts/{accountId}/agents/{ref}/devices[/pairings · /{deviceId}] 2F Agent Phone POST · GET · DELETE /v1/agent/pair · /token · /me · /search · /lobby-token · /calls… · /device 2F 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