openapi: 3.0.1
info:
  title: Retell AI Agent Web Call 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: Web Call
paths:
  /v2/create-web-call:
    post:
      operationId: createWebCall
      tags:
      - Web Call
      summary: Create a web call.
      description: Registers a browser-based (WebRTC) call and returns an access_token to hand to the Retell Web Client SDK in your frontend.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebCallRequest'
      responses:
        '201':
          description: Web call registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebCallResponse'
components:
  schemas:
    CreateWebCallRequest:
      type: object
      required:
      - agent_id
      properties:
        agent_id:
          type: string
        agent_version:
          type: integer
        metadata:
          type: object
        retell_llm_dynamic_variables:
          type: object
          additionalProperties:
            type: string
    WebCallResponse:
      type: object
      properties:
        call_id:
          type: string
        call_type:
          type: string
          enum:
          - web_call
        access_token:
          type: string
          description: Token to pass to the Retell Web Client SDK in your frontend.
        agent_id:
          type: string
        agent_version:
          type: integer
        call_status:
          $ref: '#/components/schemas/CallStatus'
    CallStatus:
      type: string
      enum:
      - registered
      - ongoing
      - ended
      - error
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: apiKey
      description: 'Retell API key, sent as: Authorization: Bearer <RETELL_API_KEY>'