Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Speech-to-speech (EVI) Subpackage Configs API
version: 1.0.0
servers:
- url: https://api.hume.ai
tags:
- name: subpackage_configs
paths:
/v0/evi/configs:
post:
operationId: create-config
summary: Create config
description: 'Creates a **Config** which can be applied to EVI.
For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration).'
tags:
- subpackage_configs
parameters:
- name: X-Hume-Api-Key
in: header
required: true
schema:
type: string
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/return_config_public'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/posted_config'
get:
operationId: list-configs
summary: List configs
description: 'Fetches a paginated list of **Configs**.
For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration).'
tags:
- subpackage_configs
parameters:
- name: page_number
in: query
description: 'Specifies the page number to retrieve, enabling pagination.
This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page.'
required: false
schema:
type: integer
default: 0
- name: page_size
in: query
description: 'Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive.
For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10.'
required: false
schema:
type: integer
- name: restrict_to_most_recent
in: query
description: By default, `restrict_to_most_recent` is set to true, returning only the latest version of each config. To include all versions of each config in the list, set `restrict_to_most_recent` to false.
required: false
schema:
type: boolean
- name: name
in: query
description: Filter to only include configs with this name.
required: false
schema:
type: string
- name: X-Hume-Api-Key
in: header
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/return_paged_configs'
/v0/evi/configs/{id}:
get:
operationId: list-config-versions
summary: List config versions
description: 'Fetches a list of a **Config''s** versions.
For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration).'
tags:
- subpackage_configs
parameters:
- name: id
in: path
description: Identifier for a Config. Formatted as a UUID.
required: true
schema:
type: string
format: uuid
- name: page_number
in: query
description: 'Specifies the page number to retrieve, enabling pagination.
This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page.'
required: false
schema:
type: integer
default: 0
- name: page_size
in: query
description: 'Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive.
For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10.'
required: false
schema:
type: integer
- name: restrict_to_most_recent
in: query
description: By default, `restrict_to_most_recent` is set to true, returning only the latest version of each config. To include all versions of each config in the list, set `restrict_to_most_recent` to false.
required: false
schema:
type: boolean
- name: X-Hume-Api-Key
in: header
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/return_paged_configs'
post:
operationId: create-config-version
summary: Create config version
description: 'Updates a **Config** by creating a new version of the **Config**.
For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration).'
tags:
- subpackage_configs
parameters:
- name: id
in: path
description: Identifier for a Config. Formatted as a UUID.
required: true
schema:
type: string
format: uuid
- name: X-Hume-Api-Key
in: header
required: true
schema:
type: string
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/return_config_public'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/posted_config_version'
patch:
operationId: update-config-name
summary: Update config name
description: 'Updates the name of a **Config**.
For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration).'
tags:
- subpackage_configs
parameters:
- name: id
in: path
description: Identifier for a Config. Formatted as a UUID.
required: true
schema:
type: string
format: uuid
- name: X-Hume-Api-Key
in: header
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/configs_update-config-name_Response_200'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/posted_config_name'
delete:
operationId: delete-config
summary: Delete config
description: 'Deletes a **Config** and its versions.
For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration).'
tags:
- subpackage_configs
parameters:
- name: id
in: path
description: Identifier for a Config. Formatted as a UUID.
required: true
schema:
type: string
format: uuid
- name: X-Hume-Api-Key
in: header
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/configs_delete-config_Response_200'
/v0/evi/configs/{id}/version/{version}:
get:
operationId: get-config-version
summary: Get config version
description: 'Fetches a specified version of a **Config**.
For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration).'
tags:
- subpackage_configs
parameters:
- name: id
in: path
description: Identifier for a Config. Formatted as a UUID.
required: true
schema:
type: string
format: uuid
- name: version
in: path
description: '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.'
required: true
schema:
type: integer
- name: X-Hume-Api-Key
in: header
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/return_config_public'
patch:
operationId: update-config-description
summary: Update config description
description: 'Updates the description of a **Config**.
For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration).'
tags:
- subpackage_configs
parameters:
- name: id
in: path
description: Identifier for a Config. Formatted as a UUID.
required: true
schema:
type: string
format: uuid
- name: version
in: path
description: '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.'
required: true
schema:
type: integer
- name: X-Hume-Api-Key
in: header
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/return_config_public'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/posted_config_version_description'
delete:
operationId: delete-config-version
summary: Delete config version
description: 'Deletes a specified version of a **Config**.
For more details on configuration options and how to configure EVI, see our [configuration guide](/docs/speech-to-speech-evi/configuration).'
tags:
- subpackage_configs
parameters:
- name: id
in: path
description: Identifier for a Config. Formatted as a UUID.
required: true
schema:
type: string
format: uuid
- name: version
in: path
description: '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.'
required: true
schema:
type: integer
- name: X-Hume-Api-Key
in: header
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/configs_delete-config-version_Response_200'
components:
schemas:
posted_turn_detection_spec:
type: object
properties:
end_of_turn_silence_ms:
type:
- integer
- 'null'
description: 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_ms:
type:
- integer
- 'null'
description: 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_threshold:
type:
- number
- 'null'
format: double
description: 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.
description: A turn detection specification posted to the server
title: posted_turn_detection_spec
posted_nudge_spec:
type: object
properties:
enabled:
type:
- boolean
- 'null'
description: If true, EVI will 'nudge' the user to speak after a determined interval of silence.
interval_secs:
type:
- integer
- 'null'
description: The interval of inactivity (in seconds) before a nudge is triggered.
description: A nudge specification posted to the server
title: posted_nudge_spec
return_nudge_spec:
type: object
properties:
enabled:
type: boolean
description: If true, EVI will 'nudge' the user to speak after a determined interval of silence.
interval_secs:
type:
- integer
- 'null'
description: The interval of inactivity (in seconds) before a nudge is triggered.
required:
- enabled
description: A specific nudge configuration returned from the server
title: return_nudge_spec
ReturnConfigLanguageModel:
type: object
properties:
model_provider:
$ref: '#/components/schemas/ModelProviderEnum'
model_resource:
$ref: '#/components/schemas/LanguageModelType'
temperature:
type:
- number
- 'null'
format: double
description: '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.'
title: ReturnConfigLanguageModel
ReturnConfigPrompt:
type: object
properties:
created_on:
type: integer
format: int64
description: Time at which the Prompt was created. Measured in seconds since the Unix epoch.
id:
type: string
description: Identifier for a Prompt. Formatted as a UUID.
modified_on:
type: integer
format: int64
description: Time at which the Prompt was last modified. Measured in seconds since the Unix epoch.
name:
type: string
description: Name applied to all versions of a particular Prompt.
text:
type: string
description: '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](/docs/speech-to-speech-evi/guides/prompting).'
version:
type: integer
description: Version number for a Prompt. Version numbers should be integers. The combination of configId and version number is unique.
version_description:
type:
- string
- 'null'
description: An optional description of the Prompt version.
version_type:
$ref: '#/components/schemas/ReturnPromptVersionType'
required:
- created_on
- id
- modified_on
- name
- text
- version
- version_type
title: ReturnConfigPrompt
return_event_message_spec:
type: object
properties:
enabled:
type: boolean
description: 'Boolean indicating if this event message is enabled.
If set to `true`, a message will be sent when the circumstances for the specific event are met.'
text:
type:
- string
- 'null'
description: Text to use as the event message when the corresponding event occurs. If no text is specified, EVI will generate an appropriate message based on its current context and the system prompt.
required:
- enabled
description: A specific event message configuration to be returned from the server
title: return_event_message_spec
configs_update-config-name_Response_200:
type: object
properties: {}
description: Empty response body
title: configs_update-config-name_Response_200
LanguageModelType:
type: string
enum:
- claude-3-7-sonnet-latest
- claude-opus-4-6
- claude-3-5-sonnet-latest
- claude-3-5-haiku-latest
- claude-3-5-sonnet-20240620
- claude-3-opus-20240229
- claude-3-sonnet-20240229
- claude-3-haiku-20240307
- claude-sonnet-4-20250514
- claude-sonnet-4-5-20250929
- claude-haiku-4-5-20251001
- us.anthropic.claude-3-5-haiku-20241022-v1:0
- us.anthropic.claude-3-5-sonnet-20240620-v1:0
- us.anthropic.claude-3-haiku-20240307-v1:0
- gpt-oss-120b
- qwen-3-235b-a22b
- qwen-3-235b-a22b-instruct-2507
- qwen-3-235b-a22b-thinking-2507
- gemini-1.5-pro
- gemini-1.5-flash
- gemini-1.5-pro-002
- gemini-1.5-flash-002
- gemini-2.0-flash
- gemini-2.5-flash
- gemini-2.5-flash-preview-04-17
- gpt-4-turbo
- gpt-4-turbo-preview
- gpt-3.5-turbo-0125
- gpt-3.5-turbo
- gpt-4o
- gpt-4o-mini
- gpt-4.1
- gpt-5
- gpt-5-mini
- gpt-5-nano
- gpt-4o-priority
- gpt-4o-mini-priority
- gpt-4.1-priority
- gpt-5-priority
- gpt-5-mini-priority
- gpt-5-nano-priority
- gpt-5.1
- gpt-5.1-priority
- gpt-5.2
- gpt-5.2-priority
- gemma-7b-it
- llama3-8b-8192
- llama3-70b-8192
- llama-3.1-70b-versatile
- llama-3.3-70b-versatile
- llama-3.1-8b-instant
- moonshotai/kimi-k2-instruct
- accounts/fireworks/models/mixtral-8x7b-instruct
- accounts/fireworks/models/llama-v3p1-405b-instruct
- accounts/fireworks/models/llama-v3p1-70b-instruct
- accounts/fireworks/models/llama-v3p1-8b-instruct
- sonar
- sonar-pro
- sambanova
- DeepSeek-R1-Distill-Llama-70B
- Llama-4-Maverick-17B-128E-Instruct
- Qwen3-32B
- grok-4-fast-non-reasoning-latest
- ellm
- custom-language-model
- hume-evi-3-web-search
title: LanguageModelType
PostedConfigPrompt:
type: object
properties:
id:
type:
- string
- 'null'
description: Identifier for a Prompt. Formatted as a UUID.
prompt_expansion:
$ref: '#/components/schemas/prompt_expansion_spec'
text:
type:
- string
- 'null'
description: Text used to create a new prompt for a particular config.
version:
type:
- integer
- 'null'
description: Version number for a Prompt. Version numbers should be integers. The combination of configId and version number is unique.
title: PostedConfigPrompt
ModelProviderEnum:
type: string
enum:
- GROQ
- OPEN_AI
- FIREWORKS
- ANTHROPIC
- CUSTOM_LANGUAGE_MODEL
- GOOGLE
- HUME_AI
- AMAZON_BEDROCK
- PERPLEXITY
- SAMBANOVA
- CEREBRAS
- X_AI
title: ModelProviderEnum
PostedConfigTimeouts:
type: object
properties:
inactivity:
$ref: '#/components/schemas/PostedTimeoutSpecsInactivity'
max_duration:
$ref: '#/components/schemas/PostedTimeoutSpecsMaxDuration'
title: PostedConfigTimeouts
return_interruption_spec:
type: object
properties:
min_interruption_ms:
type:
- integer
- 'null'
description: 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.
description: An interruption configuration returned from the server
title: return_interruption_spec
PostedEventMessageSpecsOnInactivityTimeout:
type: object
properties:
enabled:
type: boolean
description: 'Boolean indicating if this event message is enabled.
If set to `true`, a message will be sent when the circumstances for the specific event are met.'
text:
type:
- string
- 'null'
description: Text to use as the event message when the corresponding event occurs. If no text is specified, EVI will generate an appropriate message based on its current context and the system prompt.
required:
- enabled
title: PostedEventMessageSpecsOnInactivityTimeout
posted_config:
type: object
properties:
builtin_tools:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/posted_builtin_tool'
description: Built-in tool specification for a Config.
ellm_model:
$ref: '#/components/schemas/PostedConfigEllmModel'
event_messages:
$ref: '#/components/schemas/PostedConfigEventMessages'
evi_version:
type: string
description: EVI version to use. Only versions `3` and `4-mini` are supported.
interruption:
$ref: '#/components/schemas/posted_interruption_spec'
language_model:
$ref: '#/components/schemas/PostedConfigLanguageModel'
name:
type: string
description: Name applied to all versions of a particular Config.
nudges:
$ref: '#/components/schemas/PostedConfigNudges'
prompt:
$ref: '#/components/schemas/PostedConfigPrompt'
timeouts:
$ref: '#/components/schemas/PostedConfigTimeouts'
tools:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/posted_user_defined_tool_spec'
description: Tool specification for a Config.
turn_detection:
$ref: '#/components/schemas/posted_turn_detection_spec'
version_description:
type:
- string
- 'null'
description: An optional description of the Config version.
voice:
$ref: '#/components/schemas/VoiceRef'
description: A voice specification associated with this Config.
webhooks:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/posted_webhook_spec'
description: Webhook config specifications for each subscriber.
required:
- evi_version
- name
description: A configuration to be posted to the server
title: posted_config
return_config:
type: object
properties:
builtin_tools:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/return_builtin_tool'
description: List of built-in tools associated with this Config.
created_on:
type: integer
format: int64
description: Time at which the Config was created. Measured in seconds since the Unix epoch.
ellm_model:
$ref: '#/components/schemas/ReturnConfigEllmModel'
event_messages:
$ref: '#/components/schemas/ReturnConfigEventMessages'
evi_version:
type: string
description: 'Specifies the EVI version to use. See our [EVI Version Guide](/docs/speech-to-speech-evi/configuration/evi-version) 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](/docs/speech-to-speech-evi/configuration/evi-version#migrating-to-evi-3) before then.'
id:
type: string
description: Identifier for a Config. Formatted as a UUID.
interruption:
$ref: '#/components/schemas/return_interruption_spec'
language_model:
$ref: '#/components/schemas/ReturnConfigLanguageModel'
modified_on:
type: integer
format: int64
description: Time at which the Config was last modified. Measured in seconds since the Unix epoch.
name:
type: string
description: Name applied to all versions of a particular Config.
nudges:
$ref: '#/components/schemas/ReturnConfigNudges'
prompt:
$ref: '#/components/schemas/ReturnConfigPrompt'
timeouts:
$ref: '#/components/schemas/ReturnConfigTimeouts'
tools:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/return_user_defined_tool'
description: List of user-defined tools associated with this Config.
turn_detection:
$ref: '#/components/schemas/return_turn_detection_spec'
version:
type: integer
description: '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_description:
type:
- string
- 'null'
description: An optional description of the Config version.
voice:
$ref: '#/components/schemas/ReturnVoice'
description: A voice specification associated with this Config.
webhooks:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/returned_webhook_spec'
description: Map of webhooks associated with this config.
description: A specific config version returned from the server
title: return_config
PostedBuiltinToolName:
type: string
enum:
- web_search
- hang_up
title: PostedBuiltinToolName
posted_config_version:
type: object
properties:
builtin_tools:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/posted_builtin_tool'
description: Built-in tool specification for a Config.
ellm_model:
$ref: '#/components/schemas/posted_ellm_model'
event_messages:
$ref: '#/components/schemas/posted_event_message_specs'
evi_version:
type: string
description: EVI version to use. Only versions `3` and `4-mini` are supported.
interruption:
$ref: '#/components/schemas/posted_interruption_spec'
language_model:
$ref: '#/components/schemas/posted_language_model'
nudges:
$ref: '#/components/schemas/posted_nudge_spec'
prompt:
$ref: '#/components/schemas/posted_config_prompt_spec'
timeouts:
$ref: '#/components/schemas/posted_timeout_specs'
tools:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/posted_user_defined_tool_spec'
description: Tool specification for a Config.
turn_detection:
$ref: '#/components/schemas/posted_turn_detection_spec'
version_description:
type:
- string
- 'null'
description: An optional description of the Config version.
voice:
$ref: '#/components/schemas/VoiceRef'
webhooks:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/posted_webhook_spec'
description: Webhook config specifications for each subscriber.
required:
- evi_version
description: A new version of an existing configuration to be posted to the server
title: posted_config_version
PostedTimeoutSpecsInactivity:
type: object
properties:
duration_secs:
type:
- integer
- 'null'
enabled:
type: boolean
required:
- enabled
title: PostedTimeoutSpecsInactivity
return_event_message_specs:
type: object
properties:
on_inactivity_timeout:
$ref: '#/components/schemas/return_event_message_spec'
on_max_duration_timeout:
$ref: '#/components/schemas/return_event_message_spec'
on_new_chat:
$ref: '#/components/schemas/return_event_message_spec'
description: '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.'
title: return_event_message_specs
VoiceName:
type: object
properties:
name:
type: string
description: The name of a **Voice**.
provider:
$ref: '#/components/schemas/VoiceProvider'
description: "Specifies the source provider associated with the chosen voice.\n\n- **`HUME_AI`**: Select voices from Hume's [Voice Library](https://app.hume.ai/tts/voice-library), containing a variety of preset, shared voices.\n- **`CUSTOM_VOICE`**: Select from voices you've personally generated and saved in your account. \n\nIf no provider is explicitly set, the default provider is `CUSTOM_VOICE`. When using voices from Hume's **Voice Library**, you must explicitly set the provider to `HUME_AI`.\n\nPreset voices from Hume's **Voice Library** are accessible by all users. In contrast, your custom voices are private and accessible only via requests authenticated with your API key."
required:
- name
title: VoiceName
VoiceId:
type: object
properties:
id:
type: string
description: The unique ID associated with the **Voice**.
provider:
$ref: '#/components/schemas/VoiceProvider'
description: "Specifies the source provider associated with the chosen voice.\n\n- **`HUME_AI`**: Select voices from Hume's [Voice Library](https://app.hume.ai/tts/voice-library), containing a variety of preset, shared voices.\n- **`CUSTOM_VOICE`**: Select from voices you've personally generated and saved in your account. \n\nIf no provider is explicitly set, the default provider is `CUSTOM_VOICE`. When using voices from Hume's **Voice Library**, you must explicitly set the provider
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hume-ai/refs/heads/main/openapi/hume-ai-subpackage-configs-api-openapi.yml