> This page is for Voice APIs.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://dev.hume.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.hume.ai/_mcp/server.

# List configs

GET https://api.hume.ai/v0/evi/configs

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).

Reference: https://dev.hume.ai/voice/reference/speech-to-speech-evi/configs/list-configs

## Authentication

- `X-Hume-Api-Key` header (required) — API Key authentication via header

## Request

### Query parameters

- `page_number` (integer, optional, default: 0) — 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.
- `page_size` (integer, optional) — 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.
- `restrict_to_most_recent` (boolean, optional) — 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.
- `name` (string, optional) — Filter to only include configs with this name.

## Response

### 200

Success

- `total_pages` (integer, required) — The total number of pages in the collection.
- `configs_page` (list of return_config, optional) — List of configs returned for the specified `page_number` and `page_size`.
- `page_number` (integer, optional) — The page number of the returned list. This value corresponds to the `page_number` parameter specified in the request. Pagination uses zero-based indexing.
- `page_size` (integer, optional) — The maximum number of items returned per page. This value corresponds to the `page_size` parameter specified in the request.

## Types

### return_config

A specific config version returned from the server

- `builtin_tools` (list of return_builtin_tool, optional, nullable) — List of built-in tools associated with this Config.
- `created_on` (long, optional) — Time at which the Config was created. Measured in seconds since the Unix epoch.
- `ellm_model` (ReturnConfigEllmModel, optional) — 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.
- `event_messages` (ReturnConfigEventMessages, optional) — Map of event messages associated with this config.
- `evi_version` (string, optional) — 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` (string, optional) — Identifier for a Config. Formatted as a UUID.
- `interruption` (return_interruption_spec, optional) — An interruption configuration returned from the server
- `language_model` (ReturnConfigLanguageModel, optional) — 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.
- `modified_on` (long, optional) — Time at which the Config was last modified. Measured in seconds since the Unix epoch.
- `name` (string, optional) — Name applied to all versions of a particular Config.
- `nudges` (ReturnConfigNudges, optional) — 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.
- `prompt` (ReturnConfigPrompt, optional) — A Prompt associated with this Config.
- `timeouts` (ReturnConfigTimeouts, optional) — Map of timeouts associated with this config.
- `tools` (list of return_user_defined_tool, optional, nullable) — List of user-defined tools associated with this Config.
- `turn_detection` (return_turn_detection_spec, optional) — A turn detection configuration returned from the server
- `version` (integer, optional) — 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` (string, optional, nullable) — An optional description of the Config version.
- `voice` (ReturnVoice, optional) — A voice specification associated with this Config.
- `webhooks` (list of returned_webhook_spec, optional, nullable) — Map of webhooks associated with this config.

### return_builtin_tool

A specific builtin tool version returned from the server

- `name` (string, required) — 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). For more information, see our guide on [using built-in tools](/docs/speech-to-speech-evi/features/tool-use#using-built-in-tools).
- `tool_type` (enum, required)
  - Allowed values: `BUILTIN`, `FUNCTION`
- `fallback_content` (string, optional, nullable) — 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.

### ReturnConfigEllmModel

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_responses` (boolean, required) — 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).

### ReturnConfigEventMessages

Map of event messages associated with this config.

- `on_inactivity_timeout` (return_event_message_spec, optional) — A specific event message configuration to be returned from the server
- `on_max_duration_timeout` (return_event_message_spec, optional) — A specific event message configuration to be returned from the server
- `on_new_chat` (return_event_message_spec, optional) — A specific event message configuration to be returned from the server

### return_interruption_spec

An interruption configuration returned from the server

- `min_interruption_ms` (integer, optional, nullable) — 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.

### ReturnConfigLanguageModel

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_provider` (enum, optional)
  - Allowed values: `GROQ`, `OPEN_AI`, `FIREWORKS`, `ANTHROPIC`, `CUSTOM_LANGUAGE_MODEL`, `GOOGLE`, `HUME_AI`, `AMAZON_BEDROCK`, `PERPLEXITY`, `SAMBANOVA`, `CEREBRAS`, `X_AI`
- `model_resource` (enum, optional)
  - Allowed values: `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`
- `temperature` (float, optional, nullable) — 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.

### ReturnConfigNudges

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.

- `enabled` (boolean, required) — If true, EVI will 'nudge' the user to speak after a determined interval of silence.
- `interval_secs` (integer, optional, nullable) — The interval of inactivity (in seconds) before a nudge is triggered.

### ReturnConfigPrompt

A Prompt associated with this Config.

- `created_on` (long, required) — Time at which the Prompt was created. Measured in seconds since the Unix epoch.
- `id` (string, required) — Identifier for a Prompt. Formatted as a UUID.
- `modified_on` (long, required) — Time at which the Prompt was last modified. Measured in seconds since the Unix epoch.
- `name` (string, required) — Name applied to all versions of a particular Prompt.
- `text` (string, required) — 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` (integer, required) — Version number for a Prompt. Version numbers should be integers. The combination of configId and version number is unique.
- `version_type` (enum, required)
  - Allowed values: `FIXED`, `LATEST`
- `version_description` (string, optional, nullable) — An optional description of the Prompt version.

### ReturnConfigTimeouts

Map of timeouts associated with this config.

- `inactivity` (return_timeout_spec, required) — A specific timeout configuration to be returned from the server
- `max_duration` (return_timeout_spec, required) — A specific timeout configuration to be returned from the server

### return_user_defined_tool

A specific tool version returned from the server

- `created_on` (long, required) — The timestamp when the first version of this tool was created.
- `id` (string, required) — Identifier for a Tool. Formatted as a UUID.
- `modified_on` (long, required) — The timestamp when this version of the tool was created.
- `name` (string, required) — 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). For more information, see our guide on [using built-in tools](/docs/speech-to-speech-evi/features/tool-use#using-built-in-tools).
- `parameters` (string, required) — 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_type` (enum, required)
  - Allowed values: `BUILTIN`, `FUNCTION`
- `version` (integer, required) — Version number for a Tool. Version numbers should be integers. The combination of configId and version number is unique.
- `version_type` (enum, required)
  - Allowed values: `FIXED`, `LATEST`
- `description` (string, optional, nullable) — An optional description of what the Tool does, used by the supplemental LLM to choose when and how to call the function.
- `fallback_content` (string, optional, nullable) — 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_description` (string, optional, nullable) — An optional description of the Tool version.

### return_turn_detection_spec

A turn detection configuration returned from the server

- `end_of_turn_silence_ms` (integer, optional, nullable) — 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` (integer, optional, nullable) — 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` (float, optional, nullable) — 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.

### ReturnVoice

An Octave voice available for text-to-speech

- `id` (string, required) — ID of the voice in the `Voice Library`.
- `name` (string, required) — Name of the voice in the `Voice Library`.
- `provider` (enum, required)
  - Allowed values: `HUME_AI`, `CUSTOM_VOICE`
- `compatible_octave_models` (list of string, optional)

### returned_webhook_spec

Collection of webhook URL endpoints to be returned from the server

- `events` (list of enum, required) — The list of events the specified URL is subscribed to. See our [webhooks guide](/docs/speech-to-speech-evi/configuration/build-a-configuration#supported-events) for more information on supported events.
  - Allowed values: `chat_started`, `chat_ended`, `tool_call`
- `url` (string, required) — 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.

### return_event_message_spec

A specific event message configuration to be returned from the server

- `enabled` (boolean, required) — 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` (string, optional, nullable) — 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.

### return_timeout_spec

A specific timeout configuration to be returned from the server

- `enabled` (boolean, required) — Boolean indicating if this timeout is enabled. If set to false, EVI will not timeout due to a specified duration being reached. However, the conversation will eventually disconnect after 1,800 seconds (30 minutes), which is the maximum WebSocket duration limit for EVI.
- `duration_secs` (integer, optional, nullable) — Duration in seconds for the timeout (e.g. 600 seconds represents 10 minutes).

## Examples

**Response**

```json
{
  "total_pages": 1,
  "configs_page": [
    {
      "builtin_tools": [],
      "created_on": 1715267200693,
      "ellm_model": {
        "allow_short_responses": false
      },
      "event_messages": {
        "on_inactivity_timeout": {
          "enabled": false,
          "text": ""
        },
        "on_max_duration_timeout": {
          "enabled": false,
          "text": ""
        },
        "on_new_chat": {
          "enabled": false,
          "text": ""
        }
      },
      "evi_version": "3",
      "id": "1b60e1a0-cc59-424a-8d2c-189d354db3f3",
      "language_model": {
        "model_provider": "ANTHROPIC",
        "model_resource": "claude-3-7-sonnet-latest",
        "temperature": 1
      },
      "modified_on": 1715267200693,
      "name": "Weather Assistant Config",
      "prompt": {
        "created_on": 1715267200693,
        "id": "af699d45-2985-42cc-91b9-af9e5da3bac5",
        "modified_on": 1715267200693,
        "name": "Weather Assistant Prompt",
        "text": "<role>You are an AI weather assistant providing users with accurate and up-to-date weather information. Respond to user queries concisely and clearly. Use simple language and avoid technical jargon. Provide temperature, precipitation, wind conditions, and any weather alerts. Include helpful tips if severe weather is expected.</role>",
        "version": 0,
        "version_type": "FIXED",
        "version_description": ""
      },
      "timeouts": {
        "inactivity": {
          "enabled": true,
          "duration_secs": 600
        },
        "max_duration": {
          "enabled": true,
          "duration_secs": 1800
        }
      },
      "tools": [],
      "version": 0,
      "version_description": "",
      "voice": {
        "id": "5bb7de05-c8fe-426a-8fcc-ba4fc4ce9f9c",
        "name": "Ava Song",
        "provider": "HUME_AI"
      }
    }
  ],
  "page_number": 0,
  "page_size": 1
}
```