For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
For more details on configuration options and how to configure EVI, see our configuration guide.
Authentication
X-Hume-Api-Keystring
API Key authentication via header
Request
This endpoint expects an object.
evi_versionstringRequired
EVI version to use. Only versions 3 and 4-mini are supported.
namestringRequired
Name applied to all versions of a particular Config.
builtin_toolslist of objects or nullOptional
Built-in tool specification for a Config.
nameenumRequired
Allowed values:
fallback_contentstring or nullOptional
Optional text passed to the supplemental LLM in place of the tool call result. The LLM then uses this text to generate a response back to the user, ensuring continuity in the conversation if the Tool errors.
ellm_modelobjectOptional
The eLLM setup associated with this Config.
Hume’s eLLM (empathic Large Language Model) is a multimodal language model that takes into account both expression measures and language. The eLLM generates short, empathic language responses and guides text-to-speech (TTS) prosody.
allow_short_responsesboolean or nullOptional
Boolean indicating if the eLLM is allowed to generate short responses (new EVI 3 configs default to disabled; new versions inherit prior value when omitted).
event_messagesobjectOptional
Map of event messages associated with this config.
on_inactivity_timeoutobjectOptional
Specifies the message EVI provides when the chat is about to be disconnected due to a user inactivity timeout, such as a message mentioning a lack of user input for a period of time.
Enabling an inactivity message allows developers to use this message event for “checking in” with the user if they are not responding to see if they are still active.
If the user does not respond in the number of seconds specified in the inactivity_timeout field, then EVI will say the message and the user has 15 seconds to respond. If they respond in time, the conversation will continue; if not, the conversation will end.
However, if the inactivity message is not enabled, then reaching the inactivity timeout will immediately end the connection.
on_max_duration_timeoutobjectOptional
Specifies the message EVI provides when the chat is disconnected due to reaching the maximum chat duration, such as a message mentioning the time limit for the chat has been reached.
on_new_chatobjectOptional
Specifies the initial message EVI provides when a new chat is started, such as a greeting or welcome message.
interruptionobjectOptional
An interruption specification posted to the server
min_interruption_msinteger or nullOptional
How long the user must speak while the agent is outputting audio before the agent stops and yields the floor. Lower values make the agent more responsive to the user speaking up, but increase the chance of noise or backchannels stopping the agent unnecessarily. Higher values make the agent harder to interrupt, allowing it to finish more of its response before yielding. Accepts values between 50 and 2000 milliseconds.
language_modelobjectOptional
The supplemental language model associated with this Config.
This model is used to generate longer, more detailed responses from EVI. Choosing an appropriate supplemental language model for your use case is crucial for generating fast, high-quality responses from EVI.
model_providerenumOptional
model_resourceenumOptional
temperaturefloat or nullOptional
The model temperature, with values between 0 to 1 (inclusive).
Controls the randomness of the LLM’s output, with values closer to 0 yielding focused, deterministic responses and values closer to 1 producing more creative, diverse responses.
nudgesobjectOptional
Configures nudges, brief audio prompts that can guide conversations when users pause or need encouragement to continue speaking. Nudges help create more natural, flowing interactions by providing gentle conversational cues.
enabledboolean or nullOptional
If true, EVI will 'nudge' the user to speak after a determined interval of silence.
interval_secsinteger or nullOptional
The interval of inactivity (in seconds) before a nudge is triggered.
promptobjectOptional
A Prompt associated with this Config.
idstring or nullOptional
Identifier for a Prompt. Formatted as a UUID.
prompt_expansionobjectOptional
Configuration for prompt expansion behavior.
textstring or nullOptional
Text used to create a new prompt for a particular config.
versioninteger or nullOptional
Version number for a Prompt. Version numbers should be integers. The combination of configId and version number is unique.
timeoutsobjectOptional
Map of timeouts associated with this config.
inactivityobjectOptional
max_durationobjectOptional
toolslist of objects or nullOptional
Tool specification for a Config.
idstringRequired
Identifier for a Tool. Formatted as a UUID.
versioninteger or nullOptional
Version number for a Tool. Version numbers should be integers. The combination of configId and version number is unique.
turn_detectionobjectOptional
A turn detection specification posted to the server
end_of_turn_silence_msinteger or nullOptional
How long the user must be silent before EVI considers their turn complete and begins generating a response. Lower values make conversations feel snappier but increase the chance of the agent responding during a mid-thought pause. Higher values give users more room to pause and collect their thoughts before the agent responds. Accepts values between 500 and 3000 milliseconds.
prefix_padding_msinteger or nullOptional
The duration of audio captured before the detected start of speech. This ensures the beginning of an utterance is not clipped. Accepts values between 0 and 1000 milliseconds.
speech_detection_thresholdfloat or nullOptional
How confident the system must be that audio contains speech before it begins processing. Lower values increase sensitivity, capturing softer speech at the cost of more noise-triggered processing. Higher values require clearer, louder audio to register as speech. Accepts values between 0.0 and 1.0.
version_descriptionstring or nullOptional
An optional description of the Config version.
voiceobjectOptional
A voice specification associated with this Config.
VoiceIdobjectRequired
OR
VoiceNameobjectRequired
webhookslist of objects or nullOptional
Webhook config specifications for each subscriber.
eventslist of enumsRequired
The list of events the specified URL is subscribed to.
See our webhooks guide for more information on supported events.
Allowed values:
urlstringRequired
The URL where event payloads will be sent. This must be a valid https URL to ensure secure communication. The server at this URL must accept POST requests with a JSON payload.
Response
Created
builtin_toolslist of objects or nullOptional
List of built-in tools associated with this Config.
namestring
Name of the built-in tool to use. Hume supports the following built-in tools:
web_search: enables EVI to search the web for up-to-date information when applicable.
hang_up: closes the WebSocket connection when appropriate (e.g., after detecting a farewell in the conversation).
Optional text passed to the supplemental LLM in place of the tool call result. The LLM then uses this text to generate a response back to the user, ensuring continuity in the conversation if the Tool errors.
created_onlongOptional
Time at which the Config was created. Measured in seconds since the Unix epoch.
ellm_modelobjectOptional
A specific eLLM Model configuration
allow_short_responsesboolean
Boolean indicating if the eLLM is allowed to generate short responses (new EVI 3 configs default to disabled; new versions inherit prior value when omitted).
event_messagesobjectOptional
Collection of event messages returned by the server.
Event messages are sent by the server when specific events occur during a chat session. These messages are used to configure behaviors for EVI, such as controlling how EVI starts a new conversation.
on_inactivity_timeoutobjectOptional
A specific event message configuration to be returned from the server
on_max_duration_timeoutobjectOptional
A specific event message configuration to be returned from the server
on_new_chatobjectOptional
A specific event message configuration to be returned from the server
evi_versionstringOptional
Specifies the EVI version to use. See our EVI Version Guide for differences between versions.
We’re officially sunsetting EVI versions 1 and 2 on August 30, 2025. To keep things running smoothly, be sure to migrate to EVI 3 before then.
idstringOptional
Identifier for a Config. Formatted as a UUID.
interruptionobjectOptional
An interruption configuration returned from the server
min_interruption_msinteger or nullOptional
How long the user must speak while the agent is outputting audio before the agent stops and yields the floor. Lower values make the agent more responsive to the user speaking up, but increase the chance of noise or backchannels stopping the agent unnecessarily. Higher values make the agent harder to interrupt, allowing it to finish more of its response before yielding. Accepts values between 50 and 2000 milliseconds.
language_modelobjectOptional
A specific LanguageModel
model_providerenumOptional
model_resourceenumOptional
temperaturefloat or nullOptional
The model temperature, with values between 0 to 1 (inclusive).
Controls the randomness of the LLM’s output, with values closer to 0 yielding focused, deterministic responses and values closer to 1 producing more creative, diverse responses.
modified_onlongOptional
Time at which the Config was last modified. Measured in seconds since the Unix epoch.
namestringOptional
Name applied to all versions of a particular Config.
nudgesobjectOptional
A specific nudge configuration returned from the server
enabledboolean
If true, EVI will 'nudge' the user to speak after a determined interval of silence.
interval_secsinteger or nullOptional
The interval of inactivity (in seconds) before a nudge is triggered.
promptobjectOptional
A specific prompt version returned from the server
created_onlong
Time at which the Prompt was created. Measured in seconds since the Unix epoch.
idstring
Identifier for a Prompt. Formatted as a UUID.
modified_onlong
Time at which the Prompt was last modified. Measured in seconds since the Unix epoch.
namestring
Name applied to all versions of a particular Prompt.
textstring
Instructions used to shape EVI’s behavior, responses, and style.
You can use the Prompt to define a specific goal or role for EVI, specifying how it should act or what it should focus on during the conversation. For example, EVI can be instructed to act as a customer support representative, a fitness coach, or a travel advisor, each with its own set of behaviors and response styles. For help writing a system prompt, see our Prompting Guide.
versioninteger
Version number for a Prompt. Version numbers should be integers. The combination of configId and version number is unique.
version_typestring
Indicates whether this prompt is using a fixed version number or auto-updating to the latest version. Values from the VersionType enum.
prompt_expansionobjectOptional
Configuration for prompt expansion behavior.
version_descriptionstring or nullOptional
An optional description of the Prompt version.
timeoutsobjectOptional
Collection of timeout specifications returned by the server.
Timeouts are sent by the server when specific time-based events occur during a chat session. These specifications set the inactivity timeout and the maximum duration an EVI WebSocket connection can stay open before it is automatically disconnected.
inactivityobject
A specific timeout configuration to be returned from the server
max_durationobject
A specific timeout configuration to be returned from the server
toolslist of objects or nullOptional
List of user-defined tools associated with this Config.
created_onlong
The timestamp when the first version of this tool was created.
idstring
Identifier for a Tool. Formatted as a UUID.
modified_onlong
The timestamp when this version of the tool was created.
namestring
Name of the built-in tool to use. Hume supports the following built-in tools:
web_search: enables EVI to search the web for up-to-date information when applicable.
hang_up: closes the WebSocket connection when appropriate (e.g., after detecting a farewell in the conversation).
Stringified JSON defining the parameters used by this version of the Tool.
These parameters define the inputs needed for the Tool's execution, including the expected data type and description for each input field. Structured as a stringified JSON schema, this format ensures the Tool receives data in the expected format.
tool_typeenum
Allowed values:
versioninteger
Version number for a Tool. Version numbers should be integers. The combination of configId and version number is unique.
version_typeenum
Allowed values:
descriptionstring or nullOptional
An optional description of what the Tool does, used by the supplemental LLM to choose when and how to call the function.
fallback_contentstring or nullOptional
Optional text passed to the supplemental LLM in place of the tool call result. The LLM then uses this text to generate a response back to the user, ensuring continuity in the conversation if the Tool errors.
version_descriptionstring or nullOptional
An optional description of the Tool version.
turn_detectionobjectOptional
A turn detection configuration returned from the server
end_of_turn_silence_msinteger or nullOptional
How long the user must be silent before EVI considers their turn complete and begins generating a response. Lower values make conversations feel snappier but increase the chance of the agent responding during a mid-thought pause. Higher values give users more room to pause and collect their thoughts before the agent responds. Accepts values between 500 and 3000 milliseconds.
prefix_padding_msinteger or nullOptional
The duration of audio captured before the detected start of speech. This ensures the beginning of an utterance is not clipped. Accepts values between 0 and 1000 milliseconds.
speech_detection_thresholdfloat or nullOptional
How confident the system must be that audio contains speech before it begins processing. Lower values increase sensitivity, capturing softer speech at the cost of more noise-triggered processing. Higher values require clearer, louder audio to register as speech. Accepts values between 0.0 and 1.0.
versionintegerOptional
Version number for a Config.
Configs, Prompts, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine configurations and revert to previous versions if needed.
Version numbers are integer values representing different iterations of the Config. Each update to the Config increments its version number.
version_descriptionstring or nullOptional
An optional description of the Config version.
voiceobjectOptional
An Octave voice available for text-to-speech
idstring
ID of the voice in the Voice Library.
namestring
Name of the voice in the Voice Library.
providerenum
Allowed values:
compatible_octave_modelslist of stringsOptional
webhookslist of objects or nullOptional
Map of webhooks associated with this config.
eventslist of enums
The list of events the specified URL is subscribed to.
See our webhooks guide for more information on supported events.
Allowed values:
urlstring
The URL where event payloads will be sent. This must be a valid https URL to ensure secure communication. The server at this URL must accept POST requests with a JSON payload.
