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

# Update Agent Knowledge

> Update an agent's knowledge, behavior, and conversation settings

# Update Agent Knowledge

Update an agent's knowledge base, conversation behavior, and interaction settings. Modifies the agent's description, initial message, interrupt sensitivity, and other behavioral parameters.

## Endpoint

```
PUT /api/v1/agents/{agent_id}/knowledge
```

## Path parameters

<ParamField path="agent" type="string" required>
  The unique identifier of the voice agent to update.
</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="description" type="string" required>
  Agent description (min 5 characters)
</ParamField>

<ParamField body="initial_message" type="string" required={false}>
  Initial message (min 5 characters, max 255 characters)
</ParamField>

<ParamField body="interrupt_sensitivity" type="string" required>
  Interrupt sensitivity level. Options: `low`, `medium`, `high`
</ParamField>

<ParamField body="ask_if_human_present_on_idle" type="boolean" required>
  Whether to ask if human is present when idle
</ParamField>

<ParamField body="llm_temperature" type="number" required>
  LLM temperature (min: 0, max: 2)
</ParamField>

<ParamField body="initial_message_delay" type="integer" required>
  Initial message delay (min: 0, max: 60)
</ParamField>

## Example requests

<RequestExample>
  ```bash theme={null}
  # Request 1: Update basic knowledge settings
  curl -X PUT "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/knowledge" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "description": "Updated agent description with more details",
      "initial_message": "Hello! Welcome to our support line. How may I assist you today?",
      "interrupt_sensitivity": "high",
      "ask_if_human_present_on_idle": true,
      "llm_temperature": 0.8,
      "initial_message_delay": 2
    }'
  ```

  ```javascript theme={null}
  // Request 1: Update basic knowledge settings
  const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/knowledge', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      description: "Updated agent description with more details",
      initial_message: "Hello! Welcome to our support line. How may I assist you today?",
      interrupt_sensitivity: "high",
      ask_if_human_present_on_idle: true,
      llm_temperature: 0.8,
      initial_message_delay: 2
    })
  });

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

<RequestExample>
  ```bash theme={null}
  # Request 2: Update for sales-focused agent
  curl -X PUT "https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/knowledge" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "description": "Sales agent focused on product demonstrations and lead qualification",
      "initial_message": "Hi! I am calling to introduce our new product line. Do you have 5 minutes to learn about how it can benefit your business?",
      "interrupt_sensitivity": "medium",
      "ask_if_human_present_on_idle": false,
      "llm_temperature": 0.9,
      "initial_message_delay": 1
    }'
  ```

  ```javascript theme={null}
  // Request 2: Update for sales-focused agent
  const response = await fetch('https://app.talkover.ai/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/knowledge', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      description: "Sales agent focused on product demonstrations and lead qualification",
      initial_message: "Hi! I am calling to introduce our new product line. Do you have 5 minutes to learn about how it can benefit your business?",
      interrupt_sensitivity: "medium",
      ask_if_human_present_on_idle: false,
      llm_temperature: 0.9,
      initial_message_delay: 1
    })
  });

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

## Response

### Success Response (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "message": "Agent knowledge updated successfully",
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "SupportBot",
      "label": "Customer Support Agent",
      "description": "Updated agent description with more details",
      "language": "en-US",
      "voice": {.},
      "initial_message": "Hello! Welcome to our support line. How may I assist you today?",
      "interrupt_sensitivity": "high",
      "conversation_speed": 1.0,
      "initial_message_delay": 2,
      "ask_if_human_present_on_idle": true,
      "direction": "inbound",
      "who_speaks_first": "agent",
      "current_status": "draft",
      "is_sandbox": false,
      "is_ready_to_publish": false,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:35:00Z",
      "trainings": [.],
      "actions": [.],
      "phone_numbers": [.]
    }
  }
  ```
</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 agent knowledge was updated.
</ResponseField>

<ResponseField name="data" type="object" required>
  The updated agent object with all current settings.

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

    <ResponseField name="name" type="string" required>
      The name of the agent.
    </ResponseField>

    <ResponseField name="label" type="string" required>
      The display label for the agent.
    </ResponseField>

    <ResponseField name="description" type="string" required>
      Updated description of the agent's purpose and functionality.
    </ResponseField>

    <ResponseField name="initial_message" type="string">
      Updated initial message the agent will say.
    </ResponseField>

    <ResponseField name="interrupt_sensitivity" type="string" required>
      Updated interrupt sensitivity level.
    </ResponseField>

    <ResponseField name="ask_if_human_present_on_idle" type="boolean" required>
      Updated setting for asking if human is present when idle.
    </ResponseField>

    <ResponseField name="llm_temperature" type="number" required>
      Updated LLM temperature setting.
    </ResponseField>

    <ResponseField name="initial_message_delay" type="integer" required>
      Updated initial message delay in seconds.
    </ResponseField>

    <ResponseField name="current_status" type="string" required>
      Current status of the agent (will be set to "draft" after update).
    </ResponseField>

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

## Error responses

### Validation Error (422)

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
      "description": [
        "The description field is required."
      ],
      "interrupt_sensitivity": [
        "The selected interrupt sensitivity is invalid."
      ],
      "llm_temperature": [
        "The llm temperature must be between 0 and 2."
      ],
      "initial_message_delay": [
        "The initial message delay must be between 0 and 60."
      ]
    }
  }
  ```
</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 perform this action."
  }
  ```
</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 update this agent | 403         |
| `VALIDATION_ERROR` | Request data validation failed                     | 422         |

## Important notes

<Info>
  **Agent status will be set to draft.** After updating the agent's knowledge, the agent will be automatically set to "draft" status and will need to be published again to become active.
</Info>

<Info>
  **LLM Temperature affects creativity.** Higher values (closer to 2) make responses more creative and varied, while lower values (closer to 0) make responses more focused and consistent.
</Info>

## Related endpoints

* **Get Agent**: `GET /api/v1/agents/{agent_id}`
* **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`
* **List Agents**: `GET /api/v1/agents`