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

# Create/Update Training

Create new training data or update existing training for a voice agent. Provides the agent with specific instructions and knowledge to improve its responses and behavior.

## Endpoint

```
POST /api/v1/agents/{agent_id}/trainings
```

## Path parameters

<ParamField path="agent" type="string" required>
  The unique identifier of the voice agent.
</ParamField>

## Request headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer talq_your_environment_token_here`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`
</ParamField>

## Request body

<ParamField body="node_id" type="string" required={false}>
  Training node ID for workflow integration
</ParamField>

<ParamField body="subject" type="string" required>
  Training subject or title (max 255 characters)
</ParamField>

<ParamField body="instructions" type="string" required>
  Detailed training instructions that the agent will learn from
</ParamField>

<ParamField body="current_status" type="string" required={false}>
  Training status. Options: `active`, `inactive`. Default: `active`
</ParamField>

## Example requests

<RequestExample>
  ```bash theme={null}
  # 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"
    }'
  ```

  ```javascript theme={null}
  // Request 1: Create new training with active status
  const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/trainings', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      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"
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # 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."
    }'
  ```

  ```javascript theme={null}
  // Request 2: Create training with minimal required fields
  const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/trainings', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      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."
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # 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"
    }'
  ```

  ```javascript theme={null}
  // Request 3: Create inactive training for future use
  const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/trainings', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      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"
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

## Response

### Success Response (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

### Response fields

<ResponseField name="success" type="boolean" required>
  Indicates if the operation was successful.
</ResponseField>

<ResponseField name="message" type="string" required>
  Success message confirming the training was created or updated.
</ResponseField>

<ResponseField name="data" type="object" required>
  The created or updated training object.

  <Expandable title="Training Object">
    <ResponseField name="id" type="string" required>
      Unique identifier for the training.
    </ResponseField>

    <ResponseField name="subject" type="string" required>
      The subject or title of the training.
    </ResponseField>

    <ResponseField name="instructions" type="string" required>
      Detailed instructions for the training that the agent will learn from.
    </ResponseField>

    <ResponseField name="current_status" type="string" required>
      Current status of the training. Options: `active`, `inactive`.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      ISO 8601 timestamp when the training was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      ISO 8601 timestamp when the training was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

### Validation Error (422)

<ResponseExample>
  ```json theme={null}
  {
    "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."
      ]
    }
  }
  ```
</ResponseExample>

### 404 Not Found

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Agent not found"
  }
  ```
</ResponseExample>

### 401 Unauthorized

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Unauthenticated."
  }
  ```
</ResponseExample>

### 403 Forbidden

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "You are not authorized to create training for this agent."
  }
  ```
</ResponseExample>

### 500 Server Error

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Internal server error."
  }
  ```
</ResponseExample>

## 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 create training for this agent | 403         |
| `VALIDATION_ERROR` | Request data validation failed                                  | 422         |
| `SERVER_ERROR`     | Internal server error occurred                                  | 500         |

## Important notes

<Info>
  **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.
</Info>

<Info>
  **Training takes effect immediately.** Once created, the training instructions are immediately available to the agent for learning and improving responses.
</Info>

<Warning>
  **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.
</Warning>

## Related endpoints

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