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_sk_ or ac_test_sk_.

Authorization: Bearer ac_live_sk_7f8a9b2c...

Getting a Key

There are three 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.
3. OTP flow — Use POST /v1/auth/otp/send and POST /v1/auth/otp/verify for email-based authentication (used by MCP connectors).

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)
├── 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_sk_..." \
  -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_sk_..."

{
  "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_sk_..."

// 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_sk_..." \
  -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_sk_..."

{
  "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_sk_..."

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

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

{
  "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_sk_7f8a9b2c...",
  "message": "Store this key — it won't be shown again"
}

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

{ "sent": true, "email": "dev@acme.com" }

{
  "api_key": "ac_live_sk_...",
  "org_id": "01HABC...",
  "is_new": false
}

[
  {
    "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_sk_...",
  "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_sk_..."

{ "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_sk_..."

{
  "organization_id": "01HABC...",
  "plan": "free",
  "minutes_used_this_month": 24.5,
  "minutes_limit": 30.0,
  "minutes_remaining": 5.5,
  "sms_sent_this_month": 12,
  "sms_limit": 50,
  "sms_remaining": 38,
  "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,
    "rate_per_minute_usd": 0.1714,
    "sms_rate_per_message_usd": 0.013
  }
}

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)

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)

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_sk_..."
);

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,send_sms"],
      "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
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_sk_..." \
  -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.

Plans

Rate Limits

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

Cost Breakdown

Each call minute includes telephony, voice AI, and real-time media processing — all bundled into a single per-minute rate. No separate charges for individual components.

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

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 30 free minutes this month.",
    "details": {
      "plan": "free",
      "minutes_used": 30.0,
      "minutes_limit": 30.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.")