openapi: 3.0.3
info:
title: Ultravox accounts tools API
version: 0.1.0
description: API for the Ultravox service.
servers:
- url: https://api.ultravox.ai
tags:
- name: tools
paths:
/api/tools:
get:
operationId: tools_list
description: List tools available to your account.
parameters:
- name: cursor
required: false
in: query
description: The pagination cursor value.
schema:
type: string
- in: query
name: ownership
schema:
enum:
- private
- public
type: string
minLength: 1
description: 'The ownership used to filter results.
* `private` - Only private tools
* `public` - Only public tools'
- 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.
- in: query
name: sortOrder
schema:
enum:
- display
- alphabetic
- reverseAlphabetic
- chronologic
- reverseChronologic
- default
type: string
default: default
minLength: 1
description: 'How results should be ordered. If a cursor is provided, this parameter must match the sortOrder used in the previous request for results to be sensible.
* `display` - Display order. Public tools by name first, then private tools with most recent first.
* `alphabetic` - Name ascending
* `reverseAlphabetic` - Name descending
* `chronologic` - Creation order with oldest first.
* `reverseChronologic` - Creation order with newest first.
* `default` - Default ordering. Same as reverseChronologic but with private tools first.'
tags:
- tools
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedToolList'
description: ''
post:
operationId: tools_create
tags:
- tools
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Tool'
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: An OpenAPI schema file in either JSON or YAML format.
required:
- file
security:
- apiKeyAuth: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Tool'
description: ''
/api/tools/{tool_id}:
get:
operationId: tools_retrieve
parameters:
- in: path
name: tool_id
schema:
type: string
format: uuid
required: true
tags:
- tools
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Tool'
description: ''
put:
operationId: tools_update
parameters:
- in: path
name: tool_id
schema:
type: string
format: uuid
required: true
tags:
- tools
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Tool'
required: true
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Tool'
description: ''
delete:
operationId: tools_destroy
parameters:
- in: path
name: tool_id
schema:
type: string
format: uuid
required: true
tags:
- tools
security:
- apiKeyAuth: []
responses:
'204':
description: No response body
/api/tools/{tool_id}/history:
get:
operationId: tools_history_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: path
name: tool_id
schema:
type: string
format: uuid
required: true
tags:
- tools
security:
- apiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedToolHistoryList'
description: ''
/api/tools/{tool_id}/test:
post:
operationId: tools_test_create
description: Test a tool by executing it with the provided parameters.
parameters:
- in: path
name: tool_id
schema:
type: string
format: uuid
required: true
tags:
- tools
security:
- apiKeyAuth: []
responses:
default:
content:
'*/*':
schema: {}
description: ''
components:
schemas:
ToolHistory:
type: object
properties:
call:
allOf:
- $ref: '#/components/schemas/Call'
readOnly: true
errorCount:
type: integer
readOnly: true
required:
- call
- errorCount
ultravox.v1.HttpAuthRequirement:
type: object
properties:
scheme:
type: string
description: The scheme of the HTTP authentication, e.g. "Bearer".
description: A security requirement that will cause an HTTP authentication header to be added.
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.LmntVoice:
type: object
properties:
voiceId:
type: string
description: The ID of the voice in LMNT.
model:
type: string
description: The LMNT model to use.
speed:
type: number
description: "The speaking rate. Must be between 0.25 and 2. Defaults to 1.\n See https://docs.lmnt.com/api-reference/speech/synthesize-speech-bytes#body-speed"
format: float
conversational:
type: boolean
description: See https://docs.lmnt.com/api-reference/speech/synthesize-speech-bytes#body-conversational
description: Specification for a voice served by LMNT.
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.
EndReasonEnum:
enum:
- unjoined
- hangup
- agent_hangup
- timeout
- connection_error
- system_error
type: string
description: '* `unjoined` - Client never joined
* `hangup` - Client hung up
* `agent_hangup` - Agent hung up
* `timeout` - Call timed out
* `connection_error` - Connection error
* `system_error` - System error'
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.
InitialOutputMediumEnum:
enum:
- MESSAGE_MEDIUM_VOICE
- MESSAGE_MEDIUM_TEXT
type: string
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.
Call:
type: object
properties:
callId:
type: string
format: uuid
readOnly: true
clientVersion:
type: string
readOnly: true
nullable: true
description: The version of the client that joined this call.
created:
type: string
format: date-time
readOnly: true
joined:
type: string
format: date-time
readOnly: true
nullable: true
ended:
type: string
format: date-time
readOnly: true
nullable: true
endReason:
readOnly: true
nullable: true
description: 'The reason the call ended.
* `unjoined` - Client never joined
* `hangup` - Client hung up
* `agent_hangup` - Agent hung up
* `timeout` - Call timed out
* `connection_error` - Connection error
* `system_error` - System error'
oneOf:
- $ref: '#/components/schemas/EndReasonEnum'
- $ref: '#/components/schemas/NullEnum'
billedDuration:
type: string
readOnly: true
nullable: true
billedSideInputTokens:
type: integer
readOnly: true
nullable: true
billedSideOutputTokens:
type: integer
readOnly: true
nullable: true
billingStatus:
allOf:
- $ref: '#/components/schemas/BillingStatusEnum'
readOnly: true
firstSpeaker:
allOf:
- $ref: '#/components/schemas/FirstSpeakerEnum'
deprecated: true
readOnly: true
description: Who was supposed to talk first when the call started. Typically set to FIRST_SPEAKER_USER for outgoing calls and left as the default (FIRST_SPEAKER_AGENT) otherwise.
firstSpeakerSettings:
allOf:
- $ref: '#/components/schemas/ultravox.v1.FirstSpeakerSettings'
description: Settings for the initial message to get the call started.
inactivityMessages:
type: array
items:
$ref: '#/components/schemas/ultravox.v1.TimedMessage'
description: Messages spoken by the agent when the user is inactive for the specified duration. Durations are cumulative, so a message m > 1 with duration 30s will be spoken 30 seconds after message m-1.
initialOutputMedium:
allOf:
- $ref: '#/components/schemas/InitialOutputMediumEnum'
readOnly: true
description: The medium used initially by the agent. May later be changed by the client.
joinTimeout:
type: string
default: 30s
joinUrl:
type: string
nullable: true
readOnly: true
languageHint:
type: string
nullable: true
description: BCP47 language code that may be used to guide speech recognition.
maxLength: 16
maxDuration:
type: string
default: 3600s
medium:
allOf:
- $ref: '#/components/schemas/ultravox.v1.CallMedium'
nullable: true
model:
type: string
default: ultravox-v0.7
recordingEnabled:
type: boolean
default: false
retentionPolicy:
nullable: true
description: 'The retention policy for the call''s data after it ends.
* `retain` - Retain indefinitely
* `auto_delete` - Auto-delete after billing'
oneOf:
- $ref: '#/components/schemas/RetentionPolicyEnum'
- $ref: '#/components/schemas/NullEnum'
systemPrompt:
type: string
nullable: true
temperature:
type: number
format: double
maximum: 1.0
minimum: 0.0
default: 0.0
timeExceededMessage:
type: string
nullable: true
voice:
type: string
nullable: true
externalVoice:
$ref: '#/components/schemas/ultravox.v1.ExternalVoice'
voiceOverrides:
allOf:
- $ref: '#/components/schemas/ultravox.v1.ExternalVoice'
description: Overrides for the selected voice.
transcriptOptional:
type: boolean
default: true
description: Indicates whether a transcript is optional for the call.
deprecated: true
vadSettings:
allOf:
- $ref: '#/components/schemas/ultravox.v1.VadSettings'
nullable: true
description: VAD settings for the call.
shortSummary:
type: string
readOnly: true
nullable: true
description: A short summary of the call.
summary:
type: string
readOnly: true
nullable: true
description: A summary of the call.
agent:
allOf:
- $ref: '#/components/schemas/AgentBasic'
readOnly: true
description: The agent used for this call.
agentId:
type: string
nullable: true
readOnly: true
description: The ID of the agent used for this call.
experimentalSettings:
description: Experimental settings for the call.
metadata:
type: object
additionalProperties:
type: string
description: Optional metadata key-value pairs to associate with the call. All values must be strings.
initialState:
type: object
additionalProperties: {}
description: The initial state of the call which is readable/writable by tools.
requestContext: {}
dataConnectionConfig:
allOf:
- $ref: '#/components/schemas/ultravox.v1.DataConnectionConfig'
description: Settings for exchanging data messages with an additional participant.
callbacks:
allOf:
- $ref: '#/components/schemas/ultravox.v1.Callbacks'
description: Callbacks configuration for the call.
sipDetails:
allOf:
- $ref: '#/components/schemas/CallSipDetails'
readOnly: true
nullable: true
description: SIP details for the call, if applicable.
required:
- agent
- agentId
- billedDuration
- billedSideInputTokens
- billedSideOutputTokens
- billingStatus
- callId
- clientVersion
- created
- endReason
- ended
- experimentalSettings
- firstSpeaker
- firstSpeakerSettings
- initialOutputMedium
- initialState
- joinUrl
- joined
- metadata
- requestContext
- shortSummary
- sipDetails
- summary
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.TwilioMedium_OutgoingRequestParams:
type: object
properties:
to:
type: string
description: The phone number, in E.164 format (e.g. +14155552671), (or sip address) to call.
from:
type: string
description: "The phone number or client identifier to use as the caller id. If `to` is a phone\n number, `from` must be a phone number owned by your Twilio account."
additionalParams:
type: object
description: "Additional parameters to include in the Twilio call creation request.\n See https://www.twilio.com/docs/voice/api/call-resource#request-body-parameters"
description: Parameters for a Twilio call creation request.
ultravox.v1.StaticToolResponse:
type: object
properties:
responseText:
type: string
description: The predefined text response to be returned immediately
description: "A predefined, static response for a tool. When a tool has a static response, it\n can be returned immediately, without waiting for full tool execution."
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.EnabledDataMessages:
type: object
properties:
pong:
type: boolean
description: 'Responds to a ping message. (Default: enabled)'
state:
type: boolean
description: 'Indicates that the agent state has changed. (Default: enabled)'
transcript:
type: boolean
description: 'Provides transcripts of the user and agent speech. (Default: enabled)'
clientToolInvocation:
type: boolean
description: 'Requests a client-implemented tool invocation. (Default: enabled)'
dataConnectionToolInvocation:
type: boolean
description: 'Requests a data-connection-implemented tool invocation. (Default: enabled for data connections, disabled otherwise)'
playbackClearBuffer:
type: boolean
description: 'Requests the client-side audio buffer to be cleared. (Default: enabled for websocket connections, disabled otherwise)'
callStarted:
type: boolean
description: 'Provides information about the call when it starts. (Default: enabled)'
debug:
type: boolean
description: 'Communicates debug information. (Default: disabled)'
callEvent:
type: boolean
description: 'Indicates that a call event has been recorded. (Default: disabled)'
toolUsed:
type: boolean
description: 'Indicates that a tool was used. (Default: disabled)'
userStartedSpeaking:
type: boolean
description: 'Indicates that the user has started speaking (according to simple VAD). (Default: disabled)'
userStoppedSpeaking:
type: boolean
description: 'Indicates that the user has stopped speaking (according to simple VAD). (Default: disabled)'
invokingTool:
type: boolean
description: 'Indicates that a tool invocation has started. (Default: disabled)'
description: Whether certain data messages are enabled for a connection.
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.DynamicParameter:
type: object
properties:
name:
type: string
description: The name of the parameter.
location:
enum:
- PARAMETER_LOCATION_UNSPECIFIED
- PARAMETER_LOCATION_QUERY
- PARAMETER_LOCATION_PATH
- PARAMETER_LOCATION_HEADER
- PARAMETER_LOCATION_BODY
type: string
description: Where the parameter is used.
format: enum
schema:
type: object
description: "The JsonSchema definition of the parameter. This typically\n includes things like type, description, enum values, format,\n other restrictions, etc."
required:
type: boolean
description: Whether the parameter is required.
description: A dynamic parameter the tool accepts that may be set by the model.
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 used for transcript timing while audio is streamed in the response. (Once the response\n is complete, Ultravox Realtime uses the real audio duration to adjust the timing.)\n Defaults to 150 and is unused for non-streaming responses."
format: int32
responseMimeType:
type: string
description: "The real mime type of the content returned by the API. If unset, the Content-Type response header\n will be used. This is useful for APIs whose response bodies don't strictly adhere to what the\n API claims via header. For example, if your API claims to return audio/wav but omits the WAV\n header (thus really returning raw PCM), set this to audio/l16. Similarly, if your API claims to\n return JSON but actually streams JSON Lines, set this to application/jsonl."
jsonAudioFieldPath:
type: string
description: "For JSON responses, the path to the field containing base64-encoded audio data. The data must\n be PCM audio, optionally with a WAV header."
jsonByteEncoding:
enum:
- JSON_BYTE_ENCODING_UNSPECIFIED
- JSON_BYTE_ENCODING_BASE64
- JSON_BYTE_ENCODING_HEX
type: string
description: "For JSON responses, how audio bytes are encoded into the json_audio_field_path string.\n Defaults to base64. Also supports hex."
format: enum
description: "Specification for a voice served by some generic REST-based TTS API. The API must\n accept an application/json POST request (as defined below) and return either WAV\n audio, raw PCM audio, or application/json with a base64 encoded audio data field\n that itself corresponds to WAV or raw PCM audio.\n Note that this simple API implies a lack of either input streaming or audio timing\n information, so more specific voice types are preferable when available."
RetentionPolicyEnum:
enum:
- retain
- auto_delete
type: string
description: '* `retain` - Retain indefinitely
* `auto_delete` - Auto-delete after billing'
ultravox.v1.BaseToolDefinition:
type: object
properties:
modelToolName:
type: string
description: The name of the tool, as presented to the model. Must match ^[a-zA-Z0-9_-]{1,64}$.
description:
type: string
description: The description of the tool.
dynamicParameters:
type: array
items:
$ref: '#/components/schemas/ultravox.v1.DynamicParameter'
description: The parameters that the tool accepts.
staticParameters:
type: array
items:
$ref: '#/components/schemas/ultravox.v1.StaticParameter'
description: The static parameters added when the tool is invoked.
automaticParameters:
type: array
items:
$ref: '#/components/schemas/ultravox.v1.AutomaticParameter'
description: Additional parameters that are automatically set by the system when the tool is invoked.
requirements:
allOf:
- $ref: '#/components/schemas/ultravox.v1.ToolRequirements'
description: Requirements that must be fulfilled when creating a call for the tool to be used.
timeout:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: "The maximum amount of time the tool is allowed for execution. The conversation is frozen\n while tools run, so prefer sticking to the default unless you're comfortable with that\n consequence. If your tool is too slow for the default and can't be made faster, still try to\n keep this timeout as low as possible."
precomputable:
type: boolean
description: "The tool is guaranteed to be non-mutating, repeatable, and free of side-effects. Such tools\n can safely be executed speculatively, reducing their effective latency. However, the fact they\n were called may not be reflected in the call history if their result ends up unused."
http:
allOf:
- $ref: '#/components/schemas/ultravox.v1.BaseHttpToolDetails'
description: Details for an HTTP tool.
client:
allOf:
- $ref: '#/components/schemas/ultravox.v1.BaseClientToolDetails'
description: "Details for a client-implemented tool. Only body parameters are allowed\n for client tools."
dataConnection:
allOf:
- $ref: '#/components/schemas/ultravox.v1.BaseDataConnectionToolDetails'
description: "Details for a tool implemented via a data connection websocket. Only body\n parameters are allowed for data connection tools."
defaultReaction:
enum:
- AGENT_REACTION_UNSPECIFIED
- AGENT_REACTION_SPEAKS
- AGENT_REACTION_LISTENS
- AGENT_REACTION_SPEAKS_ONCE
type: string
description: "Indicates the default for how the agent should proceed after the tool is invoked.\n Can be overridden by the tool implementation via the X-Ultravox-Agent-Reaction\n header."
format: enum
staticResponse:
allOf:
- $ref: '#/components/schemas/ultravox.v1.StaticToolResponse'
description: "Static response to a tool. When this is used, this response will be returned\n without waiting for the tool's response."
description: "The base definition of a tool that can be used during a call. Exactly one\n implementation (http or client) should be set."
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
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fixie/refs/heads/main/openapi/fixie-tools-api-openapi.yml