Cleo Agent API overview

Access and contract

The Cleo Agent API lets an approved external agent submit one bounded call, receive its durable identifier, inspect or synchronize state, cancel it, and read a schema-checked result. Access requires an active Agent Project, a revocable API key, a configured managed agent, and a workspace approved for production calling.

Create a call

Send POST /v1/calls with a bearer project key and a unique Idempotency-Key. The destination must use E.164 format. The result schema must be valid JSON Schema. The request format accepts a duration from 30 to 3,600 seconds, but the active workspace entitlement applies a lower ceiling: currently 180 seconds for Free or pay-as-you-go and 600 seconds for Pro. Reusing the same key and body returns the same call; reusing it with a different body returns 409 Conflict.

curl -X POST https://api.cleolabs.com/v1/calls \
  -H "Authorization: Bearer <project-api-key>" \
  -H "Idempotency-Key: <unique-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15555550123",
    "objective": "Ask for the business opening hours on Friday.",
    "context": {"timezone": "America/New_York"},
    "constraints": ["Identify yourself as an AI assistant.", "Do not make a reservation."],
    "success_criteria": ["Return Friday opening and closing times."],
    "result_schema": {
      "type": "object",
      "properties": {
        "opens_at": {"type": "string"},
        "closes_at": {"type": "string"}
      },
      "required": ["opens_at", "closes_at"],
      "additionalProperties": false
    },
    "limits": {"max_duration_seconds": 300}
  }'

A valid request is accepted with HTTP 202 and a resource shaped like this:

{
  "id": "0f6f3d6e-3a9e-4aba-a7fc-875ac5c40274",
  "state": "queued",
  "to": "+15555550123",
  "objective": "Ask for the business opening hours on Friday.",
  "summary": null,
  "result": null,
  "result_schema_valid": null,
  "created_at": "2026-09-03T12:00:00Z",
  "started_at": null,
  "completed_at": null
}

Read, synchronize, and cancel

GET  /v1/calls/{call_id}
POST /v1/calls/{call_id}/sync
POST /v1/calls/{call_id}/cancel

Read returns the most recently stored state. Sync explicitly refreshes a non-terminal call from the private telephony gateway. Cancel is idempotent and returns the existing terminal resource if a call already ended. Public states are queued, dialing, ringing, in_progress,completed, failed, and cancelled.

Safety and failure behavior

A request cannot select an internal prompt, voice, provider, caller ID, or telephony credential. Cleo validates the destination, output schema, policy limits, workspace status, and call purpose before dialing. Unsafe or ambiguous purposes fail closed. Operational failures use problem-style JSON with a stable error code and can include invalid credentials, inactive access, conflicting idempotency keys, rejected calls, unavailable safety screening, or telephony dependency errors.

Exact rate and spend limits are deployment-specific and are communicated during access approval. Optional x402 payment authorization is planned and not part of the current public contract.