Synthflow Default API
The Default API from Synthflow — 49 operation(s) for default.
OpenAPI Specification
openapi: 3.1.0
info:
title: Platform API
version: 1.0.0
servers:
- url: https://api.synthflow.ai/v2
- url: https://api.us.synthflow.ai/v2
- url: https://api.eu.synthflow.ai/v2
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="/inbound-webhook">About inbound call webhooks</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: 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 custom variables that you can dynamically inject into the prompt. [Learn more](/custom-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/{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: '#/components/schemas/SimulationSuiteCreateIn'
get:
operationId: list-simulation-suites
summary: List simulation suites
description: List simulation suites 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 suite names.
required: false
schema:
type: string
- name: model_ids
in: query
description: Filter by list of model IDs.
required: false
schema:
type: array
items:
type: string
- name: start_date
in: query
description: Filter by created_at >= start_date (ISO format).
required: false
schema:
type: string
format: date-time
- name: end_date
in: query
description: Filter by created_at <= end_date (ISO format).
required: false
schema:
type: string
format: date-time
- 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-suites_Response_200'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/List-simulation-suitesRequestBadRequestError'
/simulation_suites/{suite_id}:
get:
operationId: get-simulation-suite
summary: Get a simulation suite
description: Retrieve a simulation suite by ID.
tags:
- ''
parameters:
- name: suite_id
in: path
description: Simulation suite 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-suite_Response_200'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/Get-simulation-suiteRequestBadRequestError'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/Get-simulation-suiteRequestNotFoundError'
put:
operationId: update-simulation-suite
summary: Update a simulation suite
description: Update an existing simulation suite.
tags:
- ''
parameters:
- name: suite_id
in: path
description: Simulation suite 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-suite_Response_200'
'400':
description: '400'
content:
application/json:
schema:
$ref: '#/components/schemas/Update-simulation-suiteRequestBadRequestError'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/Update-simulation-suiteRequestNotFoundError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SimulationSuiteUpdateIn'
delete:
operationId: delete-simulation-suite
summary: Delete a simulation suite
description: Delete a simulation suite by ID.
tags:
- ''
parameters:
- name: suite_id
in: path
description: Simulation suite 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-suiteRequestBadRequestError'
'404':
description: '404'
content:
application/json:
schema:
$ref: '#/components/schemas/Delete-simulation-suiteRequestNotFoundError'
/simulation_suites/{suite_id}/execute:
post:
operationId: execute-simulation-suite
summary: Execute a simulation suite
# --- truncated at 32 KB (323 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/synthflow/refs/heads/main/openapi/synthflow-default-api-openapi.yml