API reference

List agents with their head publication, open draft and last run; search, filter and order server-side

Get one agent

Create an agent from a template (201; an idempotent replay returns 200)

Delete (archive) an agent: it leaves the catalog and takes no new drafts, publications or runs; history is kept

Clone an agent's head, chosen version or never-published draft into a new agent's first draft (201; replay 200)

Import a Retell agent export as a draft, never live: a new agent gets it as its first draft; an existing agent's draft is replaced and its head is unchanged. Replacing a draft with unpublished changes needs replace_draft {draft_id, expected_revision} naming it (409 reason draft_has_changes otherwise). Publish the draft with publications.publish (201; re-importing the same export onto its unedited draft returns 200)

Compile a Retell export and say what agents.import would do (new agent, new or replaced draft, unpublished changes it would discard) without importing it

Read the open draft

Open a draft from the head or a chosen version

Apply domain edits to the draft (revision compare-and-set)

Discard the draft (revision compare-and-set)

Rebase the draft onto the live version after a head change (keeps its definition; 409 head_moved when live moved again)

Compile the draft and return diagnostics and the would-be digest

Publish the draft as the next immutable version; moves head unless live is false (201; replay 200)

List publications of an agent

Get one publication with its compiled plan

Move head to an existing version (manual promote or rollback), rebasing the named open draft in the same transaction

List the action descriptors available to publications

Admit a cloud or phone run of a publication (201; an idempotent replay returns 200)

List runs

Read admission capacity per channel: configured limit and runs holding it

Get one run

Update a live phone run's dynamic variables or metadata; returns a durable receipt (202 while pending, 200 once settled)

Read a live update's receipt

Cancel an active run (accepted: a live call settles cancelled when its media session ends)

Send a user message to a cloud chat run

Read the run's semantic events (JSON page or text/event-stream)

Read the run's governed effects and receipts

Read the run transcript

Read what a cloud task run produced: its output object, validated against the publication's output schema

Get a short-lived recording URL

Read post-run analysis

Read metered usage and cost of one run

Start a browser voice test of one agent version: admits a web run and returns a short-lived LiveKit room token (the same Idempotency-Key rejoins the live run with a fresh token)

Summarize metered usage by agent, run or day: the billable runs, or (purpose=test) the test runs, metered and not billed

Read the tenant budget: period, cap and metered spend (configured: false until metered pricing is installed)

Set the tenant budget cap (compare-and-set on the active policy; refused until metered pricing is installed)

Read the customer rates of the tenant's active pricing (configured: false until metered pricing is installed)

List the speech models and platform TTS voices an agent can use

Read the tenant's own daily outbound call limit and the outbound calls placed in the last 24 hours

Set or clear the tenant's daily outbound call limit (null: no limit)

List BYOC SIP trunks

Connect a BYOC SIP trunk

Update a BYOC SIP trunk

Disconnect a BYOC SIP trunk

List BYOC phone numbers

Import a phone number from a connected trunk

Assign agents or rename a phone number

Release a phone number

List secret metadata (never values)

Create a secret or add a new version

Delete a secret and all its versions

List the model-provider keys runs dial with (metadata only, never the key)

Set or rotate the tenant's own key for a model provider; the provider checks it before it is stored

Remove the tenant's key for a model provider; new runs use the platform key

List knowledge documents

Upload a knowledge document

Get one knowledge document

Delete a document and return storage/provider deletion receipts

Read knowledge configuration and the ready generation

Choose the embedding model for knowledge

Build a new knowledge generation

Score a run against a rubric

List evaluations

Compare a candidate publication against a baseline on existing runs

Get one comparison with its per-case verdicts

List comparisons

List test suites (optionally one agent's) with their last run

Get a test suite (its current revision, or ?revision) with its last run and flaky cases

Create a test suite on an agent (201; an idempotent replay returns 200)

Edit a test suite (rename, upsert, remove or reorder cases) as a compare-and-set on its revision

Archive a test suite; its runs and results are kept

Check a suite's node, action and variable references against a published version or the open draft

Estimate a test run's trials, cost and duration before starting it

Run test suites against one publication version (201; an idempotent replay returns 200)

List test runs, newest first

Get a test run: state, verdict, progress, summary and cost

List a test run's case results with each trial's assertion verdicts

Get one trial: its assertion trace and, while retained, the transcript it was judged on

Read a test run's journal events (JSON page or text/event-stream)

Cancel a test run: no new trials start and running trials are cancelled; settled results stay

List API keys (never secrets)

Create an API key with an explicit role

Revoke an API key; queued effects of its runs are denied

Replace an API key's secret

List members and pending invitations

Invite a member

Revoke a pending invitation

Send a pending invitation again with a new link and expiry

Remove a member

Change a member's role

Read the organization's display name and retention settings

Rename the organization and/or change retention (retention is a version compare-and-set)

List alert rules with their latest delivery

Create an alert rule on a metered usage or run metric

Change an alert rule (revision compare-and-set)

Delete an alert rule (revision compare-and-set)

Acknowledge an uncertain alert delivery so the rule can fire again

Read which alert destinations are configured (metadata only, never the secret)

Set or clear the Slack webhook or PagerDuty routing key (revision compare-and-set)

List the tenant's model catalog, optionally for one task

List this organization's production and sandbox environments

Create this organization's sandbox environment on first use (same members)

List the tenant audit log