openapi: 3.1.0
info:
title: Speech-to-speech (EVI) subpackage_chatGroups API
version: 1.0.0
servers:
- url: https://api.hume.ai
tags:
- name: subpackage_chatGroups
paths:
/v0/evi/chat_groups:
get:
operationId: list-chat-groups
summary: List chat_groups
description: Fetches a paginated list of **Chat Groups**.
tags:
- subpackage_chatGroups
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: ascending_order
in: query
description: Specifies the sorting order of the results based on their creation date. Set to true for ascending order (chronological, with the oldest records first) and false for descending order (reverse-chronological, with the newest records first). Defaults to true.
required: false
schema:
type: boolean
- name: config_id
in: query
description: 'The unique identifier for an EVI configuration.
Filter Chat Groups to only include Chats that used this `config_id` in their most recent Chat.'
required: false
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/return_paged_chat_groups'
/v0/evi/chat_groups/{id}:
get:
operationId: get-chat-group
summary: Get chat_group
description: Fetches a **ChatGroup** by ID, including a paginated list of **Chats** associated with the **ChatGroup**.
tags:
- subpackage_chatGroups
parameters:
- name: id
in: path
description: Identifier for a Chat Group. Formatted as a UUID.
required: true
schema:
type: string
format: uuid
- name: status
in: query
description: Chat status to apply to the chat. String from the ChatStatus enum.
required: false
schema:
type: string
- 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: 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: ascending_order
in: query
description: Specifies the sorting order of the results based on their creation date. Set to true for ascending order (chronological, with the oldest records first) and false for descending order (reverse-chronological, with the newest records first). Defaults to true.
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_chat_group_paged_chats'
/v0/evi/chat_groups/{id}/audio:
get:
operationId: get-audio
summary: Get chat group audio
description: Fetches a paginated list of audio for each **Chat** within the specified **Chat Group**. For more details, see our guide on audio reconstruction [here](/docs/speech-to-speech-evi/faq#can-i-access-the-audio-of-previous-conversations-with-evi).
tags:
- subpackage_chatGroups
parameters:
- name: id
in: path
description: Identifier for a Chat Group. 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: ascending_order
in: query
description: Specifies the sorting order of the results based on their creation date. Set to true for ascending order (chronological, with the oldest records first) and false for descending order (reverse-chronological, with the newest records first). Defaults to true.
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_chat_group_paged_audio_reconstructions'
/v0/evi/chat_groups/{id}/events:
get:
operationId: list-chat-group-events
summary: List chat events from a specific chat_group
description: Fetches a paginated list of **Chat** events associated with a **Chat Group**.
tags:
- subpackage_chatGroups
parameters:
- name: id
in: path
description: Identifier for a Chat Group. Formatted as a UUID.
required: true
schema:
type: string
format: uuid
- 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: 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: ascending_order
in: query
description: Specifies the sorting order of the results based on their creation date. Set to true for ascending order (chronological, with the oldest records first) and false for descending order (reverse-chronological, with the newest records first). Defaults to true.
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_chat_group_paged_events'
components:
schemas:
ReturnChatStatus:
type: string
enum:
- ACTIVE
- USER_ENDED
- USER_TIMEOUT
- MAX_DURATION_TIMEOUT
- INACTIVITY_TIMEOUT
- ERROR
title: ReturnChatStatus
ReturnChatAudioReconstruction:
type: object
properties:
filename:
type:
- string
- 'null'
description: Name of the chat audio reconstruction file.
id:
type: string
description: Identifier for the chat. Formatted as a UUID.
modified_at:
type:
- integer
- 'null'
format: int64
description: The timestamp of the most recent status change for this audio reconstruction, formatted milliseconds since the Unix epoch.
signed_audio_url:
type:
- string
- 'null'
description: Signed URL used to download the chat audio reconstruction file.
signed_url_expiration_timestamp_millis:
type:
- integer
- 'null'
format: int64
description: The timestamp when the signed URL will expire, formatted as a Unix epoch milliseconds.
status:
$ref: '#/components/schemas/ReturnChatAudioReconstructionStatus'
user_id:
type: string
description: Identifier for the user that owns this chat. Formatted as a UUID.
required:
- id
- status
- user_id
description: List of chat audio reconstructions returned for the specified page number and page size.
title: ReturnChatAudioReconstruction
return_chat_group_paged_chats:
type: object
properties:
active:
type: boolean
chats_page:
type: array
items:
$ref: '#/components/schemas/return_chat'
description: List of Chats and their metadata returned for the specified `page_number` and `page_size`.
first_start_timestamp:
type: integer
format: int64
description: Time at which the first Chat in this Chat Group was created. Measured in seconds since the Unix epoch.
id:
type: string
description: Identifier for the Chat Group. Any Chat resumed from this Chat Group will have the same `chat_group_id`. Formatted as a UUID.
most_recent_start_timestamp:
type: integer
format: int64
description: Time at which the most recent Chat in this Chat Group was created. Measured in seconds since the Unix epoch.
num_chats:
type: integer
description: The total number of Chats associated with this Chat Group.
page_number:
type: integer
description: '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:
type: integer
description: 'The maximum number of items returned per page.
This value corresponds to the `page_size` parameter specified in the request.'
pagination_direction:
$ref: '#/components/schemas/ReturnChatGroupPagedChatsPaginationDirection'
total_pages:
type: integer
description: The total number of pages in the collection.
required:
- chats_page
- first_start_timestamp
- id
- most_recent_start_timestamp
- num_chats
- page_number
- page_size
- pagination_direction
- total_pages
description: A description of chat_group and its status with a paginated list of each chat in the chat_group
title: return_chat_group_paged_chats
ReturnChatGroupPagedAudioReconstructionsPaginationDirection:
type: string
enum:
- ASC
- DESC
title: ReturnChatGroupPagedAudioReconstructionsPaginationDirection
return_config_spec:
type: object
properties:
id:
type: string
description: Identifier for a Config. Formatted as a UUID.
version:
type:
- integer
- 'null'
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:
- id
description: The Config associated with this Chat.
title: return_config_spec
return_chat_group_paged_audio_reconstructions:
type: object
properties:
audio_reconstructions_page:
type: array
items:
$ref: '#/components/schemas/ReturnChatAudioReconstruction'
description: List of chat audio reconstructions returned for the specified page number and page size.
id:
type: string
description: Identifier for the chat group. Formatted as a UUID.
num_chats:
type: integer
description: Total number of chats in this chatgroup
page_number:
type: integer
description: '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:
type: integer
description: 'The maximum number of items returned per page.
This value corresponds to the `page_size` parameter specified in the request.'
pagination_direction:
$ref: '#/components/schemas/ReturnChatGroupPagedAudioReconstructionsPaginationDirection'
total_pages:
type: integer
description: The total number of pages in the collection.
user_id:
type: string
description: Identifier for the user that owns this chat. Formatted as a UUID.
required:
- audio_reconstructions_page
- id
- num_chats
- page_number
- page_size
- pagination_direction
- total_pages
- user_id
description: A paginated list of chat reconstructions for a particular chatgroup
title: return_chat_group_paged_audio_reconstructions
return_paged_chat_groups:
type: object
properties:
chat_groups_page:
type: array
items:
$ref: '#/components/schemas/return_chat_group'
description: List of Chat Groups and their metadata returned for the specified `page_number` and `page_size`.
page_number:
type: integer
description: '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:
type: integer
description: 'The maximum number of items returned per page.
This value corresponds to the `page_size` parameter specified in the request.'
pagination_direction:
$ref: '#/components/schemas/ReturnPagedChatGroupsPaginationDirection'
total_pages:
type: integer
description: The total number of pages in the collection.
required:
- chat_groups_page
- page_number
- page_size
- pagination_direction
- total_pages
description: A paginated list of chat_groups returned from the server
title: return_paged_chat_groups
return_chat_group:
type: object
properties:
active:
type: boolean
first_start_timestamp:
type: integer
format: int64
description: Time at which the first Chat in this Chat Group was created. Measured in seconds since the Unix epoch.
id:
type: string
description: Identifier for the Chat Group. Any Chat resumed from this Chat Group will have the same `chat_group_id`. Formatted as a UUID.
most_recent_chat_id:
type:
- string
- 'null'
description: The `chat_id` of the most recent Chat in this Chat Group. Formatted as a UUID.
most_recent_config:
$ref: '#/components/schemas/return_config_spec'
most_recent_start_timestamp:
type: integer
format: int64
description: Time at which the most recent Chat in this Chat Group was created. Measured in seconds since the Unix epoch.
num_chats:
type: integer
description: The total number of Chats associated with this Chat Group.
required:
- first_start_timestamp
- id
- most_recent_start_timestamp
- num_chats
description: A description of chat_group and its status
title: return_chat_group
return_chat_group_paged_events:
type: object
properties:
events_page:
type: array
items:
$ref: '#/components/schemas/return_chat_event'
description: List of Chat Events for the specified `page_number` and `page_size`.
id:
type: string
description: Identifier for the Chat Group. Any Chat resumed from this Chat Group will have the same `chat_group_id`. Formatted as a UUID.
page_number:
type: integer
description: '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:
type: integer
description: 'The maximum number of items returned per page.
This value corresponds to the `page_size` parameter specified in the request.'
pagination_direction:
$ref: '#/components/schemas/ReturnChatGroupPagedEventsPaginationDirection'
total_pages:
type: integer
description: The total number of pages in the collection.
required:
- events_page
- id
- page_number
- page_size
- pagination_direction
- total_pages
description: A paginated list of chat events that occurred across chats in this chat_group from the server
title: return_chat_group_paged_events
ReturnChatGroupPagedEventsPaginationDirection:
type: string
enum:
- ASC
- DESC
title: ReturnChatGroupPagedEventsPaginationDirection
ReturnChatEventRole:
type: string
enum:
- USER
- AGENT
- SYSTEM
- TOOL
title: ReturnChatEventRole
ReturnChatEventType:
type: string
enum:
- AGENT_MESSAGE
- ASSISTANT_PROSODY
- CHAT_START_MESSAGE
- CHAT_END_MESSAGE
- FUNCTION_CALL
- FUNCTION_CALL_RESPONSE
- PAUSE_ONSET
- RESUME_ONSET
- SESSION_SETTINGS
- SYSTEM_PROMPT
- USER_INTERRUPTION
- USER_MESSAGE
- USER_RECORDING_START_MESSAGE
title: ReturnChatEventType
ReturnChatAudioReconstructionStatus:
type: string
enum:
- QUEUED
- IN_PROGRESS
- COMPLETE
- ERROR
- CANCELLED
title: ReturnChatAudioReconstructionStatus
return_chat:
type: object
properties:
chat_group_id:
type: string
description: Identifier for the Chat Group. Any chat resumed from this Chat will have the same `chat_group_id`. Formatted as a UUID.
config:
$ref: '#/components/schemas/return_config_spec'
end_timestamp:
type:
- integer
- 'null'
format: int64
description: Time at which the Chat ended. Measured in seconds since the Unix epoch.
event_count:
type:
- integer
- 'null'
format: int64
description: The total number of events currently in this chat.
id:
type: string
description: Identifier for a Chat. Formatted as a UUID.
metadata:
type:
- string
- 'null'
description: Stringified JSON with additional metadata about the chat.
start_timestamp:
type: integer
format: int64
description: Time at which the Chat started. Measured in seconds since the Unix epoch.
status:
$ref: '#/components/schemas/ReturnChatStatus'
required:
- chat_group_id
- id
- start_timestamp
- status
description: A description of chat and its status
title: return_chat
ReturnChatGroupPagedChatsPaginationDirection:
type: string
enum:
- ASC
- DESC
title: ReturnChatGroupPagedChatsPaginationDirection
ReturnPagedChatGroupsPaginationDirection:
type: string
enum:
- ASC
- DESC
title: ReturnPagedChatGroupsPaginationDirection
return_chat_event:
type: object
properties:
chat_id:
type: string
description: Identifier for the Chat this event occurred in. Formatted as a UUID.
emotion_features:
type:
- string
- 'null'
description: 'Stringified JSON containing the prosody model inference results.
EVI uses the prosody model to measure 48 expressions related to speech and vocal characteristics. These results contain a detailed emotional and tonal analysis of the audio. Scores typically range from 0 to 1, with higher values indicating a stronger confidence level in the measured attribute.'
id:
type: string
description: Identifier for a Chat Event. Formatted as a UUID.
message_text:
type:
- string
- 'null'
description: The text of the Chat Event. This field contains the message content for each event type listed in the `type` field.
metadata:
type:
- string
- 'null'
description: Stringified JSON with additional metadata about the chat event.
related_event_id:
type:
- string
- 'null'
description: Identifier for a related chat event. Currently only seen on ASSISTANT_PROSODY events, to point back to the ASSISTANT_MESSAGE that generated these prosody scores
role:
$ref: '#/components/schemas/ReturnChatEventRole'
timestamp:
type: integer
format: int64
description: Time at which the Chat Event occurred. Measured in seconds since the Unix epoch.
type:
$ref: '#/components/schemas/ReturnChatEventType'
required:
- chat_id
- id
- role
- timestamp
- type
description: A description of a single event in a chat returned from the server
title: return_chat_event
securitySchemes:
bearerAuth:
type: apiKey
in: header
name: X-Hume-Api-Key