API Reference

Welcome to itellicoAI API

The itellicoAI REST (Representational State Transfer) API lets you manage agents, phone numbers, Session Initiation Protocol (SIP) trunks, conversations, and analytics programmatically.

Use This Section When

Use the API docs when your team wants to automate setup, sync business systems, trigger agent workflows from another app, or manage data outside the dashboard. Business users usually stay in the product UI; developers and technical operators start here.

Official SDKs

Use the Python or TypeScript SDKs for a better developer experience

OpenAPI Specification

View the complete OpenAPI specification

Choose Your Integration Method

SDKs (Recommended)
REST API

Best for: Most applicationsOur official Python and TypeScript SDKs provide:

Type safety with autocomplete
Automatic authentication
Structured error handling
Less boilerplate code

View SDK Documentation →

Base URL

https://api.itellico.ai

Authentication

All API endpoints require authentication using an API key passed in the X-API-Key header:

curl -H "X-API-Key: your-api-key" https://api.itellico.ai/v1/accounts/current

Most resource endpoints are account-scoped. Call /v1/accounts/current first, then use the returned account id in paths such as /v1/accounts/{account_id}/agents. Endpoints that accept an account ID also accept me for the current account.

Learn how to create and manage API keys in the API Keys documentation.

Key Resources

The API is organized around these main resources:

Accounts - Manage your account and subaccounts
Agents - Create and configure AI voice agents
Providers - Access available models, transcribers, and voices
Phone Numbers - Manage phone numbers for inbound/outbound calls
SIP Trunks - Configure SIP carrier routing for imported numbers, including Connect Your Own setups (sometimes shortened to BYOC)
Conversations - Access conversation history and details
Analytics - Track usage metrics and performance data

Getting Started

Create an API Key

Create an API key from your dashboard

Verify Authentication

Make your first request to verify authentication:

curl
Python
TypeScript

curl -H "X-API-Key: sk-your-api-key" \
  https://api.itellico.ai/v1/accounts/current

from itellicoai import Itellicoai

client = Itellicoai(api_key="sk-your-api-key")
account = client.accounts.retrieve_current()
print(account.name)

import Itellicoai from 'itellicoai';

const client = new Itellicoai({ apiKey: 'sk-your-api-key' });
const account = await client.accounts.retrieveCurrent();
console.log(account.name);

Explore Endpoints

Browse the endpoint documentation in the sidebar

Common Operations

List Agents

curl
Python
TypeScript

curl -H "X-API-Key: sk-your-api-key" \
  https://api.itellico.ai/v1/accounts/{account_id}/agents

agents = client.agents.list("account_id")
for agent in agents.items:
    print(f"{agent.name} - {agent.id}")

const agents = await client.agents.list('account_id');
agents.items.forEach(agent => {
  console.log(`${agent.name} - ${agent.id}`);
});

List Conversations

curl
Python
TypeScript

curl -H "X-API-Key: sk-your-api-key" \
  https://api.itellico.ai/v1/accounts/{account_id}/conversations

conversations = client.accounts.list_conversations("account_id", limit=10)
for conversation in conversations.items:
    print(f"Status: {conversation.status}")
    print(f"Duration: {conversation.duration_seconds}s")

const conversations = await client.accounts.listConversations('account_id');
conversations.items.forEach(conversation => {
  console.log(`Status: ${conversation.status}`);
  console.log(`Duration: ${conversation.duration_seconds}s`);
});

Trigger an Outbound Call

curl -X POST https://api.itellico.ai/v1/accounts/{account_id}/calls \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "agent_id": "agent-uuid",
    "from_number": "+43720123456",
    "to_number": "+4312345678"
  }'

Getting started

Accounts

Subaccounts

Agents

Providers

Phone Numbers

SIP Trunks

Calls

Conversations

Analytics

API Reference

Welcome to itellicoAI API

Use This Section When

Official SDKs

OpenAPI Specification

Choose Your Integration Method

Base URL

Authentication

Key Resources

Getting Started

Common Operations

List Agents

List Conversations

Trigger an Outbound Call

Getting started

Accounts

Subaccounts

Agents

Providers

Phone Numbers

SIP Trunks

Calls

Conversations

Analytics

​Welcome to itellicoAI API

​Use This Section When

Official SDKs

OpenAPI Specification

​Choose Your Integration Method

​Base URL

​Authentication

​Key Resources

​Getting Started

​Common Operations

​List Agents

​List Conversations

​Trigger an Outbound Call

Welcome to itellicoAI API

Use This Section When

Choose Your Integration Method

Base URL

Authentication

Key Resources

Getting Started

Common Operations

List Agents

List Conversations

Trigger an Outbound Call