Skip to main content
GET
/
api
/
v1
/
agents
/
{agent_id}
/
trainings
# Request 1: List all trainings for an agent
curl -X GET "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/trainings" \
  -H "Authorization: Bearer talq_your_environment_token_here"

{
  "success": true,
  "data": [
    {
      "id": "training-uuid-1",
      "subject": "Product Knowledge",
      "instructions": "Learn about our product features, pricing, and common use cases. Focus on the main benefits and how to address common customer questions.",
      "current_status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "training-uuid-2",
      "subject": "Customer Service Best Practices",
      "instructions": "Understand how to handle customer complaints and provide excellent service. Always be polite, patient, and solution-oriented.",
      "current_status": "active",
      "created_at": "2024-01-15T11:00:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    },
    {
      "id": "training-uuid-3",
      "subject": "Technical Support",
      "instructions": "Provide technical support for common issues. Guide users through troubleshooting steps and escalate when necessary.",
      "current_status": "inactive",
      "created_at": "2024-01-15T12:00:00Z",
      "updated_at": "2024-01-15T12:00:00Z"
    }
  ]
}

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 Trainings

Retrieve all training data associated with a specific voice agent. This endpoint returns a list of training instructions that the agent uses to understand how to respond to different scenarios.

​
Endpoint

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

​
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: List all trainings for an agent
curl -X GET "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/trainings" \
  -H "Authorization: Bearer talq_your_environment_token_here"

# Request 2: List trainings with error handling
curl -X GET "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/trainings" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -w "\nHTTP Status: %{http_code}\n"

​
Response

​
Success Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "training-uuid-1",
      "subject": "Product Knowledge",
      "instructions": "Learn about our product features, pricing, and common use cases. Focus on the main benefits and how to address common customer questions.",
      "current_status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "training-uuid-2",
      "subject": "Customer Service Best Practices",
      "instructions": "Understand how to handle customer complaints and provide excellent service. Always be polite, patient, and solution-oriented.",
      "current_status": "active",
      "created_at": "2024-01-15T11:00:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    },
    {
      "id": "training-uuid-3",
      "subject": "Technical Support",
      "instructions": "Provide technical support for common issues. Guide users through troubleshooting steps and escalate when necessary.",
      "current_status": "inactive",
      "created_at": "2024-01-15T12:00:00Z",
      "updated_at": "2024-01-15T12:00:00Z"
    }
  ]
}

​
Response Fields

​
success
boolean
required
Indicates if the operation was successful.
​
data
array
required
Array of training objects 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 access this agent's trainings."
}

​
500 Server Error

{
  "success": false,
  "message": "Internal server error."
}

​
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
SERVER_ERRORInternal server error occurred500

​
Important Notes

Empty response is normal. If an agent has no training data, the response will be an empty array [] rather than an error.
Status filtering. The response includes both active and inactive trainings. You can filter by current_status on the client side if needed.

​
Best Practices

  1. Cache training data - Training data doesn’t change frequently, so consider caching the response
  2. Handle empty responses - Always check if the data array is empty before processing
  3. Monitor training status - Check the current_status to ensure trainings are active
  4. Error handling - Implement proper error handling for authentication and authorization failures
  5. Rate limiting - Be mindful of API rate limits when fetching training data
  • Create/Update Training: POST /api/v1/agents/{agent_id}/trainings
  • Delete Training: DELETE /api/v1/agents/{agent_id}/trainings/{training_id}
  • Get Agent: GET /api/v1/agents/{agent_id}
  • List Agents: GET /api/v1/agents