openapi: 3.0.1
info:
  title: Retell AI Agent API
  description: REST API for building, testing, and deploying AI voice agents that make and receive phone and web calls. Configure a response engine (Retell LLM, a custom LLM, or a Conversation Flow), attach a voice, provision phone numbers, place outbound and web calls, run batch campaigns, ground agents with knowledge bases, and read back transcripts, recordings, and call analysis. All endpoints are authenticated with a Bearer API key.
  termsOfService: https://www.retellai.com/terms-of-service
  contact:
    name: Retell AI Support
    url: https://docs.retellai.com
  version: '2.0'
servers:
- url: https://api.retellai.com
security:
- api_key: []
tags:
- name: Agent
paths:
  /create-agent:
    post:
      operationId: createAgent
      tags:
      - Agent
      summary: Create a new voice agent.
      description: Creates an agent that pairs a response engine (retell-llm, custom-llm, or conversation-flow) with a voice and call-behavior settings.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
      responses:
        '201':
          description: Agent created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
  /get-agent/{agent_id}:
    get:
      operationId: getAgent
      tags:
      - Agent
      summary: Retrieve an agent.
      parameters:
      - $ref: '#/components/parameters/AgentId'
      - $ref: '#/components/parameters/Version'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
  /list-agents:
    get:
      operationId: listAgents
      tags:
      - Agent
      summary: List all agents.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentResponse'
  /update-agent/{agent_id}:
    patch:
      operationId: updateAgent
      tags:
      - Agent
      summary: Update an agent.
      parameters:
      - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
  /delete-agent/{agent_id}:
    delete:
      operationId: deleteAgent
      tags:
      - Agent
      summary: Delete an agent.
      parameters:
      - $ref: '#/components/parameters/AgentId'
      responses:
        '204':
          description: Agent deleted.
components:
  parameters:
    Version:
      name: version
      in: query
      required: false
      description: Specific version (integer) or version tag to retrieve.
      schema:
        type: string
    AgentId:
      name: agent_id
      in: path
      required: true
      schema:
        type: string
  schemas:
    ResponseEngine:
      type: object
      description: The engine that produces agent responses during a call.
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - retell-llm
          - custom-llm
          - conversation-flow
        llm_id:
          type: string
          description: Retell LLM id when type is retell-llm.
        llm_websocket_url:
          type: string
          description: Your WebSocket URL when type is custom-llm. Retell connects to `{this-url}/{call_id}` at call start.
        conversation_flow_id:
          type: string
          description: Conversation flow id when type is conversation-flow.
        version:
          type: integer
    AgentResponse:
      allOf:
      - $ref: '#/components/schemas/AgentRequest'
      - type: object
        properties:
          agent_id:
            type: string
          version:
            type: integer
          is_published:
            type: boolean
          last_modification_timestamp:
            type: integer
    AgentRequest:
      type: object
      required:
      - response_engine
      - voice_id
      properties:
        response_engine:
          $ref: '#/components/schemas/ResponseEngine'
        voice_id:
          type: string
          example: 11labs-Adrian
        agent_name:
          type: string
        voice_model:
          type: string
        voice_speed:
          type: number
          minimum: 0.5
          maximum: 2
        voice_temperature:
          type: number
          minimum: 0
          maximum: 2
        language:
          type: string
          default: en-US
        webhook_url:
          type: string
        responsiveness:
          type: number
          minimum: 0
          maximum: 1
        interruption_sensitivity:
          type: number
          minimum: 0
          maximum: 1
        ambient_sound:
          type: string
        end_call_after_silence_ms:
          type: integer
        stt_mode:
          type: string
          enum:
          - fast
          - accurate
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: apiKey
      description: 'Retell API key, sent as: Authorization: Bearer <RETELL_API_KEY>'