CumulusDocs
Open Studio
On this page

Using the API

Connect your application to Cumulus to start agents and read their results. This quickstart builds a service-ticket agent, publishes a test version and sends it a warehouse repair request. Use curl, TypeScript or Python for the same sequence.

For the complete request and response schemas, open the API reference. Phone calls, retries and pagination follow the cloud example. Run the curl examples in a Bash script with set -euo pipefail, using jq and uuidgen; SDK installation is covered in SDKs.

Quickstart

1. Get an API key

In your authorized Studio deployment, under Settings → API keys, name the key after the system that will use it, pick its role and create it. The secret (cmls_…) is shown once; store it in your secret manager. Only organization admins manage keys; an admin can also create them with POST /api/v1/keys.

Key roleCanUse it for
memberRead everything; create and edit agents; publish; start, update and cancel runs.Cloud runs; phone calls when Can place calls is enabled
adminEverything a member can, plus API keys, secrets, SIP trunks, phone numbers and the budget.Setup and automation that manages the organization
viewerRead only.Dashboards and exports

Runs need a member or admin key

A viewer key gets 403 forbidden on every command. Each operation's required role is in the tables on these pages and in the API reference.

For real outbound phone calls, a member key also needs Can place calls enabled (can_dial: true when creating it through the API). Admin keys can place calls; viewer keys cannot. This permission is separate from the environment's carrier setup and run capacity.

Check the environment and capacity

Set CUMULUS_API_URL to the API URL supplied for your workspace, without /api/v1 or a trailing slash. Use a sandbox key while building. A key selects one environment; agent and run IDs from another environment do not resolve. Before creating an agent, check that your key selects the intended environment and that cloud admission is open:

curl
export CUMULUS_API_KEY=cmls_...
# Example placeholder: replace with your authorized API URL.
export CUMULUS_API_URL=https://talos-api.example.com
set -euo pipefail
curl --fail-with-body -sS --max-time 30 "${CUMULUS_API_URL}/api/v1/environments" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" | jq '{current, items}'
curl --fail-with-body -sS --max-time 30 "${CUMULUS_API_URL}/api/v1/runs/capacity" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" | jq '.items[] | select(.channel == "cloud")'

The environment response has current (production or sandbox) and items containing kind, tenant_id, slug and name. Match current to the item's kind. Capacity items have channel, limit, active and admission_enabled. Cloud needs admission_enabled: true and free capacity (active < limit). Capacity can change before admission; handle a later refusal too.

If capacity is unconfigured or admission is closed, ask your Cumulus contact to enable cloud runs for that environment, supplying its slug and tenant_id. An organization admin can create the sandbox and its key; see Workspace and access.

2. Call the API

Use that API URL for every request. Guide shell examples use CUMULUS_API_URL; TypeScript passes it as baseUrl, and Python passes it as base_url. Send the key as a bearer token in the Authorization header. Request and response bodies are JSON.

export CUMULUS_API_KEY=cmls_...   # a member or admin key
curl --fail-with-body -sS "${CUMULUS_API_URL}/api/v1/agents?limit=20" \
  -H "Authorization: Bearer $CUMULUS_API_KEY"

A 401 unauthenticated means the key is missing, revoked or expired. The TypeScript and Python clients read CUMULUS_API_KEY. Pass the API URL explicitly as above, or set their CUMULUS_BASE_URL environment variable. The standalone TypeScript authoring CLI has its own origin resolution.

The examples below call the same HTTP operations in curl, TypeScript and Python. To define the graph as TypeScript objects instead of sending draft edits, use the SDK tutorial.

Create and publish an agent

The agent returns a typed {category, reason} object. Its input requires a nonempty ticket; its output requires a category from repair, booking, other and a nonempty reason. Extracted flow variables are stored as strings, so this example declares string output properties.

Save the following array as ticket-edits.json. These edits are for a new cloud_task template, whose main nodes are start and done. They route start → extract_result → done. The extraction step saves category and reason as flow variables. When the task ends, Cumulus copies those values into the result fields declared in output_schema.properties. Returning JSON as conversation text alone does not populate the result.

ticket-edits.json

Complete JSON example
json
[
  {
    "type": "flow.prompt",
    "text": "Classify the service ticket as repair, booking or other. Give a brief reason grounded in the ticket. Do not ask follow-up questions."
  },
  {
    "type": "cloud.io.set",
    "cloud": {
      "modes": [
        "task"
      ],
      "input_schema": {
        "type": "object",
        "properties": {
          "ticket": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "ticket"
        ],
        "additionalProperties": false
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "category": {
            "type": "string",
            "enum": [
              "repair",
              "booking",
              "other"
            ]
          },
          "reason": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "category",
          "reason"
        ],
        "additionalProperties": false
      },
      "max_turns": 5,
      "idle_timeout_ms": 60000,
      "deadline_ms": 60000
    }
  },
  {
    "type": "node.instruction",
    "component_id": null,
    "node_id": "start",
    "instruction": {
      "type": "prompt",
      "text": "Read {{ticket}}. State its category and a brief reason, then continue to extract_result."
    }
  },
  {
    "type": "node.create",
    "component_id": null,
    "node": {
      "id": "extract_result",
      "kind": "extract_dynamic_variables",
      "variables": [
        {
          "name": "category",
          "type": "enum",
          "choices": [
            "repair",
            "booking",
            "other"
          ],
          "description": "The category of the service ticket just classified."
        },
        {
          "name": "reason",
          "type": "string",
          "description": "The brief reason for that classification, grounded in the ticket."
        }
      ],
      "edges": [
        {
          "slot": "edges",
          "destinationNodeId": "done",
          "condition": {
            "type": "always"
          }
        }
      ]
    }
  },
  {
    "type": "node.transitions",
    "component_id": null,
    "node_id": "start",
    "edges": [
      {
        "slot": "edges",
        "destinationNodeId": "extract_result",
        "condition": {
          "type": "prompt",
          "prompt": "The ticket has been classified with a category and brief reason."
        }
      }
    ]
  }
]

Create the agent, apply the edits, validate and publish with live: false. Run the returned candidate version explicitly. Validation supplies the next version number; errors block publication. For regular calls or tasks, publish the reviewed graph with live: true. Promotion selects the head; a test publication still requires a test run.

CREATE_AGENT_KEY=$(uuidgen) # retain for retries
created=$(curl --fail-with-body -sS --max-time 30 -X POST "${CUMULUS_API_URL}/api/v1/agents" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CREATE_AGENT_KEY" \
  -d '{"name":"Service-ticket triage","template":"cloud_task","channels":["cloud"],"languages":["en"]}') \
  || { echo "$created" >&2; exit 1; }
AGENT_ID=$(echo "$created" | jq -er .ref.id)
edit_body=$(echo "$created" | jq --slurpfile edits ticket-edits.json \
  '{draft_id: .draft.draft_id, expected_revision: .draft.revision, edits: $edits[0]}')
edited=$(curl --fail-with-body -sS --max-time 30 -X PATCH "${CUMULUS_API_URL}/api/v1/agents/$AGENT_ID/draft" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" -H "Content-Type: application/json" -d "$edit_body") \
  || { echo "$edited" >&2; exit 1; }
validation=$(curl --fail-with-body -sS --max-time 30 -X POST "${CUMULUS_API_URL}/api/v1/agents/$AGENT_ID/draft/validate" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" -H "Content-Type: application/json" \
  -d "$(echo "$edited" | jq '{draft_id, expected_revision: .revision}')") \
  || { echo "$validation" >&2; exit 1; }
echo "$validation" | jq -e '.ok == true' >/dev/null \
  || { echo "$validation" | jq . >&2; exit 1; }
publication=$(curl --fail-with-body -sS --max-time 30 -X POST "${CUMULUS_API_URL}/api/v1/agents/$AGENT_ID/publications" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" -H "Content-Type: application/json" \
  -d "$(echo "$edited" | jq --argjson version "$(echo "$validation" | jq -er .version)" \
       '{draft_id, expected_revision: .revision, version: $version, live: false}')") \
  || { echo "$publication" >&2; exit 1; }
PUBLICATION_VERSION=$(echo "$publication" | jq -er .ref.version)
echo "$publication" | jq '{ref, is_head}'

Start a cloud run

Send the warehouse ticket to the test version you just published. POST /api/v1/runs returns immediately with a run ID and state admitted; the agent continues working in the background.

A publication may also enable background for schedule/event-triggered work; direct API requests accept only task or chat.

Set version to pin this request to the candidate and test: true to exclude it from billing, webhooks and event triggers. mode is task or chat, and input must match the publication's input schema. Omitting version selects the current head and still enforces that publication's test-only flag. test: true does not suppress configured customer HTTP actions.

RUN_KEY=$(uuidgen) # retain this key and body if the outcome is unknown
RUN_BODY=$(jq -n --arg agent "$AGENT_ID" --argjson version "$PUBLICATION_VERSION" \
  '{channel: "cloud", agent_id: $agent, version: $version, test: true, mode: "task", input: {ticket: "The loading-bay door is stuck. We need a technician."}}')
run=$(curl --fail-with-body -sS --max-time 30 -X POST "${CUMULUS_API_URL}/api/v1/runs" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $RUN_KEY" -d "$RUN_BODY") \
  || { echo "$run" >&2; echo "Retain RUN_KEY and RUN_BODY for recovery." >&2; exit 1; }
RUN_ID=$(echo "$run" | jq -er .run_id)
echo "$run" | jq '.error // {run_id, state, version}'

Follow a run live

Follow the ticket as the agent works through it. Request GET /api/v1/runs/{run_id}/events with Accept: text/event-stream to receive server-sent events from the beginning of the run.

Each frame has an id (the per-run sequence number), an event type and JSON data. The server sends keepalive comments and bounds replay. A stream ending is not an artifact-readiness signal: fetch each result, transcript, recording and analysis state separately.

text/event-stream

Example
id: 1
event: run.admitted
data: {"event_id":"…","type":"run.admitted","sequence":1,"run":{"run_id":"…","publication":{…}},…}

id: 2
event: run.state_changed
data: {"event_id":"…","type":"run.state_changed","sequence":2,…}

: keepalive

To resume after a disconnect, send Last-Event-ID with the last sequence you processed (or the query parameter after_sequence). Without the SSE Accept header the same operation returns a JSON page: { items, next_after_sequence }, up to limit events (1 to 500, default 100).

# Server-sent events. Recheck run and artifact state after the stream ends.
curl --fail-with-body -sS -N "${CUMULUS_API_URL}/api/v1/runs/$RUN_ID/events" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" \
  -H "Accept: text/event-stream"

# Reconnect where you left off: send the id of the last event you processed.
curl --fail-with-body -sS -N "${CUMULUS_API_URL}/api/v1/runs/$RUN_ID/events" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Last-Event-ID: 3"

See Runs for event categories and live progress. Use the output states below to determine when a result is available.

Read the task result, transcript, recording and analysis

Read the task result for {category, reason}, or the transcript for the spoken classification. The default template has no structured output fields; the edits above add the schema and extraction step. Analysis is separate and provides only configured post-run fields.

The polling examples below stop starting new polling passes after two minutes; each read has a ten-second timeout. A client deadline stops waiting; it does not cancel the run. Save its ID and resume reads later rather than starting duplicate work. A failed read raises an API error; handle it with Errors and retries.

For this example, a ready result could be { "category": "repair", "reason": "The loading-bay door needs a technician." }; the wording is model-generated. Check runs.get.state and outcome.reason for a failed admitted run, including output_invalid if its final variables do not satisfy the schema. Do not parse a transcript as a substitute for missing typed output.

Check each output’s state before using it, even after the run ends. A task result uses ready; a final transcript uses complete (partial means the run is still active). pending, running or processing means an output is not ready; none, not_available or not_requested means it is unavailable; expired means retention removed it. Cloud tasks have no recording; see phone recording reads separately. Analysis uses completed for a settled extraction and can report failed or not_requested. Use its configured fields and supporting evidence; disposition and successful are null. Confirm a booking or other transaction through the corresponding tool result.

# Wait for the task's typed result. HTTP failures stop the script.
RESULT_DEADLINE=$((SECONDS + 120))
RESULT_READY=false
while (( SECONDS < RESULT_DEADLINE )); do
  current=$(curl --fail-with-body -sS --max-time 10 "${CUMULUS_API_URL}/api/v1/runs/$RUN_ID" \
    -H "Authorization: Bearer $CUMULUS_API_KEY") || { echo "$current" >&2; exit 1; }
  case $(echo "$current" | jq -r .state) in
    failed|cancelled|rejected|expired)
      echo "$current" | jq '{run_id, state, outcome}' >&2; exit 1 ;;
  esac
  result=$(curl --fail-with-body -sS --max-time 10 "${CUMULUS_API_URL}/api/v1/runs/$RUN_ID/result" \
    -H "Authorization: Bearer $CUMULUS_API_KEY") || { echo "$result" >&2; exit 1; }
  case $(echo "$result" | jq -r .state) in
    ready) echo "$result" | jq .result; RESULT_READY=true; break ;;
    none|expired) echo "$result" | jq '{state, purged}' >&2; exit 1 ;;
    pending) sleep 2 ;;
    *) echo "Unexpected result state" >&2; exit 1 ;;
  esac
done
$RESULT_READY || { echo "Result still pending; retain run ID $RUN_ID and read it later." >&2; exit 1; }
# Read final conversation text only when the transcript is complete.
transcript=$(curl --fail-with-body -sS --max-time 10 "${CUMULUS_API_URL}/api/v1/runs/$RUN_ID/transcript" \
  -H "Authorization: Bearer $CUMULUS_API_KEY") || { echo "$transcript" >&2; exit 1; }
echo "$transcript" | jq -e '.state == "complete"' >/dev/null \
  || { echo "$transcript" | jq '{state}' >&2; exit 1; }
echo "$transcript" | jq -r '.utterances[] | "\(.role): \(.text)"'
# Post-run analysis: state and configured transcript-backed fields
curl --fail-with-body -sS --max-time 10 "${CUMULUS_API_URL}/api/v1/runs/$RUN_ID/analysis" -H "Authorization: Bearer $CUMULUS_API_KEY" \
  | jq '.error // {state, fields, evaluation_id, completed_at}'

Place a phone call

The example below starts a real call using a phone agent published with live: true whose required variables are customer_name and site_name. A test-only publication instead requires an explicit version and test: true in the run request, including after promotion. The request supplies Alex’s name and warehouse. For a complete flow and its required inputs, follow Build an agent for service calls.

A phone run dials to from from, both in E.164 form. from is a number you imported on one of your SIP trunks; leave it out to use the caller ID the agent was published with. dynamic_variables fill the agent's {{variables}} for this call. Numbers and trunks are set up once, by an admin: see Phone.

curl -sS -X POST "${CUMULUS_API_URL}/api/v1/runs" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "$(jq -n --arg agent "$PHONE_AGENT_ID" '{
        channel: "phone", agent_id: $agent,
        to: "+14155550123", from: "+14155550100",
        dynamic_variables: {customer_name: "Alex", site_name: "North warehouse"},
        metadata: {crm_id: "A-1001"}
      }')" | jq '.error // {run_id, state, phone_state, to, from}'

This request places a real call. The displayed E.164 numbers are fictional placeholders: replace them with a company-controlled target, an authorized imported caller ID and a consenting recipient. Use a public-demo number or approved disposable number if the recording will be shared. test: true still dials.

phone_state follows the call (dialing, ringing, active, ended, …) while the run state stays channel-neutral. PATCH /api/v1/runs/{run_id} updates a live call's dynamic variables.

Send every variable the agent uses

If the agent's flow uses a {{variable}} you did not send, the call is refused before it dials: 400 invalid_request, details.reason: "missing_dynamic_variables", and the message names each missing one. Dynamic variables shows how to list what an agent needs.

Idempotency-Key

Operations marked for idempotency require an Idempotency-Key header. Generate a UUID for each logical request and reuse it for retries with the same body. This lets the API return the original resource instead of creating another.

  • Same key, same body: you get the original resource back, with 200 instead of 201. Nothing is created twice.
  • Same key, different body: 409 idempotency_conflict.
  • No key: 400 invalid_request. Keys are 1 to 256 characters; agents.create and agents.clone need 8 to 255 visible ASCII characters. A UUID satisfies both.
  • API keys are the exception: a replayed keys.create or keys.rotate answers 409 conflict (details.reason: "secret_returned_once"), because a key's secret is only ever returned once.

The SDKs generate a key for you when you pass none, and report it on every error. These operations take one:

POST agents.create · POST agents.clone · POST agents.import · POST runs.create · PATCH runs.update · POST runs.send_message · POST test_sessions.create · POST trunks.create · POST numbers.import · PUT secrets.put · POST test_suites.create · POST test_runs.create · POST keys.create · POST keys.rotate

Other commands use their resource or revision to prevent duplicate changes. Publishing names a version; draft edits compare the expected revision; repeating a deletion does not delete another resource.

Errors and retries

Every failure has the same body. code is stable; branch on it, not on the message.

Error body

Example
{
  "error": {
    "code": "rate_limited",
    "message": "Tenant concurrent call limit reached",
    "retryable": true,
    "outcome": "none",
    "details": { "reason": "capacity_exhausted" }
  }
}
  • retryable: the same request can succeed later (back off first).
  • outcome: "none" means nothing happened. "unknown" means the command may have taken effect: retry it with the same Idempotency-Key, never a new one.
  • details.reason says why, for example capacity_exhausted, spend_cap_exhausted, trunk_not_authorized or missing_dynamic_variables. Validation errors list details.issues; a draft that does not compile lists details.diagnostics.
codeHTTPretryableoutcome
unauthenticated401nonone
forbidden403nonone
not_found404nonone
conflict409nonone
invalid_request400nonone
idempotency_conflict409nonone
policy_denied403nonone
capability_unavailable409nonone
provider_unavailable503yesnone
knowledge_unavailable409yesnone
publication_invalid422nonone
run_not_active409nonone
rate_limited429yesnone
outcome_unknown502yesunknown
internal500yesnone

Use these samples for the candidate request above. The curl recovery handles Retry-After expressed in seconds; if your service receives an HTTP-date value, parse that date before retrying. Retain the key and exact body across process restarts; a changed body is a new logical request. The SDK examples replace the admission code in Start a cloud run; choose one version of that step. They retain the successful or recovered response as run for the event and polling steps, and show one recovery attempt for an unknown outcome. Use bounded backoff for other retryable errors and honor Retry-After when returned; fix admission or spending refusals before retrying.

# Recover an admission attempt with the SAME body/key; stop after three requests.
create_run() {  # $1: request body, $2: Idempotency-Key (keep it until you know the outcome)
  local code attempt pause
  for attempt in 1 2 3; do
    code=$(curl -sS --max-time 30 -D run.headers -o run.json -w '%{http_code}' -X POST "${CUMULUS_API_URL}/api/v1/runs" \
      -H "Authorization: Bearer $CUMULUS_API_KEY" -H "Content-Type: application/json" \
      -H "Idempotency-Key: $2" -d "$1") || code=000
    case $code in
      200|201) cat run.json; return 0 ;;             # 201 created, 200 replayed
      000) sleep $((attempt * 2)) ;;                # no answer: preserve the same key
      *)
        if jq -e '.error.retryable == true' run.json >/dev/null; then
          pause=$(awk 'tolower($1) == "retry-after:" {gsub("\r", "", $2); print $2}' run.headers)
          case $pause in
            ''|*[!0-9]*) pause=$((attempt * 2)) ;;
          esac
          sleep "$pause"
        else
          jq . run.json >&2; return 1
        fi ;;
    esac
  done
  echo "No run confirmed after 3 attempts (HTTP $code); retry later with Idempotency-Key $2" >&2
  return 1
}
# Recover the same candidate request from Start a cloud run; do not generate a new key here.
if run=$(create_run "$RUN_BODY" "$RUN_KEY"); then
  RUN_ID=$(echo "$run" | jq -er .run_id)
  echo "$run" | jq '{run_id, state}'
else
  exit 1
fi

Recover a lost edit or publish response

Keep the original request and validation response until its outcome is known. Draft edits and publications use revision/resource checks rather than an idempotency header:

  • Lost draft-edit response: read drafts.get. Its revision is state.revision and its ID is state.draft_id; compare flow.globalPrompt, flow.nodes and cloud with the edits you intended. If those changes are present, continue with the returned state and validate. If the same draft remains at the original revision and its content is unchanged, retry the original edit body. If it changed differently, reconcile before submitting a new edit; do not guess a revision or repeat node creation.
  • Lost publication response: read publications.get for the requested version. Compare ref.digest with the retained validation digest, and confirm test: true for this candidate. If they match, use its returned ref.version. If the version is absent, reread the draft and compare its ID, revision and content with what you validated before retrying the identical publication request. A conflicting version or changed draft needs review; do not silently increment the version. After a replay, use the version returned by the server.

Pagination

List operations take limit (1 to 200, default 50) and cursor. A page carries next_cursor; pass it back as cursor for the next page, until it is null. Run events page by sequence instead (after_sequence and next_after_sequence).

args=(--data-urlencode "limit=200")
while :; do
  page=$(curl -sS --fail-with-body -G "${CUMULUS_API_URL}/api/v1/runs" \
    -H "Authorization: Bearer $CUMULUS_API_KEY" "${args[@]}") || { echo "request failed: $page" >&2; break; }
  echo "$page" | jq -r '.items[] | "\(.run_id) \(.state)"'
  cursor=$(echo "$page" | jq -r '.next_cursor // empty')
  [ -n "$cursor" ] || break
  args=(--data-urlencode "limit=200" --data-urlencode "cursor=$cursor")
done

Limits

  • Concurrent runs per channel are capped for your organization. A run beyond the cap is refused with 429 rate_limited (details.reason: "capacity_exhausted") and nothing is created. GET /api/v1/runs/capacity shows each channel's limit and active runs.
  • Budget: once metered spend reaches the organization's cap, new runs get 429 with spend_cap_exhausted.
  • Request rate: API key and secret operations are rate limited per organization; beyond the limit they answer 429 with a Retry-After header.
Content version 05ac3ee5Customer SDKMarkdown source
Using the API · Cumulus developer docs