Documentation Index
Fetch the complete documentation index at: https://docs.getsmartalex.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The Agents API allows you to create, configure, and manage AI voice agents programmatically.
List Agents
Get all agents in your account.
curl -X GET "https://api.getsmartalex.com/v1/agents" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"data": [
{
"id": "agent_abc123",
"name": "Alex",
"language": "en-US",
"is_active": true,
"voice_provider": "cloud",
"created_at": "2026-01-15T10:30:00Z"
},
{
"id": "agent_def456",
"name": "Sarah",
"language": "en-US",
"is_active": true,
"voice_provider": "cloud",
"created_at": "2026-01-14T08:15:00Z"
}
]
}
Get Agent
Retrieve a single agent by ID.
curl -X GET "https://api.getsmartalex.com/v1/agents/agent_abc123" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"data": {
"id": "agent_abc123",
"name": "Alex",
"assistant_name": "Alex",
"company_name": "ABC Company",
"assistant_personality": "friendly and professional",
"objective": "Answer caller questions and schedule appointments",
"first_message": "Hello, this is Alex from ABC Company. How can I help you today?",
"call_direction": "inbound",
"language": "en-US",
"is_active": true,
"voice_provider": "cloud",
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T14:22:00Z"
}
}
Create Agent
Create a new AI voice agent. Provide a website_url and SmartAlex will auto-build an agent trained on your business in under 60 seconds. Or supply your own configuration fields directly.
curl -X POST "https://api.getsmartalex.com/v1/agents" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"website_url": "https://example.com",
"company_name": "ABC Company",
"assistant_name": "Alex"
}'
Parameters
| Parameter | Type | Required | Description |
|---|
website_url | string | No | URL to crawl and auto-build the agent from |
company_name | string | No | Company name shown to callers |
name | string | No | Internal name for the agent in your dashboard |
assistant_name | string | No | The name the agent introduces itself with |
objective | string | No | What the agent should accomplish on calls |
first_message | string | No | The agent’s opening line |
voice | string | No | Voice ID (see Available Voices) |
accent | string | No | Accent code |
At minimum, provide either website_url (Standard creation) or the manual configuration fields like name, assistant_name, and objective (Advanced creation).
Update Agent
Update an existing agent’s configuration. Only provide the fields you want to change.
curl -X PATCH "https://api.getsmartalex.com/v1/agents/agent_abc123" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"objective": "Updated objective for the agent",
"is_active": true
}'
Parameters
All parameters are optional. Only included fields will be updated.
| Parameter | Type | Description |
|---|
name | string | Internal name in your dashboard |
assistant_name | string | The name the agent introduces itself with |
company_name | string | Company name shown to callers |
assistant_personality | string | Personality descriptor (e.g., “warm and professional”) |
is_active | boolean | Toggle the agent on or off |
objective | string | What the agent should accomplish on calls |
product_description | string | Description of what your business sells |
first_message | string | The agent’s opening line |
call_direction | enum | inbound, outbound, or both |
language | string | Language code (e.g., en-US) |
custom_instructions | array of strings | Additional behavioural rules |
background_sound | enum | office or off |
enabled_tools | array of strings | List of tool names the agent can use |
knowledge_item_ids | array of UUIDs | Knowledge base documents linked to this agent |
phone_number_id | UUID or null | Phone number to assign to the agent |
Delete Agent
Delete an agent. This action cannot be undone.
curl -X DELETE "https://api.getsmartalex.com/v1/agents/agent_abc123" \
-H "Authorization: Bearer YOUR_API_KEY"
Deleting an agent will unassign it from all phone numbers and cancel any active campaigns using that agent.
Agent Status
The is_active boolean field controls whether the agent answers calls.
is_active | Behaviour |
|---|
true | Agent is live and ready to take calls |
false | Agent is toggled off and won’t answer calls |
is_active becomes true.
Error Codes
| Code | Description |
|---|
agent_not_found | Agent ID doesn’t exist |
invalid_voice | Voice ID not recognised |
invalid_language | Language code not supported |
