openapi: 3.0.3
info:
  title: Cartesia Agents Calls API
  description: 'The Cartesia REST API for real-time voice AI - text-to-speech and voice-changer generation (single-shot bytes or Server-Sent Events), batch speech-to-text transcription, voice management and cloning, audio infill, custom datasets, pronunciation dictionaries, API keys and scoped access tokens, the Voice Agents platform (agents, calls, call batches, phone numbers, telephony providers, webhooks, deployments, knowledge base documents/folders, and evaluation metrics), and usage reporting. All requests require a `Cartesia-Version` header and an `Authorization: Bearer` API key (`sk_car_...`) or short-lived access token. The lowest-latency, streaming surface for TTS and STT is a separate WebSocket protocol documented in the companion AsyncAPI document at asyncapi/cartesia-ai-asyncapi.yml.'
  version: '2026-03-01'
  contact:
    name: Cartesia
    url: https://cartesia.ai
  license:
    name: API documentation - Cartesia Terms of Service
    url: https://cartesia.ai/terms-of-service
servers:
- url: https://api.cartesia.ai
  description: Cartesia production API
security:
- bearerAuth: []
tags:
- name: Calls
  description: Outbound call placement, batching, and history.
paths:
  /calls:
    get:
      operationId: listCalls
      tags:
      - Calls
      summary: List Calls
      parameters:
      - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of calls.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Call'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /calls/outbound:
    post:
      operationId: createOutboundCall
      tags:
      - Calls
      summary: Create Outbound Call
      parameters:
      - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_id
              - to
              properties:
                agent_id:
                  type: string
                to:
                  type: string
                  description: E.164 destination phone number.
                from:
                  type: string
                  description: E.164 originating phone number, if applicable.
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: The queued call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Call'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /calls/{id}:
    parameters:
    - $ref: '#/components/parameters/CallId'
    get:
      operationId: getCall
      tags:
      - Calls
      summary: Get Call
      parameters:
      - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The requested call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Call'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCall
      tags:
      - Calls
      summary: Delete Call
      description: Deletes the sensitive data for a call.
      parameters:
      - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: Deletion confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /calls/{id}/cancel:
    parameters:
    - $ref: '#/components/parameters/CallId'
    post:
      operationId: cancelCall
      tags:
      - Calls
      summary: Cancel Call
      description: Terminates an active call.
      parameters:
      - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The cancelled call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Call'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /calls/{id}/audio:
    parameters:
    - $ref: '#/components/parameters/CallId'
    get:
      operationId: downloadCallAudio
      tags:
      - Calls
      summary: Download Call Audio
      parameters:
      - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The recorded call audio.
          content:
            audio/*:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /calls/{id}/logs:
    parameters:
    - $ref: '#/components/parameters/CallId'
    get:
      operationId: getCallLogs
      tags:
      - Calls
      summary: Get Call Runtime Logs
      parameters:
      - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: Runtime logs for the call.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /call-batches:
    get:
      operationId: listCallBatches
      tags:
      - Calls
      summary: List Call Batches
      parameters:
      - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of call batches.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CallBatch'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCallBatch
      tags:
      - Calls
      summary: Create Call Batch
      description: Queues a batch of outbound calls.
      parameters:
      - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_id
              - recipients
              properties:
                agent_id:
                  type: string
                recipients:
                  type: array
                  items:
                    type: object
                    required:
                    - to
                    properties:
                      to:
                        type: string
                      metadata:
                        type: object
                        additionalProperties: true
      responses:
        '200':
          description: The created call batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallBatch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /call-batches/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: The ID of the call batch.
      schema:
        type: string
    get:
      operationId: getCallBatch
      tags:
      - Calls
      summary: Get Call Batch
      parameters:
      - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The requested call batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallBatch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /call-batches/{id}/cancel:
    parameters:
    - name: id
      in: path
      required: true
      description: The ID of the call batch.
      schema:
        type: string
    post:
      operationId: cancelCallBatch
      tags:
      - Calls
      summary: Cancel Call Batch
      description: Stops dialing the batch's queued calls.
      parameters:
      - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The cancelled call batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallBatch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /call-batches/{id}/retry:
    parameters:
    - name: id
      in: path
      required: true
      description: The ID of the call batch.
      schema:
        type: string
    post:
      operationId: retryCallBatch
      tags:
      - Calls
      summary: Retry Call Batch
      description: Re-queues the batch's recipients whose latest call attempt failed.
      parameters:
      - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The updated call batch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallBatch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    DeleteResponse:
      type: object
      properties:
        id:
          type: string
        deleted:
          type: boolean
    Call:
      type: object
      properties:
        id:
          type: string
        agent_id:
          type: string
        to:
          type: string
        from:
          type: string
          nullable: true
        status:
          type: string
          enum:
          - queued
          - ringing
          - in_progress
          - completed
          - failed
          - cancelled
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        title:
          type: string
        message:
          type: string
        error_code:
          type: string
        status_code:
          type: integer
        doc_url:
          type: string
        request_id:
          type: string
    CallBatch:
      type: object
      properties:
        id:
          type: string
        agent_id:
          type: string
        status:
          type: string
          enum:
          - queued
          - in_progress
          - completed
          - cancelled
        total:
          type: integer
        succeeded:
          type: integer
        failed:
          type: integer
        created_at:
          type: string
          format: date-time
  parameters:
    CallId:
      name: id
      in: path
      required: true
      description: The ID of the call.
      schema:
        type: string
    CartesiaVersion:
      name: Cartesia-Version
      in: header
      required: true
      description: API version date, e.g. 2026-03-01.
      schema:
        type: string
        example: '2026-03-01'
  responses:
    Unauthorized:
      description: Missing, invalid, or expired API key / access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sk_car_... API key or short-lived access token
      description: 'Cartesia API key (sk_car_...) or a short-lived access token minted via POST /access-token, passed as Authorization: Bearer <token>. Every request also requires the Cartesia-Version header.'