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

# Delete an agent

> Deletes an agent nothing uses any more. While it is the default agent, an IVR step, a workflow's AI call step, or has calls waiting, it is refused with `agent_in_use` and the list of places.

Scope: `agents:manage`.



## OpenAPI

````yaml /api-reference/openapi.json delete /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}:
    delete:
      tags:
        - Agents
      summary: Delete an agent
      description: >-
        Deletes an agent nothing uses any more. While it is the default agent,
        an IVR step, a workflow's AI call step, or has calls waiting, it is
        refused with `agent_in_use` and the list of places.


        Scope: `agents:manage`.
      operationId: deleteAgent
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Deleted.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  object:
                    type: string
                  deleted:
                    type: boolean
        '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 agent is still in use.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: agent_in_use
                  message: This agent is still in use…
                  request_id: req_8f2c1a7e
                  details:
                    used_by:
                      - type: default_agent
                      - type: ivr_step
                        menu_id: m-1
                        menu_name: Main
                        menu_enabled: true
                        step_id: n-2
                        step_label: Talk to AI
                      - type: workflow
                        workflow_id: w-1
                        workflow_name: New lead nurture
                        workflow_status: active
                        node_id: nt-9
                        node_name: AI call
                      - type: waiting_calls
                        count: 12
        '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:
  headers:
    RequestId:
      schema:
        type: string
      description: Unique id of this request. Quote it to support.
  schemas:
    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.
  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.