Agents

Create Agent

Create a new AI voice agent for telephony.

Adds an agent to the account with its own system prompt, voice and greeting. Creating an agent is free; it cannot call until it has a number, so call buy_phone_number next with the returned id as agent_id.

Returns the new agent, including its id (agt_...). A voice_id that is not a preset from list_available_voices or a voice UUID is rejected, as is a transfer_number that differs from owner_phone (HTTP 400).

post/v1/agents

Request

  • Base URL: https://api.agentline.cloud
  • URL: https://api.agentline.cloud/v1/agents
  • Auth: HTTP bearer

Request body

namestring required

Display name for the AI voice agent

system_promptstring nullable

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_greetingstring nullable

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_idstring nullable

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

transfer_numberstring nullable

Number a live call is transferred to. Only the owner phone is allowed, so leave it out or send the same E.164 number as owner_phone; setting owner_phone fills it in.

voicemail_messagestring nullable

Message the AI agent leaves if the call goes to voicemail

owner_phonestring nullable

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

idstring required

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

account_idstring required

Account that owns this agent

namestring required

Display name of the AI voice agent

system_promptstring nullable

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

initial_greetingstring nullable

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

voice_idstring nullable

TTS voice preset or voice UUID

transfer_numberstring nullable

Always the owner phone. Live calls transfer only here.

voicemail_messagestring nullable

Message left on voicemail

owner_phonestring nullable

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

created_atstring date-time required

When the agent was created

Changes

No recorded changes to this operation across all 1 revision of this API.