openapi: 3.0.1
info:
  title: Retell AI Agent Batch 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: Batch Call
paths:
  /create-batch-call:
    post:
      operationId: createBatchCall
      tags:
      - Batch Call
      summary: Create a batch call.
      description: Queues an outbound calling campaign to many recipients from a single from_number, subject to available concurrency.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBatchCallRequest'
      responses:
        '201':
          description: Batch call created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCallResponse'
components:
  schemas:
    CreateBatchCallRequest:
      type: object
      required:
      - from_number
      - tasks
      properties:
        from_number:
          type: string
        name:
          type: string
        trigger_timestamp:
          type: integer
          description: Unix ms at which to start the campaign; omit to start immediately.
        tasks:
          type: array
          items:
            type: object
            required:
            - to_number
            properties:
              to_number:
                type: string
              retell_llm_dynamic_variables:
                type: object
                additionalProperties:
                  type: string
    BatchCallResponse:
      type: object
      properties:
        batch_call_id:
          type: string
        name:
          type: string
        from_number:
          type: string
        scheduled_timestamp:
          type: integer
        total_task_count:
          type: integer
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: apiKey
      description: 'Retell API key, sent as: Authorization: Bearer <RETELL_API_KEY>'