openapi: 3.0.3
info:
title: Ultravox accounts calls API
version: 0.1.0
description: API for the Ultravox service.
servers:
- url: https://api.ultravox.ai
tags:
- name: calls
paths:
/api/calls:
get:
operationId: calls_list
parameters:
- in: query
name: agentIds
schema:
type: array
items:
type: string
format: uuid
description: Filter calls by the agent IDs.
- name: cursor
required: false
in: query
description: The pagination cursor value.
schema:
type: string
- 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.
- 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
- 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:
- calls
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCallList'
description: ''
post:
operationId: calls_create
parameters:
- in: query
name: enableGreetingPrompt
schema:
type: boolean
default: true
description: Adds a prompt for a greeting if there's not an initial message that the model would naturally respond to (a user message or tool result).
- in: query
name: priorCallId
schema:
type: string
format: uuid
description: The UUID of a prior call. When specified, the new call will use the same properites as the prior call unless overriden in this request's body. The new call will also use the prior call's message history as its own initial_messages. (It's illegal to also set initial_messages in the body.)
- 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:
- calls
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ultravox.v1.StartCallRequest'
security:
- apiKeyAuth: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Call'
description: ''
/api/calls/{call_id}:
get:
operationId: calls_retrieve
parameters:
- in: path
name: call_id
schema:
type: string
format: uuid
required: true
tags:
- calls
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Call'
description: ''
delete:
operationId: calls_destroy
parameters:
- in: path
name: call_id
schema:
type: string
format: uuid
required: true
tags:
- calls
security:
- apiKeyAuth: []
responses:
'204':
description: No response body
/api/calls/{call_id}/events:
get:
operationId: calls_events_list
description: Fetch the (paginated) event log for a call, possibly filtered by severity.
parameters:
- in: path
name: call_id
schema:
type: string
format: uuid
required: true
- name: cursor
required: false
in: query
description: The pagination cursor value.
schema:
type: string
- in: query
name: minimum_severity
schema:
enum:
- debug
- info
- warning
- error
type: string
default: info
minLength: 1
description: 'The minimum severity of events to include.
* `debug` - debug
* `info` - info
* `warning` - warning
* `error` - error'
- name: pageSize
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- in: query
name: type
schema:
type: string
minLength: 1
description: If set, restricts returned events to those of the given type.
tags:
- calls
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCallEventList'
description: ''
/api/calls/{call_id}/messages:
get:
operationId: calls_messages_list
parameters:
- in: path
name: call_id
schema:
type: string
format: uuid
required: true
- name: cursor
required: false
in: query
description: The pagination cursor value.
schema:
type: string
- in: query
name: mode
schema:
enum:
- last_stage
- in_call
type: string
default: last_stage
minLength: 1
description: '* `last_stage` - Returns all messages for the call''s last stage, similar to most call fields
* `in_call` - Returns messages from all stages, excluding initialMessages'
- name: pageSize
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
tags:
- calls
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Paginatedultravox.v1.MessageList'
description: ''
/api/calls/{call_id}/recording:
get:
operationId: calls_recording_retrieve
description: Returns or redirects to a recording of the call.
parameters:
- in: path
name: call_id
schema:
type: string
format: uuid
required: true
tags:
- calls
security:
- apiKeyAuth: []
responses:
'200':
content:
audio/wav:
schema:
type: string
format: binary
description: ''
'302':
description: No response body
/api/calls/{call_id}/send_data_message:
post:
operationId: send_data_message_to_call
parameters:
- in: path
name: call_id
schema:
type: string
format: uuid
required: true
tags:
- calls
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SendCallDataMessage'
required: true
security:
- apiKeyAuth: []
responses:
'204':
description: No response body
/api/calls/{call_id}/sip_logs:
get:
operationId: calls_sip_logs_retrieve
description: Redirects to sip logs for the call, if available.
parameters:
- in: path
name: call_id
schema:
type: string
format: uuid
required: true
tags:
- calls
security:
- apiKeyAuth: []
responses:
'302':
description: No response body
'404':
description: No response body
'425':
description: No response body
/api/calls/{call_id}/stages:
get:
operationId: calls_stages_list
parameters:
- in: path
name: call_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:
- calls
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedCallStageList'
description: ''
/api/calls/{call_id}/stages/{call_stage_id}:
get:
operationId: calls_stages_retrieve
parameters:
- in: path
name: call_id
schema:
type: string
format: uuid
required: true
- in: path
name: call_stage_id
schema:
type: string
format: uuid
required: true
tags:
- calls
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CallStage'
description: ''
/api/calls/{call_id}/stages/{call_stage_id}/messages:
get:
operationId: calls_stages_messages_list
parameters:
- in: path
name: call_id
schema:
type: string
format: uuid
required: true
- in: path
name: call_stage_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:
- calls
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Paginatedultravox.v1.MessageList'
description: ''
/api/calls/{call_id}/stages/{call_stage_id}/messages/{call_stage_message_index}/audio:
get:
operationId: calls_stages_messages_audio_retrieve
parameters:
- in: path
name: call_id
schema:
type: string
format: uuid
required: true
- in: path
name: call_stage_id
schema:
type: string
format: uuid
required: true
- in: path
name: call_stage_message_index
schema:
type: integer
required: true
tags:
- calls
security:
- apiKeyAuth: []
responses:
'200':
description: No response body
/api/calls/{call_id}/stages/{call_stage_id}/tools:
get:
operationId: calls_stages_tools_list
parameters:
- in: path
name: call_id
schema:
type: string
format: uuid
required: true
- in: path
name: call_stage_id
schema:
type: string
format: uuid
required: true
tags:
- calls
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CallTool'
description: ''
/api/calls/{call_id}/tools:
get:
operationId: calls_tools_list
parameters:
- in: path
name: call_id
schema:
type: string
format: uuid
required: true
tags:
- calls
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CallTool'
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.
CallEvent:
type: object
properties:
callId:
type: string
format: uuid
readOnly: true
callStageId:
type: string
format: uuid
readOnly: true
callTimestamp:
type: string
description: The timestamp of the event, relative to call start.
severity:
allOf:
- $ref: '#/components/schemas/SeverityEnum'
readOnly: true
type:
type: string
description: The type of the event.
maxLength: 50
text:
type: string
extras:
type: object
additionalProperties: {}
nullable: true
readOnly: true
wallClockTimestamp:
type: string
nullable: true
description: The wall clock timestamp of the event, relative to call start.
required:
- callId
- callStageId
- callTimestamp
- extras
- severity
- text
- type
- wallClockTimestamp
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.
ultravox.v1.ClientCallToolDetails:
type: object
properties: {}
description: Details for a CallTool implemented by the client.
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.
CallTool:
type: object
properties:
callToolId:
type: string
format: uuid
readOnly: true
toolId:
type: string
format: uuid
readOnly: true
nullable: true
name:
type: string
readOnly: true
description: The possibly overridden name of the tool.
definition:
$ref: '#/components/schemas/ultravox.v1.CallTool'
required:
- callToolId
- definition
- name
- toolId
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
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.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.
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.
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.
format: int32
responseWordsPerMinute:
type: integer
description: "An estimate of the speaking rate of the returned audio in words per minute. This is\n use
# --- truncated at 32 KB (93 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fixie/refs/heads/main/openapi/fixie-calls-api-openapi.yml