On this page
Workspace and access
Before your application can run an agent, choose a workspace environment and create an API key for it. This page explains those access settings, provider credentials, phone resources and usage limits. You edit the conversation itself in the agent draft.
Choose production or sandbox
List environments identifies the production and sandbox tenants and the environment selected by your key. An admin can create the sandbox on first use. Sandbox members are shared with the organization, while agents, runs, secrets and phone setup belong to the selected environment.
Check the environment selected by your key before running an example. Agents, runs and secret IDs from another environment will not resolve. Configure phone trunks and numbers in each environment where you use them. Contact Cumulus to enable run admission and capacity if they have not been configured.
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
GET /api/v1/environments | environments_list | viewer | List the organization’s production and sandbox environments. current identifies the environment selected by your key. |
POST /api/v1/environments/sandbox | environments_ensure_sandbox | admin | Create the organization’s sandbox on first use. It shares membership with production and has separate resources. |
API keys and provider credentials
Create keys in Settings → API keys. Choose the role for the integration:
| Role | Typical use |
|---|---|
| Viewer | Read-only reporting |
| Member | Build agents and start runs |
| Admin | Manage workspace settings and access |
Each endpoint lists its minimum role. Member keys also need Can place calls (can_dial: true) for real outbound calls. Admin keys can place calls; viewer keys cannot. Store keys in your secret manager and inject them on the server, never in browser code.
API key creation and rotation return the secret once. Save it at creation; list operations return metadata. Revocation affects future access and can deny queued effects of runs started by that key. Coordinate rotation with the systems using it.
If the environment uses your own model-provider account, add that provider's key here. The selected model also needs to be enabled for the environment. Credential reads return metadata, not the secret. Check the endpoint’s validation and deletion rules before replacing a credential.
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
GET /api/v1/provider-keys | provider_keys_list | viewer | List metadata for your model-provider credentials. The response does not expose keys. |
PUT /api/v1/provider-keys/{provider} | provider_keys_put | admin | Set or rotate a model-provider credential. The provider validates it before storage. |
DELETE /api/v1/provider-keys/{provider} | provider_keys_delete | admin | Revoke your credential and its versions, including existing run pins. A tenant-pinned run cannot fall back to platform billing; later admission requires an explicitly authorized provider account. |
GET /api/v1/keys | keys_list | admin | List API key metadata. Key secrets are never returned. |
POST /api/v1/keys | keys_create | admin | Create an API key with an explicit role. Store the secret from the creation response; it is shown once. |
DELETE /api/v1/keys/{key_id} | keys_revoke | admin | Revoke an API key. Future access is refused, including queued effects authorized by that key. |
POST /api/v1/keys/{key_id}/rotate | keys_rotate | admin | Replace an API key’s secret. Store the returned secret and update the systems using it. |
Members and secrets
Invite members and assign roles as an admin. Invitation creation and resend return the email delivery result and a one-time acceptance link. If email delivery is not confirmed, copy the link from Settings → Team and share it with that invitee.
Member and invitation lists do not include acceptance links. Replaying the original creation request does not issue a new link; resend the invitation to obtain one. Revoke stale invitations and remove access when it is no longer needed. Use service API keys for integrations rather than a person’s login.
Agent action credentials, SIP passwords and webhook signing values belong in versioned secrets. The agent references a secret version; listing secrets does not expose the value. See Triggers and webhooks for integration setup.
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
GET /api/v1/secrets | secrets_list | viewer | List secret names, kinds and versions. Secret values are never returned. |
PUT /api/v1/secrets/{secret_id} | secrets_put | admin | Create a secret or add a version. Keep the returned version for references in agents and trunks; the response does not return the value. |
DELETE /api/v1/secrets/{secret_id} | secrets_delete | admin | Delete a secret and all its versions. |
GET /api/v1/team | team_list | viewer | List workspace members and pending invitations. |
POST /api/v1/team/invitations | team_invite | admin | Invite a person to join the workspace with a selected role. |
DELETE /api/v1/team/invitations/{invitation_id} | team_invite_revoke | admin | Revoke a pending invitation. |
POST /api/v1/team/invitations/{invitation_id}/resend | team_invite_resend | admin | Resend a pending invitation with a new link and expiry. |
DELETE /api/v1/team/members/{user_id} | team_remove | admin | Remove a member’s workspace access. |
PATCH /api/v1/team/members/{user_id} | team_set_role | admin | Change a workspace member’s role. |
Rates, usage and limits
Read the rate card for pricing and metered usage for consumption. If a budget or rate-card response reports configured: false, the configuration is missing; the service is not necessarily free. Usage can be incomplete while measurements are settling, so inspect the response's completeness fields.
Three limits can block a new run: the spending cap, the daily outbound call limit and concurrent run capacity. Read the error’s reason to identify the applicable limit. See API limits.
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
GET /api/v1/usage | usage_summary | viewer | Read metered usage by agent, run or day. Use purpose=test for usage that is measured but not billed, and check completeness. |
GET /api/v1/usage/budget | budgets_get | viewer | Read the spending cap and metered spend. configured: false means metered pricing has not been installed. |
PUT /api/v1/usage/budget | budgets_update | admin | Set the spending cap using the current policy revision. Metered pricing must be configured first. |
GET /api/v1/usage/rate-card | usage_rate_card | viewer | Read your environment’s active rates. configured: false means metered pricing has not been installed. |
GET /api/v1/telephony/call-limit | call_limits_get | viewer | Read the daily outbound call limit and the calls placed in the last 24 hours. |
PUT /api/v1/telephony/call-limit | call_limits_update | admin | Set the daily outbound call limit, or use null to remove it. Concurrent-run capacity is configured separately. |
Alerts and delivery
Create alert rules for supported usage or run metrics, and configure destinations separately. Destination reads return metadata rather than credentials. Rule updates use revision checks: read the current rule before changing it.
If a delivery outcome is uncertain, inspect the latest delivery before acknowledging it. Acknowledgment allows the rule to fire again; it does not confirm delivery of an earlier notification.
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
GET /api/v1/alerts | alerts_list | viewer | List alert rules and their latest deliveries. |
POST /api/v1/alerts | alerts_create | admin | Create an alert rule for a supported usage or run metric. |
PATCH /api/v1/alerts/{alert_id} | alerts_update | admin | Change an alert rule using its current revision. |
DELETE /api/v1/alerts/{alert_id} | alerts_delete | admin | Delete an alert rule using its current revision. |
POST /api/v1/alerts/{alert_id}/acknowledge | alerts_acknowledge | admin | Acknowledge an uncertain delivery so the alert rule can fire again. Check the delivery before acknowledging it. |
GET /api/v1/alert-destinations | alert_destinations_get | viewer | Read configured alert destinations without exposing their credentials. |
PATCH /api/v1/alert-destinations | alert_destinations_update | admin | Set or clear the Slack webhook or PagerDuty routing key using the current revision. |
Retention and audit history
Read workspace settings to see the current retention policy before changing it. Send the current expected version when updating retention to avoid overwriting another administrator’s change. Outputs removed by retention cannot be treated as pending; check their state when reviewing older runs.
Transcripts, metadata, context and tool outputs can contain personal information. The customer remains the authority for business records, but that does not make platform conversation data anonymous. Review the actual deployment's retention and privacy guarantees before using sensitive records.
Use the audit log to review workspace activity. Agent run transcripts, tool receipts and event timelines remain in the run API; the audit log does not replace those records.
| Operation | MCP tool | Key role | Purpose |
|---|---|---|---|
GET /api/v1/tenant/settings | tenant_settings_get | viewer | Read the organization’s display name and retention policy. |
PUT /api/v1/tenant/settings | tenant_settings_update | admin | Change the display name or retention policy. Retention updates check the policy version you last read. |
GET /api/v1/audit | audit_list | admin | Read workspace activity from the audit log. |
Security logs and incident assistance
Workspace activity is available through the audit API. Use a key or signed-in account belonging to the workspace you are investigating. Audit access does not grant access to another customer's workspace. Run events, tool receipts and recording availability are documented under Investigate runs; these records have different retention rules from security logs.
For an incident, contact cygnus@cumuluslabs.io and copy veer@cumuluslabs.io. Include your workspace ID, the UTC time range, affected run or operation IDs, and the suspected issue. Do not email passwords, API keys, card numbers, security codes, recordings or full transcripts. Cumulus verifies the requesting person's workspace authority before sharing customer-specific evidence through an authenticated, access-restricted channel.
Cumulus provides incident-response assistance and appropriately scoped security-log extracts on request. Cygnus and Veer provide 24-hour coverage; critical alerts have a 15-minute acknowledgment target. An acknowledgment is not a recovery commitment: the service recovery targets are six hours RTO and 24 hours RPO. Requests for evidence preservation should be made promptly and identify the affected records and time window.
The security-log retention standard is at least 100 days searchable and 400 days retained. The available history begins when each source was enrolled; logs from before enrollment cannot be reconstructed. Security logging is enabled by the service and does not require a customer to activate it. Infrastructure and third-party logs are reviewed by authorized Cumulus responders and filtered to the requesting customer's scope; raw shared infrastructure logs are not exposed to customers. If a requested source or period is unavailable, Cumulus identifies the gap rather than supplying an incomplete export as a complete record.