Skip to main content
POST
Create Agent

Authorizations

Authorization
string
header
required

AgentLine API key. Get one via the email OTP flow (POST /v1/auth/otp then POST /v1/auth/verify). Pass as: Authorization: Bearer al_live_... (legacy sk_live_... still works).

Body

application/json
name
string
required

Display name for the AI voice agent

system_prompt
string | null

Default instructions for the agent's personality and behavior on ALL calls (inbound and outbound). Can be overridden per-call via POST /v1/calls.

initial_greeting
string | null

Default opening line spoken on ALL calls (inbound and outbound), e.g. 'Hello, how can I help you today?'. Can be overridden per-call via POST /v1/calls.

voice_id
string | null

TTS voice preset name (e.g. 'female-1', 'male-1') or Cartesia voice UUID; defaults to system voice if not set

transfer_number
string | null

Ignored unless it is the owner phone. Live transfers always dial owner_phone; a different number is rejected.

voicemail_message
string | null

Message the AI agent leaves if the call goes to voicemail

owner_phone
string | null

Owner's phone number in E.164 format (e.g. '+12125551234'). Calls from this number enter task mode. This is also the only number a live call can be transferred to.

Response

Successful Response

id
string
required

Unique agent identifier (e.g. 'agt_abc123')

account_id
string
required

Account that owns this agent

name
string
required

Display name of the AI voice agent

created_at
string<date-time>
required

When the agent was created

system_prompt
string | null

Default system prompt for all calls (can be overridden per-call)

initial_greeting
string | null

Default greeting for all calls (can be overridden per-call)

voice_id
string | null

TTS voice preset or Cartesia UUID

transfer_number
string | null

Always the owner phone. Live calls transfer only here.

voicemail_message
string | null

Message left on voicemail

owner_phone
string | null

Owner's phone number for task mode and the only live-call transfer destination