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

# Get Agent

> Retrieve details of a specific voice agent by ID

# Get Agent

Retrieve detailed information about a specific voice agent, including its configuration, voice settings, trainings, actions, and phone numbers.

## Endpoint

```
GET /api/v1/agents/{agent_id}
```

## Path parameters

<ParamField path="agent" type="string" required>
  The unique identifier of the voice agent.
</ParamField>

## Request headers

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

## Example requests

<RequestExample>
  ```bash theme={null}
  # Request 1: Get a specific agent by ID
  curl -X GET "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
    -H "Authorization: Bearer talq_your_environment_token_here"
  ```

  ```javascript theme={null}
  // Request 1: Get a specific agent by ID
  const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here'
    }
  });

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

## Response

### Success Response (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "SupportBot",
      "label": "Customer Support Agent",
      "description": "Handles customer inquiries and support requests",
      "language": "en-US",
      "voice": {
        "id": "voice-uuid",
        "name": "Bianca",
        "label": "Bianca Voice",
        "stability": 0.6,
        "similarity_boost": 0.98,
        "ambient_background": "office",
        "template": {
          "id": "voice-template-uuid",
          "name": "Bianca"
        }
      },
      "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": "published",
      "is_sandbox": false,
      "is_ready_to_publish": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "trainings": [
        {
          "id": "training-uuid",
          "subject": "Product Knowledge",
          "instructions": "Learn about our product features and pricing",
          "current_status": "active",
          "created_at": "2024-01-15T10:30:00Z",
          "updated_at": "2024-01-15T10:30:00Z"
        }
      ],
      "actions": [
        {
          "id": "action-uuid",
          "name": "Schedule Meeting",
          "label": "Schedule Meeting",
          "description": "Schedule a meeting with the customer",
          "type": "webhook",
          "input_schema": [
            {
              "name": "date",
              "type": "string",
              "required": true,
              "description": "Meeting date"
            }
          ],
          "config": null,
          "action_trigger": null,
          "url": "https://api.example.com/schedule",
          "authorization_url": null,
          "current_status": "active",
          "created_at": "2024-01-15T10:30:00Z",
          "updated_at": "2024-01-15T10:30:00Z"
        }
      ],
      "phone_numbers": [
        {
          "id": "phone-uuid",
          "number": "+1234567890",
          "country_code": "US",
          "formatted_number": "(123) 456-7890",
          "international_number": "+1 234 567 890",
          "current_status": "active"
        }
      ]
    }
  }
  ```
</ResponseExample>

### Response fields

<ResponseField name="id" type="string" required>
  Unique identifier for the agent.
</ResponseField>

<ResponseField name="name" type="string" required>
  The name of the agent.
</ResponseField>

<ResponseField name="label" type="string" required>
  The display label for the agent.
</ResponseField>

<ResponseField name="description" type="string">
  Description of the agent's purpose and functionality.
</ResponseField>

<ResponseField name="language" type="string" required>
  The language the agent speaks. Format: `en-US`, `pt-BR`, etc.
</ResponseField>

<ResponseField name="voice" type="object">
  Voice configuration for the agent.

  <Expandable title="Voice Object">
    <ResponseField name="id" type="string" required>
      Unique identifier for the voice.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Name of the voice.
    </ResponseField>

    <ResponseField name="label" type="string" required>
      Display label for the voice.
    </ResponseField>

    <ResponseField name="stability" type="number">
      Voice stability setting (0.0 to 1.0).
    </ResponseField>

    <ResponseField name="similarity_boost" type="number">
      Voice similarity setting (0.0 to 1.0).
    </ResponseField>

    <ResponseField name="ambient_background" type="string">
      Ambient background setting.
    </ResponseField>

    <ResponseField name="template" type="object">
      Voice template information.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="initial_message" type="string">
  The first message the agent will say when a call starts.
</ResponseField>

<ResponseField name="interrupt_sensitivity" type="string" required>
  How sensitive the agent is to interruptions. Options: `low`, `medium`, `high`.
</ResponseField>

<ResponseField name="conversation_speed" type="number" required>
  Speed of the agent's speech (0.1 to 3.0).
</ResponseField>

<ResponseField name="initial_message_delay" type="integer" required>
  Delay before the agent starts speaking (0 to 60 seconds).
</ResponseField>

<ResponseField name="ask_if_human_present_on_idle" type="boolean" required>
  Whether the agent asks if a human is present when idle.
</ResponseField>

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

<ResponseField name="who_speaks_first" type="string" required>
  Who initiates the conversation. Options: `agent`, `user`.
</ResponseField>

<ResponseField name="current_status" type="string" required>
  Current status of the agent. Options: `draft`, `published`.
</ResponseField>

<ResponseField name="is_sandbox" type="boolean" required>
  Whether the agent is in sandbox mode.
</ResponseField>

<ResponseField name="is_ready_to_publish" type="boolean" required>
  Whether the agent is ready to be published.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp when the agent was created.
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  ISO 8601 timestamp when the agent was last updated.
</ResponseField>

<ResponseField name="trainings" type="array">
  Array of training data associated with the agent.
</ResponseField>

<ResponseField name="actions" type="array">
  Array of actions (webhooks, transfers, etc.) associated with the agent.
</ResponseField>

<ResponseField name="phone_numbers" type="array">
  Array of phone numbers associated with the agent.
</ResponseField>

## Error responses

### 404 Not Found

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Agent not found"
  }
  ```
</ResponseExample>

### 401 Unauthorized

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

### 403 Forbidden

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "You are not authorized to perform this action."
  }
  ```
</ResponseExample>

## Error codes

| Code              | Description                                        | HTTP Status |
| ----------------- | -------------------------------------------------- | ----------- |
| `AGENT_NOT_FOUND` | Specified agent does not exist                     | 404         |
| `INVALID_TOKEN`   | Authentication token is invalid or missing         | 401         |
| `UNAUTHORIZED`    | User does not have permission to access this agent | 403         |

## Related endpoints

* **List Agents**: `GET /api/v1/agents`
* **Create Agent**: `POST /api/v1/agents`
* **Update Agent Knowledge**: `PUT /api/v1/agents/{agent_id}/knowledge`
* **Update Agent Voice**: `PUT /api/v1/agents/{agent_id}/voice`
* **Update Agent Calling Settings**: `PUT /api/v1/agents/{agent_id}/calling`
* **Publish Agent**: `POST /api/v1/agents/{agent_id}/publish`
* **Unpublish Agent**: `POST /api/v1/agents/{agent_id}/unpublish`
* **Delete Agent**: `DELETE /api/v1/agents/{agent_id}`