Bland AI Calls API

openapi: 3.1.0
info:
  title: Bland AI Platform Calls API
  description: 'REST API for the Bland enterprise voice AI platform. Send and manage

    AI phone calls, list call history, fetch call details (transcripts,

    recordings, analysis), and stop active or scheduled calls. All

    requests require the `authorization` header set to your API key.

    '
  version: '1'
  contact:
    name: Bland AI
    url: https://docs.bland.ai
servers:
- url: https://api.bland.ai
security:
- apiKey: []
tags:
- name: Calls
  description: Send, list, retrieve, and stop AI phone calls.
paths:
  /v1/calls:
    post:
      tags:
      - Calls
      summary: Send a call
      description: Initiate an outbound AI phone call.
      operationId: sendCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendCallRequest'
      responses:
        '200':
          description: Call accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendCallResponse'
    get:
      tags:
      - Calls
      summary: List calls
      operationId: listCalls
      parameters:
      - in: query
        name: from_number
        schema:
          type: string
      - in: query
        name: to_number
        schema:
          type: string
      - in: query
        name: from
        schema:
          type: integer
        description: Pagination start index.
      - in: query
        name: to
        schema:
          type: integer
        description: Pagination end index.
      - in: query
        name: limit
        schema:
          type: integer
          default: 1000
      - in: query
        name: start_date
        schema:
          type: string
          format: date
      - in: query
        name: end_date
        schema:
          type: string
          format: date
      - in: query
        name: completed
        schema:
          type: boolean
      - in: query
        name: batch_id
        schema:
          type: string
      - in: query
        name: campaign_id
        schema:
          type: string
      - in: query
        name: duration_gt
        schema:
          type: number
      - in: query
        name: duration_lt
        schema:
          type: number
      responses:
        '200':
          description: Paginated list of calls.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                  count:
                    type: integer
                  calls:
                    type: array
                    items:
                      $ref: '#/components/schemas/CallSummary'
  /v1/calls/{call_id}:
    get:
      tags:
      - Calls
      summary: Get call details
      operationId: getCall
      parameters:
      - in: path
        name: call_id
        required: true
        schema:
          type: string
      - in: header
        name: encrypted_key
        required: false
        schema:
          type: string
        description: Optional encrypted Twilio account key for filtering.
      responses:
        '200':
          description: Full call detail including transcript and summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallDetail'
  /v1/calls/{call_id}/stop:
    post:
      tags:
      - Calls
      summary: Stop an active call
      operationId: stopCall
      parameters:
      - in: path
        name: call_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Stop acknowledged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
components:
  schemas:
    SendCallResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - error
        call_id:
          type: string
        message:
          type: string
        errors:
          type: array
          items:
            type: string
    SendCallRequest:
      type: object
      required:
      - phone_number
      properties:
        phone_number:
          type: string
          description: E.164-formatted destination number.
          example: '+15551234567'
        task:
          type: string
          description: Instructions and example flow for the agent. Required if `pathway_id` is not set.
        pathway_id:
          type: string
          description: Pre-built conversational pathway id. Required if `task` is not set.
        voice:
          type: string
        from:
          type: string
        first_sentence:
          type: string
        wait_for_greeting:
          type: boolean
        record:
          type: boolean
        max_duration:
          type: integer
        webhook:
          type: string
          format: uri
        metadata:
          type: object
          additionalProperties: true
    StatusResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - error
        message:
          type: string
    CallDetail:
      type: object
      properties:
        call_id:
          type: string
        status:
          type: string
        created_at:
          type: string
          format: date-time
        call_length:
          type: number
        to:
          type: string
        from:
          type: string
        completed:
          type: boolean
        summary:
          type: string
        transcripts:
          type: array
          items:
            type: object
            properties:
              user:
                type: string
              text:
                type: string
              created_at:
                type: string
                format: date-time
        recording_url:
          type: string
          format: uri
          nullable: true
        analysis:
          type: object
          additionalProperties: true
        variables:
          type: object
          additionalProperties: true
        price:
          type: number
    CallSummary:
      type: object
      properties:
        call_id:
          type: string
        created_at:
          type: string
          format: date-time
        call_length:
          type: number
        to:
          type: string
        from:
          type: string
        completed:
          type: boolean
        answered_by:
          type: string
        batch_id:
          type: string
          nullable: true
        campaign_id:
          type: string
          nullable: true
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: authorization
      description: Bland API key supplied as the raw value of the `authorization` header.