API Reference

The ScaleTalk API allows you to programmatically manage your voice AI infrastructure, including agents, phone numbers, calls, and integrations.

Overview

The API is RESTful and uses JSON for request and response bodies. All API requests require authentication.

Base URL

https://app.scaletalk.ai/api/v1

Authentication

All API requests require an API key in the header:

Authorization: Bearer YOUR_API_KEY

Getting Your API Key

Navigate to Settings > API Keys
Click Generate New Key
Copy and securely store your key

Keep Your Key Secret

API keys provide full access to your account. Never expose them in client-side code or public repositories.

Agents API

List Agents

GET /agents

Response:

{
  "agents": [
    {
      "id": "ast_123456",
      "name": "Customer Support",
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Get Agent

GET /agents/{agent_id}

Create Agent

POST /agents

Request Body:

{
  "name": "New Agent",
  "language": "en",
  "voice": {
    "provider": "elevenlabs",
    "voice_id": "jessica"
  },
  "system_prompt": "You are a helpful customer service agent..."
}

Update Agent

PATCH /agents/{agent_id}

Delete Agent

DELETE /agents/{agent_id}

Calls API

List Calls

GET /calls

Query Parameters:

Parameter	Type	Description
`limit`	integer	Number of results (default: 50)
`offset`	integer	Pagination offset
`agent_id`	string	Filter by agent
`start_date`	string	Filter by date (ISO 8601)
`end_date`	string	Filter by date (ISO 8601)

Get Call Details

GET /calls/{call_id}

Response:

{
  "id": "call_789012",
  "agent_id": "ast_123456",
  "phone_number": "+491234567890",
  "caller_id": "+499876543210",
  "duration": 245,
  "status": "completed",
  "recording_url": "https://...",
  "transcript": "...",
  "variables": {
    "caller_name": "John Smith",
    "reason": "Support inquiry"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Initiate Outbound Call

POST /calls/outbound

Request Body:

{
  "agent_id": "ast_123456",
  "phone_number": "+491234567890",
  "to_number": "+499876543210",
  "context": {
    "customer_name": "John Smith",
    "order_id": "ORD-123"
  }
}

Phone Numbers API

List Phone Numbers

GET /phone-numbers

Search Available Numbers

GET /phone-numbers/available

Query Parameters:

Parameter	Type	Description
`country_code`	string	ISO country code (e.g., "DE")
`contains`	string	Number pattern to match
`limit`	integer	Number of results

Purchase Number

POST /phone-numbers

Request Body:

{
  "phone_number": "+491234567890",
  "friendly_name": "Support Line"
}

Update Number

PATCH /phone-numbers/{phone_number_id}

Delete Number

DELETE /phone-numbers/{phone_number_id}

Webhooks API

List Webhooks

GET /webhooks

Create Webhook

POST /webhooks

Request Body:

{
  "url": "https://your-server.com/webhook",
  "events": ["call.completed", "call.started"],
  "secret": "your_webhook_secret"
}

Update Webhook

PATCH /webhooks/{webhook_id}

Delete Webhook

DELETE /webhooks/{webhook_id}

Error Handling

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is missing required fields",
    "details": {
      "field": "name",
      "reason": "required"
    }
  }
}

Common Error Codes

Code	Description
`invalid_request`	Request validation failed
`unauthorized`	Invalid or missing API key
`forbidden`	Insufficient permissions
`not_found`	Resource doesn't exist
`rate_limited`	Too many requests
`internal_error`	Server error

Rate Limits

Endpoint	Limit
All endpoints	1000 requests/minute
Outbound calls	100 calls/minute

When rate limited, you'll receive a 429 response with a Retry-After header.

Pagination

List endpoints support pagination:

GET /calls?limit=50&offset=100

Response:

{
  "data": [...],
  "total": 500,
  "limit": 50,
  "offset": 100,
  "has_more": true
}

SDK Libraries

We provide official SDKs for common languages:

Python: pip install scaletalk
Node.js: npm install @scaletalk/sdk

SDK Documentation

See our GitHub repositories for SDK documentation and examples.

API Reference

On this page