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