openapi: 3.1.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:
ReturnedWebhookSpecEventsItems:
type: string
enum:
- chat_started
- chat_ended
- tool_call
description: "The list of events the specified URL is subscribed to. \n\nSee our [webhooks guide](/docs/speech-to-speech-evi/configuration/build-a-configuration#supported-events) for more information on supported events."
title: ReturnedWebhookSpecEventsItems
posted_ellm_model:
type: object
properties:
allow_short_responses:
type:
- boolean
- 'null'
description: 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).
description: A eLLM model configuration to be posted to the server
title: posted_ellm_model
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
VoiceProvider:
type: string
enum:
- HUME_AI
- CUSTOM_VOICE
title: VoiceProvider
posted_event_message_specs:
type: object
properties:
on_inactivity_timeout:
$ref: '#/components/schemas/PostedEventMessageSpecsOnInactivityTimeout'
on_max_duration_timeout:
$ref: '#/components/schemas/PostedEventMessageSpecsOnMaxDurationTimeout'
on_new_chat:
$ref: '#/components/schemas/PostedEventMessageSpecsOnNewChat'
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: posted_event_message_specs
posted_config_version_description:
type: object
properties:
version_description:
type:
- string
- 'null'
description: An optional description of the Config version.
description: A config version description to be posted to the server
title: posted_config_version_description
ReturnPromptVersionType:
type: string
enum:
- FIXED
- LATEST
title: ReturnPromptVersionType
ReturnConfigEventMessages:
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'
title: ReturnConfigEventMessages
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
PostedBuiltinToolName:
type: string
enum:
- web_search
- hang_up
title: PostedBuiltinToolName
prompt_expansion_spec:
type: object
properties:
enabled:
type: boolean
description: 'Boolean indicating whether prompt expansion is enabled.
Defaults to `true`. When set to `false`, no additional instructions are appended to the system prompt, giving full control over the prompt content. Only applicable when using an external supplemental language model.'
description: Configuration for prompt expansion behavior.
title: prompt_expansion_spec
posted_config_prompt_spec:
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.
description: Identifies which prompt to use in a a config OR how to create a new prompt to use in the config
title: posted_config_prompt_spec
return_ellm_model:
type: object
properties:
allow_short_responses:
type: boolean
description: 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).
required:
- allow_short_responses
description: A specific eLLM Model configuration
title: return_ellm_model
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
return_timeout_specs:
type: object
properties:
inactivity:
$ref: '#/components/schemas/return_timeout_spec'
max_duration:
$ref: '#/components/schemas/return_timeout_spec'
required:
- inactivity
- max_duration
description: '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.'
title: return_timeout_specs
ReturnUserDefinedToolVersionType:
type: string
enum:
- FIXED
- LATEST
title: ReturnUserDefinedToolVersionType
PostedTimeoutSpecsMaxDuration:
type: object
properties:
duration_secs:
type:
- integer
- 'null'
enabled:
type: boolean
required:
- enabled
title: PostedTimeoutSpecsMaxDuration
PostedTimeoutSpecsInactivity:
type: object
properties:
duration_secs:
type:
- integer
- 'null'
enabled:
type: boolean
required:
- enabled
title: PostedTimeoutSpecsInactivity
ReturnVoice:
type: object
properties:
compatible_octave_models:
type: array
items:
type: string
id:
type: string
description: ID of the voice in the `Voice Library`.
name:
type: string
description: Name of the voice in the `Voice Library`.
provider:
$ref: '#/components/schemas/VoiceProvider'
required:
- id
- name
- provider
description: An Octave voice available for text-to-speech
title: ReturnVoice
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
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
ReturnBuiltinToolToolType:
type: string
enum:
- BUILTIN
- FUNCTION
title: ReturnBuiltinToolToolType
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
ReturnConfigEllmModel:
type: object
properties:
allow_short_responses:
type: boolean
description: 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).
required:
- allow_short_responses
title: ReturnConfigEllmModel
ReturnConfigNudges:
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
title: ReturnConfigNudges
PostedConfigTimeouts:
type: object
properties:
inactivity:
$ref: '#/components/schemas/PostedTimeoutSpecsInactivity'
max_duration:
$ref: '#/components/schemas/PostedTimeoutSpecsMaxDuration'
title: PostedConfigTimeouts
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 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:
- id
title: VoiceId
configs_update-config-name_Response_200:
type: object
properties: {}
description: Empty response body
title: configs_update-config-name_Response_200
return_prompt_public:
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.
prompt_expansion:
$ref: '#/components/schemas/prompt_expansion_spec'
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:
type: string
description: Indicates whether this prompt is using a fixed version number or auto-updating to the latest version. Values from the VersionType enum.
required:
- created_on
- id
- modified_on
- name
- text
- version
- version_type
description: A specific prompt version returned from the server
title: return_prompt_public
PostedEventMessageSpecsOnNewChat:
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: PostedEventMessageSpecsOnNewChat
posted_builtin_tool:
type: object
properties:
fallback_content:
type:
- string
- 'null'
description: 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.
name:
$ref: '#/components/schemas/PostedBuiltinToolName'
required:
- name
description: A configuration of a built-in tool to be posted to the server
title: posted_builtin_tool
PostedWebhookSpecEventsItems:
type: string
enum:
- chat_started
- chat_ended
- tool_call
description: "The list of events the specified URL is subscribed to. \n\nSee our [webhooks guide](/docs/speech-to-speech-evi/configuration/build-a-configuration#supported-events) for more information on supported events."
title: Po
# --- 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