openapi: 3.1.0 info: title: Speech-to-speech (EVI) subpackage_chats API version: 1.0.0 servers: - url: https://api.hume.ai tags: - name: subpackage_chats paths: /v0/evi/chats: get: operationId: list-chats summary: List chats description: Fetches a paginated list of **Chats**. tags: - subpackage_chats 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: Filter to only include chats that used this config. required: false 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: X-Hume-Api-Key in: header required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/return_paged_chats' /v0/evi/chats/{id}: get: operationId: list-chat-events summary: List chat events description: Fetches a paginated list of **Chat** events. tags: - subpackage_chats parameters: - name: id in: path description: Identifier for a Chat. 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_paged_events' /v0/evi/chats/{id}/audio: get: operationId: get-audio summary: Get chat audio description: Fetches the audio of a previous **Chat**. 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_chats parameters: - name: id in: path description: Identifier for a Chat. 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/ReturnChatAudioReconstruction' 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_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 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 ReturnChatPagedEventsPaginationDirection: type: string enum: - ASC - DESC title: ReturnChatPagedEventsPaginationDirection ReturnChatPagedEventsStatus: type: string enum: - ACTIVE - USER_ENDED - USER_TIMEOUT - MAX_DURATION_TIMEOUT - INACTIVITY_TIMEOUT - ERROR title: ReturnChatPagedEventsStatus ReturnChatAudioReconstructionStatus: type: string enum: - QUEUED - IN_PROGRESS - COMPLETE - ERROR - CANCELLED title: ReturnChatAudioReconstructionStatus return_paged_chats: type: object properties: 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`. 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/ReturnPagedChatsPaginationDirection' total_pages: type: integer description: The total number of pages in the collection. required: - chats_page - page_number - page_size - pagination_direction - total_pages description: A paginated list of chats returned from the server title: return_paged_chats ReturnPagedChatsPaginationDirection: type: string enum: - ASC - DESC title: ReturnPagedChatsPaginationDirection 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 return_chat_paged_events: 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. 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 a Chat. Formatted as a UUID. metadata: type: - string - 'null' description: Stringified JSON with additional metadata about the chat. 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/ReturnChatPagedEventsPaginationDirection' start_timestamp: type: integer format: int64 description: Time at which the Chat started. Measured in seconds since the Unix epoch. status: $ref: '#/components/schemas/ReturnChatPagedEventsStatus' total_pages: type: integer description: The total number of pages in the collection. required: - chat_group_id - events_page - id - page_number - page_size - pagination_direction - start_timestamp - status - total_pages description: A description of chat status with a paginated list of chat events returned from the server title: return_chat_paged_events 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