Synthflow Default API

openapi: 3.2.0
info:
  title: PLATFORM API
  version: 1.0.0
servers:
- url: https://api.synthflow.ai/v2
  description: Global
- url: https://api.us.synthflow.ai/v2
  description: United States
- url: https://api.eu.synthflow.ai/v2
  description: European Union
tags:
- name: ''
paths:
  /assistants:
    post:
      operationId: create-assistant
      summary: Create an agent
      description: ''
      tags:
      - ''
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-assistant_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Create-assistantRequestBadRequestError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                end_call_reasons:
                  type: array
                  items:
                    type: string
                  description: 'Deprecated: use end_call_reasons_v2 instead. Custom conditions that trigger automatic call termination (simple string array format).'
                description:
                  type: string
                  description: Agent description.
                phone_number:
                  type: string
                  description: The phone number attached to the agent.
                external_webhook_url:
                  type: string
                  description: URL of the webhook that should receive data after the call, such as the transcript.
                is_recording:
                  type: boolean
                  description: Whether the conversation should be recorded.
                max_duration:
                  $ref: '#/components/schemas/AssistantsPostRequestBodyContentApplicationJsonSchemaMaxDuration'
                voicemail_message:
                  $ref: '#/components/schemas/AssistantsPostRequestBodyContentApplicationJsonSchemaVoicemailMessage'
                  description: Configuration for the message left when a voicemail is detected. Requires `greeting_message_mode` to be set to `human`.
                type:
                  $ref: '#/components/schemas/type'
                name:
                  $ref: '#/components/schemas/name'
                agent:
                  $ref: '#/components/schemas/AssistantsPostRequestBodyContentApplicationJsonSchemaAgent'
                inbound_call_webhook_url:
                  type: string
                  description: 'The URL for your inbound webhook. For more details on inbound webhooks, see <a href="/webhooks#inbound-webhook">Inbound webhook</a>.

                    '
              required:
              - type
              - name
              - agent
  /assistants/{model_id}:
    put:
      operationId: update-assistant
      summary: Update an agent
      description: "Use this endpoint to update an agent's name, phone number, or other parameters. \n Only the provided parameters will be updated, and others won't be removed or changed."
      tags:
      - ''
      parameters:
      - name: model_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/model_id'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-assistant_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Update-assistantRequestBadRequestError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                end_call_reasons:
                  type: array
                  items:
                    type: string
                  description: 'Deprecated: use end_call_reasons_v2 instead. Custom conditions that trigger automatic call termination (simple string array format).'
                description:
                  type: string
                  description: Agent description.
                phone_number:
                  type: string
                  description: The phone number attached to the agent.
                external_webhook_url:
                  type: string
                  description: URL of the webhook that should receive data after the call, such as the transcript.
                is_recording:
                  type: boolean
                  description: Whether the conversation should be recorded.
                max_duration:
                  $ref: '#/components/schemas/AssistantsModelIdPutRequestBodyContentApplicationJsonSchemaMaxDuration'
                voicemail_message:
                  $ref: '#/components/schemas/AssistantsModelIdPutRequestBodyContentApplicationJsonSchemaVoicemailMessage'
                  description: Configuration for the message left when a voicemail is detected. Requires `greeting_message_mode` to be set to `human`.
                name:
                  $ref: '#/components/schemas/name'
                agent:
                  $ref: '#/components/schemas/Agent'
    delete:
      operationId: delete-assistant
      summary: Delete an agent
      description: Use this endpoint to delete an agent.
      tags:
      - ''
      parameters:
      - name: model_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/model_id'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delete-assistant_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Delete-assistantRequestBadRequestError'
    get:
      operationId: get-assistant
      summary: Get an agent
      description: ''
      tags:
      - ''
      parameters:
      - name: model_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/model_id'
      - name: include_actions
        in: query
        description: Include action IDs and `input_variables` (each with the action's `trigger_condition`) grouped by `action_id`.
        required: false
        schema:
          type: boolean
          default: false
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-assistant_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-assistantRequestBadRequestError'
  /assistants/:
    get:
      operationId: list-assistant
      summary: List agents
      description: Lists all agents you have in your account.
      tags:
      - ''
      parameters:
      - name: limit
        in: query
        description: Agents displayed per page.
        required: false
        schema:
          type: integer
          default: 20
      - name: offset
        in: query
        description: Index of the first agent to be returned.
        required: false
        schema:
          type: integer
          default: 0
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-assistant_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List-assistantRequestBadRequestError'
  /assistants/{model_id}/phone_numbers:
    put:
      operationId: attach-phone-numbers-to-assistant
      summary: Attach phone numbers to an outbound agent
      description: Attach multiple outbound phone numbers to an agent by phone numbers or by slugs.
      tags:
      - ''
      parameters:
      - name: model_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/model_id'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/attach-phone-numbers-to-assistant_Response_200'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attach-phone-numbers-to-assistantRequestNotFoundError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/attach-phone-numbers-to-assistant_Request'
  /assistants/{model_id}/phone_numbers/{phone_number_slug}:
    delete:
      operationId: detach-phone-number-from-assistant
      summary: Detach phone number from an outbound agent
      description: Remove one attached outbound phone number from an agent.
      tags:
      - ''
      parameters:
      - name: model_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/model_id'
      - name: phone_number_slug
        in: path
        description: Phone number slug to remove from the agent.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/detach-phone-number-from-assistant_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detach-phone-number-from-assistantRequestBadRequestError'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detach-phone-number-from-assistantRequestNotFoundError'
  /calls:
    post:
      operationId: voice-call
      summary: Make a call
      description: Initiates a real-time phone call through the AI agent.
      tags:
      - ''
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voice-call_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Voice-callRequestBadRequestError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                model_id:
                  $ref: '#/components/schemas/model_id'
                phone:
                  type: string
                  description: Call recipient's phone number.
                from_phone_number:
                  type: string
                  description: Optional outbound caller ID. Must match a phone number attached to the outbound agent.
                name:
                  type: string
                  description: Call recipient's name.
                custom_variables:
                  type: array
                  items:
                    $ref: '#/components/schemas/CallsPostRequestBodyContentApplicationJsonSchemaCustomVariablesItems'
                  description: Key-value pairs of pre-call variables, called custom variables in the API, that you can dynamically inject into the prompt. [Learn more](/variables#pre-call-variables).
                lead_email:
                  type: string
                  description: The customer's email that can be used to book an appointment.
                lead_timezone:
                  type: string
                  description: The customer's time zone that can be used to book an appointment. For a list of all available time zones, see [Time zones](/time-zones).
                prompt:
                  type: string
                  description: The prompt that the agent will use.
                greeting:
                  type: string
                  description: The greeting the agent will use.
              required:
              - model_id
              - phone
              - name
    get:
      operationId: list-calls
      summary: List calls
      description: Returns a paginated list of calls for the specified model. You can optionally filter by time window, status, duration range, or phone number.
      tags:
      - ''
      parameters:
      - name: model_id
        in: query
        description: The calls for the specified model ID will be returned
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: How many calls will be displayed in every page, default is 20
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        description: Index of the first call to be returned.
        required: false
        schema:
          type: integer
      - name: from_date
        in: query
        description: 'Begin timestamp (milliseconds since epoch) of the call. Available after the call starts. Example: 1732546200000'
        required: false
        schema:
          type: integer
          format: int64
      - name: to_date
        in: query
        description: 'End timestamp (milliseconds since epoch) of the call. Available after the call ends. Example: 1732546200000'
        required: false
        schema:
          type: integer
          format: int64
      - name: call_status
        in: query
        description: Status of call.
        required: false
        schema:
          type: string
      - name: duration_min
        in: query
        description: Only retrieve calls with duration greater than or equal to this value (seconds).
        required: false
        schema:
          type: integer
      - name: duration_max
        in: query
        description: Only retrieve calls with duration less than or equal to this value (seconds).
        required: false
        schema:
          type: integer
      - name: lead_phone_number
        in: query
        description: Phone number of the caller or callee (E.164 format preferred) and URL-encode the leading "+" (e.g. %2B14155552671)
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-calls_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List-callsRequestBadRequestError'
  /calls/outbound-test-ws-media:
    post:
      operationId: start-ws-media-call
      summary: Start a WebSocket media call
      description: Starts an outbound test call and returns a short-lived WebSocket URL for streaming call audio.
      tags:
      - ''
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: WebSocket media call created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/start-ws-media-call_Response_200'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Start-ws-media-callRequestBadRequestError'
        '401':
          description: Missing or invalid API credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Start-ws-media-callRequestUnauthorizedError'
        '502':
          description: Room join failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Start-ws-media-callRequestBadGatewayError'
        '503':
          description: WebSocket media is not enabled in this environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Start-ws-media-callRequestServiceUnavailableError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                modelId:
                  type: string
                  format: uuid
                  description: Agent model UUID.
                fromPhoneNumber:
                  type: string
                  description: Caller ID for the test call.
                toPhoneNumber:
                  type: string
                  description: Destination phone number.
                leadName:
                  type: string
                  description: Lead display name.
                agentVersion:
                  type: string
                  description: Agent version to use. Set to `draft` to test the draft version, pass a version UUID, or omit for the live version.
                wsMediaCodec:
                  $ref: '#/components/schemas/CallsOutboundTestWsMediaPostRequestBodyContentApplicationJsonSchemaWsMediaCodec'
                  default: opus
                  description: Codec to use for the WebSocket media stream. `l16` is raw big-endian 16-bit PCM at 16 kHz.
                wsMediaFraming:
                  $ref: '#/components/schemas/CallsOutboundTestWsMediaPostRequestBodyContentApplicationJsonSchemaWsMediaFraming'
                  default: rtp
                  description: Wire format for the WebSocket media stream. `rtp` (default) sends full RTP packets; `payload` sends raw codec payloads (RTP header stripped), which is simpler for external AI/STT/TTS clients. Use `payload` with `pcma`/`pcmu` — avoid `payload` with `opus` (see the integration guide for why).
                wsMediaServerName:
                  type: string
                  default: ''
                  description: Media node the client reached, taken from the `server-name` in the `server_info` message. Provide it to start the call on that exact node and receive a `sid` to bind over the open WebSocket (connect-then-bind). Omit it only for the legacy single-node flow that returns a ready-to-use `wsMediaUrl`.
              required:
              - modelId
              - fromPhoneNumber
              - toPhoneNumber
  /calls/outbound-test-ws-media/base-url:
    get:
      operationId: get-ws-media-base-url
      summary: Get the WebSocket media base URL
      description: Returns the region-correct WebSocket base URL (no session id) for the connect-then-bind flow. Connect to this URL first, read the `server_info` message, then start the call with `wsMediaServerName` set to the `server-name` you received. This call is stateless and does not start or reserve a call.
      tags:
      - ''
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Base URL issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-ws-media-base-url_Response_200'
        '401':
          description: Missing or invalid API credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-ws-media-base-urlRequestUnauthorizedError'
        '503':
          description: WebSocket media is not enabled in this environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-ws-media-base-urlRequestServiceUnavailableError'
  /calls/{call_id}:
    get:
      operationId: get-phone-call
      summary: Get a call
      description: Retrieve the transcript and other metadata for a phone call.
      tags:
      - ''
      parameters:
      - name: call_id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/call_id'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-phone-call_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-phone-callRequestBadRequestError'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-phone-callRequestNotFoundError'
  /simulation_cases:
    post:
      operationId: create-simulation-case
      summary: Create a simulation case
      description: Create a new simulation case for a workspace.
      tags:
      - ''
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-simulation-case_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Create-simulation-caseRequestBadRequestError'
        '422':
          description: '422'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Create-simulation-caseRequestUnprocessableEntityError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulationCaseCreateIn'
    get:
      operationId: list-simulation-cases
      summary: List simulation cases
      description: List simulation cases with pagination and optional filtering.
      tags:
      - ''
      parameters:
      - name: page_number
        in: query
        description: Page number.
        required: false
        schema:
          type: integer
          default: 1
      - name: page_size
        in: query
        description: Number of items per page.
        required: false
        schema:
          type: integer
          default: 10
      - name: search
        in: query
        description: Search term for simulation case names.
        required: false
        schema:
          type: string
      - name: simulation_case_type
        in: query
        description: Filter by simulation case type.
        required: false
        schema:
          $ref: '#/components/schemas/SimulationCasesGetParametersSimulationCaseType'
      - name: suite_id
        in: query
        description: Filter by simulation suite ID.
        required: false
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-simulation-cases_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List-simulation-casesRequestBadRequestError'
  /simulation_cases/{simulation_case_id}:
    get:
      operationId: get-simulation-case
      summary: Get a simulation case
      description: Retrieve a simulation case by ID.
      tags:
      - ''
      parameters:
      - name: simulation_case_id
        in: path
        description: Simulation case ID.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-simulation-case_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-simulation-caseRequestBadRequestError'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Get-simulation-caseRequestNotFoundError'
    put:
      operationId: update-simulation-case
      summary: Update a simulation case
      description: Update an existing simulation case.
      tags:
      - ''
      parameters:
      - name: simulation_case_id
        in: path
        description: Simulation case ID.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update-simulation-case_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Update-simulation-caseRequestBadRequestError'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Update-simulation-caseRequestNotFoundError'
        '422':
          description: '422'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Update-simulation-caseRequestUnprocessableEntityError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulationCaseUpdateIn'
    delete:
      operationId: delete-simulation-case
      summary: Delete a simulation case
      description: Delete a simulation case by ID.
      tags:
      - ''
      parameters:
      - name: simulation_case_id
        in: path
        description: Simulation case ID.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '204':
          description: '204'
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Delete-simulation-caseRequestBadRequestError'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Delete-simulation-caseRequestNotFoundError'
  /simulation_cases/generate:
    post:
      operationId: generate-simulation-cases
      summary: Generate test cases
      description: Generate test cases for an agent. Supports both custom prompt and flow designer agents. You can optionally specify scenarios to ensure the generated tests cover specific situations. The response is streamed as NDJSON, providing progress and results incrementally.
      tags:
      - ''
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: string
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generate-simulation-casesRequestBadRequestError'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generate-simulation-casesRequestNotFoundError'
        '422':
          description: '422'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Generate-simulation-casesRequestUnprocessableEntityError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulationCaseGenerateIn'
  /simulation_cases/by_agent:
    get:
      operationId: list-simulation-cases-by-agent
      summary: List simulation cases by agent
      description: List all simulation cases created for a specific agent.
      tags:
      - ''
      parameters:
      - name: agent_id
        in: query
        description: Agent ID whose cases to list.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-simulation-cases-by-agent_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List-simulation-cases-by-agentRequestBadRequestError'
  /simulation_suites:
    post:
      operationId: create-simulation-suite
      summary: Create a simulation suite
      description: Create a new simulation suite attached to a specific agent. The suite can only be executed on the agent specified by model_id.
      tags:
      - ''
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-simulation-suite_Response_200'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Create-simulation-suiteRequestBadRequestError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/co

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