find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/phonic-conversations-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: 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:
    conversations_evaluate_Response_201:
      type: object
      properties:
        evaluation:
          $ref: '#/components/schemas/ConversationsIdEvalsPostResponsesContentApplicationJsonSchemaEvaluation'
      required:
      - evaluation
      title: conversations_evaluate_Response_201
    ConversationsIdEvalsPostResponsesContentApplicationJsonSchemaEvaluation:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/ConversationsIdEvalsPostResponsesContentApplicationJsonSchemaEvaluationResult'
          description: The evaluation result.
      required:
      - result
      title: ConversationsIdEvalsPostResponsesContentApplicationJsonSchemaEvaluation
    ConversationsListResponseConversationsPagination:
      type: object
      properties:
        prev_cursor:
          type:
          - string
          - 'null'
          description: Cursor to fetch the previous page of conversations (newer). Use this value in the `before` query parameter. `null` if there is no previous page.
        next_cursor:
          type:
          - string
          - 'null'
          description: Cursor to fetch the next page of conversations (older). Use this value in the `after` query parameter. `null` if there is no next page.
      required:
      - prev_cursor
      - next_cursor
      title: ConversationsListResponseConversationsPagination
    ConversationExtraction:
      type: object
      properties:
        id:
          type: string
          description: The extraction ID.
        schema:
          $ref: '#/components/schemas/ConversationExtractionSchema'
        result:
          type: object
          additionalProperties:
            description: Any type
          description: The extracted data.
        created_at:
          type: string
          format: date-time
          description: When the extraction was created.
      required:
      - id
      - schema
      - result
      - created_at
      title: ConversationExtraction
    EvaluateConversationRequest:
      type: object
      properties:
        prompt_id:
          type: string
          description: ID of the evaluation prompt to use.
      required:
      - prompt_id
      title: EvaluateConversationRequest
    OutboundCallInitiatedResponse:
      type: object
      properties:
        conversation_id:
          type: string
          description: The ID of the created conversation.
        dry_run:
          type: boolean
          description: Always false when a call was placed.
      required:
      - conversation_id
      - dry_run
      title: OutboundCallInitiatedResponse
    DataRetentionPolicyOneOf1Transcripts:
      type: object
      properties:
        delete_after_hours:
          type:
          - integer
          - 'null'
          description: Number of hours after which transcripts are deleted. Null means transcripts are retained indefinitely.
      required:
      - delete_after_hours
      title: DataRetentionPolicyOneOf1Transcripts
    Conversation:
      type: object
      properties:
        id:
          type: string
          description: The conversation ID.
        agent:
          oneOf:
          - $ref: '#/components/schemas/ConversationAgent'
          - type: 'null'
          description: The agent associated with the conversation.
        workspace:
          type: string
          description: The organization/workspace name.
        project:
          $ref: '#/components/schemas/ConversationProject'
          description: The project associated with the conversation.
        external_id:
          type:
          - string
          - 'null'
          description: External ID for conversation tracking.
        origin:
          $ref: '#/components/schemas/ConversationOrigin'
          description: The origin of the conversation.
        model:
          type: string
          description: The STS model used.
        generate_welcome_message:
          type: boolean
          description: Will be `true` if welcome message was automatically generated.
        is_welcome_message_interruptible:
          type: boolean
          description: When `false`, the welcome message will not be interruptible by the user.
        welcome_message:
          type:
          - string
          - 'null'
          description: Welcome message played at start. Will be `null` when `generate_welcome_message` is `true`.
        template_variables:
          type: object
          additionalProperties:
            type: string
          description: Template variables used in the conversation.
        system_prompt:
          type:
          - string
          - 'null'
          description: System prompt used in the conversation.
        input_format:
          type: string
          description: Audio input format.
        output_format:
          type: string
          description: Audio output format.
        background_noise_level:
          type: number
          format: double
          description: Background noise level used in the conversation.
        background_noise:
          $ref: '#/components/schemas/ConversationBackgroundNoise'
          description: The background noise type used in the conversation.
        live_transcript:
          type:
          - string
          - 'null'
          description: Live transcript of the conversation.
        post_call_transcript:
          type:
          - string
          - 'null'
          description: Post-call processed transcript.
        duration_ms:
          type: number
          format: double
          description: Duration of the conversation in milliseconds.
        audio_url:
          type:
          - string
          - 'null'
          format: uri
          description: Presigned URL to the conversation audio file. Expires in 1 day.
        started_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the conversation started.
        ended_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the conversation ended.
        ended_by:
          $ref: '#/components/schemas/ConversationEndedBy'
          description: Who or what ended the conversation.
        boosted_keywords:
          type:
          - array
          - 'null'
          items:
            type: string
          description: These words, or short p

# --- 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