Customer HTTP API
Customer HTTP API reference
Use these endpoints from your application to manage agents and publications, place calls and retrieve results. Find an endpoint by task, name or path, then open its request and response reference. For agent builders, customer-server handlers and call helpers, use the customer SDK reference.
https://api.cumuluslabs.ioYour API key selects the workspace and permissions. If Cumulus provides a separate development API URL, use that origin instead. Pass the origin as baseUrl to the client or CUMULUS_API_URL to the CLI.
Send Authorization: Bearer <API key>. Write requests use JSON; endpoints marked for idempotency also require Idempotency-Key. Keep keys server-side; browser clients use an authenticated same-origin proxy.
The SDK uses these same endpoints. The customer SDK tutorial shows the complete definition, publication and calling workflow; this reference provides the HTTP details for each operation.
Browse by feature
105 of 105 endpoints · Select one for fields, responses and integration guidance.
21 endpoints
- GETList agents
/api/v1/agentsagents.list · viewer key - GETGet an agent
/api/v1/agents/{agent_id}agents.get · viewer key - POSTCreate an agent
/api/v1/agentsagents.create · member key - DELETEArchive an agent
/api/v1/agents/{agent_id}agents.delete · member key - POSTClone an agent
/api/v1/agents/{agent_id}/cloneagents.clone · member key - POSTImport a Retell agent
/api/v1/agents/importagents.import · member key - POSTPreview a Retell import
/api/v1/agents/import/inspectagents.import_inspect · member key - GETGet the draft
/api/v1/agents/{agent_id}/draftdrafts.get · viewer key - POSTOpen a draft
/api/v1/agents/{agent_id}/draftdrafts.open · member key - PATCHEdit a draft
/api/v1/agents/{agent_id}/draftdrafts.edit · member key - DELETEDiscard a draft
/api/v1/agents/{agent_id}/draftdrafts.discard · member key - POSTRebase a draft
/api/v1/agents/{agent_id}/draft/rebasedrafts.rebase · member key - POSTValidate a draft
/api/v1/agents/{agent_id}/draft/validatedrafts.validate · member key - POSTPublish a version
/api/v1/agents/{agent_id}/publicationspublications.publish · member key - GETList published versions
/api/v1/agents/{agent_id}/publicationspublications.list · viewer key - GETGet a published version
/api/v1/agents/{agent_id}/publications/{version}publications.get · viewer key - POSTPromote or roll back a version
/api/v1/agents/{agent_id}/headpublications.promote · member key - GETList available actions
/api/v1/actionsactions.list · viewer key - GETList speech models and voices
/api/v1/voicesvoices.list · viewer key - POSTPreview configured speech
/api/v1/voices/previewvoices.preview · member key - GETList available models
/api/v1/modelsmodels.list · viewer key
16 endpoints
- POSTStart a run
/api/v1/runsruns.create · member key - GETList runs
/api/v1/runsruns.list · viewer key - GETCheck run capacity
/api/v1/runs/capacityruns.capacity · viewer key - GETGet a run
/api/v1/runs/{run_id}runs.get · viewer key - PATCHUpdate a live phone run
/api/v1/runs/{run_id}runs.update · member key - GETGet an update receipt
/api/v1/runs/{run_id}/updates/{update_id}runs.update_get · viewer key - POSTCancel a run
/api/v1/runs/{run_id}/cancelruns.cancel · member key - POSTSend a chat message
/api/v1/runs/{run_id}/messagesruns.send_message · member key - GETRead or stream run events
/api/v1/runs/{run_id}/eventsruns.events · viewer key - GETGet action receipts
/api/v1/runs/{run_id}/effectsruns.effects · viewer key - GETGet a transcript
/api/v1/runs/{run_id}/transcriptruns.transcript · viewer key - GETGet a task result
/api/v1/runs/{run_id}/resultruns.result · viewer key - GETGet a recording URL
/api/v1/runs/{run_id}/recordingruns.recording · viewer key - GETGet post-run analysis
/api/v1/runs/{run_id}/analysisruns.analysis · viewer key - GETGet run usage and cost
/api/v1/runs/{run_id}/usageruns.usage · viewer key - POSTStart a browser voice test
/api/v1/test-sessionstest_sessions.create · member key
19 endpoints
- POSTEvaluate a run
/api/v1/evaluationsevaluations.create · member key - GETList evaluations
/api/v1/evaluationsevaluations.list · viewer key - POSTCompare agent versions
/api/v1/comparisonscomparisons.create · member key - GETGet a version comparison
/api/v1/comparisons/{comparison_id}comparisons.get · viewer key - GETList version comparisons
/api/v1/comparisonscomparisons.list · viewer key - GETList test suites
/api/v1/test-suitestest_suites.list · viewer key - GETGet a test suite
/api/v1/test-suites/{suite_id}test_suites.get · viewer key - POSTCreate a test suite
/api/v1/test-suitestest_suites.create · member key - PATCHEdit a test suite
/api/v1/test-suites/{suite_id}test_suites.edit · member key - DELETEArchive a test suite
/api/v1/test-suites/{suite_id}test_suites.delete · member key - POSTValidate a test suite
/api/v1/test-suites/{suite_id}/validatetest_suites.validate · member key - POSTEstimate a test run
/api/v1/test-runs/estimatetest_runs.estimate · viewer key - POSTStart a test run
/api/v1/test-runstest_runs.create · member key - GETList test runs
/api/v1/test-runstest_runs.list · viewer key - GETGet a test run
/api/v1/test-runs/{test_run_id}test_runs.get · viewer key - GETGet case results
/api/v1/test-runs/{test_run_id}/resultstest_runs.results · viewer key - GETGet a trial transcript
/api/v1/test-runs/{test_run_id}/cases/{case_id}/trials/{trial}test_runs.trial · viewer key - GETRead or stream test events
/api/v1/test-runs/{test_run_id}/eventstest_runs.events · viewer key - POSTCancel a test run
/api/v1/test-runs/{test_run_id}/canceltest_runs.cancel · member key
10 endpoints
- GETGet your outbound call limit
/api/v1/telephony/call-limitcall_limits.get · viewer key - PUTSet your outbound call limit
/api/v1/telephony/call-limitcall_limits.update · admin key - GETList SIP trunks
/api/v1/telephony/trunkstrunks.list · viewer key - POSTConnect a SIP trunk
/api/v1/telephony/trunkstrunks.create · admin key - PATCHUpdate a SIP trunk
/api/v1/telephony/trunks/{trunk_id}trunks.update · admin key - DELETEDisconnect a SIP trunk
/api/v1/telephony/trunks/{trunk_id}trunks.delete · admin key - GETList phone numbers
/api/v1/telephony/numbersnumbers.list · viewer key - POSTImport a phone number
/api/v1/telephony/numbersnumbers.import · admin key - PATCHUpdate a phone number
/api/v1/telephony/numbers/{number_id}numbers.update · admin key - DELETERelease a phone number
/api/v1/telephony/numbers/{number_id}numbers.release · admin key
7 endpoints
- GETList knowledge documents
/api/v1/documentsdocuments.list · viewer key - POSTUpload a knowledge document
/api/v1/documentsdocuments.upload · member key - GETGet a knowledge document
/api/v1/documents/{document_id}documents.get · viewer key - DELETEDelete a knowledge document
/api/v1/documents/{document_id}documents.delete · member key - GETGet knowledge status
/api/v1/knowledgeknowledge.status · viewer key - PUTConfigure knowledge embeddings
/api/v1/knowledgeknowledge.configure · admin key - POSTRebuild knowledge embeddings
/api/v1/knowledge/reembedknowledge.reembed · member key
11 endpoints
- GETSummarize usage
/api/v1/usageusage.summary · viewer key - GETGet your budget
/api/v1/usage/budgetbudgets.get · viewer key - PUTSet your budget
/api/v1/usage/budgetbudgets.update · admin key - GETGet your rate card
/api/v1/usage/rate-cardusage.rate_card · viewer key - GETList alert rules
/api/v1/alertsalerts.list · viewer key - POSTCreate an alert rule
/api/v1/alertsalerts.create · admin key - PATCHUpdate an alert rule
/api/v1/alerts/{alert_id}alerts.update · admin key - DELETEDelete an alert rule
/api/v1/alerts/{alert_id}alerts.delete · admin key - POSTAcknowledge an uncertain alert delivery
/api/v1/alerts/{alert_id}/acknowledgealerts.acknowledge · admin key - GETGet alert destinations
/api/v1/alert-destinationsalert_destinations.get · viewer key - PATCHSet alert destinations
/api/v1/alert-destinationsalert_destinations.update · admin key
21 endpoints
- GETList secret metadata
/api/v1/secretssecrets.list · viewer key - PUTCreate or version a secret
/api/v1/secrets/{secret_id}secrets.put · admin key - DELETEDelete a secret
/api/v1/secrets/{secret_id}secrets.delete · admin key - GETList provider credentials
/api/v1/provider-keysprovider_keys.list · viewer key - PUTSet a provider credential
/api/v1/provider-keys/{provider}provider_keys.put · admin key - DELETERemove a provider credential
/api/v1/provider-keys/{provider}provider_keys.delete · admin key - GETList API keys
/api/v1/keyskeys.list · admin key - POSTCreate an API key
/api/v1/keyskeys.create · admin key - DELETERevoke an API key
/api/v1/keys/{key_id}keys.revoke · admin key - POSTRotate an API key
/api/v1/keys/{key_id}/rotatekeys.rotate · admin key - GETList members and invitations
/api/v1/teamteam.list · viewer key - POSTInvite a member
/api/v1/team/invitationsteam.invite · admin key - DELETERevoke an invitation
/api/v1/team/invitations/{invitation_id}team.invite_revoke · admin key - POSTResend an invitation
/api/v1/team/invitations/{invitation_id}/resendteam.invite_resend · admin key - DELETERemove a member
/api/v1/team/members/{user_id}team.remove · admin key - PATCHChange a member’s role
/api/v1/team/members/{user_id}team.set_role · admin key - GETGet workspace settings
/api/v1/tenant/settingstenant_settings.get · viewer key - PUTUpdate workspace settings
/api/v1/tenant/settingstenant_settings.update · admin key - GETList environments
/api/v1/environmentsenvironments.list · viewer key - POSTCreate a sandbox
/api/v1/environments/sandboxenvironments.ensure_sandbox · admin key - GETRead the audit log
/api/v1/auditaudit.list · admin key
Interactive API reference
Browse the same endpoints and schemas below, or copy a request in your preferred language.