Phonic conversations API

openapi: 3.1.0
info:
  title: API Reference agents conversations API
  version: 1.0.0
servers:
- url: https://api.phonic.ai/v1
  description: https://api.phonic.ai/v1
tags:
- name: conversations
paths:
  /conversations:
    get:
      operationId: list
      summary: List
      description: Returns conversations with optional filtering.
      tags:
      - conversations
      parameters:
      - name: project
        in: query
        description: The name of the project to list conversations for.
        required: false
        schema:
          type: string
          default: main
      - name: external_id
        in: query
        description: Filter by external ID to get a specific conversation.
        required: false
        schema:
          type: string
      - name: duration_min
        in: query
        description: Minimum duration in seconds.
        required: false
        schema:
          type: integer
      - name: duration_max
        in: query
        description: Maximum duration in seconds.
        required: false
        schema:
          type: integer
      - name: started_at_min
        in: query
        description: 'Minimum start date/time. Valid examples: `2025-04-17`, `2025-04-17T02:48:52.708Z`'
        required: false
        schema:
          type: string
      - name: started_at_max
        in: query
        description: 'Maximum start date/time. Valid examples: `2025-04-17`, `2025-04-17T02:48:52.708Z`'
        required: false
        schema:
          type: string
      - name: before
        in: query
        description: Cursor for backward pagination. Use a conversation ID from `pagination.prev_cursor` to fetch the previous page of conversations. Cannot be used with `after`.
        required: false
        schema:
          type: string
      - name: after
        in: query
        description: Cursor for forward pagination. Use a conversation ID from `pagination.next_cursor` to fetch the next page of conversations. Cannot be used with `before`.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of conversations to return per page.
        required: false
        schema:
          type: integer
          default: 20
      - name: audio_container
        in: query
        description: Format of the presigned `audio_url` in each conversation in the response.
        required: false
        schema:
          $ref: '#/components/schemas/ConversationsGetParametersAudioContainer'
          default: wav.gz
      - name: Authorization
        in: header
        description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Paginated list (`conversations`, `pagination`) when listing, or a single `conversation` when the `external_id` query parameter matches exactly one conversation.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversations_list_Response_200'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (authentication missing or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '404':
          description: Project or conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
  /conversations/{id}:
    get:
      operationId: get
      summary: Get
      description: Returns a conversation by ID.
      tags:
      - conversations
      parameters:
      - name: id
        in: path
        description: The ID of the conversation to get.
        required: true
        schema:
          type: string
      - name: audio_container
        in: query
        description: Format of the presigned `audio_url` in the response.
        required: false
        schema:
          $ref: '#/components/schemas/ConversationsIdGetParametersAudioContainer'
          default: wav.gz
      - name: Authorization
        in: header
        description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversations_get_Response_200'
        '401':
          description: Unauthorized (authentication missing or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
    delete:
      operationId: delete
      summary: Delete
      description: Deletes a conversation, scheduling its transcripts and audio recordings for deletion. The conversation must have ended.
      tags:
      - conversations
      parameters:
      - name: id
        in: path
        description: The ID of the conversation to delete.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversations_delete_Response_200'
        '401':
          description: Unauthorized (authentication missing or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '409':
          description: Cannot delete an active conversation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
  /conversations/{id}/cancel:
    post:
      operationId: cancel
      summary: Cancel
      description: Cancels an active conversation.
      tags:
      - conversations
      parameters:
      - name: id
        in: path
        description: The ID of the conversation to cancel.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversations_cancel_Response_200'
        '401':
          description: Unauthorized (authentication missing or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '409':
          description: Conversation already ended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '504':
          description: Cancellation timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /conversations/{id}/analysis:
    get:
      operationId: get-analysis
      summary: Get Analysis
      description: Returns an analysis of the specified conversation.
      tags:
      - conversations
      parameters:
      - name: id
        in: path
        description: The ID of the conversation to analyze.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversations_get_analysis_Response_200'
        '401':
          description: Unauthorized (authentication missing or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
  /conversations/{id}/extractions:
    get:
      operationId: list-extractions
      summary: List Extractions
      description: Returns all extractions for a conversation.
      tags:
      - conversations
      parameters:
      - name: id
        in: path
        description: The ID of the conversation to get extractions for.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversations_list_extractions_Response_200'
        '401':
          description: Unauthorized (authentication missing or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
    post:
      operationId: extract-data
      summary: Extract Data
      description: Extracts data from a conversation using a schema.
      tags:
      - conversations
      parameters:
      - name: id
        in: path
        description: The ID of the conversation to extract data from.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversations_extract_data_Response_201'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (authentication missing or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '404':
          description: Conversation or schema not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractDataRequest'
  /conversations/{id}/evals:
    get:
      operationId: list-evaluations
      summary: List Evaluations
      description: Returns all evaluations for a conversation.
      tags:
      - conversations
      parameters:
      - name: id
        in: path
        description: The ID of the conversation to get evaluations for.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversations_list_evaluations_Response_200'
        '401':
          description: Unauthorized (authentication missing or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
    post:
      operationId: evaluate
      summary: Evaluate
      description: Evaluates a conversation using an evaluation prompt.
      tags:
      - conversations
      parameters:
      - name: id
        in: path
        description: The ID of the conversation to evaluate.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversations_evaluate_Response_201'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (authentication missing or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Conversation or evaluation prompt not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluateConversationRequest'
  /conversations/outbound_call:
    post:
      operationId: outbound-call
      summary: Outbound Call
      description: Initiates a call to a given phone number using Phonic's Twilio account.
      tags:
      - conversations
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversations_outbound_call_Response_200'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized (authentication missing or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutboundCallRequest'
  /conversations/sip/outbound_call:
    post:
      operationId: sip-outbound-call
      summary: Sip Outbound Call
      description: Initiates a SIP outbound call using user-supplied SIP credentials in headers.
      tags:
      - conversations
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).
        required: true
        schema:
          type: string
      - name: X-Sip-Address
        in: header
        description: SIP address of the user's SIP trunk. Required.
        required: true
        schema:
          type: string
      - name: X-Sip-Auth-Username
        in: header
        description: SIP auth username, if your provider requires it.
        required: false
        schema:
          type: string
      - name: X-Sip-Auth-Password
        in: header
        description: SIP auth password, if your provider requires it.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversations_sip_outbound_call_Response_200'
        '400':
          description: Invalid query parameters or body, or missing required headers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostConversationsSipOutboundCallRequestBadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '409':
          description: The SIP call could not be completed. The `sip_status_code` and `sip_status` fields contain the carrier's SIP response details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipCallError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                from_phone_number:
                  type: string
                  description: Caller ID phone number in E.164 format.
                to_phone_number:
                  type: string
                  description: Destination phone number in E.164 format.
                config:
                  $ref: '#/components/schemas/OutboundCallConfig'
                dry_run:
                  type: boolean
                  default: false
                  description: If true, validates the outbound call setup without placing a call. Returns HTTP 200 with `conversation_id` and `twilio_call_sid` set to null.
              required:
              - from_phone_number
              - to_phone_number
  /conversations/{id}/replay:
    post:
      operationId: replay
      summary: Replay
      description: 'Replays an ended conversation by re-running its recorded audio through an

        agent. Requires API key or access token authentication. The conversation must

        have audio recordings available and an associated agent (or one specified in

        the request body).

        '
      tags:
      - conversations
      parameters:
      - name: id
        in: path
        description: The ID of the conversation to replay.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Replay started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversations_replay_Response_200'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized (authentication missing or invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '409':
          description: Cannot replay an active conversation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '422':
          description: Conversation cannot be replayed (no audio, deleted recordings, or no agent)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '429':
          description: Concurrency limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
        '503':
          description: Insufficient capacity available to start the replay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplayConversationRequest'
components:
  schemas:
    ConversationItem:
      type: object
      properties:
        id:
          type: string
          description: The conversation item ID.
        item_idx:
          type: integer
          description: Index of the item in the conversation.
        role:
          $ref: '#/components/schemas/ConversationItemRole'
          description: Who spoke in this turn.
        live_transcript:
          type:
          - string
          - 'null'
          description: Live transcript of this turn. `null` when the turn has been redacted.
        post_call_transcript:
          type:
          - string
          - 'null'
          description: Post-call processed transcript.
        redacted_transcript:
          type:
          - string
          - 'null'
          description: The redacted transcript of this turn. `null` when the turn is not redacted.
        duration_ms:
          type: number
          format: double
          description: Duration of this turn in milliseconds.
        started_at:
          type: string
          format: date-time
          description: When this turn started.
        voice_id:
          type: string
          description: Voice ID used (assistant only).
        audio_speed:
          type: number
          format: double
          description: Audio speed used (assistant only).
        system_prompt:
          type: string
          description: System prompt used for this assistant turn.
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ConversationItemToolCallsItems'
          description: Tool calls made by the assistant.
      required:
      - id
      - item_idx
      - role
      - live_transcript
      - post_call_transcript
      - duration_ms
      - started_at
      title: ConversationItem
    DataRetentionPolicy0:
      type: object
      properties:
        zero_data_retention:
          type: boolean
          description: When `true`, no transcripts or audio recordings are retained.
      required:
      - zero_data_retention
      description: Zero data retention mode. No transcripts or audio recordings are retained.
      title: DataRetentionPolicy0
    OutboundCallConfig:
      type: object
      properties:
        agent:
          type: string
          description: The name of the agent to use for the call.
        project:
          type: string
          default: main
          description: The name of the project to use for the call.
        generate_welcome_message:
          type: boolean
          default: false
          description: When `true`, the welcome message will be automatically generated and the `welcome_message` field will be ignored.
        is_welcome_message_interruptible:
          type: boolean
          default: true
          description: When `false`, the welcome message will not be interruptible by the user.
        welcome_message:
          type:
          - string
          - 'null'
          description: Message to play when the conversation starts. Can contain template variables like `{{customer_name}}`. Ignored when `generate_welcome_message` is `true`.
        system_prompt:
          type: string
          default: Respond in 1-2 sentences.
          description: Instructions for the conversation. Can contain template variables like `{{subject}}`.
        template_variables:
          type: object
          additionalProperties:
            type: string
          description: Variables that can be used in the welcome message and the system prompt.
        voice_id:
          type: string
          default: sabrina
          description: The voice ID to use for the agent.
        generate_no_input_poke_text:
          type: boolean
          default: false
          description: Whether to have the no-input poke text be generated by AI.
        no_input_poke_sec:
          type:
          - integer
          - 'null'
          description: Number of seconds of silence before sending a poke message. `null` disables the poke message.
        no_input_poke_text:
          type: string
          default: Are you still there?
          description: The message to send after the specified silence. Ignored when generate_no_input_poke_text is true.
        no_input_end_conversation_sec:
          type: integer
          default: 180
          description: Seconds of silence before ending the conversation.
        default_language:
          $ref: '#/components/schemas/LanguageCode'
          description: ISO 639-1 language code that sets the agent's default language to recognize and speak. Welcome message and no input poke text should be in this language.
        additional_languages:
          type: array
          items:
            $ref: '#/components/schemas/LanguageCode'
          default: []
          description: Array of additional ISO 639-1 language codes that the agent should be able to recognize and speak. Should not include `default_language`. When `multilingual_mode` is `"auto"`, a maximum of 2 additional languages is allowed.
        languages:
          type: array
          items:
            $ref: '#/components/schemas/LanguageCode'
          default:
          - en
          description: Array of ISO 639-1 language codes that the agent should be able to recognize. This field is deprecated. Use `default_language` and `additional_languages` instead.
        multilingual_mode:
          $ref: '#/components/schemas/OutboundCallConfigMultilingualMode'
          default: request
          description: If `"auto"`, each user audio is automatically identified for the language to respond in. If `"request"`, user must request to change language (recommended). If `"initial"` the first turn user audio determines the language for the rest of the conversation.
        push_to_talk:
          type: boolean
          default: false
          description: Push to talk mode. User must send mute/unmute messages to turn on/off listening to audio. Defaults to false.
        intelligence_level:
          $ref: '#/components/schemas/OutboundCallConfigIntelligenceLevel'
          default: standard
          description: The intelligence level of the agent. `high` uses a more capable model for more complex reasoning, while `standard` is optimized for lower latency.
        boosted_keywords:
          type: array
          items:
            type: string
          description: These words, o

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/phonic/refs/heads/main/openapi/phonic-conversations-api-openapi.yml