Authentication

API keys and Bearer token authentication.

API Keys

All API requests require a Bearer token in the Authorization header. API keys are prefixed with ac_live_ or ac_test_.

Authorization: Bearer ac_live_7f8a9b2c...

Getting a Key

There are two ways to obtain an API key:

1. Dashboard — Sign up at agenticcalling.ai/dashboard and create a key from the API Keys page.
2. Register endpoint — POST /v1/auth/register creates an organization and returns a one-time API key.

Key Management

Each organization can have multiple active API keys. Use GET /v1/auth/api-keys to list them, POST /v1/auth/api-keys to create new ones, and DELETE /v1/auth/api-keys/{key_id} to revoke.

Usage Warning Headers

Every API response may include an X-AC-Usage-Warning header when usage is high:

Core Concepts

Understand how AgenticCalling works under the hood.

Resource Hierarchy

Organization (top-level container)
├── PhoneLine (+1-415-555-0142)
│   ├── Call (outbound to +1-415-555-1234)
│   │   ├── Recording (audio file)
│   │   └── Transcript (structured text + extracted data)
│   ├── Conversation (groups related calls)
│   └── SMS Thread (text messages — coming soon)
├── Playbook (reusable call strategies)
├── Persona (reusable caller identities)
└── Pod (multi-tenant isolation)

Calls

A Call is an individual phone conversation. Every call has an objective (what to accomplish), follows a lifecycle managed by the platform, and produces a recording, transcript, and structured data.

Call Lifecycle

Objectives

The objective tells the call LLM what to accomplish. It should be specific and outcome-oriented:

• Good: "Book a table for 6 at 8pm this Friday. If 8pm unavailable, anything between 7:30-9pm works. Name: Alex Chen."
• Bad: "Make a reservation"

Playbooks

A Playbook is a reusable conversation strategy. Different call types (negotiation, reservation, outreach) use fundamentally different approaches. See the Playbooks section for details.

Personas

A Persona is a reusable caller identity — name, company, role, voice, and default behavior rules. See Personas.

Data Extraction

After every call, the platform extracts structured JSON data from the transcript automatically. You can define custom extraction schemas in playbooks. See Data Extraction.

Pods

A Pod provides multi-tenant isolation for SaaS platforms building on AgenticCalling. All resources within a Pod are invisible to other Pods.

call = client.calls.create(
    to="+14155551234",
    objective="...",
    pod_id="customer_acme"  # Isolated to this tenant
)

Calls API

Create, retrieve, and manage phone calls.

Base URL: https://api.agenticcalling.ai/v1

curl -X POST https://api.agenticcalling.ai/v1/calls \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "objective": "Get bulk pricing for 500 steel beams",
    "context": "We are Acme Corp. Budget is $50-60 per unit.",
    "voice": "professional_male_en",
    "behavior_rules": ["Never agree to price above $60/unit"],
    "client_id": "steel-inquiry-v1"
  }'

{
  "id": "01HXYZ...",
  "organization_id": "01HABC...",
  "to_number": "+14155551234",
  "objective": "Get bulk pricing for 500 steel beams",
  "status": "queued",
  "attempt_number": 1,
  "max_attempts": 3,
  "language": "en",
  "max_duration_minutes": 30,
  "structured_data": null,
  "summary": null,
  "duration_seconds": null,
  "cost": null,
  "created_at": "2026-03-26T10:00:00Z",
  "updated_at": "2026-03-26T10:00:00Z"
}

curl https://api.agenticcalling.ai/v1/calls/01HXYZ... \
  -H "Authorization: Bearer ac_live_..."

{
  "id": "01HXYZ...",
  "status": "completed",
  "duration_seconds": 252,
  "cost": 0.42,
  "attempt_number": 2,
  "structured_data": {
    "quoted_price": 52.00,
    "currency": "USD",
    "moq": 100,
    "lead_time_days": 14,
    "payment_terms": "Net 30",
    "contact_name": "Mike Chen"
  },
  "summary": "Supplier quoted $52/unit, 14-day lead time, Net 30 terms.",
  "recording_url": "/v1/calls/01HXYZ.../recording",
  "transcript": [
    {"speaker": "agent", "text": "Hi, this is Alex from Acme Corp..."},
    {"speaker": "human", "text": "Sure, how many units?"}
  ]
}

curl "https://api.agenticcalling.ai/v1/calls?status=completed&limit=10" \
  -H "Authorization: Bearer ac_live_..."

// Array of call objects
[
  { "id": "01HXYZ...", "status": "completed", ... },
  { "id": "01HABC...", "status": "completed", ... }
]
// Header: X-Next-Page-Token: eyJ...

curl -X POST https://api.agenticcalling.ai/v1/calls/batch \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [
      {"to": "+14155551111", "context": "Shenzhen Metals Co"},
      {"to": "+14155552222", "context": "Guangzhou Supply Ltd"},
      {"to": "+14155553333", "context": "Dongguan PhoneTech"}
    ],
    "objective": "Get steel beam pricing quote for 500 units",
    "playbook_id": "platform.price_inquiry"
  }'

{
  "batch_id": "batch_01HXYZ...",
  "total": 3,
  "calls": [
    { "id": "01H...", "status": "queued", "to_number": "+14155551111" },
    { "id": "01H...", "status": "queued", "to_number": "+14155552222" },
    { "id": "01H...", "status": "queued", "to_number": "+14155553333" }
  ]
}

curl https://api.agenticcalling.ai/v1/calls/batch/batch_01HXYZ... \
  -H "Authorization: Bearer ac_live_..."

{
  "batch_id": "batch_01HXYZ...",
  "total": 3,
  "statuses": { "completed": 2, "exhausted": 1 },
  "calls": [ /* array of full call objects */ ]
}

curl -L https://api.agenticcalling.ai/v1/calls/01HXYZ.../transcript \
  -H "Authorization: Bearer ac_live_..."

curl -L https://api.agenticcalling.ai/v1/calls/01HXYZ.../recording \
  -H "Authorization: Bearer ac_live_..."

curl -X DELETE https://api.agenticcalling.ai/v1/calls/01HXYZ.../cancel \
  -H "Authorization: Bearer ac_live_..."

{
  "id": "01HXYZ...",
  "status": "cancelled",
  ...
}

Auth & API Keys

Registration, API key management, and billing.

Base URL: https://api.agenticcalling.ai/v1

curl -X POST https://api.agenticcalling.ai/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "email": "dev@acme.com"}'

{
  "org_id": "01HABC...",
  "api_key": "ac_live_7f8a9b2c...",
  "message": "Store this key — it won't be shown again"
}

[
  {
    "id": "01HKEY...",
    "name": "Production",
    "key_prefix": "ac_live_",
    "is_active": true,
    "created_at": "2026-03-01T00:00:00Z",
    "last_used_at": "2026-03-26T12:00:00Z"
  }
]

{
  "id": "01HKEY...",
  "api_key": "ac_live_...",
  "name": "Production",
  "message": "Store this key — it won't be shown again"
}

curl -X DELETE https://api.agenticcalling.ai/v1/auth/api-keys/01HKEY... \
  -H "Authorization: Bearer ac_live_..."

{ "updated": true }

{ "url": "https://billing.stripe.com/session/..." }

{ "url": "https://checkout.stripe.com/..." }

Usage & Billing

Monitor your usage, billing, and plan limits.

curl https://api.agenticcalling.ai/v1/usage \
  -H "Authorization: Bearer ac_live_..."

{
  "organization_id": "01HABC...",
  "plan": "free",
  "minutes_used_this_month": 3.5,
  "minutes_limit": 5.0,
  "minutes_remaining": 1.5,
  "sms_sent_this_month": 4,
  "sms_limit": 10,
  "sms_remaining": 6,
  "billing_reset_at": "2026-04-01T00:00:00Z",
  "concurrent_calls_limit": 3,
  "cost": {
    "total_spend_usd": 4.20,
    "total_calls_billed": 15,
    "total_seconds_billed": 1470,
    "rates_per_pipeline": {
      "gemini": { "platform_per_min": 0.036, "llm_per_min": 0.006, "total_per_min": 0.042 },
      "pipeline": { "platform_per_min": 0.036, "llm_per_min": 0.018, "total_per_min": 0.054 },
      "realtime": { "platform_per_min": 0.036, "llm_per_min": 0.300, "total_per_min": 0.336 }
    },
    "sms_rate_per_message_usd": 0.0095
  }
}

What Counts as Usage

Balance Behavior

Playbooks

Reusable conversation strategies for different types of calls.

A Playbook defines how a call should be conducted. Different call types require different approaches, extraction schemas, and success criteria.

Platform Playbooks (built-in)

Pre-built strategies that ship with the platform. Auto-selected based on the objective when no playbook is specified.

Custom Playbooks

Fork a platform playbook or create from scratch:

playbook = client.playbooks.create(
    name="Steel beam negotiation",
    base="platform.negotiation",
    strategy="""
        Build rapport first. Our target is $50/unit for 500 units.
        Walk-away ceiling is $58. We have a competing quote at $53.
        Always ask for bulk discount and payment terms.
    """,
    behavior_rules=[
        "Never agree to price above $58/unit",
        "Never disclose our current supplier",
        "Always ask for a written quote",
    ],
    extraction_schema={
        "quoted_price": "number",
        "currency": "string",
        "moq": "number",
        "lead_time_days": "number",
        "payment_terms": "string",
    },
    voice_tone="Warm, professional, never pushy."
)

Auto-Classification

When no playbook_id is passed, the platform analyzes the objective and auto-selects the best playbook:

# No playbook specified — platform figures it out
call = client.calls.create(
    to="+14155551234",
    objective="Book a table for 4 at 7pm Saturday"
)
# Auto-selects platform.reservation

Playbook API

# Create
playbook = client.playbooks.create(name, strategy, base?, behavior_rules?, extraction_schema?, voice_tone?, success_criteria?)

# List
playbooks = client.playbooks.list()

# Update
client.playbooks.update(playbook_id, strategy?, behavior_rules?, extraction_schema?)

# Delete
client.playbooks.delete(playbook_id)

Creating Playbooks via Claude or ChatGPT

If you're using AgenticCalling through Claude or ChatGPT (via MCP), you don't need to write any code. Just ask conversationally:

Personas

Reusable caller identities for consistent representation.

A Persona is a reusable caller identity — name, company, role, voice, and default behavior rules. Instead of specifying who the agent should be on every call, create a Persona once and reference it.

persona = client.personas.create(
    name="Procurement Agent",
    caller_name="Alex",
    company="Acme Corp",
    role="Procurement specialist",
    voice="professional_male_en",
    language="en",
    default_rules=[
        "Always identify yourself as Alex from Acme Corp",
        "Never commit to purchases over $10,000 without approval",
    ]
)

# Use in calls
call = client.calls.create(
    to="+14155551234",
    persona_id=persona.persona_id,
    objective="Get steel beam pricing"
)
# Agent introduces itself as "Alex from Acme Corp"

Persona API

personas.create(name, caller_name, company?, role?, voice?, language?, default_rules?, client_id?)
personas.list(limit?, page_token?)
personas.get(persona_id)
personas.update(persona_id, caller_name?, company?, voice?, default_rules?)
personas.delete(persona_id)

Creating Personas via Claude or ChatGPT

No code needed — just describe who you want the caller to be:

Phone Numbers

Your AI agent's caller ID for outbound calls.

Automatic Provisioning

When you create your account, a US phone number is automatically provisioned for you — no setup required. This number is used as the caller ID for all outbound calls your AI agent makes.

Plan Limits

Provisioning Additional Lines

Need more numbers? Provision them via the API or ask Claude/ChatGPT:

curl -X POST https://api.agenticcalling.ai/v1/lines \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{"country": "US"}'

Response

{
  "id": "line_abc123",
  "phone_number": "+14155550142",
  "country": "US",
  "created_at": "2026-03-26T12:00:00Z"
}

Using a Specific Line

By default, the platform selects the best available line. To use a specific number as caller ID:

curl -X POST https://api.agenticcalling.ai/v1/calls \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "objective": "Schedule a demo",
    "from_line_id": "line_abc123"
  }'

Inbound Calls

Coming soon. Inbound call handling — where someone calls your AI agent's phone number — is currently in development.

Structured Data Extraction

Automatically extract structured JSON data from every conversation.

After every call, the platform runs an extraction pass on the full transcript using the playbook's extraction_schema. This produces clean, structured JSON that agents can immediately use for comparison, storage, or follow-up actions.

How It Works

1. Call completes and transcript is finalized
2. Platform runs extraction using the playbook's schema (or auto-generates one from the objective)
3. Structured data is attached to the call response in structured_data
4. A natural-language summary is also generated

Defining Extraction Schemas

playbook = client.playbooks.create(
    name="Supplier quote",
    strategy="Get pricing details for our order",
    extraction_schema={
        "quoted_price": "number",
        "currency": "string",
        "moq": "number",
        "lead_time_days": "number",
        "payment_terms": "string",
        "contact_name": "string",
        "willingness_to_negotiate": "high/medium/low",
        "next_steps": "string"
    }
)

Example Output

// result.structured_data
{
  "quoted_price": 52.00,
  "currency": "USD",
  "moq": 100,
  "lead_time_days": 14,
  "payment_terms": "Net 30",
  "contact_name": "Mike Chen",
  "willingness_to_negotiate": "medium",
  "next_steps": "Send PO to mike@supplier.com"
}

// result.summary
"Supplier quoted $52/unit for 500 steel beams, 14-day lead time, Net 30 terms. Contact: Mike Chen. Willing to negotiate on bulk orders."

Webhooks

Receive real-time notifications for call events.

Setup

webhook = client.webhooks.create(
    url="https://myapp.com/webhooks/agenticcalling",
    event_types=["call.completed", "call.exhausted", "call.dnc_requested"],
    client_id="my-webhook-v1"
)
# webhook.secret = "whsec_..." (for signature verification)

You can also set a per-call webhook:

call = client.calls.create(
    to="+14155551234",
    objective="...",
    webhook_url="https://myapp.com/webhooks/specific-call"
)

Call Events

SMS Events

Billing Events

Example: call.completed Payload

{
  "event_type": "call.completed",
  "event_id": "evt_01HXYZ...",
  "call": {
    "call_id": "call_01HXYZ...",
    "status": "completed",
    "duration_seconds": 252,
    "cost": 0.42,
    "attempts": 2,
    "structured_data": {
      "quoted_price": 52,
      "lead_time_days": 14
    },
    "summary": "Supplier quoted $52/unit, 14-day lead time",
    "transcript_url": "/v1/calls/call_.../transcript",
    "recording_url": "/v1/calls/call_.../recording"
  }
}

Verifying Signatures

Every webhook includes an X-AC-Signature header (HMAC-SHA256). Verify it with your webhook secret:

import hmac, hashlib

def verify_signature(headers, body, secret):
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(
        headers.get("X-AC-Signature", ""), expected
    )

Delivery & Retries

• Your endpoint must return 200 OK within 10 seconds
• Failed deliveries retried 3 times: 1 min, 5 min, 30 min
• Events stored for 7 days if all deliveries fail

WebSockets

Real-time streaming for live transcripts and call status updates.

WebSockets provide a persistent connection for real-time events during active calls. Build live dashboards and stream transcripts.

Connecting

const ws = new WebSocket(
  "wss://api.agenticcalling.ai/v1/ws?token=ac_live_..."
);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.event_type, data);
};

Filtering

// Stream events for a specific call
"wss://api.agenticcalling.ai/v1/ws?token=ac_...&call_id=call_01HXYZ"

// Stream events for a batch
"wss://api.agenticcalling.ai/v1/ws?token=ac_...&batch_id=batch_01HXYZ"

// Stream events for a PhoneLine
"wss://api.agenticcalling.ai/v1/ws?token=ac_...&line_id=line_01HXYZ"

Live Transcript Events

{"event_type": "transcript.partial", "call_id": "call_...", "speaker": "agent", "text": "Hi, this is Alex from Acme."}
{"event_type": "transcript.partial", "call_id": "call_...", "speaker": "human", "text": "How can I help you?"}

When to Use WebSockets vs Webhooks

MCP Integration

Connect AgenticCalling to Claude, ChatGPT, Cursor, and other AI agents.

MCP Server Setup

MCP (Model Context Protocol) is an open standard that enables AI applications to connect with external tools. Add this to your MCP client configuration:

{
  "mcpServers": {
    "AgenticCalling": {
      "command": "npx",
      "args": ["-y", "agenticcalling-mcp"],
      "env": {
        "AC_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "AgenticCalling": {
      "command": "npx",
      "args": ["-y", "agenticcalling-mcp", "--tools", "make_call,get_call_status"],
      "env": { "AC_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Available MCP Tools

Claude.ai (Web / Mobile)

1. Go to Claude Settings → Integrations → Add MCP
2. Enter MCP server URL: https://mcp.agenticcalling.ai/sse
3. Enter your API key when prompted
4. Done. Claude now has calling tools.

Skills Installation

npx skills add autoacquire/agenticcalling-skills --skill agenticcalling --agent claude-code

npx skills add autoacquire/agenticcalling-skills --skill agenticcalling --agent cursor

npx clawhub@latest install agenticcalling

Then configure in ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "agenticcalling": {
        "enabled": true,
        "env": { "AC_API_KEY": "your-api-key-here" }
      }
    }
  }
}

Docs for Agents

Give your agent current docs in three formats:

SDKs

Official client libraries for AgenticCalling.

Python SDK

pip install agenticcalling python-dotenv

import os
from dotenv import load_dotenv
from agenticcalling import AgenticCalling

load_dotenv()
client = AgenticCalling(api_key=os.getenv("AC_API_KEY"))

# Make a call
call = client.calls.create(
    to="+14155551234",
    objective="Ask about bulk pricing for 500 steel beams",
    context="We are Acme Corp. Budget is $50-60 per unit.",
    voice="professional_male_en",
    client_id="steel-inquiry-v1"
)

# Get results
result = client.calls.get(call.call_id)
print(result.structured_data)

# Batch calls
batch = client.calls.create_batch(
    targets=[
        {"to": "+14155551111", "context": "Supplier A"},
        {"to": "+14155552222", "context": "Supplier B"},
    ],
    objective="Get steel beam pricing",
    playbook_id="platform.price_inquiry"
)

# Check usage
usage = client.usage.get()
print(f"{usage.minutes_remaining} minutes remaining")

# Send SMS (Coming Soon)
# sms = client.sms.send(
#     to="+14155551234",
#     message="Following up on our call about steel pricing."
# )

REST API (cURL)

The REST API works with any HTTP client. No SDK required.

curl -X POST https://api.agenticcalling.ai/v1/calls \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155551234", "objective": "Ask about business hours"}'

Node.js / TypeScript SDK

npm install @agenticcalling/sdk  # Coming soon

Pricing & Rate Limits

Usage-based pricing with a generous free tier.

Per-Minute Rates by Pipeline

Pricing depends on which voice AI pipeline you use. Platform costs (telephony + servers) are the same across all pipelines. LLM costs vary by model.

Platform fee breakdown: Twilio SIP $0.010 + LiveKit $0.004 + Servers $0.016 + 20% margin = $0.036/min.

Plans

Rate Limits

Rate-limited requests return 429 Too Many Requests with a Retry-After header.

Billing Details

Calls under 2 minutes (grace buffer) are free. Billing starts per-second when the call connects (human or voicemail answers). Rounding is to the next full minute. Ringing, no-answer, and busy signals are always free.

Every completed call stores a cost_breakdown object showing exact charges for telephony, servers, and LLM separately. Check via GET /v1/calls/{'{call_id}'}.

Error Codes

HTTP status codes and error response format.

Error Response Format

{
  "detail": "Description of what went wrong"
}

For 402 errors, a structured body is returned:

{
  "error": {
    "code": "insufficient_balance",
    "message": "You've used all 5 free minutes this month.",
    "details": {
      "plan": "free",
      "minutes_used": 5.0,
      "minutes_limit": 5.0,
      "resets_at": "2026-04-01T00:00:00Z",
      "upgrade_url": "https://agenticcalling.ai/dashboard/upgrade"
    },
    "suggestions": [
      "Upgrade to Pro for unlimited calls",
      "Wait until April 1 for free tier reset"
    ]
  }
}

Status Codes

SDK Exception Classes

Handling Errors (Python SDK)

from agenticcalling.exceptions import (
    InsufficientBalanceError,
    RateLimitError,
    AuthenticationError,
)

try:
    call = client.calls.create(to="+14155551234", objective="...")

except InsufficientBalanceError as e:
    print(f"Out of minutes: {e.minutes_used}/{e.minutes_limit} used")
    print(f"Resets: {e.resets_at}")
    print(f"Upgrade: {e.upgrade_url}")

except RateLimitError as e:
    time.sleep(e.retry_after or 60)

except AuthenticationError:
    print("Invalid API key. Check AC_API_KEY.")