API Reference

Telepath REST API for programmatic integration.

Overview

The Telepath API allows you to programmatically create and manage SIP trunks (connections), monitor calls, and retrieve analytics. All API interactions use HTTPS with JSON request and response bodies.

Use the API to build automated provisioning workflows, integrate call data with your own systems, or power custom dashboards on top of Telepath's observability data.

Base URL

All API endpoints are relative to the following base URL:

https://api.telepathvoice.com/v1

Authentication

The Telepath API uses Bearer token authentication. Include your API key in the Authorization header of every request.

You can generate and manage API keys from the Settings › API Keys page in the Telepath Dashboard.

Authorization: Bearer YOUR_API_KEY

For example, a complete authenticated request looks like:

curl https://api.telepathvoice.com/v1/trunks \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

For full authentication documentation, including key scopes and rotation procedures, see the Authentication reference page.

API Endpoints

Trunks (Connections)

Trunks represent your SIP connections. Each trunk links a carrier SIP endpoint to an AI agent WebSocket URL and holds the SIP credentials your carrier uses to authenticate with Telepath.

Calls

Call records are automatically created for every call routed through Telepath. Each record includes detailed latency breakdowns, duration, status, and associated trunk information.

Analytics

Analytics endpoints provide aggregated performance data across all calls in your account. Use these to build reporting dashboards or trigger alerting based on latency thresholds.

Rate Limiting

The Telepath API enforces rate limits to ensure fair usage across all accounts. The current limits are:

• 6,000 requests per minute across all endpoints for a given API key.
• Rate limits are applied per API key, not per account. Multiple keys share independent limits.

Every API response includes the following rate limit headers:

X-RateLimit-Limit: 6000
X-RateLimit-Remaining: 5987
X-RateLimit-Reset: 1741603260

When you exceed the rate limit, the API responds with HTTP 429 Too Many Requests. The X-RateLimit-Reset header contains a Unix timestamp indicating when your limit resets. Implement exponential backoff in your client when you receive a 429 response.

Common Request Patterns

Pagination

List endpoints return paginated results using cursor-based pagination. Use the limit and cursor query parameters to navigate pages.

GET /trunks?limit=20&cursor=trunk_01abc123

The response includes a next_cursor field. Pass this value as the cursor parameter in your next request to retrieve the following page. When next_cursor is null, you have reached the last page.

{
  "data": [ ... ],
  "next_cursor": "trunk_01xyz789",
  "has_more": true
}

Filtering

Most list endpoints support filtering via query parameters. Combine multiple filters to narrow results:

GET /calls?trunk_id=trunk_01abc123&status=completed&limit=50

Date Range

Use ISO 8601 timestamps with the from and to parameters to filter by date range. All timestamps are in UTC.

GET /calls?from=2026-03-01T00:00:00Z&to=2026-03-10T23:59:59Z

Response Format

All responses are JSON. Successful responses include a data key containing the result object or array. Error responses include an error key with a machine-readable code and a human-readable message.

Success

{
  "data": {
    "id": "trunk_01abc123",
    "name": "My AI Agent",
    "provider": "openai",
    "sip_endpoint": "sip.telepathvoice.com",
    "sip_username": "trunk_01abc123",
    "status": "active",
    "created_at": "2026-03-10T12:00:00Z",
    "updated_at": "2026-03-10T12:00:00Z"
  }
}

Error

{
  "error": {
    "code": "trunk_not_found",
    "message": "No trunk with ID 'trunk_01abc123' exists in your account.",
    "status": 404
  }
}

HTTP Status Codes

Common Use Cases

Automated Provisioning

Use the API to provision trunks automatically as part of your onboarding workflow. For example, when a new customer signs up for your service, programmatically create a Telepath trunk and return the SIP credentials to your customer's carrier configuration interface.

Call Data Integration

Pull call records from the GET /calls endpoint on a schedule to sync call history into your CRM, data warehouse, or analytics platform. Use the from and to date filters with cursor-based pagination to efficiently sync only new records.

Latency Alerting

Poll GET /analytics/overview at regular intervals and trigger alerts when average AI Latency or Carrier Lag exceeds your defined thresholds. Combine with the GET /calls endpoint to drill into individual calls that exceeded the threshold.

Automated Key Rotation

Rotate SIP passwords on a schedule using POST /trunks/{id}/rotate-sip-password. Coordinate with your carrier's configuration update API to apply the new password before the old one is invalidated.

SDKs & Libraries

The Telepath API is a standard REST API that works with any HTTP client. Official SDKs and community-maintained libraries are listed below:

• Official REST API — Works directly with curl, fetch, axios, requests, or any HTTP client in any language.
• OpenAPI Spec — Download the OpenAPI 3.0 specification to auto-generate a client in your language using tools like OpenAPI Generator.
• Postman Collection — Import the Telepath Postman collection from the Dashboard under Settings › Developer Tools to get a ready-to-use set of API requests with example payloads.