Skip to main content
POST
/
api
/
v1
/
agents
/
{agent_id}
/
trainings
# Request 1: Create new training with active status
curl -X POST "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/trainings" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "training-node-123",
    "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. Always provide accurate information about our services.",
    "current_status": "active"
  }'
{
  "success": true,
  "message": "Agent training updated successfully",
  "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. Always provide accurate information about our services.",
    "current_status": "active",
    "created_at": "2024-01-15T10:30: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.

Create/Update Training

Create new training data or update existing training for a voice agent. This endpoint allows you to provide the agent with specific instructions and knowledge to improve its responses and behavior.

Endpoint

POST /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
Content-Type
string
required
Must be set to application/json

Request Body

node_id
string
Training node ID for workflow integration
subject
string
required
Training subject or title (max 255 characters)
instructions
string
required
Detailed training instructions that the agent will learn from
current_status
string
Training status. Options: active, inactive. Default: active

Example Requests

# Request 1: Create new training with active status
curl -X POST "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/trainings" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "training-node-123",
    "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. Always provide accurate information about our services.",
    "current_status": "active"
  }'
# Request 2: Create training with minimal required fields
curl -X POST "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/trainings" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Customer Service Best Practices",
    "instructions": "Understand how to handle customer complaints and provide excellent service. Always be polite, patient, and solution-oriented. Escalate issues when necessary."
  }'
# Request 3: Create inactive training for future use
curl -X POST "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/trainings" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Technical Support",
    "instructions": "Provide technical support for common issues. Guide users through troubleshooting steps and escalate when necessary. Use clear, simple language.",
    "current_status": "inactive"
  }'

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Agent training updated successfully",
  "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. Always provide accurate information about our services.",
    "current_status": "active",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}

Response Fields

success
boolean
required
Indicates if the operation was successful.
message
string
required
Success message confirming the training was created or updated.
data
object
required
The created or updated training object.

Error Responses

Validation Error (422)

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "subject": [
      "The subject field is required."
    ],
    "instructions": [
      "The instructions field is required."
    ],
    "current_status": [
      "The selected current status is invalid."
    ]
  }
}

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 create training for this agent."
}

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 create training for this agent403
VALIDATION_ERRORRequest data validation failed422
SERVER_ERRORInternal server error occurred500

Important Notes

Agent status will be set to draft. After creating or updating training, the agent will be automatically set to “draft” status and will need to be published again to become active.
Training takes effect immediately. Once created, the training instructions are immediately available to the agent for learning and improving responses.
Character limits. The subject field has a maximum of 255 characters. Instructions can be much longer but should be clear and concise for best results.

Best Practices

  1. Be specific and clear - Write training instructions that are specific and easy to understand
  2. Use active voice - Write instructions in active voice for better clarity
  3. Include examples - Provide examples of good responses when possible
  4. Test training - Always test new training data before publishing the agent
  5. Organize by topic - Create separate training entries for different topics or scenarios
  6. Regular updates - Update training data regularly based on agent performance and feedback
  • List Trainings: GET /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}
  • Publish Agent: POST /api/v1/agents/{agent_id}/publish