Skip to main content
GET
/
api
/
v1
/
agents
# Request 1: List all agents
curl -X GET "https://app.talkover.ai/api/v1/agents" \
  -H "Authorization: Bearer talq_your_environment_token_here"
{
  "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"
        }
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 25,
    "last_page": 3
  }
}

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.

List Agents

Retrieve a list of voice agents with optional filtering by status, direction, and search terms. Supports pagination for large datasets.

Endpoint

GET /api/v1/agents

Path Parameters

None

Query Parameters

status
string
Filter by agent status. Options: draft, published
direction
string
Filter by call direction. Options: inbound, outbound
Search by agent name or label
per_page
integer
Number of items per page (default: 20)
page
integer
Page number for pagination (default: 1)

Request Headers

Authorization
string
required
Bearer token for authentication. Format: Bearer talq_your_environment_token_here

Example Requests

# Request 1: List all agents
curl -X GET "https://app.talkover.ai/api/v1/agents" \
  -H "Authorization: Bearer talq_your_environment_token_here"
# Request 2: List published inbound agents
curl -X GET "https://app.talkover.ai/api/v1/agents?status=published&direction=inbound" \
  -H "Authorization: Bearer talq_your_environment_token_here"
# Request 3: Search agents with pagination
curl -X GET "https://app.talkover.ai/api/v1/agents?search=support&per_page=5&page=1" \
  -H "Authorization: Bearer talq_your_environment_token_here"

Response

Success Response (200 OK)

{
  "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"
        }
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 25,
    "last_page": 3
  }
}

Error Responses

Validation Error (422)

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "status": [
      "The selected status is invalid."
    ],
    "direction": [
      "The selected direction is invalid."
    ],
    "per_page": [
      "The per page must be between 1 and 100."
    ]
  }
}

Unauthorized Error (401)

{
  "success": false,
  "message": "Unauthenticated."
}

Too Many Requests (429)

{
  "success": false,
  "message": "Too many requests. Please try again later."
}