openapi: 3.0.3
info:
  title: Cartesia 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: Text-to-Speech
    description: Single-shot and streamed speech generation over plain HTTP.
  - name: Speech-to-Text
    description: Batch transcription of an audio file of any length.
  - name: Voices
    description: Voice catalog management and voice cloning.
  - name: Voice Changer
    description: Transform speech into a different target voice.
  - name: Infill
    description: Generate audio that smoothly connects two existing audio segments.
  - name: Datasets
    description: Audio/text collections used to build custom fine-tunes and voices.
  - name: Pronunciation Dictionaries
    description: Custom pronunciation overrides referenced by TTS requests.
  - name: API Keys
    description: Standard API key metadata.
  - name: Auth
    description: Short-lived, scoped access token generation.
  - name: Agents
    description: Voice agent configuration and public templates.
  - name: Calls
    description: Outbound call placement, batching, and history.
  - name: Phone Numbers
    description: Telephony number provisioning and import.
  - name: Providers
    description: Linked telephony provider accounts.
  - name: Webhooks
    description: Webhook endpoint registration.
  - name: Deployments
    description: Agent deployment inspection.
  - name: Knowledge Base
    description: Documents and folders used by agents.
  - name: Metrics
    description: LLM-as-a-judge quality metrics for agents.
  - name: Usage
    description: Credit and agent usage reporting.
  - name: Status
    description: API health and version.
paths:
  /tts/bytes:
    post:
      operationId: ttsBytes
      tags:
        - Text-to-Speech
      summary: Text-to-Speech (Bytes)
      description: Synthesizes a complete transcript and returns raw audio bytes in a single response.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TtsRequest'
      responses:
        '200':
          description: Synthesized audio.
          content:
            audio/*:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /tts/sse:
    post:
      operationId: ttsSse
      tags:
        - Text-to-Speech
      summary: Text-to-Speech (SSE)
      description: Streams audio chunks with extra metadata (timestamps) from a complete transcript as Server-Sent Events.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TtsRequest'
      responses:
        '200':
          description: Server-Sent Events stream of audio chunks and metadata.
          content:
            text/event-stream:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /stt:
    post:
      operationId: transcribe
      tags:
        - Speech-to-Text
      summary: Batch Speech-to-Text
      description: Transcribes an audio file of any length using the ink-whisper model.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
        - name: encoding
          in: query
          required: false
          description: PCM encoding, required only when uploading raw headerless PCM.
          schema:
            type: string
            enum: [pcm_s16le, pcm_s32le, pcm_f16le, pcm_f32le, pcm_mulaw, pcm_alaw]
        - name: sample_rate
          in: query
          required: false
          description: Sample rate in Hz, required only when uploading raw headerless PCM.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - model
              properties:
                file:
                  type: string
                  format: binary
                  description: 'Audio file. Supported formats: flac, m4a, mp3, mp4, mpeg.'
                model:
                  type: string
                  enum: [ink-whisper]
                language:
                  type: string
                  description: ISO-639-1 code. Defaults to en. Supports 99+ languages.
                  default: en
                timestamp_granularities[]:
                  type: array
                  items:
                    type: string
                    enum: [word]
      responses:
        '200':
          description: The transcript.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscriptResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /voices:
    get:
      operationId: listVoices
      tags:
        - Voices
      summary: List Voices
      description: Returns a paginated list of voices, with search and filtering.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: starting_after
          in: query
          schema:
            type: string
        - name: ending_before
          in: query
          schema:
            type: string
        - name: q
          in: query
          description: Search voices by name, description, or ID.
          schema:
            type: string
        - name: is_owner
          in: query
          schema:
            type: boolean
        - name: gender
          in: query
          schema:
            type: string
            enum: [masculine, feminine, gender_neutral]
        - name: language
          in: query
          schema:
            type: string
        - name: expand[]
          in: query
          schema:
            type: array
            items:
              type: string
              enum: [preview_file_url]
      responses:
        '200':
          description: A page of voices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetVoicesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /voices/clone:
    post:
      operationId: cloneVoice
      tags:
        - Voices
      summary: Clone Voice
      description: Clones a new voice from an uploaded audio clip.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - clip
                - name
                - language
              properties:
                clip:
                  type: string
                  format: binary
                  description: 'Supported audio formats: flac, mp3, mpeg, mpga, oga, ogg, wav, webm.'
                name:
                  type: string
                description:
                  type: string
                language:
                  type: string
                  description: ISO 639-1 code (en, fr, de, es, ...).
                base_voice_id:
                  type: string
                  description: Derive the cloned voice from an existing voice ID.
      responses:
        '200':
          description: The cloned voice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /voices/{id}:
    parameters:
      - $ref: '#/components/parameters/VoiceId'
    get:
      operationId: getVoice
      tags:
        - Voices
      summary: Get Voice
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The requested voice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateVoice
      tags:
        - Voices
      summary: Update Voice
      description: Updates voice metadata (name, description).
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: The updated voice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteVoice
      tags:
        - Voices
      summary: Delete Voice
      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'
  /voices/localize:
    post:
      operationId: localizeVoice
      tags:
        - Voices
      summary: Localize Voice
      description: Creates a new voice from an existing voice localized to a new language and dialect.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - voice_id
                - name
                - language
              properties:
                voice_id:
                  type: string
                name:
                  type: string
                description:
                  type: string
                language:
                  type: string
                original_speaker_gender:
                  type: string
                  enum: [masculine, feminine]
      responses:
        '200':
          description: The localized voice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoiceMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /voice-changer/bytes:
    post:
      operationId: voiceChangerBytes
      tags:
        - Voice Changer
      summary: Voice Changer (Bytes)
      description: Transforms an uploaded speech recording into a different target voice, returning raw audio bytes.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/VoiceChangerRequest'
      responses:
        '200':
          description: Transformed audio.
          content:
            audio/*:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /voice-changer/sse:
    post:
      operationId: voiceChangerSse
      tags:
        - Voice Changer
      summary: Voice Changer (SSE)
      description: Transforms an uploaded speech recording into a different target voice, streamed as Server-Sent Events.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/VoiceChangerRequest'
      responses:
        '200':
          description: Server-Sent Events stream of transformed audio chunks.
          content:
            text/event-stream:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /infill/bytes:
    post:
      operationId: infillBytes
      tags:
        - Infill
      summary: Infill (Bytes)
      description: >-
        Generates audio that smoothly connects two existing audio segments.
        At least one of left_audio or right_audio must be provided.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - transcript
              properties:
                left_audio:
                  type: string
                  format: binary
                  description: Audio preceding the infill text.
                right_audio:
                  type: string
                  format: binary
                  description: Audio following the infill text.
                transcript:
                  type: string
                  description: Text to generate between the two audio segments.
                model_id:
                  type: string
                  enum: [sonic-3, sonic-3-2026-01-12, sonic-3-2025-10-27]
                voice_id:
                  type: string
                language:
                  type: string
                output_format[container]:
                  type: string
                  enum: [raw, wav, mp3]
                output_format[sample_rate]:
                  type: integer
                  enum: [8000, 16000, 22050, 24000, 44100, 48000]
                output_format[encoding]:
                  type: string
                  enum: [pcm_f32le, pcm_s16le, pcm_mulaw, pcm_alaw]
                output_format[bit_rate]:
                  type: integer
                  enum: [32000, 64000, 96000, 128000, 192000]
      responses:
        '200':
          description: Infilled audio.
          content:
            audio/*:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /datasets:
    get:
      operationId: listDatasets
      tags:
        - Datasets
      summary: List Datasets
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of datasets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Dataset'
                  has_more:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
  /datasets/:
    post:
      operationId: createDataset
      tags:
        - Datasets
      summary: Create Dataset
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: The created dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /datasets/{id}:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      operationId: getDataset
      tags:
        - Datasets
      summary: Get Dataset
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The requested dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateDataset
      tags:
        - Datasets
      summary: Update Dataset
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '200':
          description: The updated dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteDataset
      tags:
        - Datasets
      summary: Delete Dataset
      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'
  /datasets/{id}/files:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      operationId: listDatasetFiles
      tags:
        - Datasets
      summary: List files in a dataset
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of dataset files.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DatasetFile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: uploadDatasetFile
      tags:
        - Datasets
      summary: Upload a file to a dataset
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: The uploaded file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetFile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /datasets/{id}/files/{file_id}:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
      - name: file_id
        in: path
        required: true
        description: The ID of the dataset file.
        schema:
          type: string
    delete:
      operationId: deleteDatasetFile
      tags:
        - Datasets
      summary: Remove a file from a dataset
      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'
  /pronunciation-dictionaries:
    get:
      operationId: listPronunciationDictionaries
      tags:
        - Pronunciation Dictionaries
      summary: List pronunciation dictionaries
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of pronunciation dictionaries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PronunciationDictionary'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPronunciationDictionary
      tags:
        - Pronunciation Dictionaries
      summary: Create a pronunciation dictionary
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - rules
              properties:
                name:
                  type: string
                rules:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
      responses:
        '200':
          description: The created pronunciation dictionary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PronunciationDictionary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /pronunciation-dictionaries/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the pronunciation dictionary.
        schema:
          type: string
    get:
      operationId: getPronunciationDictionary
      tags:
        - Pronunciation Dictionaries
      summary: Get a pronunciation dictionary
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The requested pronunciation dictionary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PronunciationDictionary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updatePronunciationDictionary
      tags:
        - Pronunciation Dictionaries
      summary: Update a pronunciation dictionary
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                rules:
                  type: array
                  items:
                    type: object
                    additionalProperties: true
      responses:
        '200':
          description: The updated pronunciation dictionary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PronunciationDictionary'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deletePronunciationDictionary
      tags:
        - Pronunciation Dictionaries
      summary: Delete a pronunciation dictionary
      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'
  /api-keys:
    get:
      operationId: listApiKeys
      tags:
        - API Keys
      summary: List API Keys
      description: Returns a paginated list of standard API keys.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of API keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api-keys/{id}:
    get:
      operationId: getApiKey
      tags:
        - API Keys
      summary: Get API Key
      description: Returns metadata for a single API key.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /access-token:
    post:
      operationId: generateAccessToken
      tags:
        - Auth
      summary: Generate a New Access Token
      description: Generates a short-lived (max 3600s) access token scoped by grants for making API requests, suitable for use in browser clients.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                grants:
                  type: object
                  properties:
                    tts:
                      type: boolean
                    stt:
                      type: boolean
                    agent:
                      type: boolean
                expires_in:
                  type: integer
                  maximum: 3600
                  description: Token validity in seconds.
      responses:
        '200':
          description: The generated access token.
          content:
            application/json:
              schema:
                type: object
                required:
                  - token
                properties:
                  token:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /agents:
    get:
      operationId: listAgents
      tags:
        - Agents
      summary: List Agents
      description: Lists all agents associated with your account.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of agents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Agent'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /agents/templates:
    get:
      operationId: listAgentTemplates
      tags:
        - Agents
      summary: List Templates
      description: List of public, Cartesia-provided agent templates.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of agent templates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /agents/{id}:
    parameters:
      - $ref: '#/components/parameters/AgentId'
    get:
      operationId: getAgent
      tags:
        - Agents
      summary: Get Agent
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The requested agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateAgent
      tags:
        - Agents
      summary: Update Agent
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: The updated agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteAgent
      tags:
        - Agents
      summary: Delete Agent
      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'
  /agents/{id}/phone-numbers:
    parameters:
      - $ref: '#/components/parameters/AgentId'
    get:
      operationId: listAgentPhoneNumbers
      tags:
        - Agents
      summary: Agent Phone Numbers
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: Phone numbers assigned to this agent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PhoneNumber'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /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'
  /phone-numbers:
    get:
      operationId: listPhoneNumbers
      tags:
        - Phone Numbers
      summary: List Phone Numbers
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of phone numbers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PhoneNumber'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /phone-numbers/import:
    post:
      operationId: importPhoneNumber
      tags:
        - Phone Numbers
      summary: Import Phone Number
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - provider_id
                - number
              properties:
                provider_id:
                  type: string
                number:
                  type: string
      responses:
        '200':
          description: The imported phone number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /phone-numbers/provision:
    post:
      operationId: provisionPhoneNumber
      tags:
        - Phone Numbers
      summary: Provision Cartesia Number
      description: Provision a new Cartesia-managed US phone number.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                area_code:
                  type: string
      responses:
        '200':
          description: The provisioned phone number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /phone-numbers/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the phone number.
        schema:
          type: string
    get:
      operationId: getPhoneNumber
      tags:
        - Phone Numbers
      summary: Get Phone Number
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The requested phone number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updatePhoneNumber
      tags:
        - Phone Numbers
      summary: Update Phone Number
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                agent_id:
                  type: string
      responses:
        '200':
          description: The updated phone number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deletePhoneNumber
      tags:
        - Phone Numbers
      summary: Delete Phone Number
      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'
  /providers:
    get:
      operationId: listProviders
      tags:
        - Providers
      summary: List Providers
      description: List telephony provider accounts linked to your account.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of provider accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Provider'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProvider
      tags:
        - Providers
      summary: Create Provider
      description: Link a telephony provider account.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
              properties:
                type:
                  type: string
                  description: e.g. twilio, telnyx.
                credentials:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: The linked provider account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Provider'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /providers/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the provider account.
        schema:
          type: string
    get:
      operationId: getProvider
      tags:
        - Providers
      summary: Get Provider
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The requested provider account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Provider'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateProvider
      tags:
        - Providers
      summary: Update Provider
      description: Update a provider's credentials.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                credentials:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: The updated provider account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Provider'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteProvider
      tags:
        - Providers
      summary: Delete Provider
      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'
  /webhooks:
    get:
      operationId: listWebhooks
      tags:
        - Webhooks
      summary: List Webhooks
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of webhooks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWebhook
      tags:
        - Webhooks
      summary: Create Webhook
      description: Register a webhook endpoint.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
                - events
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: The created webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /webhooks/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the webhook.
        schema:
          type: string
    get:
      operationId: getWebhook
      tags:
        - Webhooks
      summary: Get Webhook
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The requested webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateWebhook
      tags:
        - Webhooks
      summary: Update Webhook
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: The updated webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete Webhook
      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'
  /deployments:
    get:
      operationId: listDeployments
      tags:
        - Deployments
      summary: List Deployments
      description: List of all deployments associated with an agent.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
        - name: agent_id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A page of deployments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Deployment'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /deployments/{id}:
    get:
      operationId: getDeployment
      tags:
        - Deployments
      summary: Get Deployment
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested deployment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /documents:
    get:
      operationId: listDocuments
      tags:
        - Knowledge Base
      summary: List Documents
      description: List all knowledge base documents in your organization.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of documents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDocument
      tags:
        - Knowledge Base
      summary: Create Document
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                folder_id:
                  type: string
      responses:
        '200':
          description: The created document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /documents/bulk:
    post:
      operationId: bulkCreateDocuments
      tags:
        - Knowledge Base
      summary: Bulk Create Documents
      description: Upload up to 100 knowledge base documents in a single request.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                folder_id:
                  type: string
      responses:
        '200':
          description: The created documents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /documents/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
    get:
      operationId: getDocument
      tags:
        - Knowledge Base
      summary: Get Document
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The requested document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateDocument
      tags:
        - Knowledge Base
      summary: Update Document
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                folder_id:
                  type: string
      responses:
        '200':
          description: The updated document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteDocument
      tags:
        - Knowledge Base
      summary: Delete Document
      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'
  /folders:
    get:
      operationId: listFolders
      tags:
        - Knowledge Base
      summary: List Folders
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of folders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Folder'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createFolder
      tags:
        - Knowledge Base
      summary: Create Folder
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                parent_folder_id:
                  type: string
      responses:
        '200':
          description: The created folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /folders/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the folder.
        schema:
          type: string
    get:
      operationId: getFolder
      tags:
        - Knowledge Base
      summary: Get Folder
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The requested folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateFolder
      tags:
        - Knowledge Base
      summary: Update Folder
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                parent_folder_id:
                  type: string
      responses:
        '200':
          description: The updated folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteFolder
      tags:
        - Knowledge Base
      summary: Delete Folder
      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'
  /metrics:
    get:
      operationId: listMetrics
      tags:
        - Metrics
      summary: List Metrics
      description: List of all LLM-as-a-Judge metrics owned by your account.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of metrics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Metric'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createMetric
      tags:
        - Metrics
      summary: Create Metric
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - prompt
              properties:
                name:
                  type: string
                prompt:
                  type: string
      responses:
        '200':
          description: The created metric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metric'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /metrics/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the metric.
        schema:
          type: string
    get:
      operationId: getMetric
      tags:
        - Metrics
      summary: Get Metric
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: The requested metric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metric'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteMetric
      tags:
        - Metrics
      summary: Delete Metric
      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'
  /metrics/{id}/results:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the metric.
        schema:
          type: string
    get:
      operationId: listMetricResults
      tags:
        - Metrics
      summary: List Metric Results
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: A page of metric results.
          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'
  /metrics/{id}/results/export:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the metric.
        schema:
          type: string
    get:
      operationId: exportMetricResults
      tags:
        - Metrics
      summary: Export Metric Results as CSV
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: CSV export of metric results.
          content:
            text/csv:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /agents/{id}/metrics/{metric_id}:
    parameters:
      - $ref: '#/components/parameters/AgentId'
      - name: metric_id
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: addMetricToAgent
      tags:
        - Metrics
      summary: Add Metric to Agent
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: Confirmation the metric was attached.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: removeMetricFromAgent
      tags:
        - Metrics
      summary: Remove Metric from Agent
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
      responses:
        '200':
          description: Confirmation the metric was removed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /usage/credits:
    get:
      operationId: getCreditUsage
      tags:
        - Usage
      summary: Get Credit Usage
      description: Returns your credit usage over time, bucketed by the requested interval.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
        - name: interval
          in: query
          schema:
            type: string
            enum: [hour, day, week, month]
        - name: start
          in: query
          schema:
            type: string
            format: date-time
        - name: end
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Credit usage buckets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        timestamp:
                          type: string
                          format: date-time
                        credits:
                          type: number
        '401':
          $ref: '#/components/responses/Unauthorized'
  /usage/agents:
    get:
      operationId: getAgentUsage
      tags:
        - Usage
      summary: Get Agent Usage
      description: Returns your agent usage over time, bucketed by the requested interval.
      parameters:
        - $ref: '#/components/parameters/CartesiaVersion'
        - name: interval
          in: query
          schema:
            type: string
            enum: [hour, day, week, month]
        - name: agent_id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Agent usage buckets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        timestamp:
                          type: string
                          format: date-time
                        minutes:
                          type: number
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api-status:
    get:
      operationId: getApiStatus
      tags:
        - Status
      summary: API Status and Version
      security: []
      responses:
        '200':
          description: API health and current version.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  version:
                    type: string
components:
  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.
  parameters:
    CartesiaVersion:
      name: Cartesia-Version
      in: header
      required: true
      description: API version date, e.g. 2026-03-01.
      schema:
        type: string
        example: '2026-03-01'
    VoiceId:
      name: id
      in: path
      required: true
      description: The ID of the voice.
      schema:
        type: string
    DatasetId:
      name: id
      in: path
      required: true
      description: The ID of the dataset.
      schema:
        type: string
    AgentId:
      name: id
      in: path
      required: true
      description: The ID of the agent.
      schema:
        type: string
    CallId:
      name: id
      in: path
      required: true
      description: The ID of the call.
      schema:
        type: string
  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'
  schemas:
    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
    DeleteResponse:
      type: object
      properties:
        id:
          type: string
        deleted:
          type: boolean
    VoiceRef:
      type: object
      required:
        - mode
        - id
      properties:
        mode:
          type: string
          enum: [id]
        id:
          type: string
          format: uuid
    OutputFormat:
      type: object
      required:
        - container
        - sample_rate
      properties:
        container:
          type: string
          enum: [raw, wav, mp3]
        encoding:
          type: string
          enum: [pcm_f32le, pcm_s16le, pcm_mulaw, pcm_alaw]
          description: Required for raw and wav containers.
        sample_rate:
          type: integer
          enum: [8000, 16000, 22050, 24000, 44100, 48000]
        bit_rate:
          type: integer
          enum: [32000, 64000, 96000, 128000, 192000]
          description: Required for mp3 container.
    GenerationConfig:
      type: object
      properties:
        volume:
          type: number
          minimum: 0.5
          maximum: 2.0
          default: 1
        speed:
          type: number
          minimum: 0.6
          maximum: 1.5
          default: 1
        emotion:
          type: string
          enum:
            - neutral
            - happy
            - excited
            - calm
            - angry
            - content
            - sad
            - scared
            - proud
            - confident
            - distant
            - skeptical
            - contemplative
            - determined
    TtsRequest:
      type: object
      required:
        - model_id
        - transcript
        - voice
        - output_format
      properties:
        model_id:
          type: string
          enum: [sonic-3.5, sonic-3, sonic-latest]
        transcript:
          type: string
        voice:
          $ref: '#/components/schemas/VoiceRef'
        language:
          type: string
          description: One of 40+ supported language codes (en, fr, de, es, ja, zh, ...).
        output_format:
          $ref: '#/components/schemas/OutputFormat'
        pronunciation_dict_id:
          type: string
          nullable: true
        generation_config:
          $ref: '#/components/schemas/GenerationConfig'
    VoiceChangerRequest:
      type: object
      required:
        - clip
        - voice_id
        - output_format[container]
        - output_format[sample_rate]
      properties:
        clip:
          type: string
          format: binary
          description: Source speech recording to transform.
        voice_id:
          type: string
        output_format[container]:
          type: string
          enum: [raw, wav, mp3]
        output_format[sample_rate]:
          type: integer
          enum: [8000, 16000, 22050, 24000, 44100, 48000]
        output_format[encoding]:
          type: string
          enum: [pcm_f32le, pcm_s16le, pcm_mulaw, pcm_alaw]
        output_format[bit_rate]:
          type: integer
          enum: [32000, 64000, 96000, 128000, 192000]
    WordTiming:
      type: object
      properties:
        word:
          type: string
        start:
          type: number
        end:
          type: number
    TranscriptResponse:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum: [transcript]
        request_id:
          type: string
        text:
          type: string
        language:
          type: string
        duration:
          type: number
        words:
          type: array
          items:
            $ref: '#/components/schemas/WordTiming'
    VoiceMetadata:
      type: object
      properties:
        id:
          type: string
        user_id:
          type: string
        is_owner:
          type: boolean
        is_public:
          type: boolean
        name:
          type: string
        description:
          type: string
        gender:
          type: string
          nullable: true
        language:
          type: string
        country:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        preview_file_url:
          type: string
          nullable: true
    GetVoicesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/VoiceMetadata'
        has_more:
          type: boolean
        next_page:
          type: string
          nullable: true
    Dataset:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        created_at:
          type: string
          format: date-time
    DatasetFile:
      type: object
      properties:
        id:
          type: string
        dataset_id:
          type: string
        name:
          type: string
        size_bytes:
          type: integer
        created_at:
          type: string
          format: date-time
    PronunciationDictionary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        rules:
          type: array
          items:
            type: object
            additionalProperties: true
        created_at:
          type: string
          format: date-time
    ApiKey:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        prefix:
          type: string
          description: Redacted prefix of the key, e.g. sk_car_.
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
          nullable: true
    Agent:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        voice_id:
          type: string
        tts_model_id:
          type: string
        stt_model:
          type: string
        system_prompt:
          type: string
        created_at:
          type: string
          format: date-time
    PhoneNumber:
      type: object
      properties:
        id:
          type: string
        number:
          type: string
          description: E.164 phone number.
        provider_id:
          type: string
          nullable: true
        agent_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    Provider:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          description: e.g. twilio, telnyx.
        created_at:
          type: string
          format: date-time
    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
    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
    Webhook:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
    Deployment:
      type: object
      properties:
        id:
          type: string
        agent_id:
          type: string
        status:
          type: string
        created_at:
          type: string
          format: date-time
    Document:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        folder_id:
          type: string
          nullable: true
        size_bytes:
          type: integer
        created_at:
          type: string
          format: date-time
    Folder:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        parent_folder_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    Metric:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        prompt:
          type: string
        created_at:
          type: string
          format: date-time