Skip to content
cleo.Developers
Build reliably/Safety & permissions
Cleo documentation

Safety & permissions

How Cleo evaluates a call task before it can dial.

Content reviewed · Maintained by Cleo Powered · Report a documentation issue · Verification basis

Cleo identifies itself as an AI assistant calling on behalf of the verified owner of the workspace associated with your API key. The profile name is supplied automatically as caller_identity.name; do not supply caller identity in the request or task context. This identity does not prove permission to access a third-party account.

Purpose screening

Before execution, Cleo’s LLM safety layer evaluates the destination, objective, context, constraints, success criteria, requested output, and duration. API keys use the same purpose evaluator as the customer platform.

Decision
allowed
Outcome
The call can proceed to the remaining checks.
Decision
blocked
Outcome
The call cannot proceed.
Decision
review
Outcome
The call cannot proceed; the purpose or authorization needs clarification.

Missing safety configuration, timeouts, invalid model output, and authorization-signing failures stop the request. An allowed decision produces a signed authorization tied to the task, which the calling service verifies before dialing.

Calling permissions

A valid API key is necessary, but a call also needs an available assistant, workspace calling permission, and enabled service-level calling. Admission reserves allowed usage; the executor rechecks revocable caller, workspace, assistant, API-key, policy, and purpose authority before dispatch. An accepted queued job can fail if permission is withdrawn before dialing.

Public API calling has an independent service switch. Platform calls can work while API calls return live_calls_disabled. Contact your service operator if this happens; changing your task will not enable the switch.

Protected context

Ordinary context supplies facts to the calling model. Send private answers that must be withheld in protected_context: an object of named strings with the documented limits. Cleo stores these answers encrypted and redacts matching values from task prose, ordinary context, and execution snapshots before provider submission.

The current voice flow does not automatically disclose protected values to a recipient. Do not put passwords, card PINs, or one-time codes in this field or ordinary task text. Do not promise that an identity check requiring a withheld value will succeed. Redaction targets supplied protected values; it does not identify every private fact in free text. Protect the original payload in your storage, including during idempotency recovery.

Write a clear task

  • Explain the legitimate purpose and your relationship to the recipient.
  • Include only the information needed to complete the call.
  • State what Cleo may do and what requires further approval.
  • Ask the assistant to identify itself appropriately and stop if the recipient declines.

Fraud, impersonation, harassment, nuisance calls, unsolicited marketing, and other prohibited uses can be blocked. A test_call label supplies context; it does not bypass screening.

The API currently returns some safety and workspace failures as 502 control_plane_error, with the explanation in detail. Read that explanation before deciding whether to retry.

Documentation
Get an API key

Explore the docs

IntroductionSubmit a phone errand, follow the call, and inspect its outcome.Bot account onboardingRegister from Muse or another bot, verify your phone, receive an API key, and set your dashboard password by email.API overviewWhich endpoints are available, how they authenticate, and what is supported today.Make your first callCall your own phone, refresh its status, and inspect the returned call data.AuthenticationCreate a key in Cleo and authenticate requests with a bearer token.Create a callQueue one bounded phone task and receive durable task and call IDs.Get a callRead the most recently saved state of a call.Sync a callRefresh a call from the calling service and retrieve its latest saved state.Cancel a callCancel queued work or request a stop, then follow confirmation.The call objectThe shared response returned by create, get, sync, and cancel.Health checksCheck API liveness and readiness without an API key or placing a call.Results & schemasUnderstand result_schema, returned metadata, and what result_schema_valid does and does not establish.Task and call lifecycleFollow a call from acceptance to its final outcome.Idempotency & retriesRecover from an interrupted request without accidentally placing a second call.Safety & permissionsHow Cleo evaluates a call task before it can dial.Errors & troubleshootingUnderstand API errors and choose a safe next step.LimitsKeep call tasks bounded and leave room for API rate limits.Verification & limitationsReproduce our public health and schema checks and understand what has not been tested.Bot integrationsChoose a route for connecting your assistant to Cleo's public API.ChatGPTConfigure a private GPT Action with Cleo OpenAPI and bearer authentication.ClaudeConnect Claude client tools or a Claude Code shell workflow.Grok & Grok BotConnect xAI function tools and check Grok Bot execution requirements.OpenClawInstall a local skill for an approved Cleo calling workflow.GeminiMap Gemini function declarations to Cleo REST operations.Copilot StudioAdd Cleo through a REST API tool, custom connector, or flow.n8nBuild an authenticated HTTP workflow with durable call recovery.ZapierBuild a private Zapier integration for approved Cleo calls.