Source: https://docs.cumuluslabs.io/api-reference
Content version: e10c0bf5

# API reference

- [agents.list](https://docs.cumuluslabs.io/reference/agents.list): List agents with their head publication, open draft and last run; search, filter and order server-side
- [agents.get](https://docs.cumuluslabs.io/reference/agents.get): Get one agent
- [agents.create](https://docs.cumuluslabs.io/reference/agents.create): Create an agent from a template (201; an idempotent replay returns 200)
- [agents.delete](https://docs.cumuluslabs.io/reference/agents.delete): Delete (archive) an agent: it leaves the catalog and takes no new drafts, publications or runs; history is kept
- [agents.clone](https://docs.cumuluslabs.io/reference/agents.clone): Clone an agent's head, chosen version or never-published draft into a new agent's first draft (201; replay 200)
- [agents.import](https://docs.cumuluslabs.io/reference/agents.import): 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)
- [agents.import_inspect](https://docs.cumuluslabs.io/reference/agents.import_inspect): 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
- [drafts.get](https://docs.cumuluslabs.io/reference/drafts.get): Read the open draft
- [drafts.open](https://docs.cumuluslabs.io/reference/drafts.open): Open a draft from the head or a chosen version
- [drafts.edit](https://docs.cumuluslabs.io/reference/drafts.edit): Apply domain edits to the draft (revision compare-and-set)
- [drafts.discard](https://docs.cumuluslabs.io/reference/drafts.discard): Discard the draft (revision compare-and-set)
- [drafts.rebase](https://docs.cumuluslabs.io/reference/drafts.rebase): Rebase the draft onto the live version after a head change (keeps its definition; 409 head_moved when live moved again)
- [drafts.validate](https://docs.cumuluslabs.io/reference/drafts.validate): Compile the draft and return diagnostics and the would-be digest
- [publications.publish](https://docs.cumuluslabs.io/reference/publications.publish): Publish the draft as the next immutable version; moves head unless live is false (201; replay 200)
- [publications.list](https://docs.cumuluslabs.io/reference/publications.list): List publications of an agent
- [publications.get](https://docs.cumuluslabs.io/reference/publications.get): Get one publication with its compiled plan
- [publications.promote](https://docs.cumuluslabs.io/reference/publications.promote): Move head to an existing version (manual promote or rollback), rebasing the named open draft in the same transaction
- [actions.list](https://docs.cumuluslabs.io/reference/actions.list): List the action descriptors available to publications
- [runs.create](https://docs.cumuluslabs.io/reference/runs.create): Admit a cloud or phone run of a publication (201; an idempotent replay returns 200)
- [runs.list](https://docs.cumuluslabs.io/reference/runs.list): List runs
- [runs.capacity](https://docs.cumuluslabs.io/reference/runs.capacity): Read admission capacity per channel: configured limit and runs holding it
- [runs.get](https://docs.cumuluslabs.io/reference/runs.get): Get one run
- [runs.update](https://docs.cumuluslabs.io/reference/runs.update): Update a live phone run's dynamic variables or metadata; returns a durable receipt (202 while pending, 200 once settled)
- [runs.update_get](https://docs.cumuluslabs.io/reference/runs.update_get): Read a live update's receipt
- [runs.cancel](https://docs.cumuluslabs.io/reference/runs.cancel): Cancel an active run (accepted: a live call settles cancelled when its media session ends)
- [runs.send_message](https://docs.cumuluslabs.io/reference/runs.send_message): Send a user message to a cloud chat run
- [runs.events](https://docs.cumuluslabs.io/reference/runs.events): Read the run's semantic events (JSON page or text/event-stream)
- [runs.effects](https://docs.cumuluslabs.io/reference/runs.effects): Read the run's governed effects and receipts
- [runs.transcript](https://docs.cumuluslabs.io/reference/runs.transcript): Read the run transcript
- [runs.result](https://docs.cumuluslabs.io/reference/runs.result): Read what a cloud task run produced: its output object, validated against the publication's output schema
- [runs.recording](https://docs.cumuluslabs.io/reference/runs.recording): Get a short-lived recording URL
- [runs.analysis](https://docs.cumuluslabs.io/reference/runs.analysis): Read post-run analysis
- [runs.usage](https://docs.cumuluslabs.io/reference/runs.usage): Read metered usage and cost of one run
- [test_sessions.create](https://docs.cumuluslabs.io/reference/test_sessions.create): 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)
- [usage.summary](https://docs.cumuluslabs.io/reference/usage.summary): Summarize metered usage by agent, run or day: the billable runs, or (purpose=test) the test runs, metered and not billed
- [budgets.get](https://docs.cumuluslabs.io/reference/budgets.get): Read the tenant budget: period, cap and metered spend (configured: false until metered pricing is installed)
- [budgets.update](https://docs.cumuluslabs.io/reference/budgets.update): Set the tenant budget cap (compare-and-set on the active policy; refused until metered pricing is installed)
- [usage.rate_card](https://docs.cumuluslabs.io/reference/usage.rate_card): Read the customer rates of the tenant's active pricing (configured: false until metered pricing is installed)
- [voices.list](https://docs.cumuluslabs.io/reference/voices.list): List the speech models and platform TTS voices an agent can use
- [call_limits.get](https://docs.cumuluslabs.io/reference/call_limits.get): Read the tenant's own daily outbound call limit and the outbound calls placed in the last 24 hours
- [call_limits.update](https://docs.cumuluslabs.io/reference/call_limits.update): Set or clear the tenant's daily outbound call limit (null: no limit)
- [trunks.list](https://docs.cumuluslabs.io/reference/trunks.list): List BYOC SIP trunks
- [trunks.create](https://docs.cumuluslabs.io/reference/trunks.create): Connect a BYOC SIP trunk
- [trunks.update](https://docs.cumuluslabs.io/reference/trunks.update): Update a BYOC SIP trunk
- [trunks.delete](https://docs.cumuluslabs.io/reference/trunks.delete): Disconnect a BYOC SIP trunk
- [numbers.list](https://docs.cumuluslabs.io/reference/numbers.list): List BYOC phone numbers
- [numbers.import](https://docs.cumuluslabs.io/reference/numbers.import): Import a phone number from a connected trunk
- [numbers.update](https://docs.cumuluslabs.io/reference/numbers.update): Assign agents or rename a phone number
- [numbers.release](https://docs.cumuluslabs.io/reference/numbers.release): Release a phone number
- [secrets.list](https://docs.cumuluslabs.io/reference/secrets.list): List secret metadata (never values)
- [secrets.put](https://docs.cumuluslabs.io/reference/secrets.put): Create a secret or add a new version
- [secrets.delete](https://docs.cumuluslabs.io/reference/secrets.delete): Delete a secret and all its versions
- [provider_keys.list](https://docs.cumuluslabs.io/reference/provider_keys.list): List the model-provider keys runs dial with (metadata only, never the key)
- [provider_keys.put](https://docs.cumuluslabs.io/reference/provider_keys.put): Set or rotate the tenant's own key for a model provider; the provider checks it before it is stored
- [provider_keys.delete](https://docs.cumuluslabs.io/reference/provider_keys.delete): Remove the tenant's key for a model provider; new runs use the platform key
- [documents.list](https://docs.cumuluslabs.io/reference/documents.list): List knowledge documents
- [documents.upload](https://docs.cumuluslabs.io/reference/documents.upload): Upload a knowledge document
- [documents.get](https://docs.cumuluslabs.io/reference/documents.get): Get one knowledge document
- [documents.delete](https://docs.cumuluslabs.io/reference/documents.delete): Delete a document and return storage/provider deletion receipts
- [knowledge.status](https://docs.cumuluslabs.io/reference/knowledge.status): Read knowledge configuration and the ready generation
- [knowledge.configure](https://docs.cumuluslabs.io/reference/knowledge.configure): Choose the embedding model for knowledge
- [knowledge.reembed](https://docs.cumuluslabs.io/reference/knowledge.reembed): Build a new knowledge generation
- [evaluations.create](https://docs.cumuluslabs.io/reference/evaluations.create): Score a run against a rubric
- [evaluations.list](https://docs.cumuluslabs.io/reference/evaluations.list): List evaluations
- [comparisons.create](https://docs.cumuluslabs.io/reference/comparisons.create): Compare a candidate publication against a baseline on existing runs
- [comparisons.get](https://docs.cumuluslabs.io/reference/comparisons.get): Get one comparison with its per-case verdicts
- [comparisons.list](https://docs.cumuluslabs.io/reference/comparisons.list): List comparisons
- [test_suites.list](https://docs.cumuluslabs.io/reference/test_suites.list): List test suites (optionally one agent's) with their last run
- [test_suites.get](https://docs.cumuluslabs.io/reference/test_suites.get): Get a test suite (its current revision, or ?revision) with its last run and flaky cases
- [test_suites.create](https://docs.cumuluslabs.io/reference/test_suites.create): Create a test suite on an agent (201; an idempotent replay returns 200)
- [test_suites.edit](https://docs.cumuluslabs.io/reference/test_suites.edit): Edit a test suite (rename, upsert, remove or reorder cases) as a compare-and-set on its revision
- [test_suites.delete](https://docs.cumuluslabs.io/reference/test_suites.delete): Archive a test suite; its runs and results are kept
- [test_suites.validate](https://docs.cumuluslabs.io/reference/test_suites.validate): Check a suite's node, action and variable references against a published version or the open draft
- [test_runs.estimate](https://docs.cumuluslabs.io/reference/test_runs.estimate): Estimate a test run's trials, cost and duration before starting it
- [test_runs.create](https://docs.cumuluslabs.io/reference/test_runs.create): Run test suites against one publication version (201; an idempotent replay returns 200)
- [test_runs.list](https://docs.cumuluslabs.io/reference/test_runs.list): List test runs, newest first
- [test_runs.get](https://docs.cumuluslabs.io/reference/test_runs.get): Get a test run: state, verdict, progress, summary and cost
- [test_runs.results](https://docs.cumuluslabs.io/reference/test_runs.results): List a test run's case results with each trial's assertion verdicts
- [test_runs.trial](https://docs.cumuluslabs.io/reference/test_runs.trial): Get one trial: its assertion trace and, while retained, the transcript it was judged on
- [test_runs.events](https://docs.cumuluslabs.io/reference/test_runs.events): Read a test run's journal events (JSON page or text/event-stream)
- [test_runs.cancel](https://docs.cumuluslabs.io/reference/test_runs.cancel): Cancel a test run: no new trials start and running trials are cancelled; settled results stay
- [keys.list](https://docs.cumuluslabs.io/reference/keys.list): List API keys (never secrets)
- [keys.create](https://docs.cumuluslabs.io/reference/keys.create): Create an API key with an explicit role
- [keys.revoke](https://docs.cumuluslabs.io/reference/keys.revoke): Revoke an API key; queued effects of its runs are denied
- [keys.rotate](https://docs.cumuluslabs.io/reference/keys.rotate): Replace an API key's secret
- [team.list](https://docs.cumuluslabs.io/reference/team.list): List members and pending invitations
- [team.invite](https://docs.cumuluslabs.io/reference/team.invite): Invite a member
- [team.invite_revoke](https://docs.cumuluslabs.io/reference/team.invite_revoke): Revoke a pending invitation
- [team.invite_resend](https://docs.cumuluslabs.io/reference/team.invite_resend): Send a pending invitation again with a new link and expiry
- [team.remove](https://docs.cumuluslabs.io/reference/team.remove): Remove a member
- [team.set_role](https://docs.cumuluslabs.io/reference/team.set_role): Change a member's role
- [tenant_settings.get](https://docs.cumuluslabs.io/reference/tenant_settings.get): Read the organization's display name and retention settings
- [tenant_settings.update](https://docs.cumuluslabs.io/reference/tenant_settings.update): Rename the organization and/or change retention (retention is a version compare-and-set)
- [alerts.list](https://docs.cumuluslabs.io/reference/alerts.list): List alert rules with their latest delivery
- [alerts.create](https://docs.cumuluslabs.io/reference/alerts.create): Create an alert rule on a metered usage or run metric
- [alerts.update](https://docs.cumuluslabs.io/reference/alerts.update): Change an alert rule (revision compare-and-set)
- [alerts.delete](https://docs.cumuluslabs.io/reference/alerts.delete): Delete an alert rule (revision compare-and-set)
- [alerts.acknowledge](https://docs.cumuluslabs.io/reference/alerts.acknowledge): Acknowledge an uncertain alert delivery so the rule can fire again
- [alert_destinations.get](https://docs.cumuluslabs.io/reference/alert_destinations.get): Read which alert destinations are configured (metadata only, never the secret)
- [alert_destinations.update](https://docs.cumuluslabs.io/reference/alert_destinations.update): Set or clear the Slack webhook or PagerDuty routing key (revision compare-and-set)
- [models.list](https://docs.cumuluslabs.io/reference/models.list): List the tenant's model catalog, optionally for one task
- [environments.list](https://docs.cumuluslabs.io/reference/environments.list): List this organization's production and sandbox environments
- [environments.ensure_sandbox](https://docs.cumuluslabs.io/reference/environments.ensure_sandbox): Create this organization's sandbox environment on first use (same members)
- [audit.list](https://docs.cumuluslabs.io/reference/audit.list): List the tenant audit log