Calls

Calls are what drive all speech-to-speech interactions between your end users and AI. At their most basic level, calls consist of a set of instructions to instruct the LLM how to behave (i.e. the systemPrompt) and the selection of the voice the AI should use when speaking.

List Calls

GET /calls

Lists all calls that have been created. API key scoped.

Parameters


cursor	Pagination cursor.


none


uuid	string	Unique identifier for the call.
created	string	Datetime in UTC when the call was created.
ended	string	Datetime in UTC when the call was ended. Will be null upon call creation and while call is underway.
model	string	Name of the model used for the call. Currently only `fixie-ai/ultravox` is supported.
systemPrompt	string	The system prompt used to create the call.
temperature	float	The temperature setting used for the model in this call.
voice	string	The name of the AI voice used for the call.
languageHint	string	BCP47 identifier used as a hint to indentify the user’s spoken language.
joinUrl	string	URL to use with the ultravox client library to join (AKA start) the call.

Create Call

POST /calls

Creates a new call using the specified system prompt. API key scoped.

Optional parameters can be used to specify voice, temperature, language hint, and recordingEnabled.

An optional query parameter called priorCallId can be provided to continue a previous conversation. If used, all properties of the prior call (e.g. systemPrompt, voice, etc.) will be used for the new call. Can also be used in combination with overriding individual properties (e.g. inherit all properties but override the voice).

Parameters


priorCallId	string	The UUID of an existing call. If provided, the new call will inherit all call properties (unless overridden in the current request body). The prior call’s message history will be used in place of `initialMessages`. Setting `initialMessages` in the body is not allowed.


systemPrompt required	string	The system prompt to use for the AI.
languageHint	string	A hint about the language to be used if your end users are speaking a language other than English. Must be a valid BCP47 language code. Best effort is made to select the closest supported language. (default: “en”)
model	string	The model to be used for the call. Currently only `fixie-ai/ultravox` is supported and is the default.
recordingEnabled	boolean	A recording will be saved for the call when set to `true`. Recording can be retrieved via `GET /calls/{uuid}/recording`. Default value of `false`.
temperature	float	The temperature setting for the model. Value between 0.0 and 1.0. (default: 0.0)
voice	string	The voice the AI will use for speaking. There are currently two options: `lily` (default) and `terrence`. Please contact us if you have other voice requirements.


uuid	string	Unique identifier for the call.
created	string	Datetime in UTC when the call was created.
ended	string	Datetime in UTC when the call was ended. Will be null upon call creation and while call is underway.
model	string	Name of the model used for the call. Currently only `fixie-ai/ultravox` is supported.
systemPrompt	string	The system prompt used to create the call.
temperature	float	The temperature setting used for the model in this call.
voice	string	The name of the AI voice used for the call.
languageHint	string	BCP47 identifier used as a hint to indentify the user’s spoken language.
joinUrl	string	URL to use with the ultravox client library to join (AKA start) the call.

Get Call

GET /calls/{uuid}

Gets details for the call with uuid specified in the path. API key scoped.

Parameters


uuid required	Unique identifier for the call to retrieve.


None


uuid	string	Unique identifier for the call.
created	string	Datetime in UTC when the call was created.
ended	string	Datetime in UTC when the call was ended. Will be null upon call creation and while call is underway.
model	string	Name of the model used for the call. Currently only `fixie-ai/ultravox` is supported.
systemPrompt	string	The system prompt used to create the call.
temperature	float	The temperature setting used for the model in this call.
voice	string	The name of the AI voice used for the call.
languageHint	string	BCP47 identifier used as a hint to indentify the user’s spoken language.
joinUrl	string	URL to use with the ultravox client library to join (AKA start) the call.

Delete Call

DELETE /calls/{uuid}

Deletes the specified call.

Parameters


uuid required	Unique identifier for the call to delete.


No request body


No response body

List Call Messages

GET /calls/{uuid}/messages

Lists all messages generated during the given call.

Parameters


uuid required	Unique identifier of the call for which messages are being retrieved.
cursor	Pagination cursor.


No request body


next	string	URL with the cursor value for the next page of results.
previous	string	URL with the cursor value for the previous page of results.
results	array	Array of message objects. Each message object contains:
ordinal	number	Ordinal position of the message. Used to determine sequence.
role	string	Role that generated the message. Corresponds to one of the following: `USER` or `ASSISTANT`.
text	string	The message text.

Get Call Recording

GET /calls/{uuid}/recording

Returns a link to the recording of the call (via a 302 redirect to the file location). The recording only becomes available after the call ends. If the recording is not yet available, a 425 (Too Early) HTTP status will be returned.

Parameters


uuid required	Unique identifier of the call for which the recording is being retrieved.


No request body


detail	string	Only returned if call recording was not enabled. If a recording was enabled, there is no response body and the call recording location is provided via a 302 redirect.

Examples

curl --request GET \
--url https://api.ultravox.ai/api/voices \
--header 'X-API-Key: aBCDef.123456'

fetch('https://api.ultravox.ai/api/voices', {
  method: 'GET',
  headers: {
    'X-API-Key': 'aBCDef.123456'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Response

cURL
JavaScript

{
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "lily",
      "description": "Default Female",
      "previewUrl": "https://zfmrfvimiaqahezndsse.supabase.co/storage/v1/object/public/ultravox-voice-previews/lily_preview.wav"
    },
    {
      "name": "terrence",
      "description": "Default Male",
      "previewUrl": "https://zfmrfvimiaqahezndsse.supabase.co/storage/v1/object/public/ultravox-voice-previews/terrence_preview.wav"
    }
  ]
}

{
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "lily",
      "description": "Default Female",
      "previewUrl": "https://zfmrfvimiaqahezndsse.supabase.co/storage/v1/object/public/ultravox-voice-previews/lily_preview.wav"
    },
    {
      "name": "terrence",
      "description": "Default Male",
      "previewUrl": "https://zfmrfvimiaqahezndsse.supabase.co/storage/v1/object/public/ultravox-voice-previews/terrence_preview.wav"
    }
  ]
}