Skip to main content
GET
/
api
/
v1
/
agents
/
{agent_id}
# 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"
{
  "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"
      }
    ]
  }
}

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

agent
string
required
The unique identifier of the voice agent. You can find this in your dashboard under Voice Agents.

Request Headers

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

Example Requests

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

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"
      }
    ]
  }
}

Response Fields

id
string
required
Unique identifier for the agent.
name
string
required
The name of the agent.
label
string
required
The display label for the agent.
description
string
Description of the agent’s purpose and functionality.
language
string
required
The language the agent speaks. Format: en-US, pt-BR, etc.
voice
object
Voice configuration for the agent.
initial_message
string
The first message the agent will say when a call starts.
interrupt_sensitivity
string
required
How sensitive the agent is to interruptions. Options: low, medium, high.
conversation_speed
number
required
Speed of the agent’s speech (0.1 to 3.0).
initial_message_delay
integer
required
Delay before the agent starts speaking (0 to 60 seconds).
ask_if_human_present_on_idle
boolean
required
Whether the agent asks if a human is present when idle.
direction
string
required
Call direction. Options: inbound, outbound.
who_speaks_first
string
required
Who initiates the conversation. Options: agent, user.
current_status
string
required
Current status of the agent. Options: draft, published.
is_sandbox
boolean
required
Whether the agent is in sandbox mode.
is_ready_to_publish
boolean
required
Whether the agent is ready to be published.
created_at
string
required
ISO 8601 timestamp when the agent was created.
updated_at
string
required
ISO 8601 timestamp when the agent was last updated.
trainings
array
Array of training data associated with the agent.
actions
array
Array of actions (webhooks, transfers, etc.) associated with the agent.
phone_numbers
array
Array of phone numbers associated with the agent.

Error Responses

404 Not Found

{
  "success": false,
  "message": "Agent not found"
}

401 Unauthorized

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

403 Forbidden

{
  "success": false,
  "message": "You are not authorized to perform this action."
}

Error Codes

CodeDescriptionHTTP Status
AGENT_NOT_FOUNDSpecified agent does not exist404
INVALID_TOKENAuthentication token is invalid or missing401
UNAUTHORIZEDUser does not have permission to access this agent403
  • 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}