# 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"
// 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);
{
"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"
}
]
}
}
Agents
Get Agent
Retrieve details of a specific voice agent by ID
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"
// 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);
{
"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"
}
]
}
}
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
string
required
The unique identifier of the voice agent.
Request headers
string
required
Bearer token for authentication. Format:
Bearer talq_your_environment_token_hereExample 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"
// 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);
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
string
required
Unique identifier for the agent.
string
required
The name of the agent.
string
required
The display label for the agent.
string
Description of the agent’s purpose and functionality.
string
required
The language the agent speaks. Format:
en-US, pt-BR, etc.object
Voice configuration for the agent.
string
The first message the agent will say when a call starts.
string
required
How sensitive the agent is to interruptions. Options:
low, medium, high.number
required
Speed of the agent’s speech (0.1 to 3.0).
integer
required
Delay before the agent starts speaking (0 to 60 seconds).
boolean
required
Whether the agent asks if a human is present when idle.
string
required
Call direction. Options:
inbound, outbound.string
required
Who initiates the conversation. Options:
agent, user.string
required
Current status of the agent. Options:
draft, published.boolean
required
Whether the agent is in sandbox mode.
boolean
required
Whether the agent is ready to be published.
string
required
ISO 8601 timestamp when the agent was created.
string
required
ISO 8601 timestamp when the agent was last updated.
array
Array of training data associated with the agent.
array
Array of actions (webhooks, transfers, etc.) associated with the agent.
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
| 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}
Was this page helpful?