> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Agent

> Create a new voice agent with specified configuration and settings

# Create Agent

Create a new voice agent with specified configuration, voice settings, and behavior parameters. The agent will be created in draft status and can be published later.

## Endpoint

```
POST /api/v1/agents
```

## Path parameters

None

## Request headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer talq_your_environment_token_here`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`
</ParamField>

## Request body

<ParamField body="label" type="string" required>
  Agent label (max 255 characters)
</ParamField>

<ParamField body="description" type="string" required={false}>
  Agent description
</ParamField>

<ParamField body="name" type="string" required>
  Agent name (max 255 characters)
</ParamField>

<ParamField body="language" type="string" required>
  Agent language code. Supported values: `pt-BR`, `pt-PT`, `en-US`, `en-CA`, `es-ES`, `fr-FR`, `de-DE`, `it-IT`, `nl-NL`, `ja-JP`, `ko-KR`, `zh-TW`.
</ParamField>

<ParamField body="initial_message" type="string" required={false}>
  Initial message the agent will say. Optional.
</ParamField>

<ParamField body="interrupt_sensitivity" type="string" required>
  How easily the agent allows the caller to interrupt. Options: `low`, `medium`, `high`.
</ParamField>

<ParamField body="endpointing_sensitivity" type="string" required>
  How aggressively the agent detects end-of-utterance. Max 255 characters.
</ParamField>

<ParamField body="ivr_navigation_mode" type="string" required>
  IVR navigation behavior for outbound calls that hit interactive menus. Max 255 characters.
</ParamField>

<ParamField body="conversation_speed" type="number" required>
  Conversation playback speed multiplier. Range: `0.1`–`3.0`.
</ParamField>

<ParamField body="initial_message_delay" type="integer" required>
  Delay in seconds before the agent says the initial message. Range: `0`–`60`.
</ParamField>

<ParamField body="ask_if_human_present_on_idle" type="boolean" required>
  When `true`, the agent asks "Are you still there?" after the idle timeout instead of ending the call.
</ParamField>

<ParamField body="idle_time_seconds" type="integer" required>
  Seconds of caller silence before triggering the idle behavior. Range: `1`–`60`.
</ParamField>

<ParamField body="max_idle_check_count" type="integer" required={false}>
  Maximum number of idle re-prompts before ending the call. Range: `1`–`10`. Optional.
</ParamField>

<ParamField body="max_call_duration_seconds" type="integer" required={false}>
  Hard limit on call duration in seconds. Range: `1`–`3600`. Optional.
</ParamField>

<ParamField body="say_goodbye_on_max_duration" type="boolean" required={false}>
  When `true`, the agent says a closing message before terminating a call that hits `max_call_duration_seconds`. Optional.
</ParamField>

<ParamField body="user_inactivity_timeout_seconds" type="integer" required={false}>
  Seconds of total inactivity before the agent gives up entirely. Range: `5`–`120`. Optional.
</ParamField>

<ParamField body="initial_idle_time_seconds" type="integer" required={false}>
  Idle threshold to use **before** the agent has said its initial message (handles cases where the line opens but the caller doesn't speak). Range: `1`–`60`. Optional.
</ParamField>

<ParamField body="initial_max_idle_check_count" type="integer" required={false}>
  Maximum number of initial idle prompts before terminating. Range: `0`–`10`. Optional.
</ParamField>

<ParamField body="llm_temperature" type="number" required>
  Sampling temperature for the language model. Range: `0`–`2`. Lower values make responses more deterministic.
</ParamField>

<ParamField body="enable_recording" type="boolean" required>
  Whether to record calls handled by this agent.
</ParamField>

<ParamField body="direction" type="string" required>
  Call direction. Options: `inbound`, `outbound`.
</ParamField>

<ParamField body="who_speaks_first" type="string" required>
  Who speaks first. Options: `agent`, `user`.
</ParamField>

<ParamField body="phone_number_ids" type="array" required={false}>
  Array of phone number UUIDs to assign to this agent at creation. Use [List Phone Numbers](/api-reference/endpoints/list-phone-numbers) to retrieve available IDs. Can also be set later via [Update Agent Calling](/api-reference/endpoints/update-agent-calling).
</ParamField>

## Example requests

<RequestExample>
  ```bash theme={null}
  # Request 1: Create a basic inbound support agent
  curl -X POST "https://app.talkover.ai/api/v1/agents" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "label": "Customer Support Agent",
      "description": "Handles customer inquiries and support requests",
      "name": "SupportBot",
      "language": "en-US",
      "initial_message": "Hello, how can I help you today?",
      "interrupt_sensitivity": "medium",
      "endpointing_sensitivity": "auto",
      "ivr_navigation_mode": "off",
      "conversation_speed": 1.0,
      "initial_message_delay": 0,
      "ask_if_human_present_on_idle": false,
      "idle_time_seconds": 5,
      "llm_temperature": 0.7,
      "enable_recording": true,
      "direction": "inbound",
      "who_speaks_first": "agent"
    }'
  ```

  ```javascript theme={null}
  // Request 1: Create a basic inbound support agent
  const response = await fetch('https://app.talkover.ai/api/v1/agents', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      label: "Customer Support Agent",
      description: "Handles customer inquiries and support requests",
      name: "SupportBot",
      language: "en-US",
      initial_message: "Hello, how can I help you today?",
      interrupt_sensitivity: "medium",
      endpointing_sensitivity: "auto",
      ivr_navigation_mode: "off",
      conversation_speed: 1.0,
      initial_message_delay: 0,
      ask_if_human_present_on_idle: false,
      idle_time_seconds: 5,
      llm_temperature: 0.7,
      enable_recording: true,
      direction: "inbound",
      who_speaks_first: "agent"
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # Request 2: Create an outbound sales agent
  curl -X POST "https://app.talkover.ai/api/v1/agents" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "label": "Sales Agent",
      "description": "Outbound sales calls for product demos",
      "name": "SalesBot",
      "language": "en-US",
      "initial_message": "Hi, this is SalesBot calling about our new product. Do you have a moment?",
      "interrupt_sensitivity": "high",
      "endpointing_sensitivity": "auto",
      "ivr_navigation_mode": "off",
      "conversation_speed": 1.2,
      "initial_message_delay": 2,
      "ask_if_human_present_on_idle": true,
      "idle_time_seconds": 10,
      "llm_temperature": 0.8,
      "enable_recording": true,
      "direction": "outbound",
      "who_speaks_first": "agent"
    }'
  ```

  ```javascript theme={null}
  // Request 2: Create an outbound sales agent
  const response = await fetch('https://app.talkover.ai/api/v1/agents', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      label: "Sales Agent",
      description: "Outbound sales calls for product demos",
      name: "SalesBot",
      language: "en-US",
      initial_message: "Hi, this is SalesBot calling about our new product. Do you have a moment?",
      interrupt_sensitivity: "high",
      endpointing_sensitivity: "auto",
      ivr_navigation_mode: "off",
      conversation_speed: 1.2,
      initial_message_delay: 2,
      ask_if_human_present_on_idle: true,
      idle_time_seconds: 10,
      llm_temperature: 0.8,
      enable_recording: true,
      direction: "outbound",
      who_speaks_first: "agent"
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

## Response

### Success Response (201 Created)

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "message": "Agent created successfully",
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "SupportBot",
      "label": "Customer Support Agent",
      "description": "Handles customer inquiries and support requests",
      "language": "en-US",
      "voice": null,
      "initial_message": "Hello, how can I help you today?",
      "interrupt_sensitivity": "medium",
      "conversation_speed": 1.0,
      "initial_message_delay": 0,
      "ask_if_human_present_on_idle": false,
      "direction": "inbound",
      "who_speaks_first": "agent",
      "current_status": "draft",
      "is_sandbox": false,
      "is_ready_to_publish": false,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "trainings": [],
      "actions": [],
      "phone_numbers": []
    }
  }
  ```
</ResponseExample>

## Error responses

### Validation Error (422)

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
      "name": [
        "The name field is required."
      ],
      "label": [
        "The label field is required."
      ],
      "language": [
        "The selected language is invalid."
      ],
      "interrupt_sensitivity": [
        "The selected interrupt sensitivity is invalid."
      ],
      "direction": [
        "The selected direction is invalid."
      ],
      "conversation_speed": [
        "The conversation speed must be between 0.1 and 3.0."
      ],
      "initial_message_delay": [
        "The initial message delay must be between 0 and 60."
      ],
      "llm_temperature": [
        "The llm temperature must be between 0 and 2."
      ],
      "idle_time_seconds": [
        "The idle time seconds must be between 1 and 300."
      ]
    }
  }
  ```
</ResponseExample>

### Unauthorized Error (401)

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Unauthenticated."
  }
  ```
</ResponseExample>

### Too Many Requests (429)

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Too many requests. Please try again later."
  }
  ```
</ResponseExample>