openapi: 3.0.3
info:
title: Ultravox accounts agents API
version: 0.1.0
description: API for the Ultravox service.
servers:
- url: https://api.ultravox.ai
tags:
- name: agents
paths:
/api/agents:
get:
operationId: agents_list
parameters:
- name: cursor
required: false
in: query
description: The pagination cursor value.
schema:
type: string
- name: pageSize
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- in: query
name: search
schema:
type: string
minLength: 1
description: The search string used to filter results
- name: sort
required: false
in: query
description: Which field to use when ordering the results.
schema:
type: string
tags:
- agents
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedAgentList'
description: ''
post:
operationId: agents_create
tags:
- agents
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
security:
- apiKeyAuth: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
description: ''
/api/agents/{agent_id}:
get:
operationId: agents_retrieve
parameters:
- in: path
name: agent_id
schema:
type: string
format: uuid
required: true
tags:
- agents
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
description: ''
patch:
operationId: agents_partial_update
parameters:
- in: path
name: agent_id
schema:
type: string
format: uuid
required: true
tags:
- agents
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedAgent'
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
description: ''
delete:
operationId: agents_destroy
parameters:
- in: path
name: agent_id
schema:
type: string
format: uuid
required: true
tags:
- agents
security:
- apiKeyAuth: []
responses:
'204':
description: No response body
/api/agents/{agent_id}/calls:
get:
operationId: agents_calls_list
parameters:
- in: path
name: agent_id
schema:
type: string
format: uuid
required: true
- name: cursor
required: false
in: query
description: The pagination cursor value.
schema:
type: string
- name: pageSize
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
tags:
- agents
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCallList'
description: ''
post:
operationId: agents_calls_create
parameters:
- in: path
name: agent_id
schema:
type: string
format: uuid
required: true
- in: query
name: throttle
schema:
type: string
minLength: 1
description: The name or ID of a call throttle to apply to this call. If the throttle's rate limits have been exceeded, the call will be rejected with a 429 status.
tags:
- agents
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ultravox.v1.StartAgentCallRequest'
security:
- apiKeyAuth: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Call'
description: ''
/api/agents/{agent_id}/scheduled_batches:
get:
operationId: agents_scheduled_batches_list
parameters:
- in: path
name: agent_id
schema:
type: string
format: uuid
required: true
- name: cursor
required: false
in: query
description: The pagination cursor value.
schema:
type: string
- name: pageSize
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
tags:
- agents
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedScheduledCallBatchList'
description: ''
post:
operationId: agents_scheduled_batches_create
parameters:
- in: path
name: agent_id
schema:
type: string
format: uuid
required: true
tags:
- agents
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledCallBatch'
required: true
security:
- apiKeyAuth: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledCallBatch'
description: ''
/api/agents/{agent_id}/scheduled_batches/{batch_id}:
get:
operationId: agents_scheduled_batches_retrieve
parameters:
- in: path
name: agent_id
schema:
type: string
format: uuid
required: true
- in: path
name: batch_id
schema:
type: string
format: uuid
required: true
tags:
- agents
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledCallBatch'
description: ''
patch:
operationId: agents_scheduled_batches_partial_update
parameters:
- in: path
name: agent_id
schema:
type: string
format: uuid
required: true
- in: path
name: batch_id
schema:
type: string
format: uuid
required: true
tags:
- agents
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedScheduledCallBatch'
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledCallBatch'
description: ''
delete:
operationId: agents_scheduled_batches_destroy
parameters:
- in: path
name: agent_id
schema:
type: string
format: uuid
required: true
- in: path
name: batch_id
schema:
type: string
format: uuid
required: true
tags:
- agents
security:
- apiKeyAuth: []
responses:
'204':
description: No response body
/api/agents/{agent_id}/scheduled_batches/{batch_id}/created_calls:
get:
operationId: agents_scheduled_batches_created_calls_list
parameters:
- in: path
name: agent_id
schema:
type: string
format: uuid
required: true
- in: path
name: batch_id
schema:
type: string
format: uuid
required: true
- name: cursor
required: false
in: query
description: The pagination cursor value.
schema:
type: string
- name: pageSize
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
tags:
- agents
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCallList'
description: ''
/api/agents/{agent_id}/scheduled_batches/{batch_id}/scheduled_calls:
get:
operationId: agents_scheduled_batches_scheduled_calls_list
description: List scheduled calls within a batch.
parameters:
- in: path
name: agent_id
schema:
type: string
format: uuid
required: true
- in: path
name: batch_id
schema:
type: string
format: uuid
required: true
- name: cursor
required: false
in: query
description: The pagination cursor value.
schema:
type: string
- name: pageSize
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- in: query
name: status
schema:
enum:
- FUTURE
- PENDING
- SUCCESS
- EXPIRED
- ERROR
type: string
minLength: 1
description: '* `FUTURE` - FUTURE
* `PENDING` - PENDING
* `SUCCESS` - SUCCESS
* `EXPIRED` - EXPIRED
* `ERROR` - ERROR'
tags:
- agents
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedScheduledCallList'
description: ''
/api/agents/{agent_id}/telephony_xml:
post:
operationId: agents_telephony_xml
description: Allows supported telephony providers to create incoming calls with an agent, returning XML instructions for handling the call.
parameters:
- in: path
name: agent_id
schema:
type: string
format: uuid
required: true
tags:
- agents
requestBody:
content:
application/x-www-form-urlencoded:
schema:
description: Provider-defined request.
application/json:
schema:
description: Provider-defined request.
responses:
'200':
content:
text/xml:
schema:
description: XML appropriate for the telephony provider.
description: ''
/api/agents/usage:
get:
operationId: agents_usage_list
parameters:
- in: query
name: agentIds
schema:
type: array
items:
type: string
format: uuid
description: Filter calls by the agent IDs.
- in: query
name: durationMax
schema:
type: string
description: Maximum duration of calls
- in: query
name: durationMin
schema:
type: string
description: Minimum duration of calls
- in: query
name: fromDate
schema:
type: string
format: date-time
description: Start datetime (inclusive) for filtering calls by creation date. If no time component is present, this defaults to the start of the day (midnight).
- in: query
name: metadata
schema:
type: object
additionalProperties:
type: string
description: Filter calls by metadata. Use metadata.key=value to filter by specific key-value pairs.
- in: query
name: search
schema:
type: string
minLength: 1
description: The search string used to filter results
- in: query
name: timeOfDayEnd
schema:
type: string
format: time
default: '23:59:59.999999'
description: 'Filter calls by the time of day of their creation, regardless of date. Format: HH:MM:SS. Defaults to 23:59:59 if not specified.'
- in: query
name: timeOfDayStart
schema:
type: string
format: time
default: 00:00:00
description: 'Filter calls by the time of day of their creation, regardless of date. Format: HH:MM:SS. Defaults to 00:00:00 if not specified.'
- in: query
name: toDate
schema:
type: string
format: date-time
description: End datetime (inclusive) for filtering calls by creation date. If no time component is present, this defaults to the end of the day (11:59:59.999999 PM).
- in: query
name: voiceId
schema:
type: string
format: uuid
description: Filter calls by the associated voice ID
tags:
- agents
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgentUsage'
description: ''
components:
schemas:
ultravox.v1.CallMedium_WebSocketMedium:
type: object
properties:
inputSampleRate:
type: integer
description: The sample rate for input (user) audio. Required.
format: int32
outputSampleRate:
type: integer
description: The desired sample rate for output (agent) audio. If unset, defaults to the input_sample_rate.
format: int32
clientBufferSizeMs:
type: integer
description: "The size of the client-side audio buffer in milliseconds. Smaller buffers allow for faster\n interruptions but may cause audio underflow if network latency fluctuates too greatly. For\n the best of both worlds, set this to some large value (e.g. 30000) and implement support for\n playback_clear_buffer messages. Defaults to 60."
format: int32
dataMessages:
allOf:
- $ref: '#/components/schemas/ultravox.v1.EnabledDataMessages'
description: Controls which data messages are enabled for the call.
mediaIdleTimeout:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: "Depending on your implementation, severe underflow from something further downstream from\n your server may result in audio no longer being delivered to Ultravox at all (despite\n heartbeats continuing). If media_idle_timeout is set and Ultravox stops receiving audio for\n longer than this duration, the call will be ended with a \"Connection error\" end reason.\n Values in the 30s to 60s range are recommended (and may become the default in the future).\n Values below 10s will be treated as 10s."
description: Details for a WebSocket call.
ultravox.v1.CallMedium_WebRtcMedium:
type: object
properties:
dataMessages:
allOf:
- $ref: '#/components/schemas/ultravox.v1.EnabledDataMessages'
description: Controls which data messages are enabled for the call.
description: Details for a WebRTC call.
ultravox.v1.CartesiaVoice_CartesiaGenerationConfig:
type: object
properties:
volume:
type: number
description: Adjust the volume of the generated speech between 0.5x and 2.0x the original volume (default is 1.0x). Valid values are between [0.5, 2.0] inclusive.
format: float
speed:
type: number
description: Adjust the speed of the generated speech between 0.6x and 2.0x the original speed (default is 1.0x). Valid values are between [0.6, 1.5] inclusive.
format: float
emotion:
type: string
description: The primary emotions are neutral, calm, angry, content, sad, scared. For more options, see Prompting Sonic-3.
pronunciationDictId:
type: string
description: "The ID of a pronunciation dictionary to use for the generation.\n Pronunciation dictionaries are supported by sonic-3 models and newer.\n See https://docs.cartesia.ai/build-with-cartesia/capability-guides/specify-custom-pronunciations"
description: Cartesia generation configuration for Sonic-3 and later models.
RetentionPolicyEnum:
enum:
- retain
- auto_delete
type: string
description: '* `retain` - Retain indefinitely
* `auto_delete` - Auto-delete after billing'
ultravox.v1.TimedMessage:
type: object
properties:
duration:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: The duration after which the message should be spoken.
message:
type: string
description: The message to speak.
endBehavior:
enum:
- END_BEHAVIOR_UNSPECIFIED
- END_BEHAVIOR_HANG_UP_SOFT
- END_BEHAVIOR_HANG_UP_STRICT
type: string
description: The behavior to exhibit when the message is finished being spoken.
format: enum
description: "A message the agent should say after some duration. The duration's meaning\n varies depending on the context."
ultravox.v1.HeaderApiKeyRequirement:
type: object
properties:
name:
type: string
description: The name of the header.
description: A security requirement that will cause an API key to be added to the header.
google.protobuf.Value:
description: Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
ultravox.v1.CallMedium_DtmfHandling:
type: object
properties:
ignore:
type: boolean
description: If true, DTMF digits are ignored entirely.
userTextMessage:
allOf:
- $ref: '#/components/schemas/ultravox.v1.CallMedium_DtmfUserTextMessage'
description: Customizes how DTMF digits are sent as a user text message.
description: "Configuration for how incoming DTMF digits are handled during a call.\n When dtmf_handling is absent from the enclosing medium, DTMF digits are\n sent as a user text message containing just the digits with urgency\n URGENCY_IMMEDIATE (the default behavior).\n Note: consecutive DTMF digits are batched together with a short delay\n before being dispatched, so a rapid sequence of key presses will be\n delivered as a single message."
ultravox.v1.FirstSpeakerSettings_AgentGreeting:
type: object
properties:
uninterruptible:
type: boolean
description: "Whether the user should be prevented from interrupting the agent's first message.\n Defaults to false (meaning the agent is interruptible as usual)."
text:
type: string
description: A specific greeting the agent should say.
prompt:
type: string
description: A prompt for the agent to generate a greeting.
delay:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: "If set, the agent will wait this long before starting its greeting. This may be useful\n for ensuring the user is ready."
description: Additional properties for when the agent speaks first.
FirstSpeakerEnum:
enum:
- FIRST_SPEAKER_AGENT
- FIRST_SPEAKER_USER
type: string
PaginatedScheduledCallList:
type: object
required:
- results
properties:
next:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?cursor=cD00ODY%3D"
previous:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
results:
type: array
items:
$ref: '#/components/schemas/ScheduledCall'
total:
type: integer
example: 123
ultravox.v1.ToolRequirements:
type: object
properties:
httpSecurityOptions:
allOf:
- $ref: '#/components/schemas/ultravox.v1.SecurityOptions'
description: Security requirements for an HTTP tool.
requiredParameterOverrides:
type: array
items:
type: string
description: Dynamic parameters that must be overridden with an explicit (static) value.
description: The requirements for using a tool, which must be satisfied when creating a call with the tool.
ultravox.v1.ToolOverrides:
type: object
properties:
remove:
type: array
items:
type: string
description: "Tools to remove from the set, identified by their unique model-facing name\n (i.e. nameOverride if set, otherwise modelToolName). May not be set\n together with removeAll."
removeAll:
type: boolean
description: "If true, all existing tools are removed. May not be set together with\n remove."
add:
type: array
items:
$ref: '#/components/schemas/ultravox.v1.SelectedTool'
description: Tools to add.
description: "Overrides for a set of selected tools. Items in remove are applied before\n items in add. Use remove + add for replacements."
ultravox.v1.InworldVoice:
type: object
properties:
voiceId:
type: string
description: The ID of the voice in Inworld.
modelId:
type: string
description: "The ID of the model to use for generations, e.g. \"inworld-tts-1-max\".\n See https://docs.inworld.ai/docs/tts/tts-models"
speakingRate:
type: number
description: "The speaking rate. Must be between 0.5 and 1.5. Defaults to 1.\n See https://docs.inworld.ai/api-reference/ttsAPI/texttospeech/synthesize-speech-stream#body-audio-config-speaking-rate"
format: float
temperature:
type: number
description: "How much randomness to use when sampling audio tokens. Must be between 0.0 and 2.0.\n See https://docs.inworld.ai/api-reference/ttsAPI/texttospeech/synthesize-speech-stream#body-temperature"
format: float
applyTextNormalization:
type: boolean
description: "Whether or not to apply text normalization. This should typically only be disabled if the\n agent is instructed to normalize text directly.\n See https://docs.inworld.ai/api-reference/ttsAPI/texttospeech/synthesize-speech-stream#body-apply-text-normalization."
description: Specification for a voice served by Inworld.
ultravox.v1.Callbacks:
type: object
properties:
joined:
allOf:
- $ref: '#/components/schemas/ultravox.v1.Callback'
description: Callback invoked when the call is joined.
ended:
allOf:
- $ref: '#/components/schemas/ultravox.v1.Callback'
description: Callback invoked when the call has ended.
billed:
allOf:
- $ref: '#/components/schemas/ultravox.v1.Callback'
description: Callback invoked when the call is billed.
description: Configuration for call lifecycle callbacks.
ultravox.v1.DataConnectionAudioConfig:
type: object
properties:
sampleRate:
type: integer
description: The sample rate of the audio stream. If not set, will default to 16000.
format: int32
channelMode:
enum:
- CHANNEL_MODE_UNSPECIFIED
- CHANNEL_MODE_MIXED
- CHANNEL_MODE_SEPARATED
type: string
description: "The audio channel mode to use. CHANNEL_MODE_MIXED will combine user and agent audio\n into a single mono output while CHANNEL_MODE_SEPARATED will result in stereo audio\n where user and agent are separated. The latter is the default."
format: enum
description: Configuration for audio in data connections
ultravox.v1.ElevenLabsVoice_PronunciationDictionaryReference:
type: object
properties:
dictionaryId:
type: string
description: The dictionary's ID.
versionId:
type: string
description: The dictionary's version.
description: A reference to a pronunciation dictionary within ElevenLabs.
PaginatedScheduledCallBatchList:
type: object
required:
- results
properties:
next:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?cursor=cD00ODY%3D"
previous:
type: string
nullable: true
format: uri
example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
results:
type: array
items:
$ref: '#/components/schemas/ScheduledCallBatch'
total:
type: integer
example: 123
ultravox.v1.Message:
type: object
properties:
role:
enum:
- MESSAGE_ROLE_UNSPECIFIED
- MESSAGE_ROLE_USER
- MESSAGE_ROLE_AGENT
- MESSAGE_ROLE_TOOL_CALL
- MESSAGE_ROLE_TOOL_RESULT
type: string
description: The message's role.
format: enum
text:
type: string
description: The message text for user and agent messages, tool arguments for tool_call messages, tool results for tool_result messages.
invocationId:
type: string
description: The invocation ID for tool messages. Used to pair tool calls with their results.
toolName:
type: string
description: The tool name for tool messages.
errorDetails:
type: string
description: "For failed tool calls, additional debugging information. While the text field is\n presented to the model so it can respond to failures gracefully, the full details\n are only exposed via the Ultravox REST API."
medium:
enum:
- MESSAGE_MEDIUM_UNSPECIFIED
- MESSAGE_MEDIUM_VOICE
- MESSAGE_MEDIUM_TEXT
type: string
description: The medium of the message.
format: enum
callStageMessageIndex:
type: integer
description: The index of the message within the call stage.
format: int32
callStageId:
type: string
description: The call stage this message appeared in.
callState:
type: object
description: If the message updated the call state, the new call state.
timespan:
allOf:
- $ref: '#/components/schemas/ultravox.v1.InCallTimespan'
description: "The timespan during the call when this message occurred, according\n to the input audio stream.\n This is only set for messages that occurred during the call (stage)\n and not for messages in the call's (call stage's) initial messages."
wallClockTimespan:
allOf:
- $ref: '#/components/schemas/ultravox.v1.InCallTimespan'
description: "The timespan during the call when this message occurred, according\n the wall clock, relative to the call's joined time.\n This is only set for messages that occurred during the call (stage)\n and not for messages in the call's (call stage's) initial messages."
metadata:
type: object
description: Arbitrary metadata associated with the message.
description: A message exchanged during a call.
ultravox.v1.PlivoMedium_OutgoingRequestParams:
type: object
properties:
to:
type: string
description: The phone number(s) or sip URI(s) to call, separated by `<` if multiple.
from:
type: string
description: The phone number initiating the call, in E.164 format (e.g. +14155552671).
additionalParams:
type: object
description: "Additional parameters to include in the Plivo call creation request.\n See https://www.plivo.com/docs/voice/api/call/make-a-call"
description: Parameters for a Plivo call creation request.
AgentStatistics:
type: object
properties:
calls:
type: integer
readOnly: true
default: 0
required:
- calls
ultravox.v1.ExternalVoice:
type: object
properties:
elevenLabs:
allOf:
- $ref: '#/components/schemas/ultravox.v1.ElevenLabsVoice'
description: A voice served by ElevenLabs.
cartesia:
allOf:
- $ref: '#/components/schemas/ultravox.v1.CartesiaVoice'
description: A voice served by Cartesia.
lmnt:
allOf:
- $ref: '#/components/schemas/ultravox.v1.LmntVoice'
description: A voice served by LMNT.
google:
allOf:
- $ref: '#/components/schemas/ultravox.v1.GoogleVoice'
description: "A voice served by Google, using bidirectional streaming.\n (For non-streaming or output-only streaming, use generic.)"
inworld:
allOf:
- $ref: '#/components/schemas/ultravox.v1.InworldVoice'
description: "A voice served by Inworld, using bidirectional streaming.\n (For non-streaming or output-only streaming, use generic.)"
respeecher:
allOf:
- $ref: '#/components/schemas/ultravox.v1.RespeecherVoice'
description: A voice served by Respeecher, using bidirectional streaming.
generic:
allOf:
- $ref: '#/components/schemas/ultravox.v1.GenericVoice'
description: A voice served by a generic REST-based TTS API.
description: "A voice not known to Ultravox Realtime that can nonetheless be used for a call.\n Such voices are significantly less validated than normal voices and you'll be\n responsible for your own TTS-related errors.\n Exactly one field must be set."
ultravox.v1.BaseHttpToolDetails:
type: object
properties:
baseUrlPattern:
type: string
description: The base URL pattern for the tool, possibly with placeholders for path parameters.
httpMethod:
type: string
description: The HTTP method for the tool.
description: Details for invoking a tool via HTTP.
ultravox.v1.DataConnectionConfig:
type: object
properties:
websocketUrl:
type: string
description: The websocket URL to which the session will connect to stream data messages.
audioConfig:
allOf:
- $ref: '#/components/schemas/ultravox.v1.DataConnectionAudioConfig'
description: Audio configuration for the data connection. If not set, no audio will be sent.
dataMessages:
allOf:
- $ref: '#/components/schemas/ultravox.v1.EnabledDataMessages'
description: Controls which data messages are enabled for the data connection.
headers:
type: object
additionalProperties:
type: string
description: Additional headers to include when connecting to the websocket endpoint.
description: Data connection enables an auxiliary websocket for streaming data messages.
ultravox.v1.GenericVoice:
type: object
properties:
url:
type: string
description: The endpoint to which requests are sent.
headers:
type: object
additionalProperties:
type: string
description: Headers to include in the request.
body:
type: object
description: "The request body to send. Some field should include a placeholder for text\n represented as {text}. The placeholder will be replaced with the text to synthesize."
responseSampleRate:
type: integer
description: The sample rate of the audio returned by the API.
# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fixie/refs/heads/main/openapi/fixie-agents-api-openapi.yml