CumulusDocs
Open Studio
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.

OperationMCP toolKey rolePurpose
GET /api/v1/environmentsenvironments_listviewerList the organization’s production and sandbox environments. current identifies the environment selected by your key.
POST /api/v1/environments/sandboxenvironments_ensure_sandboxadminCreate 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:

RoleTypical use
ViewerRead-only reporting
MemberBuild agents and start runs
AdminManage 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.

OperationMCP toolKey rolePurpose
GET /api/v1/provider-keysprovider_keys_listviewerList metadata for your model-provider credentials. The response does not expose keys.
PUT /api/v1/provider-keys/{provider}provider_keys_putadminSet or rotate a model-provider credential. The provider validates it before storage.
DELETE /api/v1/provider-keys/{provider}provider_keys_deleteadminRevoke 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/keyskeys_listadminList API key metadata. Key secrets are never returned.
POST /api/v1/keyskeys_createadminCreate 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_revokeadminRevoke an API key. Future access is refused, including queued effects authorized by that key.
POST /api/v1/keys/{key_id}/rotatekeys_rotateadminReplace 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.

OperationMCP toolKey rolePurpose
GET /api/v1/secretssecrets_listviewerList secret names, kinds and versions. Secret values are never returned.
PUT /api/v1/secrets/{secret_id}secrets_putadminCreate 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_deleteadminDelete a secret and all its versions.
GET /api/v1/teamteam_listviewerList workspace members and pending invitations.
POST /api/v1/team/invitationsteam_inviteadminInvite a person to join the workspace with a selected role.
DELETE /api/v1/team/invitations/{invitation_id}team_invite_revokeadminRevoke a pending invitation.
POST /api/v1/team/invitations/{invitation_id}/resendteam_invite_resendadminResend a pending invitation with a new link and expiry.
DELETE /api/v1/team/members/{user_id}team_removeadminRemove a member’s workspace access.
PATCH /api/v1/team/members/{user_id}team_set_roleadminChange 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.

OperationMCP toolKey rolePurpose
GET /api/v1/usageusage_summaryviewerRead 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/budgetbudgets_getviewerRead the spending cap and metered spend. configured: false means metered pricing has not been installed.
PUT /api/v1/usage/budgetbudgets_updateadminSet the spending cap using the current policy revision. Metered pricing must be configured first.
GET /api/v1/usage/rate-cardusage_rate_cardviewerRead your environment’s active rates. configured: false means metered pricing has not been installed.
GET /api/v1/telephony/call-limitcall_limits_getviewerRead the daily outbound call limit and the calls placed in the last 24 hours.
PUT /api/v1/telephony/call-limitcall_limits_updateadminSet 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.

OperationMCP toolKey rolePurpose
GET /api/v1/alertsalerts_listviewerList alert rules and their latest deliveries.
POST /api/v1/alertsalerts_createadminCreate an alert rule for a supported usage or run metric.
PATCH /api/v1/alerts/{alert_id}alerts_updateadminChange an alert rule using its current revision.
DELETE /api/v1/alerts/{alert_id}alerts_deleteadminDelete an alert rule using its current revision.
POST /api/v1/alerts/{alert_id}/acknowledgealerts_acknowledgeadminAcknowledge an uncertain delivery so the alert rule can fire again. Check the delivery before acknowledging it.
GET /api/v1/alert-destinationsalert_destinations_getviewerRead configured alert destinations without exposing their credentials.
PATCH /api/v1/alert-destinationsalert_destinations_updateadminSet 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.

OperationMCP toolKey rolePurpose
GET /api/v1/tenant/settingstenant_settings_getviewerRead the organization’s display name and retention policy.
PUT /api/v1/tenant/settingstenant_settings_updateadminChange the display name or retention policy. Retention updates check the policy version you last read.
GET /api/v1/auditaudit_listadminRead 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.

Content version 4e632851Customer SDKMarkdown source
Workspace and access · Cumulus developer docs