{ "openapi": "3.1.0", "info": { "title": "Cleo Public API", "version": "1.0.0", "description": "Cleo task-owned outbound calling, phone-verified bot onboarding, and public health checks. Read https://docs.cleopowered.com for durable acceptance, protected input, authentication, recovery, and limitations." }, "paths": { "/v1/calls": { "post": { "tags": [ "calls" ], "summary": "Create Call", "operationId": "create_call_v1_calls_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Save one key per intended call. Reuse it with the identical payload to recover an uncertain request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallCreate" } } } }, "responses": { "202": { "description": "Durably accepted task/call, or the existing record for an identical idempotent retry. Dialing may not have started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallView" } } } }, "400": { "description": "Missing idempotency key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "401": { "description": "Invalid, expired, or revoked API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "403": { "description": "Calling disabled or Agent Project inactive", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "409": { "description": "Idempotency conflict or managed assistant unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "422": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "502": { "description": "Upstream request failed; inspect detail before retrying", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "503": { "description": "Calling service unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "Retry-After": { "description": "Minimum seconds to wait before another request.", "schema": { "type": "integer", "minimum": 1 } } } }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "description": "Payment Required" } }, "description": "Durably admit one approved task and call. Persisted work is acknowledged with HTTP 202; it is not proof of dialing. Save id and task_id and inspect execution alongside state. Requires a separate saved project-scoped idempotency key and unchanged complete request, including protected_context. Identical retries return the same task/call; changed content conflicts. If the ID is known, poll it. Never create a new task/call/key to recover a timeout." } }, "/v1/calls/{call_id}": { "get": { "tags": [ "calls" ], "summary": "Get Call", "operationId": "get_call_v1_calls__call_id__get", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Call Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallView" } } } }, "422": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "401": { "description": "Invalid, expired, or revoked API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "403": { "description": "Calling disabled or Agent Project inactive", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "Retry-After": { "description": "Minimum seconds to wait before another request.", "schema": { "type": "integer", "minimum": 1 } } } }, "502": { "description": "Upstream request failed; inspect detail before retrying", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "503": { "description": "Calling service unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "404": { "description": "Call not found in this Agent Project", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "409": { "description": "Idempotency conflict or managed assistant unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } } }, "description": "Read saved call state only; this does not refresh the calling service. Use POST on the sync subroute for current progress. Requires no request body or Idempotency-Key." } }, "/v1/calls/{call_id}/sync": { "post": { "tags": [ "calls" ], "summary": "Sync Call", "operationId": "sync_call_v1_calls__call_id__sync_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Call Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallView" } } } }, "422": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "401": { "description": "Invalid, expired, or revoked API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "403": { "description": "Calling disabled or Agent Project inactive", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "Retry-After": { "description": "Minimum seconds to wait before another request.", "schema": { "type": "integer", "minimum": 1 } } } }, "502": { "description": "Upstream request failed; inspect detail before retrying", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "503": { "description": "Calling service unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "404": { "description": "Call not found in this Agent Project", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "409": { "description": "Idempotency conflict or managed assistant unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } } }, "description": "Refresh the same call when eligible and return saved task/execution progress. Undispatched and recovering jobs return local state without another originate. Sync cannot bypass a paused bounded recovery; reconciliation_required needs operator review. Terminal sync may retry failed result extraction without dialing." } }, "/v1/calls/{call_id}/cancel": { "post": { "tags": [ "calls" ], "summary": "Cancel Call", "operationId": "cancel_call_v1_calls__call_id__cancel_post", "security": [ { "HTTPBearer": [] } ], "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Call Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallView" } } } }, "422": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "401": { "description": "Invalid, expired, or revoked API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "403": { "description": "Calling disabled or Agent Project inactive", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } }, "headers": { "Retry-After": { "description": "Minimum seconds to wait before another request.", "schema": { "type": "integer", "minimum": 1 } } } }, "502": { "description": "Upstream request failed; inspect detail before retrying", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "503": { "description": "Calling service unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "404": { "description": "Call not found in this Agent Project", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } }, "409": { "description": "Idempotency conflict or managed assistant unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetail" } } } } }, "description": "Cancel an undispatched queued job locally, or request cancellation of a call whose dispatch may have started. HTTP 200 returns current state, not proof of hangup. execution.stage remains cancel_requested until terminal confirmation. A natural completion can race cancellation; report the confirmed outcome. reconciliation_required needs operator review, not redial." } }, "/health": { "get": { "tags": [ "system" ], "summary": "Health", "operationId": "health_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Response Health Health Get" } } } } }, "security": [], "description": "Gateway liveness only. Does not authenticate a key, check calling permissions, or place a call." } }, "/health/ready": { "get": { "tags": [ "system" ], "summary": "Readiness", "operationId": "readiness_health_ready_get", "responses": { "200": { "description": "Gateway readiness checks succeeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "degraded" ] }, "components": { "type": "object", "properties": { "configuration": { "type": "boolean" }, "control_plane": { "type": "boolean" }, "control_plane_status": { "type": "string" }, "configuration_error": { "type": "string" }, "control_plane_error": { "type": "string" } }, "required": [ "configuration", "control_plane" ], "additionalProperties": true } }, "required": [ "status", "components" ] } } } }, "503": { "description": "Gateway configuration or upstream readiness request unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "degraded" ] }, "components": { "type": "object", "properties": { "configuration": { "type": "boolean" }, "control_plane": { "type": "boolean" }, "control_plane_status": { "type": "string" }, "configuration_error": { "type": "string" }, "control_plane_error": { "type": "string" } }, "required": [ "configuration", "control_plane" ], "additionalProperties": true } }, "required": [ "status", "components" ] } } } } }, "security": [], "description": "Checks gateway credential configuration and reachability of internal API readiness. Does not establish live-call enablement, account permissions, or carrier readiness. Both 200 and 503 responses are application/json status objects." } }, "/v1/onboarding/start": { "post": { "tags": [ "onboarding" ], "summary": "Onboarding Start", "operationId": "onboarding_start_v1_onboarding_start_post", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "title": "Idempotency-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingStart" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingView" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/onboarding/resend": { "post": { "tags": [ "onboarding" ], "summary": "Onboarding Resend", "operationId": "onboarding_resend_v1_onboarding_resend_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneStatus" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/onboarding/verify": { "post": { "tags": [ "onboarding" ], "summary": "Onboarding Verify", "operationId": "onboarding_verify_v1_onboarding_verify_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneVerify" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneStatus" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/v1/onboarding/complete": { "post": { "tags": [ "onboarding" ], "summary": "Onboarding Complete", "operationId": "onboarding_complete_v1_onboarding_complete_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingKey" } } } } }, "security": [ { "HTTPBearer": [] } ] } } }, "components": { "schemas": { "CallCreate": { "additionalProperties": false, "properties": { "to": { "maxLength": 16, "minLength": 9, "pattern": "^\\+[1-9][0-9]{7,14}$", "title": "To", "type": "string" }, "objective": { "maxLength": 4000, "minLength": 1, "title": "Objective", "type": "string" }, "context": { "additionalProperties": true, "title": "Context", "type": "object", "description": "Provider-bound background information. Use protected_context for private answers that must be withheld; ordinary free text is not a protected-secret channel." }, "protected_context": { "additionalProperties": { "format": "password", "type": "string", "writeOnly": true, "minLength": 1, "maxLength": 2000 }, "maxProperties": 20, "title": "Protected Context", "type": "object", "propertyNames": { "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "description": "Optional named answers stored encrypted and withheld from the voice flow. At most 20 fields; each value contains 1-2000 characters, with combined UTF-8 value bytes at most 16384. Matching values are redacted from ordinary task/context and admitted snapshots. No automatic recipient disclosure. Do not submit passwords, card PINs, or one-time codes. Preserve these values privately as part of the unchanged idempotency payload." }, "constraints": { "items": { "type": "string", "maxLength": 500 }, "maxItems": 50, "title": "Constraints", "type": "array" }, "success_criteria": { "items": { "type": "string", "maxLength": 500 }, "maxItems": 50, "title": "Success Criteria", "type": "array" }, "result_schema": { "additionalProperties": true, "title": "Result Schema", "type": "object", "description": "Required JSON Schema for requested answers. Cleo attempts recipient-evidence-backed extraction after the call and validates candidates against this schema. Missing required information or failed validation can leave result null. Nullable unknowns may yield a schema-valid incomplete result; read result_extraction." }, "limits": { "$ref": "#/components/schemas/CallLimits" } }, "required": [ "to", "objective", "result_schema" ], "title": "CallCreate", "type": "object" }, "CallLimits": { "additionalProperties": false, "properties": { "max_duration_seconds": { "default": 300, "maximum": 3600, "minimum": 30, "title": "Max Duration Seconds", "type": "integer" } }, "title": "CallLimits", "type": "object" }, "CallView": { "properties": { "id": { "format": "uuid", "title": "Id", "type": "string", "description": "Stable call ID used by get, sync, and cancel." }, "task_id": { "format": "uuid", "title": "Task Id", "type": "string", "description": "Owning durable task ID. Existing call routes take id, not task_id." }, "execution": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Execution", "description": "Durable dispatch/cancellation progress: stage and nullable error_code. Stages: queued, submitting, reconciling, running, cancel_requested, cancelled, failed, completed. Null for historical calls without a job. submission_unconfirmed/cancellation_unconfirmed indicate unresolved gateway acknowledgement; reconciliation_required means bounded automatic recovery paused for operator review. Keep the same IDs and never redial to resolve uncertainty." }, "state": { "enum": [ "queued", "dialing", "ringing", "in_progress", "completed", "failed", "cancelled" ], "title": "State", "type": "string" }, "to": { "title": "To", "type": "string" }, "objective": { "title": "Objective", "type": "string" }, "caller_identity": { "$ref": "#/components/schemas/CallerIdentity", "description": "Server-owned profile identity of the verified API-key workspace owner, frozen at call creation. Legacy calls may have name null. Not accepted in create requests." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary", "description": "Automatically prepared evidence-based conversation summary, or null while pending or unavailable. When unavailable after completion, transcript contains available speaker-labeled conversation turns." }, "transcript": { "items": { "$ref": "#/components/schemas/TranscriptSegment" }, "title": "Transcript", "type": "array", "description": "Available diarized conversation when a terminal call has no summary; otherwise empty. No captured evidence means an empty array." }, "result": { "title": "Result", "description": "Published JSON extracted from recipient evidence under the requested schema, including possible scalar or array roots. Null while unavailable or withheld; a schema-valid null root may be incomplete. Provider diagnostics are not returned as a substitute." }, "result_schema_valid": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Result Schema Valid", "description": "True for a current validated published candidate; null if validation/publication is unavailable. This is not proof of factual accuracy or successful real-world action." }, "result_extraction": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Result Extraction", "description": "Extraction status, missing_fields as JSON Pointers, recipient evidence {path, sequence, quote}, and bounded issues. Processing may be pending, complete, incomplete, unavailable, or invalid. Missing answers remain missing; a schema-valid result can still be incomplete." }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Started At" }, "completed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completed At" } }, "required": [ "id", "task_id", "state", "to", "objective", "summary", "result", "result_schema_valid", "created_at", "started_at", "completed_at" ], "title": "CallView", "type": "object" }, "ProblemDetail": { "properties": { "type": { "type": "string", "title": "Type", "default": "about:blank" }, "title": { "type": "string", "title": "Title" }, "status": { "type": "integer", "title": "Status" }, "detail": { "type": "string", "title": "Detail" }, "code": { "type": "string", "title": "Code" }, "action_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Action Url" }, "retryable": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Retryable" } }, "type": "object", "required": [ "title", "status", "detail", "code" ], "title": "ProblemDetail" }, "TranscriptSegment": { "properties": { "sequence": { "title": "Sequence", "type": "integer" }, "speaker": { "enum": [ "assistant", "recipient", "system", "unknown" ], "title": "Speaker", "type": "string" }, "text": { "title": "Text", "type": "string" } }, "required": [ "sequence", "speaker", "text" ], "title": "TranscriptSegment", "type": "object" }, "CallerIdentity": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" } }, "title": "CallerIdentity", "type": "object" }, "OnboardingKey": { "properties": { "api_key": { "type": "string", "title": "Api Key" }, "project_id": { "type": "string", "format": "uuid", "title": "Project Id" }, "workspace_id": { "type": "string", "format": "uuid", "title": "Workspace Id" }, "login_url": { "type": "string", "title": "Login Url" }, "recharge_url": { "type": "string", "title": "Recharge Url" }, "password_setup_email": { "type": "string", "const": "requested", "title": "Password Setup Email" } }, "type": "object", "required": [ "api_key", "project_id", "workspace_id", "login_url", "recharge_url", "password_setup_email" ], "title": "OnboardingKey" }, "OnboardingStart": { "properties": { "name": { "type": "string", "maxLength": 160, "minLength": 1, "title": "Name" }, "email": { "type": "string", "maxLength": 320, "minLength": 3, "title": "Email" }, "phone_number": { "type": "string", "maxLength": 40, "minLength": 1, "title": "Phone Number" }, "organization": { "anyOf": [ { "type": "string", "maxLength": 160 }, { "type": "null" } ], "title": "Organization" }, "client_name": { "type": "string", "maxLength": 80, "minLength": 1, "title": "Client Name", "default": "Personal bot" }, "acceptable_use_accepted": { "type": "boolean", "const": true, "title": "Acceptable Use Accepted" } }, "additionalProperties": false, "type": "object", "required": [ "name", "email", "phone_number", "acceptable_use_accepted" ], "title": "OnboardingStart" }, "OnboardingView": { "properties": { "onboarding_token": { "type": "string", "title": "Onboarding Token" }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At" }, "phone": { "$ref": "#/components/schemas/PhoneStatus" } }, "type": "object", "required": [ "onboarding_token", "expires_at", "phone" ], "title": "OnboardingView" }, "PhoneStatus": { "properties": { "verified": { "type": "boolean", "title": "Verified" }, "phone_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number" }, "challenge_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Challenge Id" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires At" }, "resend_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Resend At" } }, "type": "object", "required": [ "verified" ], "title": "PhoneStatus" }, "PhoneVerify": { "properties": { "challenge_id": { "type": "string", "format": "uuid", "title": "Challenge Id" }, "code": { "type": "string", "pattern": "^[0-9]{6}$", "title": "Code" } }, "additionalProperties": false, "type": "object", "required": [ "challenge_id", "code" ], "title": "PhoneVerify" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } }, "servers": [ { "url": "https://api.cleolabs.com" } ] }