API Reference

The studio runs entirely on this public REST surface — there is no private backend channel, so everything the studio does, an integration can do. Authentication is a JWT Authorization: Bearer header from POST /api/v1/auth/login; every request is scoped to the token's tenant by row-level security beneath the application, so an integration cannot reach another tenant's data even by accident.

This page maps the surface by area. The api is served on port 29092 by default.

Conventions

• Base path /api/v1; JSON in and out.
• Authorization is the three-role model — STUDIO_ADMIN, STUDIO_PROJECT, STUDIO_MONITORING, any combination per user (see Roles). /api/v1/admin/** and the telephony trunk/test-call endpoints require STUDIO_ADMIN.
• Errors carry a message and, where useful, a machine-readable code (e.g. PASSWORD_CHANGE_REQUIRED, ACCOUNT_DISABLED on 403).
• 409 Conflict on scenario writes means the edit lock — read GET …/lock to see who holds it.
• Validation problems answer 400/422 with findings (nodeId, path, message) the studio pins to nodes; integrations get the same list.

Scenarios

Method & path	What it does
GET /scenarios · POST /scenarios	list and create
GET /scenarios/{id}	the scenario with its latest definition
POST /scenarios/validate	validate a definition document (the body is the document)
GET/POST /scenarios/{id}/versions	version history · save a new immutable version
GET /scenarios/{id}/versions/{n}	one version's definition
POST /scenarios/{id}/publish	put the latest version live
POST/GET/DELETE /scenarios/{id}/lock	take (?force=true for admins) · read · release the edit lock
POST /scenarios/{id}/migrate-v2	translate v1 → v2 as a new version
POST /scenarios/{id}/duplicate	copy, optionally across callbots
GET /scenarios/{id}/analysis/…	node-flow, node-graph, node-trace, node-messages, nlu-evaluation

Projects, callbots, campaigns

Area	Surface
Projects	GET/POST /projects, membership, per-project libraries
Callbots	GET /projects/{id}/callbots, GET /callbots/{id}/scenario-schedules, …/active-scenario
Campaigns	CRUD, contact upload, start/pause, per-contact state, campaign groups

Calls, monitoring, admin

Area	Surface
Calls	list with filters, call detail, transcript, recording, tags
Monitoring	today counters + WebSocket live call events
Admin	tenants, users, managers, roles, audit, login history, AI settings, usage
Telephony	GET/PUT /api/v1/admin/telephony-trunks — the Studio-managed trunk document (gateways, ACL, prefix routes; passwords write-only); GET /internal/v1/telephony-trunks — the voice gateway's decrypted read
Auth	login, password change, session introspection

Webhooks out

The api delivers outbound webhooks (call finished, campaign finished) through an outbox with idempotency keys (ADR-0016): at-least-once delivery, retries with backoff, and a deliveries page in the studio showing every attempt.