---
title: "Create Agent"
method: POST
path: "/v1/agents"
tags: ["Agents"]
---

# Create Agent

`POST /v1/agents`

## Request

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

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).

## Request body

- AgentCreate
  - `name` string, required: Display name for the AI voice agent
  - `system_prompt` string, 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_greeting` string, 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_id` string, nullable: TTS voice preset name (e.g. 'female-1', 'male-1') or a voice UUID; defaults to system voice if not set
  - `transfer_number` string, 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_message` string, nullable: Message the AI agent leaves if the call goes to voicemail
  - `owner_phone` string, 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 `200`

Successful Response

- AgentOut
  - `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
  - `system_prompt` string, nullable: Default system prompt for all calls (can be overridden per-call)
  - `initial_greeting` string, nullable: Default greeting for all calls (can be overridden per-call)
  - `voice_id` string, nullable: TTS voice preset or voice UUID
  - `transfer_number` string, nullable: Always the owner phone. Live calls transfer only here.
  - `voicemail_message` string, nullable: Message left on voicemail
  - `owner_phone` string, nullable: Owner's phone number for task mode and the only live-call transfer destination
  - `created_at` string, date-time, required: When the agent was created

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/agentline/apis/agentline-prepaid-phone-service-for-ai-agents.md) · [All operations](https://skmtc.dev/agentline/apis/agentline-prepaid-phone-service-for-ai-agents/llms.txt) · [OpenAPI document](https://skmtc.dev/agentline/apis/agentline-prepaid-phone-service-for-ai-agents/revisions/18c0bdbb4b30?raw)