> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telleo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update an agent

> Changes only the fields you send; everything else keeps its stored value. Setting `enabled: false` cancels the calls waiting for it (`waiting_calls_canceled`). Send the `updated_at` you last read as `If-Match` (or `expected_updated_at` in the body) to refuse the change with `409 version_conflict` if someone saved the agent since.

Scope: `agents:manage`.



## OpenAPI

````yaml /api-reference/openapi.json patch /agents/{id}
openapi: 3.1.0
info:
  title: Telleo API
  version: 1.3.0
  description: >-
    Start AI phone calls, or connect your counsellors to contacts, from your own
    systems and get each call's outcome back. Manage your counsellors and AI
    agents from the same API.
servers:
  - url: https://api.telleo.ai/v1
security:
  - ApiKey: []
tags:
  - name: Calls
  - name: Batches
  - name: Agents
  - name: Human calls
  - name: Counsellors
  - name: Credits
  - name: Webhook
paths:
  /agents/{id}:
    patch:
      tags:
        - Agents
      summary: Update an agent
      description: >-
        Changes only the fields you send; everything else keeps its stored
        value. Setting `enabled: false` cancels the calls waiting for it
        (`waiting_calls_canceled`). Send the `updated_at` you last read as
        `If-Match` (or `expected_updated_at` in the body) to refuse the change
        with `409 version_conflict` if someone saved the agent since.


        Scope: `agents:manage`.
      operationId: updateAgent
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: If-Match
          in: header
          required: false
          schema:
            type: string
          description: >-
            The agent's `updated_at` as you last read it, e.g.
            `"2026-10-19T10:15:00.123456Z"`. Optional.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgent'
            example:
              opening_line: Namaste {{name}}!
              max_call_minutes: 6
      responses:
        '200':
          description: The updated agent.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDetail'
        '400':
          description: The request is not valid.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  value:
                    error:
                      code: invalid_request
                      message: >-
                        speech_cache_mode is read-only: support sets it per
                        agent.
                      request_id: req_8f2c1a7e
        '401':
          description: The key is missing, unknown, revoked or expired.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_api_key:
                  value:
                    error:
                      code: missing_api_key
                      message: Send your API key in the X-API-Key header.
                      request_id: req_8f2c1a7e
                invalid_api_key:
                  value:
                    error:
                      code: invalid_api_key
                      message: This API key is not valid.
                      request_id: req_8f2c1a7e
        '403':
          description: >-
            The key lacks the agents:manage scope. Keys only have it when
            created with it.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                insufficient_scope:
                  value:
                    error:
                      code: insufficient_scope
                      message: This API key does not have the agents:manage scope.
                      request_id: req_8f2c1a7e
        '404':
          description: No agent with this id in your account.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                agent_not_found:
                  value:
                    error:
                      code: agent_not_found
                      message: >-
                        No agent 17ea… in this account. List your agents with
                        GET /v1/agents.
                      request_id: req_8f2c1a7e
        '409':
          description: The name is taken, or the agent changed since `If-Match`.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                agent_name_taken:
                  value:
                    error:
                      code: agent_name_taken
                      message: An agent named Kabir already exists in this account.
                      request_id: req_8f2c1a7e
                version_conflict:
                  value:
                    error:
                      code: version_conflict
                      message: >-
                        The agent changed since you read it. GET it again,
                        re-apply your change and retry.
                      request_id: req_8f2c1a7e
        '422':
          description: A value is not supported.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_voice:
                  value:
                    error:
                      code: invalid_voice
                      message: voice is required for the sarvam engine.
                      request_id: req_8f2c1a7e
                unsupported_language:
                  value:
                    error:
                      code: unsupported_language
                      message: language klingon is not supported.
                      request_id: req_8f2c1a7e
        '429':
          description: Too many requests for this key.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error:
                      code: rate_limited
                      message: Too many requests. Retry after 12 seconds.
                      request_id: req_8f2c1a7e
components:
  schemas:
    UpdateAgent:
      type: object
      minProperties: 1
      description: Only the fields you send change. Send `null` to clear a nullable field.
      properties:
        name:
          type: string
          maxLength: 128
          description: Unique in your account, ignoring case.
        enabled:
          type: boolean
          default: true
        direction:
          type: string
          enum:
            - outbound
            - inbound
            - both
          default: outbound
          description: >-
            `outbound` places calls, `inbound` answers your numbers, `both` does
            both.
        language:
          type:
            - string
            - 'null'
          description: >-
            hinglish, hindi, english, punjabi, marathi, gujarati, bengali,
            tamil, telugu, kannada, malayalam, odia, a code (`hi`) or a tag
            (`hi-IN`). `null` = Hindi or Hinglish.
          example: hinglish
        tts_model:
          type: string
          description: >-
            Voice engine id from `GET /voices`. Default for a new agent:
            `google`.
        voice:
          type: string
          description: >-
            A voice of `tts_model` (`GET /voices`). Changing `tts_model` needs a
            voice of the new engine.
        opening_line:
          type: string
          maxLength: 2000
          description: >-
            The first thing the agent says. `{{placeholders}}` are filled per
            call.
        system_prompt:
          type: string
          maxLength: 60000
          description: The agent's script and instructions.
        extraction_questions:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 500
          description: Questions whose answers come back in `outcome.answers`.
        dispositions:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 64
          description: Labels the agent may give a call. Empty = your account's defaults.
        handoff_numbers:
          type: array
          maxItems: 10
          items:
            type: string
          description: E.164 numbers the agent can transfer a caller to.
        max_call_minutes:
          type:
            - integer
            - 'null'
          minimum: 1
          maximum: 30
          description: '`null` = 10 minutes.'
        pace:
          type:
            - number
            - 'null'
          minimum: 0.5
          maximum: 2
          description: Speaking rate; `null` = default.
        temperature:
          type:
            - number
            - 'null'
          minimum: 0.01
          maximum: 2
          description: Voice expressiveness; `null` = engine default.
        voice_modulation:
          type:
            - number
            - 'null'
          minimum: 1
          maximum: 2.5
          description: Pitch-range expansion; `null` = off.
        booking_page_id:
          type:
            - string
            - 'null'
          description: A booking page of your account the agent books on.
        send_rules:
          type: array
          items:
            type: object
            additionalProperties: true
            description: >-
              A post-call or mid-call action (send a WhatsApp template or an
              email, or book a meeting) and when it fires. Same rules as the
              dashboard's agent editor, snake_case (`action_type`,
              `message_body`, `booking_page_id`, `when.meeting_requested` …).
              Not used on API calls.
    AgentDetail:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          const: agent
        name:
          type: string
          maxLength: 128
          description: Unique in your account, ignoring case.
        enabled:
          type: boolean
          default: true
        direction:
          type: string
          enum:
            - outbound
            - inbound
            - both
          default: outbound
          description: >-
            `outbound` places calls, `inbound` answers your numbers, `both` does
            both.
        language:
          type:
            - string
            - 'null'
          description: >-
            hinglish, hindi, english, punjabi, marathi, gujarati, bengali,
            tamil, telugu, kannada, malayalam, odia, a code (`hi`) or a tag
            (`hi-IN`). `null` = Hindi or Hinglish.
          example: hinglish
        tts_model:
          type: string
          description: >-
            Voice engine id from `GET /voices`. Default for a new agent:
            `google`.
        voice:
          type: string
          description: >-
            A voice of `tts_model` (`GET /voices`). Changing `tts_model` needs a
            voice of the new engine.
        opening_line:
          type: string
          maxLength: 2000
          description: >-
            The first thing the agent says. `{{placeholders}}` are filled per
            call.
        system_prompt:
          type: string
          maxLength: 60000
          description: The agent's script and instructions.
        extraction_questions:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 500
          description: Questions whose answers come back in `outcome.answers`.
        dispositions:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 64
          description: Labels the agent may give a call. Empty = your account's defaults.
        handoff_numbers:
          type: array
          maxItems: 10
          items:
            type: string
          description: E.164 numbers the agent can transfer a caller to.
        max_call_minutes:
          type:
            - integer
            - 'null'
          minimum: 1
          maximum: 30
          description: '`null` = 10 minutes.'
        pace:
          type:
            - number
            - 'null'
          minimum: 0.5
          maximum: 2
          description: Speaking rate; `null` = default.
        temperature:
          type:
            - number
            - 'null'
          minimum: 0.01
          maximum: 2
          description: Voice expressiveness; `null` = engine default.
        voice_modulation:
          type:
            - number
            - 'null'
          minimum: 1
          maximum: 2.5
          description: Pitch-range expansion; `null` = off.
        booking_page_id:
          type:
            - string
            - 'null'
          description: A booking page of your account the agent books on.
        send_rules:
          type: array
          items:
            type: object
            additionalProperties: true
            description: >-
              A post-call or mid-call action (send a WhatsApp template or an
              email, or book a meeting) and when it fires. Same rules as the
              dashboard's agent editor, snake_case (`action_type`,
              `message_body`, `booking_page_id`, `when.meeting_requested` …).
              Not used on API calls.
        is_default:
          type: boolean
          description: >-
            This is your account's default agent (`GET
            /settings/default-agent`).
        speech_cache_mode:
          type: string
          enum:
            - 'off'
            - fixed
            - full
          description: Read-only; set by support.
        configuration:
          type: string
          enum:
            - full
            - summary
          description: >-
            `summary` for a key without `agents:manage`: `system_prompt`,
            `handoff_numbers`, `send_rules` and `booking_page_id` are left out.
        uses_contact_name:
          type: boolean
        variables:
          type: array
          items:
            type: string
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        updated_at:
          type:
            - string
            - 'null'
          format: date-time
        waiting_calls_canceled:
          type: integer
          description: >-
            On disable (and a PATCH of `enabled`): calls that were waiting for
            this agent and were canceled.
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/Warning'
          description: >-
            Non-fatal notes about what was (not) done, e.g.
            `mobile_number_missing`.
        idempotent_replay:
          type: boolean
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable code. Branch on this, not on the message.
              example: invalid_request
            message:
              type: string
              description: A sentence you can log or show to an operator.
            request_id:
              type: string
              description: Quote this when you contact support.
            details:
              type: object
              additionalProperties: true
              description: >-
                Extra context, e.g. `errors: [{field, message}]` for validation
                errors or `call_id` for conflicts.
    Warning:
      type: object
      description: >-
        Something in the request that was accepted but may not do what you
        expect.
      properties:
        field:
          type: string
          example: variables.date
        code:
          type: string
          enum:
            - reserved_variable
        message:
          type: string
          example: >-
            {{date}} in the agent's script is always filled with the current
            date and time; this value does not replace it. The agent receives it
            only as information about the contact.
  headers:
    RequestId:
      schema:
        type: string
      description: Unique id of this request. Quote it to support.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your AI calling API key (`vak_call_…`). `Authorization: Bearer <key>`
        also works.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.