openapi: 3.1.0
info:
title: Speech-to-speech (EVI) subpackage_prompts API
version: 1.0.0
servers:
- url: https://api.hume.ai
tags:
- name: subpackage_prompts
paths:
/v0/evi/prompts:
post:
operationId: create-prompt
summary: Create prompt
description: 'Creates a **Prompt** that can be added to an [EVI configuration](/reference/speech-to-speech-evi/configs/create-config).
See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt.'
tags:
- subpackage_prompts
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_prompt_public'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/posted_prompt'
get:
operationId: list-prompts
summary: List prompts
description: 'Fetches a paginated list of **Prompts**.
See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt.'
tags:
- subpackage_prompts
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 prompt. To include all versions of each prompt in the list, set `restrict_to_most_recent` to false.
required: false
schema:
type: boolean
- name: name
in: query
description: Filter to only include prompts with 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_prompts'
/v0/evi/prompts/{id}:
get:
operationId: list-prompt-versions
summary: List prompt versions
description: 'Fetches a list of a **Prompt''s** versions.
See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt.'
tags:
- subpackage_prompts
parameters:
- name: id
in: path
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 prompt. To include all versions of each prompt 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_prompts'
post:
operationId: create-prompt-version
summary: Create prompt version
description: 'Updates a **Prompt** by creating a new version of the **Prompt**.
See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt.'
tags:
- subpackage_prompts
parameters:
- name: id
in: path
description: Identifier for a Prompt. 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_prompt_public'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/posted_prompt_version'
patch:
operationId: update-prompt-name
summary: Update prompt name
description: 'Updates the name of a **Prompt**.
See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt.'
tags:
- subpackage_prompts
parameters:
- name: id
in: path
description: Identifier for a Prompt. 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/prompts_update-prompt-name_Response_200'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/posted_prompt_name'
delete:
operationId: delete-prompt
summary: Delete prompt
description: 'Deletes a **Prompt** and its versions.
See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt.'
tags:
- subpackage_prompts
parameters:
- name: id
in: path
description: Identifier for a Prompt. 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/prompts_delete-prompt_Response_200'
/v0/evi/prompts/{id}/version/{version}:
get:
operationId: get-prompt-version
summary: Get prompt version
description: 'Fetches a specified version of a **Prompt**.
See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt.'
tags:
- subpackage_prompts
parameters:
- name: id
in: path
description: Identifier for a Prompt. Formatted as a UUID.
required: true
schema:
type: string
format: uuid
- name: version
in: path
description: 'Version number for a Prompt.
Prompts, Configs, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine prompts and revert to previous versions if needed.
Version numbers are integer values representing different iterations of the Prompt. Each update to the Prompt 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_prompt_public'
patch:
operationId: update-prompt-description
summary: Update prompt description
description: 'Updates the description of a **Prompt**.
See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt.'
tags:
- subpackage_prompts
parameters:
- name: id
in: path
description: Identifier for a Prompt. Formatted as a UUID.
required: true
schema:
type: string
format: uuid
- name: version
in: path
description: 'Version number for a Prompt.
Prompts, Configs, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine prompts and revert to previous versions if needed.
Version numbers are integer values representing different iterations of the Prompt. Each update to the Prompt 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_prompt_public'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/patched_prompt_version_description'
delete:
operationId: delete-prompt-version
summary: Delete prompt version
description: 'Deletes a specified version of a **Prompt**.
See our [prompting guide](/docs/speech-to-speech-evi/guides/phone-calling) for tips on crafting your system prompt.'
tags:
- subpackage_prompts
parameters:
- name: id
in: path
description: Identifier for a Prompt. Formatted as a UUID.
required: true
schema:
type: string
format: uuid
- name: version
in: path
description: 'Version number for a Prompt.
Prompts, Configs, Custom Voices, and Tools are versioned. This versioning system supports iterative development, allowing you to progressively refine prompts and revert to previous versions if needed.
Version numbers are integer values representing different iterations of the Prompt. Each update to the Prompt 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/prompts_delete-prompt-version_Response_200'
components:
schemas:
posted_prompt_name:
type: object
properties:
name:
type: string
description: Name applied to all versions of a particular Prompt.
required:
- name
description: A prompt name change to be posted to the server
title: posted_prompt_name
posted_prompt:
type: object
properties:
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_description:
type:
- string
- 'null'
description: An optional description of the Prompt version.
required:
- name
- text
description: A prompt to be posted to the server
title: posted_prompt
prompts_delete-prompt-version_Response_200:
type: object
properties: {}
description: Empty response body
title: prompts_delete-prompt-version_Response_200
prompts_update-prompt-name_Response_200:
type: object
properties: {}
description: Empty response body
title: prompts_update-prompt-name_Response_200
patched_prompt_version_description:
type: object
properties:
version_description:
type:
- string
- 'null'
description: An optional description of the Prompt version.
description: A prompt version description to be patched to the server
title: patched_prompt_version_description
ReturnPromptVersionType:
type: string
enum:
- FIXED
- LATEST
title: ReturnPromptVersionType
posted_prompt_version:
type: object
properties:
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_description:
type:
- string
- 'null'
description: An optional description of the Prompt version.
required:
- text
description: A new version of an existing prompt to be posted to the server
title: posted_prompt_version
return_prompt:
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.
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:
$ref: '#/components/schemas/ReturnPromptVersionType'
required:
- created_on
- id
- modified_on
- name
- text
- version
- version_type
description: A Prompt associated with this Config.
title: return_prompt
prompts_delete-prompt_Response_200:
type: object
properties: {}
description: Empty response body
title: prompts_delete-prompt_Response_200
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
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
return_paged_prompts:
type: object
properties:
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.'
prompts_page:
type: array
items:
$ref: '#/components/schemas/return_prompt'
description: List of prompts returned for the specified `page_number` and `page_size`.
total_pages:
type: integer
description: The total number of pages in the collection.
required:
- page_number
- page_size
- prompts_page
- total_pages
description: A paginated list of prompt versions returned from the server
title: return_paged_prompts
securitySchemes:
bearerAuth:
type: apiKey
in: header
name: X-Hume-Api-Key