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
Path parameters
idstringRequiredformat: "uuid"
Identifier for a Config. Formatted as a UUID.
versionintegerRequired
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.
Response
Success
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.
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.
