openapi: 3.0.1
info:
  title: Retell AI Agent Retell LLM 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: Retell LLM
paths:
  /create-retell-llm:
    post:
      operationId: createRetellLLM
      tags:
      - Retell LLM
      summary: Create a Retell LLM response engine.
      description: Creates a Retell-managed LLM response engine (prompt, model, tools, states, and knowledge base references) that an agent can use to drive the conversation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetellLLMRequest'
      responses:
        '201':
          description: Retell LLM created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetellLLMResponse'
  /get-retell-llm/{llm_id}:
    get:
      operationId: getRetellLLM
      tags:
      - Retell LLM
      summary: Retrieve a Retell LLM.
      parameters:
      - $ref: '#/components/parameters/LlmId'
      - $ref: '#/components/parameters/Version'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetellLLMResponse'
  /list-retell-llms:
    get:
      operationId: listRetellLLMs
      tags:
      - Retell LLM
      summary: List all Retell LLMs.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RetellLLMResponse'
  /update-retell-llm/{llm_id}:
    patch:
      operationId: updateRetellLLM
      tags:
      - Retell LLM
      summary: Update a Retell LLM.
      parameters:
      - $ref: '#/components/parameters/LlmId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetellLLMRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetellLLMResponse'
  /delete-retell-llm/{llm_id}:
    delete:
      operationId: deleteRetellLLM
      tags:
      - Retell LLM
      summary: Delete a Retell LLM.
      parameters:
      - $ref: '#/components/parameters/LlmId'
      responses:
        '204':
          description: Retell LLM deleted.
components:
  parameters:
    Version:
      name: version
      in: query
      required: false
      description: Specific version (integer) or version tag to retrieve.
      schema:
        type: string
    LlmId:
      name: llm_id
      in: path
      required: true
      schema:
        type: string
  schemas:
    RetellLLMResponse:
      allOf:
      - $ref: '#/components/schemas/RetellLLMRequest'
      - type: object
        properties:
          llm_id:
            type: string
          version:
            type: integer
          is_published:
            type: boolean
          last_modification_timestamp:
            type: integer
    Tool:
      type: object
      properties:
        type:
          type: string
          enum:
          - end_call
          - transfer_call
          - check_availability_cal
          - book_appointment_cal
          - press_digit
          - custom
        name:
          type: string
        description:
          type: string
        url:
          type: string
          description: Webhook URL for a custom tool.
    RetellLLMRequest:
      type: object
      properties:
        general_prompt:
          type: string
          description: General prompt appended to the system prompt in every state.
        model:
          type: string
          default: gpt-4.1
        model_temperature:
          type: number
          minimum: 0
          maximum: 1
        s2s_model:
          type: string
        begin_message:
          type: string
          description: First utterance said by the agent.
        start_speaker:
          type: string
          enum:
          - agent
          - user
        general_tools:
          type: array
          items:
            $ref: '#/components/schemas/Tool'
        states:
          type: array
          items:
            type: object
        starting_state:
          type: string
        knowledge_base_ids:
          type: array
          items:
            type: string
        default_dynamic_variables:
          type: object
          additionalProperties:
            type: string
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: apiKey
      description: 'Retell API key, sent as: Authorization: Bearer <RETELL_API_KEY>'