API · v1

The Call0 API.

Retrieve calls, manage agents, receive results via webhook, and control enabled outbound workflows through a focused REST API.

Introduction

All endpoints use the base URL https://www.call0.ai/api/v1. Requests and responses are JSON (Content-Type: application/json). Every resource is limited to the account associated with your API key.

Authentication

Create API keys in the dashboard under Developer. Keys begin with ck_live_, are shown once, and use either the read or write scope.

curl https://www.call0.ai/api/v1/calls \
  -H "Authorization: Bearer ck_live_yourKey"

An invalid key returns 401; an insufficient scope returns 403.

List calls

GET/v1/calls

Lists calls for your account, newest first. Scope: read.

Field	Type	Description
limit	integer	Items per page, max. 100 (default 20).
offset	integer	Pagination offset (default 0).
agent_id	string	Optional: only calls for this agent.

curl "https://www.call0.ai/api/v1/calls?limit=2" \
  -H "Authorization: Bearer ck_live_…"

Response · 200

{
  "calls": [{
    "id": "3af91e9e-…",
    "agent_id": "23061e5a-…",
    "direction": "inbound",
    "status": "completed",
    "duration_seconds": 216,
    "summary": "Table reservation for four people on Friday at 7 PM.",
    "callback_requested": false
  }],
  "limit": 2,
  "offset": 0
}

Retrieve a call

GET/v1/calls/{id}

Returns one call with its complete transcript. Scope: read. A missing call or a call owned by another account returns 404.

curl https://www.call0.ai/api/v1/calls/3af91e9e-… \
  -H "Authorization: Bearer ck_live_…"

Start a call (outbound)

POST/v1/calls/outbound

Outbound calling requires an outbound agent and an enabled project dialer. A disabled dialer returns 409 outbound_disabled.

Starts an outgoing call. Scope: write. The agent_id may identify either the outbound agent or its inbound parent.

Field	Type	Description
agent_id	string	Required. Outbound agent or associated inbound agent ID.
to	string	Required. Destination number in E.164 format.
mode	string	Optional. Demo mode "1", "2", or "3" for this call only.
variables	object	Optional conversation variables; values may contain up to 200 characters.

curl -X POST https://www.call0.ai/api/v1/calls/outbound \
  -H "Authorization: Bearer ck_live_…" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"23061e5a-…","to":"+14155550120","mode":"2"}'

Retrieve progress through GET /v1/calls/{call_id} or receive the result via webhook. A missing caller ID returns 422.

Agents

GET/v1/agents

Lists account agents with their ID, name, role, language, and status.

POST/v1/agents

Field	Type	Description
name	string	Display name or company name used in the greeting.
system_prompt	string	Agent behavior and instructions.
greeting	string	Greeting or outbound opening line.
language	string	Language code such as de-DE, en-US, or fr-FR.
voice_id	string	Voice selected from the dashboard voice library.

Webhooks

Add webhook endpoints under Developer. After each completed conversation, Call0 sends a call.completed POST request to your URL.

{
  "event": "call.completed",
  "call": {
    "id": "3af91e9e-…",
    "status": "completed",
    "duration_seconds": 216,
    "summary": "…",
    "transcript": [ … ]
  }
}

Verify X-Call0-Signature as an HMAC-SHA256 of timestamp.body using your webhook secret. The timestamp is provided in X-Call0-Timestamp. Return a 2xx status and reject stale timestamps to prevent replay attacks.

Errors

Field	Type	Description
400	invalid_request	A required field is missing or malformed.
401	unauthorized	The API key is missing or invalid.
403	insufficient_scope	The key does not have the required scope.
404	not_found	The resource does not exist or belongs to another account.
422	unprocessable	The request is valid but cannot be completed.
5xx	server_error	Unexpected error; retry with backoff.

Errors use { "error": "…" } with the corresponding HTTP status. Questions? Contact us.