openapi: 3.0.1
info:
  title: Retell AI Agent Phone 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: Phone Call
paths:
  /v2/create-phone-call:
    post:
      operationId: createPhoneCall
      tags:
      - Phone Call
      summary: Create an outbound phone call.
      description: Places an outbound PSTN call from a number you own to a destination number, handled by the agent bound to the from_number (or an override agent).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePhoneCallRequest'
      responses:
        '201':
          description: Phone call registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneCallResponse'
components:
  schemas:
    CreatePhoneCallRequest:
      type: object
      required:
      - from_number
      - to_number
      properties:
        from_number:
          type: string
          description: E.164 number you own.
          example: '+14157774444'
        to_number:
          type: string
          description: E.164 destination number.
          example: '+12137774445'
        override_agent_id:
          type: string
        override_agent_version:
          type: integer
        metadata:
          type: object
        retell_llm_dynamic_variables:
          type: object
          additionalProperties:
            type: string
        custom_sip_headers:
          type: object
          additionalProperties:
            type: string
    CallStatus:
      type: string
      enum:
      - registered
      - ongoing
      - ended
      - error
    PhoneCallResponse:
      type: object
      properties:
        call_id:
          type: string
        call_type:
          type: string
          enum:
          - phone_call
        agent_id:
          type: string
        agent_version:
          type: integer
        call_status:
          $ref: '#/components/schemas/CallStatus'
        from_number:
          type: string
        to_number:
          type: string
        direction:
          type: string
          enum:
          - inbound
          - outbound
        telephony_identifier:
          type: object
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: apiKey
      description: 'Retell API key, sent as: Authorization: Bearer <RETELL_API_KEY>'