canonical: https://jentic.com/apis/cumuluslabs.io/cumuluslabs

# Cumuluslabs Cumulus Talos API

The Cumulus Talos API builds, runs, and evaluates conversational voice agents that operate over the phone and the web. It versions agent drafts and publications, starts runs that place or take calls, and returns recordings, transcripts, and post-run analysis for each one. Telephony management covers imported phone numbers, SIP trunks, and outbound call limits, while test suites and scored test runs let you regression-test an agent before publishing a new version.

## For AI agents

Build and run AI voice agents over the phone: start calls, stream run events, and pull recordings, transcripts, and analysis. Provision numbers and SIP trunks, configure voices, and evaluate agents with test suites and scored test runs.

## Scope

Does not handle video conferencing, email, or SMS marketing campaigns. Use for building, running, and evaluating voice agents over the phone only.

## Capabilities

- Build conversational voice agents and publish versioned revisions
- Start phone and web runs, then stream run events until the call completes
- Retrieve call recordings, transcripts, and post-run analysis
- Provision phone numbers and connect SIP trunks for outbound and inbound calls
- Evaluate agent behaviour with test suites, test runs, and scored trials
- Configure speech models and preview voices before publishing
- Track usage, budgets, and rate cards across runs

## Use cases

### Agent-Operated Voice Calls

An AI agent connected through Jentic can configure and run voice calls end to end: it creates and publishes an agent, starts a run against a provisioned phone number, streams run events while the call is live, and pulls the recording and transcript once it ends. Cumulus Talos runs are asynchronous, so the agent subscribes to events or polls status until the call completes.

Example prompt: Create an agent, publish the draft, start an outbound run to a phone number, and return the transcript once the call ends

### Agent Evaluation and Regression Testing

Teams shipping voice agents use Cumulus Talos to catch regressions before a new version goes live. A test suite holds cases that are run as scored trials against a specific agent version, and the results report per-case outcomes and transcripts. An agent or CI step can estimate a test run's cost, launch it, and read the pass rate before promoting the version.

Example prompt: Create a test suite with three cases, start a test run against the latest agent version, and return the pass rate from the case results

### Telephony Provisioning

Before an agent can take calls it needs numbers and routing, which Cumulus Talos manages directly. You can import a phone number, connect a SIP trunk for carrier routing, and set an outbound call limit to cap spend. These controls sit alongside budgets and rate cards so an operator can bound both call volume and cost.

Example prompt: Import a phone number, connect a SIP trunk, and set the outbound call limit for the account

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/agents` | Create an agent |
| POST | `/api/v1/runs` | Start a run |
| GET | `/api/v1/runs/{run_id}/transcript` | Get a transcript |
| GET | `/api/v1/runs/{run_id}/recording` | Get a recording URL |
| POST | `/api/v1/telephony/numbers` | Import a phone number |
| POST | `/api/v1/test-runs` | Start a test run |
| GET | `/api/v1/voices` | List speech models and voices |

## Key resources

- **Agents** — Create agents, edit drafts, and publish or roll back versioned revisions.
- **Runs** — Start runs, stream events, and read recordings, transcripts, analysis, and cost.
- **Telephony** — Import phone numbers, connect SIP trunks, and set outbound call limits.
- **Testing** — Create test suites and launch scored test runs against agent versions.
- **Voices and Usage** — List speech models and voices, and track usage, budgets, and rate cards.

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 40 / 100
- **Maturity:** Non-Ready
- **Dimensions:**
  - Foundational Compliance: 73 / 100
  - Developer Experience & Jentic Compatibility: 69 / 100
  - AI-Readiness & Agent Experience: 17 / 100
  - Agent Usability: 83 / 100
  - Security: 60 / 100
  - AI Discoverability: 75 / 100
- **View full report:** https://jentic.com/apis/cumuluslabs.io/cumuluslabs/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Cumulus Talos API by hand means handling its bearer tokens, Idempotency-Key headers on writes, asynchronous run and test-run jobs, event streams, and telephony setup for numbers and SIP trunks. Through Jentic you install once, import Cumulus Talos from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Cumulus Talos puts the agent id and run id in the URL path, so a rule can pin your agent to one agent's runs and the transcript and analysis reads it needs. Destructive operations like phone-number release or API key rotation stay out of that set unless you add them.
- **Credential handling:** Your Cumulus Talos token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a phone call' or 'evaluate an agent', and Jentic returns the matching Cumulus Talos operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Bland AI** — AI phone-call platform for outbound and inbound voice agents, with less emphasis on built-in evaluation suites.
- **Bolna** — Voice-agent platform for building and running conversational phone agents.
- **Rev AI** — Speech-to-text transcription for standalone audio that did not originate from a voice-agent run.

## FAQ

### What authentication does the Cumulus Talos API use?

The Cumulus Talos API authenticates with a bearer token per its OpenAPI spec: every request sends an Authorization header carrying your API key. Write operations also accept an Idempotency-Key header so a retry does not duplicate an agent, run, or key. Through Jentic the token is stored once, encrypted, by your own Jentic One instance and injected at call time.

### Can I get call recordings and transcripts with the Cumulus Talos API?

Yes. After a run completes you can fetch a recording URL, a transcript, and a post-run analysis, and you can read or stream run events while a call is still live. Each run also reports its own usage and cost.

### What are the rate limits for the Cumulus Talos API?

The OpenAPI spec does not define rate limits for the Cumulus Talos API. It does let you set per-account outbound call limits and budgets, and you can check the Cumulus Labs documentation at https://docs.cumuluslabs.io for current limits.

### Is there a Cumulus Talos MCP server?

You don't need an MCP server to connect your agent to the Cumulus Talos API. Jentic imports it directly from the API Directory: store your token once and your agent can build agents, start runs, and read transcripts. Operations are discovered on demand instead of loading another server's tool definitions into context.

### Can I limit what my agent is allowed to do with the Cumulus Talos API?

Yes. Write a rule that allows only the operations the task needs, such as starting runs and reading transcripts, so destructive operations like releasing phone numbers, disconnecting SIP trunks, or revoking API keys are not included unless you add them. Every call the agent makes is logged.

### How do I start a voice call with the Cumulus Talos API through Jentic?

Search Jentic for 'start a voice agent run', and it returns the matching Cumulus Talos operations with their input schemas. Your agent creates and publishes an agent, starts a run against a provisioned number, and reads the transcript when the call ends. To run it on your own infrastructure, install Jentic One from its GitHub repo.