On this page
Build and test recipes
Use these short sequences to save a test version, simulate a caller, release reviewed behavior or roll back a change. Each step links to its request and response fields. For a complete phone workflow, start with the equipment-service guide.
Prerequisites
Connect your coding agent or the API with a sandbox member or admin key. Check the selected environment with environments.list. Use IDs returned by requests, and retain an idempotency key for each mutation. Simulations require open run admission; check runs.capacity and contact Cumulus if the environment has not been configured.
Create and publish without going live
- agents.create: create from a template. The response supplies the agent ID and draft identity/revision.
- drafts.edit: send typed edits with that draft ID and
expected_revision. Carry the returned revision forward. - drafts.validate: fix errors and validate again. Keep the next version returned by validation.
- publications.publish: pass the draft ID, current revision, validated version and
live: false. Use the actual version returned, including on an idempotent replay. - agents.get: verify the live head did not change.
Result: a test publication exists. New API-started runs that omit a version still use the previous head; incoming numbers retain their assigned publication. A new agent may have no live head yet.
Always send
live: falsewhen publishing a test version. Leaving it out can change the live head. Editing a draft does not change an existing publication.
Import and simulate a phone agent
- agents.import_inspect: inspect the Retell export and resolve model-binding and secret diagnostics. See Import from Retell.
- agents.import: import the resolved configuration. This creates a draft.
- Validate and publish the test version using the workflow above.
- test_suites.create: define simulated callers and assertions appropriate to the agent. Read the schema for the suite kind and case fields.
- test_runs.estimate: inspect the estimate before starting work.
- test_runs.create: run the suite against the selected agent version.
- Poll test_runs.get until it completes or is cancelled, then inspect test_runs.results and failing test_runs.trial transcripts.
Result: the assertions produce a verdict for the selected version without dialing a phone. A trunk and number are not required for text simulations.
Release the tested behavior
A test publication requires test: true when run. To release the behavior for regular calls or tasks:
- Read the current draft and confirm it contains the changes you tested.
- Validate it and keep the next version returned by validation.
- Publish with that draft ID, revision and version, and
live: true. - Read the publication and verify its version and digest. New requests that omit
versionselect this head. - For incoming calls, reassign the number and check its returned publication version.
Promotion changes which existing publication is the head. It does not remove a test publication's test-only restriction. Use it to select an earlier live version during rollback; review a conflict instead of guessing a newer head.
Start and follow a cloud run
Read runs.create, choose a published version, supply the required input and start a cloud run. Follow runs.events or poll runs.get. Once ended, read runs.result, the transcript and usage.
Use the complete curl, TypeScript and Python examples to carry the run ID from creation into subsequent requests.
Result: the run reaches a terminal state under a fixed publication version. Read the result’s state before using its output. If run creation returns outcome_unknown, retry the same creation request with its original idempotency key.
Roll back the live head
List publications, inspect the intended earlier version and read the current head. Promote the earlier version with the current expected_head_version, then verify the new head with agents.get.
Result: subsequent API-started runs that omit a version use the earlier publication. For incoming calls, reassign the number after rollback and verify its publication pin. Rollback does not rewrite completed or in-flight runs.
Diagnose a refused call
Read the error’s code and details.reason. Check the selected environment, run capacity, trunk, caller-ID number and required dynamic variables. Troubleshooting lists the recovery for each refusal. Fix the cause before retrying.
Phone tests dial real numbers:
runs.createwith channelphoneplaces a call even whentest: true. Use simulations for testing without a call.