openapi: 3.1.0
info:
title: API Reference agents API
version: 1.0.0
servers:
- url: https://api.phonic.ai/v1
description: https://api.phonic.ai/v1
tags:
- name: agents
paths:
/agents:
get:
operationId: list
summary: List
description: Returns all agents in a project.
tags:
- agents
parameters:
- name: project
in: query
description: The name of the project to list agents for.
required: false
schema:
type: string
default: main
- 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/agents_list_Response_200'
'404':
description: Project not found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
post:
operationId: create
summary: Create
description: Creates a new agent in a project.
tags:
- agents
parameters:
- name: project
in: query
description: The name of the project to create the agent in.
required: false
schema:
type: string
default: main
- 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/agents_create_Response_201'
'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: Project 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/CreateAgentRequest'
/agents/upsert:
put:
operationId: upsert
summary: Upsert
description: Upserts an agent by name. If an agent with the same name already exists, it will be updated. Otherwise, it will be created.
tags:
- agents
parameters:
- name: project
in: query
description: The name of the project containing the agent.
required: false
schema:
type: string
default: main
- 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/agents_upsert_Response_200'
'400':
description: Invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Project not found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertAgentRequest'
/agents/{nameOrId}:
get:
operationId: get
summary: Get
description: Returns an agent by name or ID.
tags:
- agents
parameters:
- name: nameOrId
in: path
description: The name or the ID of the agent to get.
required: true
schema:
type: string
- name: project
in: query
description: The name of the project containing the agent. Only used when `nameOrId` is a name.
required: false
schema:
type: string
default: main
- 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/agents_get_Response_200'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'404':
description: Agent not found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
delete:
operationId: delete
summary: Delete
description: Deletes an agent by name or ID.
tags:
- agents
parameters:
- name: nameOrId
in: path
description: The name or the ID of the agent to delete.
required: true
schema:
type: string
- name: project
in: query
description: The name of the project containing the agent. Only used when `nameOrId` is a name.
required: false
schema:
type: string
default: main
- 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/agents_delete_Response_200'
'403':
description: Forbidden (resource belongs to a different organization)
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'404':
description: Agent not found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
patch:
operationId: update
summary: Update
description: Updates an agent by name or ID.
tags:
- agents
parameters:
- name: nameOrId
in: path
description: The name or the ID of the agent to update.
required: true
schema:
type: string
- name: project
in: query
description: The name of the project containing the agent. Only used when `nameOrId` is a name.
required: false
schema:
type: string
default: main
- 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/agents_update_Response_200'
'400':
description: Invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'404':
description: Agent not found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAgentRequest'
/agents/{nameOrId}/custom-phone-numbers:
post:
operationId: add-custom-phone-number
summary: Add Custom Phone Number
description: Adds a custom phone number to an agent. The user must configure their SIP trunk to point to Phonic's SIP server.
tags:
- agents
parameters:
- name: nameOrId
in: path
description: The name or the ID of the agent.
required: true
schema:
type: string
- name: project
in: query
description: The name of the project containing the agent. Only used when `nameOrId` is a name.
required: false
schema:
type: string
default: main
- 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. Optional, but if provided, all three SIP headers (X-Sip-Address, X-Sip-Auth-Username, X-Sip-Auth-Password) must be provided. When these headers are provided, call transfers from the agent will use the provided SIP details.
required: false
schema:
type: string
- name: X-Sip-Auth-Username
in: header
description: SIP auth username. Optional, but if provided, all three SIP headers (X-Sip-Address, X-Sip-Auth-Username, X-Sip-Auth-Password) must be provided. When these headers are provided, call transfers from the agent will use the provided SIP details.
required: false
schema:
type: string
- name: X-Sip-Auth-Password
in: header
description: SIP auth password. Optional, but if provided, all three SIP headers (X-Sip-Address, X-Sip-Auth-Username, X-Sip-Auth-Password) must be provided. When these headers are provided, call transfers from the agent will use the provided SIP details.
required: false
schema:
type: string
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/agents_add_custom_phone_number_Response_200'
'400':
description: Invalid parameters or phone number already assigned
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'401':
description: Unsupported authentication method
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'404':
description: Agent not found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'409':
description: The agent is currently being updated. Please try again.
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
requestBody:
content:
application/json:
schema:
type: object
properties:
phone_number:
type: string
description: The E.164 formatted phone number to add (e.g., "+15551234567").
configuration_endpoint:
oneOf:
- $ref: '#/components/schemas/AgentsNameOrIdCustomPhoneNumbersPostRequestBodyContentApplicationJsonSchemaConfigurationEndpoint'
- type: 'null'
description: When not `null`, the agent will call this endpoint to get configuration options for calls on this phone number.
required:
- phone_number
delete:
operationId: delete-custom-phone-number
summary: Delete Custom Phone Number
description: Deletes a custom phone number from an agent.
tags:
- agents
parameters:
- name: nameOrId
in: path
description: The name or the ID of the agent.
required: true
schema:
type: string
- name: project
in: query
description: The name of the project containing the agent. Only used when `nameOrId` is a name.
required: false
schema:
type: string
default: main
- 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/agents_delete_custom_phone_number_Response_200'
'400':
description: Invalid parameters, phone number not assigned to agent, or not a custom phone number
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'401':
description: Unsupported authentication method
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'404':
description: Agent or phone number not found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'409':
description: The agent is currently being updated. Please try again.
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
requestBody:
content:
application/json:
schema:
type: object
properties:
phone_number:
type: string
description: The E.164 formatted phone number to remove (e.g., "+15551234567").
required:
- phone_number
/agents/{nameOrId}/phone-numbers:
patch:
operationId: update-phone-number
summary: Update Phone Number
description: Updates a phone number on an agent.
tags:
- agents
parameters:
- name: nameOrId
in: path
description: The name or the ID of the agent.
required: true
schema:
type: string
- name: project
in: query
description: The name of the project containing the agent. Only used when `nameOrId` is a name.
required: false
schema:
type: string
default: main
- 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/agents_update_phone_number_Response_200'
'400':
description: Invalid parameters or phone number already assigned
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'401':
description: Unsupported authentication method
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'404':
description: Agent not found
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
'409':
description: The agent is currently being updated. Please try again.
content:
application/json:
schema:
$ref: '#/components/schemas/BasicError'
requestBody:
content:
application/json:
schema:
type: object
properties:
phone_number:
type: string
description: The E.164 formatted phone number to add (e.g., "+15551234567").
configuration_endpoint:
oneOf:
- $ref: '#/components/schemas/AgentsNameOrIdPhoneNumbersPatchRequestBodyContentApplicationJsonSchemaConfigurationEndpoint'
- type: 'null'
description: When not `null`, the agent will call this endpoint to get configuration options for calls on this phone number.
required:
- phone_number
components:
schemas:
CreateAgentRequestIntelligenceLevel:
type: string
enum:
- standard
- high
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.
title: CreateAgentRequestIntelligenceLevel
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
UpdateAgentRequestPronunciationDictionaryItems:
type: object
properties:
word:
type: string
pronunciation:
type: string
required:
- word
- pronunciation
title: UpdateAgentRequestPronunciationDictionaryItems
UpsertAgentRequest:
type: object
properties:
name:
type: string
description: The name of the agent. Can only contain lowercase letters, numbers and hyphens. Must be unique within the project.
slug:
type: string
description: URL-friendly agent slug. Can only contain lowercase letters, numbers and hyphens. Must be unique within the project.
phone_number:
oneOf:
- $ref: '#/components/schemas/CreateAgentRequestPhoneNumber'
- type: 'null'
description: When set to `null`, the agent will not be associated with a phone number. When set to `"assign-automatically"`, the agent will be assigned a random phone number. When set to `"custom"`, you must provide `custom_phone_numbers`.
custom_phone_number:
type:
- string
- 'null'
description: The custom phone number to use for the agent in E.164 format (e.g., +1234567890). This field is deprecated. Use `custom_phone_numbers` instead.
custom_phone_numbers:
type: array
items:
type: string
default: []
description: Array of custom phone numbers in E.164 format (e.g., ["+1234567890", "+0987654321"]). The agent will be able to receive phone calls on any of these numbers. Required when `phone_number` is set to `"custom"`. All phone numbers must be unique.
timezone:
type: string
description: The timezone of the agent. Used to format system variables like `{{system_time}}`.
voice_id:
type: string
default: grant
description: The voice ID to use.
audio_format:
$ref: '#/components/schemas/CreateAgentRequestAudioFormat'
default: pcm_44100
description: The audio format of the agent.
audio_speed:
type: number
format: double
default: 1.2
description: The audio speed of the agent.
background_noise_level:
type: number
format: double
default: 0
description: The background noise level of the agent.
background_noise:
$ref: '#/components/schemas/CreateAgentRequestBackgroundNoise'
description: The background noise type. Can be "office", "call-center", "coffee-shop", or null.
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.
websocket_timeout_sec:
type: integer
default: 60
description: Number of seconds of inactivity before the conversation WebSocket is closed.
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: Today's date is {{system_date}} {{system_year}}. The day of week is {{system_weekday}}. The current time is {{system_time}}. The timezone for the current conversation is {{system_conversation_timezone}}. Use it only for date/time calculations. Do not infer location from it.
description: Instructions for the conversation. Can contain template variables like `{{subject}}`.
template_variables:
type: object
additionalProperties:
$ref: '#/components/schemas/CreateAgentRequestTemplateVariables'
description: Variables that can be used in the welcome message and the system prompt.
tools:
type: array
items:
$ref: '#/components/schemas/CreateAgentRequestToolsItems'
description: Array of built-in or custom tool names to use.
built_in_tool_configs:
$ref: '#/components/schemas/BuiltInToolConfigs'
description: Configuration overrides for built-in tools, keyed by built-in tool ID. Built-in tools not listed here use their default configuration.
tasks:
type: array
items:
$ref: '#/components/schemas/Task'
description: Array of task objects with `name` and `description` fields.
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.
enable_assistant_backchannel:
type: boolean
default: false
description: When `true`, the assistant will produce backchannel responses (e.g. "mm-hmm") while the user is speaking.
assistant_backchannel_aggressiveness:
type: number
format: double
default: 0.1
description: How aggressively the assistant produces backchannel responses. Only relevant when `enable_assistant_backchannel` is `true`.
data_retention_policy:
$ref: '#/components/schemas/DataRetentionPolicy'
description: Controls how long transcripts and audio recordings are retained before deletion.
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/CreateAgentRequestMultilingualMode'
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/CreateAgentRequestIntelligenceLevel'
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, or short phrases, will be more accurately recognized by the agent.
pronunciation_dictionary:
type: array
items:
$ref: '#/components/schemas/CreateAgentRequestPronunciationDictionaryItems'
description: Array of `{ word, pronunciation }` entries. Words must be unique.
min_words_to_interrupt:
type: integer
default: 1
description: Minimum number of words required to interrupt the assistant.
configuration_endpoint:
oneOf:
- $ref: '#/components/schemas/CreateAgentRequestConfigurationEndpoint'
- type: 'null'
description: When not `null`, at the beginning of the conversation the agent will make a POST request to this endpoint to get configuration options.
inbound_rollout:
type: number
format: double
default: 1
description: Float between 0.0 and 1.0 representing the percentage of inbound calls handled by Agent. Defaults to `1.0`. Requires `phone_number` to be set when less than 1.0.
inbound_rollout_forward_phone_number:
type:
- string
- 'null'
description: E.164 formatted phone number where non-agent calls will be forwarded. Required when `inbound_rollout < 1.0`, must be `null` when `inbound_rollout = 1.0`. Defaults to `null`.
vad_prebuffer_duration_ms:
type: integer
default: 500
description: Voice activity detection prebuffer duration in milliseconds.
vad_min_speech_duration_ms:
type: integer
default: 50
description: Minimum speech duration for voice activity detection in milliseconds.
vad_min_silence_duration_ms:
type: integer
default: 800
description: Minimum silence duration for voice activity detection in milliseconds.
vad_threshold:
type: number
format: double
default: 0.38
description: Voice activity detection threshold.
enable_redaction:
type: boolean
default: false
description: When `true`, PII and PHI are redacted from text transcripts (e.g. replaced with tags like `[PHONE NUMBER]`) and bleeped from audio recordings after the conversation ends.
mcp_server_ids:
type: array
items:
type: string
default: []
description: Array of MCP server IDs to make available to the agent.
observability_integrations:
type: array
items:
$ref: '#/components/schemas/CreateAgentRequestObservabilityIntegrationsItems'
default: []
description: Names of observability integrations to enable for the agent. Each must be one of the supported providers.
outbound_number_pool:
oneOf:
- $ref: '#/components/schemas/OutboundNumberPool'
- type: 'null'
description: Pool of phone numbers used for outbound calls. Set to `null` to remove the pool.
procedure_ids:
type: array
items:
type: string
description: Array of procedure IDs associated with the agent.
required:
- name
title: UpsertAgentRequest
Task:
type: object
properties:
name:
type: string
description: The name of the task.
description:
type: string
description: The description of the task.
required:
- name
- description
title: Task
AgentMultilingualMode:
type: string
enum:
- auto
- request
- initial
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.
title: AgentMultilingualMode
AgentPronunciationDictionaryItems:
type: object
properties:
word:
type: string
pronunciation:
type: string
required:
- word
- pronunciation
title: AgentPronunciationDictionaryItems
DataRetentionPolicy1:
type: object
properties:
zero_data_retention:
type: boolean
description: Must be `false` for standard data retention.
transcripts:
$ref: '#/components/schemas/DataRetentionPolicyOneOf1Transcripts'
audio_recordings:
$ref: '#/components/schemas/DataRetentionPolicyOneOf1AudioRecordings'
required:
- zero_data_retention
- transcripts
- audio_recordings
description: Standard data retention with configurable deletion windows.
title: DataRetentionPolicy1
DataRetentionPolicyOneOf1AudioRecordings:
type: object
properties:
delete_after_hours:
type:
- integer
- 'null'
description: Number of hours after which audio recordings are deleted. Null means audio recordings are retained indefinitely.
required:
- delete_after_hours
title: DataRetentionPolicyOneOf1AudioRecordings
AgentIntegration:
type: object
properties:
account_id:
type: string
# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/phonic/refs/heads/main/openapi/phonic-agents-api-openapi.yml