openapi: 3.1.0
info:
  title: Speech-to-speech (EVI) subpackage_tools API
  version: 1.0.0
servers:
- url: https://api.hume.ai
tags:
- name: subpackage_tools
paths:
  /v0/evi/tools:
    post:
      operationId: create-tool
      summary: Create tool
      description: 'Creates a **Tool** that can be added to an [EVI configuration](/reference/speech-to-speech-evi/configs/create-config).


        Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI.'
      tags:
      - subpackage_tools
      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_user_defined_tool'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/posted_user_defined_tool'
    get:
      operationId: list-tools
      summary: List tools
      description: 'Fetches a paginated list of **Tools**.


        Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI.'
      tags:
      - subpackage_tools
      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 tool. To include all versions of each tool in the list, set `restrict_to_most_recent` to false.
        required: false
        schema:
          type: boolean
      - name: name
        in: query
        description: Filter to only include tools 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_user_defined_tools'
  /v0/evi/tools/{id}:
    get:
      operationId: list-tool-versions
      summary: List tool versions
      description: 'Fetches a list of a **Tool''s** versions.


        Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI.'
      tags:
      - subpackage_tools
      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 tool. To include all versions of each tool 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_user_defined_tools'
    post:
      operationId: create-tool-version
      summary: Create tool version
      description: 'Updates a **Tool** by creating a new version of the **Tool**.


        Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI.'
      tags:
      - subpackage_tools
      parameters:
      - name: id
        in: path
        description: Identifier for a Tool. 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_user_defined_tool'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/posted_user_defined_tool_version'
    patch:
      operationId: update-tool-name
      summary: Update tool name
      description: 'Updates the name of a **Tool**.


        Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI.'
      tags:
      - subpackage_tools
      parameters:
      - name: id
        in: path
        description: Identifier for a Tool. 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/tools_update-tool-name_Response_200'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/posted_user_defined_tool_name'
    delete:
      operationId: delete-tool
      summary: Delete tool
      description: 'Deletes a **Tool** and its versions.


        Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI.'
      tags:
      - subpackage_tools
      parameters:
      - name: id
        in: path
        description: Identifier for a Tool. 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/tools_delete-tool_Response_200'
  /v0/evi/tools/{id}/version/{version}:
    get:
      operationId: get-tool-version
      summary: Get tool version
      description: 'Fetches a specified version of a **Tool**.


        Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI.'
      tags:
      - subpackage_tools
      parameters:
      - name: id
        in: path
        description: Identifier for a Tool. Formatted as a UUID.
        required: true
        schema:
          type: string
          format: uuid
      - name: version
        in: path
        description: 'Version number for a Tool.


          Tools, Configs, Custom Voices, and Prompts are versioned. This versioning system supports iterative development, allowing you to progressively refine tools and revert to previous versions if needed.


          Version numbers are integer values representing different iterations of the Tool. Each update to the Tool 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_user_defined_tool'
    patch:
      operationId: update-tool-description
      summary: Update tool description
      description: 'Updates the description of a specified **Tool** version.


        Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI.'
      tags:
      - subpackage_tools
      parameters:
      - name: id
        in: path
        description: Identifier for a Tool. Formatted as a UUID.
        required: true
        schema:
          type: string
          format: uuid
      - name: version
        in: path
        description: 'Version number for a Tool.


          Tools, Configs, Custom Voices, and Prompts are versioned. This versioning system supports iterative development, allowing you to progressively refine tools and revert to previous versions if needed.


          Version numbers are integer values representing different iterations of the Tool. Each update to the Tool 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_user_defined_tool'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/posted_user_defined_tool_version_description'
    delete:
      operationId: delete-tool-version
      summary: Delete tool version
      description: 'Deletes a specified version of a **Tool**.


        Refer to our [tool use](/docs/speech-to-speech-evi/features/tool-use#function-calling) guide for comprehensive instructions on defining and integrating tools into EVI.'
      tags:
      - subpackage_tools
      parameters:
      - name: id
        in: path
        description: Identifier for a Tool. Formatted as a UUID.
        required: true
        schema:
          type: string
          format: uuid
      - name: version
        in: path
        description: 'Version number for a Tool.


          Tools, Configs, Custom Voices, and Prompts are versioned. This versioning system supports iterative development, allowing you to progressively refine tools and revert to previous versions if needed.


          Version numbers are integer values representing different iterations of the Tool. Each update to the Tool 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/tools_delete-tool-version_Response_200'
components:
  schemas:
    posted_user_defined_tool:
      type: object
      properties:
        description:
          type:
          - string
          - 'null'
          description: An optional description of what the Tool does, used by the supplemental LLM to choose when and how to call the function.
        fallback_content:
          type:
          - string
          - 'null'
          description: 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.
        name:
          type: string
          description: '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:
          type: string
          description: '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.'
        version_description:
          type:
          - string
          - 'null'
          description: An optional description of the Tool version.
      required:
      - name
      - parameters
      description: A tool to be posted to the server
      title: posted_user_defined_tool
    return_paged_user_defined_tools:
      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.'
        tools_page:
          type: array
          items:
            $ref: '#/components/schemas/return_user_defined_tool'
          description: List of tools 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
      - tools_page
      - total_pages
      description: A paginated list of user defined tool versions returned from the server
      title: return_paged_user_defined_tools
    ReturnUserDefinedToolToolType:
      type: string
      enum:
      - BUILTIN
      - FUNCTION
      title: ReturnUserDefinedToolToolType
    tools_update-tool-name_Response_200:
      type: object
      properties: {}
      description: Empty response body
      title: tools_update-tool-name_Response_200
    posted_user_defined_tool_name:
      type: object
      properties:
        name:
          type: string
          description: '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).'
      required:
      - name
      description: A tool name change to be posted to the server
      title: posted_user_defined_tool_name
    tools_delete-tool_Response_200:
      type: object
      properties: {}
      description: Empty response body
      title: tools_delete-tool_Response_200
    tools_delete-tool-version_Response_200:
      type: object
      properties: {}
      description: Empty response body
      title: tools_delete-tool-version_Response_200
    posted_user_defined_tool_version_description:
      type: object
      properties:
        version_description:
          type:
          - string
          - 'null'
          description: An optional description of the Tool version.
      description: A tool version description to be posted to the server
      title: posted_user_defined_tool_version_description
    posted_user_defined_tool_version:
      type: object
      properties:
        description:
          type:
          - string
          - 'null'
          description: An optional description of what the Tool does, used by the supplemental LLM to choose when and how to call the function.
        fallback_content:
          type:
          - string
          - 'null'
          description: 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.
        parameters:
          type: string
          description: '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.'
        version_description:
          type:
          - string
          - 'null'
          description: An optional description of the Tool version.
      required:
      - parameters
      description: A new version of an existing tool to be posted to the server
      title: posted_user_defined_tool_version
    return_user_defined_tool:
      type: object
      properties:
        created_on:
          type: integer
          format: int64
          description: The timestamp when the first version of this tool was created.
        description:
          type:
          - string
          - 'null'
          description: An optional description of what the Tool does, used by the supplemental LLM to choose when and how to call the function.
        fallback_content:
          type:
          - string
          - 'null'
          description: 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.
        id:
          type: string
          description: Identifier for a Tool. Formatted as a UUID.
        modified_on:
          type: integer
          format: int64
          description: The timestamp when this version of the tool was created.
        name:
          type: string
          description: '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:
          type: string
          description: '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:
          $ref: '#/components/schemas/ReturnUserDefinedToolToolType'
        version:
          type: integer
          description: Version number for a Tool. 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 Tool version.
        version_type:
          $ref: '#/components/schemas/ReturnUserDefinedToolVersionType'
      required:
      - created_on
      - id
      - modified_on
      - name
      - parameters
      - tool_type
      - version
      - version_type
      description: A specific tool version returned from the server
      title: return_user_defined_tool
    ReturnUserDefinedToolVersionType:
      type: string
      enum:
      - FIXED
      - LATEST
      title: ReturnUserDefinedToolVersionType
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: X-Hume-Api-Key