---
title: Knowledge Generative AI API
slug: q6qa8496
canonical_url: https://docs.coveo.com/en/q6qa8496/
collection: api-reference
source_format: yml
---
# Knowledge Generative AI API

- **OpenAPI Version:** `3.1.1`
- **API Version:** `v1`

## Servers

- **URL:** `https://platform.cloud.coveo.com`
  - **Description:** Generated server url

## Operations

### List agents

- **Method:** `GET`
- **Path:** `/api/preview/organizations/{organizationId}/agents`
- **Tags:** Agent Configuration API

Privilege required

\`\`\` {"owner":"COVEO_ML","targetDomain":"AGENT_CONFIGURATION","type":"VIEW","targetId":"\*"} \`\`\`

#### Parameters

##### `organizationId` required

- **In:** `path`

`string` — Organization identifier

##### `page`

- **In:** `query`

The zero-based index of the results page to retrieve

`integer`, format: `int32`, default: `0`

##### `perPage`

- **In:** `query`

The number of items to return per page

`integer`, format: `int32`, default: `10`

#### Responses

##### Status: 200 OK

###### Content-Type: \*/\*

- **`items`**

  `array`

  **Items:**

  - **`agentType` (required)**

    `string` — Agent type

  - **`followUpEnabled` (required)**

    `boolean` — Does the model support follow-up questions.

  - **`name` (required)**

    `string` — The name of the Agent

  - **`passageRetrievalModelId` (required)**

    `string` — Passage retrieval model identifier

  - **`behaviors`**

    `array` — Optional behaviors to persist with the created agent.

    **Items:**

    - **`conditions` (required)**

      `array` — The list of conditions that must be met for this behavior to apply.

      **Items:**

      `string` — The list of conditions that must be met for this behavior to apply.

    - **`obligation` (required)**

      `string` — The obligation/instruction that applies when conditions are met.

  - **`createdDate`**

    `string`, format: `date-time` — Creation timestamp in ISO-8601 format

  - **`description`**

    `string` — The description of the Agent

  - **`id`**

    `string`, format: `uuid` — The public UUID for this configuration

  - **`modifiedDate`**

    `string`, format: `date-time` — Last modification timestamp in ISO-8601 format

  - **`numberOfItemsToConsider`**

    `integer`, format: `int32` — The maximum number of items/documents to consider for the Passage Retrieval model

  - **`status`**

    `string` — Overall status of the Agent. Possible values: - ACTIVE: The agent is active and can be queried. - SOON_TO_BE_ARCHIVED: The agent is still available, but will be archived soon if it is not queried. - INACTIVE: The agent is not ready to be queried yet. - LIMITED: The latest build completed with issues that may affect performance. - ARCHIVED: The agent has been archived and is no longer active. - BUILD_IN_PROGRESS: A build or rebuild is currently in progress. - ERROR: The latest build failed and the issue is customer-visible. - NO_MODELS_DEFINED: No underlying models are configured for this agent. - NOT_FETCHED: The status property was not fetched from the server.

- **`pagination`**

  `object`

  - **`page`**

    `integer`, format: `int32`

  - **`perPage`**

    `integer`, format: `int32`

  - **`totalItems`**

    `integer`, format: `int32`

  - **`totalPages`**

    `integer`, format: `int32`

**Example:**

```json
{
  "items": [
    {
      "agentType": "",
      "behaviors": [],
      "createdDate": "",
      "description": "",
      "followUpEnabled": true,
      "id": "",
      "modifiedDate": "",
      "name": "",
      "numberOfItemsToConsider": 1,
      "passageRetrievalModelId": "",
      "status": ""
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 1,
    "totalItems": 1,
    "totalPages": 1
  }
}
```

### Create an agent

- **Method:** `POST`
- **Path:** `/api/preview/organizations/{organizationId}/agents`
- **Tags:** Agent Configuration API

Privilege required

\`\`\` {"owner":"COVEO_ML","targetDomain":"AGENT_CONFIGURATION","type":"CREATE","targetId":"\*"} \`\`\`

#### Parameters

##### `organizationId` required

- **In:** `path`

`string` — Organization identifier

#### Request Body

##### Content-Type: application/json

- **`agentType` (required)**

  `string` — Agent type

- **`followUpEnabled` (required)**

  `boolean` — Does the model support follow-up questions.

- **`name` (required)**

  `string` — The name of the Agent

- **`passageRetrievalModelId` (required)**

  `string` — Passage retrieval model identifier

- **`behaviors`**

  `array` — Optional behaviors to persist with the created agent.

  **Items:**

  - **`conditions` (required)**

    `array` — The list of conditions that must be met for this behavior to apply.

    **Items:**

    `string` — The list of conditions that must be met for this behavior to apply.

  - **`obligation` (required)**

    `string` — The obligation/instruction that applies when conditions are met.

- **`description`**

  `string` — The description of the Agent

- **`numberOfItemsToConsider`**

  `integer`, format: `int32` — The maximum number of items/documents to consider for the Passage Retrieval model

**Example:**

```json
{
  "agentType": "",
  "behaviors": [
    {
      "conditions": [
        ""
      ],
      "obligation": ""
    }
  ],
  "description": "",
  "followUpEnabled": true,
  "name": "",
  "numberOfItemsToConsider": 1,
  "passageRetrievalModelId": ""
}
```

#### Responses

##### Status: 200 OK

###### Content-Type: \*/\*

- **`agentType` (required)**

  `string` — Agent type

- **`followUpEnabled` (required)**

  `boolean` — Does the model support follow-up questions.

- **`name` (required)**

  `string` — The name of the Agent

- **`passageRetrievalModelId` (required)**

  `string` — Passage retrieval model identifier

- **`behaviors`**

  `array` — Optional behaviors to persist with the created agent.

  **Items:**

  - **`conditions` (required)**

    `array` — The list of conditions that must be met for this behavior to apply.

    **Items:**

    `string` — The list of conditions that must be met for this behavior to apply.

  - **`obligation` (required)**

    `string` — The obligation/instruction that applies when conditions are met.

- **`createdDate`**

  `string`, format: `date-time` — Creation timestamp in ISO-8601 format

- **`description`**

  `string` — The description of the Agent

- **`id`**

  `string`, format: `uuid` — The public UUID for this configuration

- **`modifiedDate`**

  `string`, format: `date-time` — Last modification timestamp in ISO-8601 format

- **`numberOfItemsToConsider`**

  `integer`, format: `int32` — The maximum number of items/documents to consider for the Passage Retrieval model

- **`status`**

  `string` — Overall status of the Agent. Possible values: - ACTIVE: The agent is active and can be queried. - SOON_TO_BE_ARCHIVED: The agent is still available, but will be archived soon if it is not queried. - INACTIVE: The agent is not ready to be queried yet. - LIMITED: The latest build completed with issues that may affect performance. - ARCHIVED: The agent has been archived and is no longer active. - BUILD_IN_PROGRESS: A build or rebuild is currently in progress. - ERROR: The latest build failed and the issue is customer-visible. - NO_MODELS_DEFINED: No underlying models are configured for this agent. - NOT_FETCHED: The status property was not fetched from the server.

**Example:**

```json
{
  "agentType": "",
  "behaviors": [
    {
      "conditions": [
        ""
      ],
      "obligation": ""
    }
  ],
  "createdDate": "",
  "description": "",
  "followUpEnabled": true,
  "id": "",
  "modifiedDate": "",
  "name": "",
  "numberOfItemsToConsider": 1,
  "passageRetrievalModelId": "",
  "status": ""
}
```

### Delete an agent

- **Method:** `DELETE`
- **Path:** `/api/preview/organizations/{organizationId}/agents/{agentId}`
- **Tags:** Agent Configuration API

Privilege required

\`\`\` {"owner":"COVEO_ML","targetDomain":"AGENT_CONFIGURATION","type":"EDIT","targetId":"\*"} \`\`\`

#### Parameters

##### `organizationId` required

- **In:** `path`

`string` — Organization identifier

##### `agentId` required

- **In:** `path`

`string`, format: `uuid`

#### Responses

##### Status: 204 No Content

### Get an agent by agentId

- **Method:** `GET`
- **Path:** `/api/preview/organizations/{organizationId}/agents/{agentId}`
- **Tags:** Agent Configuration API

Privilege required

\`\`\` {"owner":"COVEO_ML","targetDomain":"AGENT_CONFIGURATION","type":"VIEW","targetId":"\*"} \`\`\`

#### Parameters

##### `organizationId` required

- **In:** `path`

`string` — Organization identifier

##### `agentId` required

- **In:** `path`

`string`, format: `uuid`

#### Responses

##### Status: 200 OK

###### Content-Type: \*/\*

- **`agentType` (required)**

  `string` — Agent type

- **`followUpEnabled` (required)**

  `boolean` — Does the model support follow-up questions.

- **`name` (required)**

  `string` — The name of the Agent

- **`passageRetrievalModelId` (required)**

  `string` — Passage retrieval model identifier

- **`behaviors`**

  `array` — Optional behaviors to persist with the created agent.

  **Items:**

  - **`conditions` (required)**

    `array` — The list of conditions that must be met for this behavior to apply.

    **Items:**

    `string` — The list of conditions that must be met for this behavior to apply.

  - **`obligation` (required)**

    `string` — The obligation/instruction that applies when conditions are met.

- **`createdDate`**

  `string`, format: `date-time` — Creation timestamp in ISO-8601 format

- **`description`**

  `string` — The description of the Agent

- **`id`**

  `string`, format: `uuid` — The public UUID for this configuration

- **`modifiedDate`**

  `string`, format: `date-time` — Last modification timestamp in ISO-8601 format

- **`numberOfItemsToConsider`**

  `integer`, format: `int32` — The maximum number of items/documents to consider for the Passage Retrieval model

- **`status`**

  `string` — Overall status of the Agent. Possible values: - ACTIVE: The agent is active and can be queried. - SOON_TO_BE_ARCHIVED: The agent is still available, but will be archived soon if it is not queried. - INACTIVE: The agent is not ready to be queried yet. - LIMITED: The latest build completed with issues that may affect performance. - ARCHIVED: The agent has been archived and is no longer active. - BUILD_IN_PROGRESS: A build or rebuild is currently in progress. - ERROR: The latest build failed and the issue is customer-visible. - NO_MODELS_DEFINED: No underlying models are configured for this agent. - NOT_FETCHED: The status property was not fetched from the server.

**Example:**

```json
{
  "agentType": "",
  "behaviors": [
    {
      "conditions": [
        ""
      ],
      "obligation": ""
    }
  ],
  "createdDate": "",
  "description": "",
  "followUpEnabled": true,
  "id": "",
  "modifiedDate": "",
  "name": "",
  "numberOfItemsToConsider": 1,
  "passageRetrievalModelId": "",
  "status": ""
}
```

### Update an agent

- **Method:** `PATCH`
- **Path:** `/api/preview/organizations/{organizationId}/agents/{agentId}`
- **Tags:** Agent Configuration API

Privilege required

\`\`\` {"owner":"COVEO_ML","targetDomain":"AGENT_CONFIGURATION","type":"EDIT","targetId":"\*"} \`\`\`

#### Parameters

##### `organizationId` required

- **In:** `path`

`string` — Organization identifier

##### `agentId` required

- **In:** `path`

`string`, format: `uuid`

#### Request Body

##### Content-Type: application/json

- **`behaviors`**

  `array` — Optional behaviors to persist with the updated agent.

  **Items:**

  - **`conditions` (required)**

    `array` — The list of conditions that must be met for this behavior to apply.

    **Items:**

    `string` — The list of conditions that must be met for this behavior to apply.

  - **`obligation` (required)**

    `string` — The obligation/instruction that applies when conditions are met.

- **`description`**

  `string` — The description of the Agent

- **`name`**

  `string` — The name of the Agent

**Example:**

```json
{
  "behaviors": [
    {
      "conditions": [
        ""
      ],
      "obligation": ""
    }
  ],
  "description": "",
  "name": ""
}
```

#### Responses

##### Status: 200 OK

###### Content-Type: \*/\*

- **`agentType` (required)**

  `string` — Agent type

- **`followUpEnabled` (required)**

  `boolean` — Does the model support follow-up questions.

- **`name` (required)**

  `string` — The name of the Agent

- **`passageRetrievalModelId` (required)**

  `string` — Passage retrieval model identifier

- **`behaviors`**

  `array` — Optional behaviors to persist with the created agent.

  **Items:**

  - **`conditions` (required)**

    `array` — The list of conditions that must be met for this behavior to apply.

    **Items:**

    `string` — The list of conditions that must be met for this behavior to apply.

  - **`obligation` (required)**

    `string` — The obligation/instruction that applies when conditions are met.

- **`createdDate`**

  `string`, format: `date-time` — Creation timestamp in ISO-8601 format

- **`description`**

  `string` — The description of the Agent

- **`id`**

  `string`, format: `uuid` — The public UUID for this configuration

- **`modifiedDate`**

  `string`, format: `date-time` — Last modification timestamp in ISO-8601 format

- **`numberOfItemsToConsider`**

  `integer`, format: `int32` — The maximum number of items/documents to consider for the Passage Retrieval model

- **`status`**

  `string` — Overall status of the Agent. Possible values: - ACTIVE: The agent is active and can be queried. - SOON_TO_BE_ARCHIVED: The agent is still available, but will be archived soon if it is not queried. - INACTIVE: The agent is not ready to be queried yet. - LIMITED: The latest build completed with issues that may affect performance. - ARCHIVED: The agent has been archived and is no longer active. - BUILD_IN_PROGRESS: A build or rebuild is currently in progress. - ERROR: The latest build failed and the issue is customer-visible. - NO_MODELS_DEFINED: No underlying models are configured for this agent. - NOT_FETCHED: The status property was not fetched from the server.

**Example:**

```json
{
  "agentType": "",
  "behaviors": [
    {
      "conditions": [
        ""
      ],
      "obligation": ""
    }
  ],
  "createdDate": "",
  "description": "",
  "followUpEnabled": true,
  "id": "",
  "modifiedDate": "",
  "name": "",
  "numberOfItemsToConsider": 1,
  "passageRetrievalModelId": "",
  "status": ""
}
```

### Generates an answer for the given configuration

- **Method:** `POST`
- **Path:** `/api/preview/organizations/{organizationId}/agents/{agentId}/answer`
- **Tags:** Agent Orchestration API

Clients should send `Accept: text/event-stream, application/json` to receive streamed responses (`text/event-stream`) and JSON error responses for requests rejected before streaming begins (e.g., validation/auth errors).

#### Parameters

##### `organizationId` required

- **In:** `path`

The organization id

`string` — Organization identifier

##### `agentId` required

- **In:** `path`

The agent id

`string`, format: `uuid` — The agent id

#### Request Body

##### Content-Type: application/json

- **`q` (required)**

  `string` — The user question.

- **`analytics`**

  `object | null` — Analytics parameters to forward to the search API.

  - **`capture`**

    `boolean | null` — Whether the search API call should be tracked for analytics and ML purposes.

  - **`clientId`**

    `string | null` — A GUID representing the current client.

- **`aq`**

  `string` — The advanced query expression.

- **`citationsFieldToInclude`**

  `array` — The citation fields to include in the response.

  **Items:**

  `string` — The citation fields to include in the response.

- **`context`**

  `object`

- **`cq`**

  `string` — The constant query expression.

- **`facets`**

  `array` — The list of facets.

  **Items:**

  **One of:**

  - **`currentValues`**

    `array` — The values displayed by the facet in the search interface at the moment of the request.

    **Items:**

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

    - **`value`**

      `string` — The facet value name.

  - **`customSort`**

    `array` — Facet values that must appear at the top, in this order.

    **Items:**

    `string` — Facet values that must appear at the top, in this order.

  - **`facetId`**

    `string` — The unique identifier of the facet in the search interface.

  - **`field`**

    `string` — The name of the field on which to base the facet request.

  - **`filterFacetCount`**

    `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

  - **`freezeCurrentValues`**

    `boolean` — Whether to include the facet request's currentValues in corresponding facet response's values array.

  - **`injectionDepth`**

    `integer`, format: `int32` — The maximum number of items to scan for facet values.

  - **`isFieldExpanded`**

    `boolean` — Whether to make this facet request in the context of requesting more facet values.

  - **`numberOfValues`**

    `integer`, format: `int32` — The maximum number of facet values to fetch.

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting values.

  - **`resultsMustMatch`**

    `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

  - **`sortCriteria`**

    `string`, possible values: `"score", "alphanumeric", "alphanumericNatural", "occurrences", "score", "alphanumeric", "alphanumericNatural", "occurrences"` — The sort criterion to apply to the returned facet values. Values outside the documented list are accepted but treated as unsupported and deserialized to null, which causes the sort criterion to be omitted and the default behavior to apply.

  - **`type`**

    `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

  * **`basePath`**

    `array` — The base path shared by all values for the facet.

    **Items:**

    `string` — The base path shared by all values for the facet.

  * **`currentValues`**

    `array` — The values displayed by the facet in the search interface at the moment of the request.

    **Items:**

    - **`children`**

      `array` — The children of this hierarchical facet value.

      **Items:**

      - **`children`**

        `array` — The children of this hierarchical facet value.

        **Items:**

        - **`children`**

          `array` — The children of this hierarchical facet value.

          **Items:**

          - **`children`**

            `array` — The children of this hierarchical facet value.

            **Items:**

            - **`children`**

              `array` — The children of this hierarchical facet value.

              **Items:**

              - **`children`**

                `array` — The children of this hierarchical facet value.

                **Items:**

                - **`children`**

                  `array` — The children of this hierarchical facet value.

                  **Items:**

                  *[Circular Reference]*

                - **`preventAutoSelect`**

                  `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

                - **`previousState`**

                  `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

                - **`retrieveChildren`**

                  `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

                - **`retrieveCount`**

                  `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

                - **`state`**

                  `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

                - **`value`**

                  `string` — This represents a single path segment.

              - **`preventAutoSelect`**

                `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

              - **`previousState`**

                `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

              - **`retrieveChildren`**

                `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

              - **`retrieveCount`**

                `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

              - **`state`**

                `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

              - **`value`**

                `string` — This represents a single path segment.

            - **`preventAutoSelect`**

              `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

            - **`previousState`**

              `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

            - **`retrieveChildren`**

              `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

            - **`retrieveCount`**

              `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

            - **`state`**

              `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

            - **`value`**

              `string` — This represents a single path segment.

          - **`preventAutoSelect`**

            `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

          - **`previousState`**

            `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

          - **`retrieveChildren`**

            `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

          - **`retrieveCount`**

            `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

          - **`state`**

            `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

          - **`value`**

            `string` — This represents a single path segment.

        - **`preventAutoSelect`**

          `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

        - **`previousState`**

          `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

        - **`retrieveChildren`**

          `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

        - **`retrieveCount`**

          `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

        - **`state`**

          `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

        - **`value`**

          `string` — This represents a single path segment.

      - **`preventAutoSelect`**

        `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

      - **`previousState`**

        `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

      - **`retrieveChildren`**

        `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

      - **`retrieveCount`**

        `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

      - **`state`**

        `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

      - **`value`**

        `string` — This represents a single path segment.

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`retrieveChildren`**

      `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

    - **`retrieveCount`**

      `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

    - **`value`**

      `string` — This represents a single path segment.

  * **`delimitingCharacter`**

    `string`, default: `";"` — The character to use to split field values into a hierarchical sequence.

  * **`facetId`**

    `string` — The unique identifier of the facet in the search interface.

  * **`field`**

    `string` — The name of the field on which to base the facet request.

  * **`filterByBasePath`**

    `boolean` — Whether to use basePath as a filter for the results.

  * **`filterFacetCount`**

    `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

  * **`injectionDepth`**

    `integer`, format: `int32` — The maximum number of items to scan for facet values.

  * **`isFieldExpanded`**

    `boolean` — Whether to make this facet request in the context of requesting more facet values.

  * **`numberOfValues`**

    `integer`, format: `int32` — The maximum number of facet values to fetch.

  * **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting values.

  * **`resultsMustMatch`**

    `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

  * **`sortCriteria`**

    `string`, possible values: `"score", "ascending", "descending", "alphanumeric", "alphanumericNatural", "occurrences", "score", "ascending", "descending", "alphanumeric", "alphanumericNatural", "occurrences"` — The criterion to use for sorting returned facet values. Unsupported values are deserialized to null and treated as if no sort criteria was specified (ignored).

  * **`type`**

    `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

  - **`currentValues`**

    `array` — The values displayed by the facet in the search interface at the moment of the request.

    **Items:**

    - **`end`**

      `string` — The value to end the range at. Must be later than the start value.

    - **`endInclusive`**

      `boolean` — Whether to include the end value in the range.

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`start`**

      `string` — The value to start the range at.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

  - **`facetId`**

    `string` — The unique identifier of the facet in the search interface.

  - **`field`**

    `string` — The name of the field on which to base the facet request.

  - **`filterFacetCount`**

    `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

  - **`freezeCurrentValues`**

    `boolean` — Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.

  - **`generateAutomaticRanges`**

    `boolean` — Whether to automatically generate range values for this facet.

  - **`injectionDepth`**

    `integer`, format: `int32` — The maximum number of items to scan for facet values.

  - **`isFieldExpanded`**

    `boolean` — Whether to make this facet request in the context of requesting more facet values.

  - **`numberOfValues`**

    `integer`, format: `int32` — The maximum number of facet values to fetch.

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting values.

  - **`resultsMustMatch`**

    `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

  - **`sortCriteria`**

    `string`, possible values: `"ascending", "descending", "occurrences", "ascending", "descending", "occurrences"` — The criterion to use for sorting returned facet values.

  - **`type`**

    `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

  * **`currentValues`**

    `array` — The values displayed by the facet in the search interface at the moment of the request.

    **Items:**

    - **`end`**

      `number` — The value to end the range at. Must be greater than the start value.

    - **`endInclusive`**

      `boolean` — Whether to include the end value in the range.

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`start`**

      `number` — The value to start the range at.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

  * **`facetId`**

    `string` — The unique identifier of the facet in the search interface.

  * **`field`**

    `string` — The name of the field on which to base the facet request.

  * **`filterFacetCount`**

    `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

  * **`freezeCurrentValues`**

    `boolean` — Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.

  * **`generateAutomaticRanges`**

    `boolean` — Whether to automatically generate range values for this facet.

  * **`injectionDepth`**

    `integer`, format: `int32` — The maximum number of items to scan for facet values.

  * **`isFieldExpanded`**

    `boolean` — Whether to make this facet request in the context of requesting more facet values.

  * **`numberOfValues`**

    `integer`, format: `int32` — The maximum number of facet values to fetch.

  * **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting values.

  * **`rangeAlgorithm`**

    `string`, possible values: `"equiprobable", "even"` — Determines which algorithm is used to generate the ranges if generateAutomaticRanges is enabled.

  * **`resultsMustMatch`**

    `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

  * **`sortCriteria`**

    `string`, possible values: `"ascending", "descending", "occurrences", "ascending", "descending", "occurrences"` — The criterion to use for sorting returned facet values.

  * **`type`**

    `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

- **`locale`**

  `string` — The user locale preferences.

- **`pipeline`**

  `string` — The query pipeline name.

- **`recordDebugSession`**

  `boolean`, default: `false` — Optional. Whether to record debug session data for this conversation. Defaults to false when omitted.

- **`referrer`**

  `string | null` — The URL of the referrer page.

- **`searchHub`**

  `string` — The search hub.

- **`tab`**

  `string` — The name or identifier of the search tab.

**Example:**

```json
{
  "analytics": {
    "capture": null,
    "clientId": null
  },
  "aq": "",
  "citationsFieldToInclude": [
    ""
  ],
  "context": {},
  "cq": "",
  "facets": [
    {
      "currentValues": [],
      "customSort": [
        ""
      ],
      "facetId": "author-1",
      "field": "author",
      "filterFacetCount": true,
      "freezeCurrentValues": true,
      "injectionDepth": 1,
      "isFieldExpanded": true,
      "numberOfValues": 1,
      "preventAutoSelect": true,
      "resultsMustMatch": "atLeastOneValue",
      "sortCriteria": "score",
      "type": "specific"
    }
  ],
  "locale": "",
  "pipeline": "",
  "q": "",
  "recordDebugSession": false,
  "referrer": null,
  "searchHub": "",
  "tab": ""
}
```

#### Responses

##### Status: 200 OK

###### Content-Type: application/json

- **`timeout`**

  `integer | null`, format: `int64`

**Example:**

```json
{
  "timeout": null
}
```

###### Content-Type: text/event-stream

- **`timeout`**

  `integer | null`, format: `int64`

**Example:**

```json
{
  "timeout": null
}
```

### Generates an answer to the follow-up question for the given configuration

- **Method:** `POST`
- **Path:** `/api/preview/organizations/{organizationId}/agents/{agentId}/follow-up`
- **Tags:** Agent Orchestration API

Clients should send `Accept: text/event-stream, application/json` to receive streamed responses (`text/event-stream`) and JSON error responses for requests rejected before streaming begins (e.g., validation/auth errors).

#### Parameters

##### `organizationId` required

- **In:** `path`

The organization id

`string` — Organization identifier

##### `agentId` required

- **In:** `path`

The agent id

`string`, format: `uuid` — The agent id

#### Request Body

##### Content-Type: application/json

- **`conversationId` (required)**

  `string` — Conversation identifier

- **`conversationToken` (required)**

  `string` — The conversation token received from the /answer response.

- **`q` (required)**

  `string` — The query string.

- **`analytics`**

  `object | null` — Analytics parameters to forward to the search API.

  - **`capture`**

    `boolean | null` — Whether the search API call should be tracked for analytics and ML purposes.

  - **`clientId`**

    `string | null` — A GUID representing the current client.

**Example:**

```json
{
  "analytics": {
    "capture": null,
    "clientId": null
  },
  "conversationId": "",
  "conversationToken": "",
  "q": ""
}
```

#### Responses

##### Status: 200 OK

###### Content-Type: application/json

- **`timeout`**

  `integer | null`, format: `int64`

**Example:**

```json
{
  "timeout": null
}
```

###### Content-Type: text/event-stream

- **`timeout`**

  `integer | null`, format: `int64`

**Example:**

```json
{
  "timeout": null
}
```

### List agents

- **Method:** `GET`
- **Path:** `/api/v1/organizations/{organizationId}/agents`
- **Tags:** Agent Configuration API

Privilege required

\`\`\` {"owner":"COVEO_ML","targetDomain":"AGENT_CONFIGURATION","type":"VIEW","targetId":"\*"} \`\`\`

#### Parameters

##### `organizationId` required

- **In:** `path`

`string` — Organization identifier

##### `page`

- **In:** `query`

The zero-based index of the results page to retrieve

`integer`, format: `int32`, default: `0`

##### `perPage`

- **In:** `query`

The number of items to return per page

`integer`, format: `int32`, default: `10`

#### Responses

##### Status: 200 OK

###### Content-Type: \*/\*

- **`items`**

  `array`

  **Items:**

  - **`agentType` (required)**

    `string` — Agent type

  - **`followUpEnabled` (required)**

    `boolean` — Does the model support follow-up questions.

  - **`name` (required)**

    `string` — The name of the Agent

  - **`passageRetrievalModelId` (required)**

    `string` — Passage retrieval model identifier

  - **`behaviors`**

    `array` — Optional behaviors to persist with the created agent.

    **Items:**

    - **`conditions` (required)**

      `array` — The list of conditions that must be met for this behavior to apply.

      **Items:**

      `string` — The list of conditions that must be met for this behavior to apply.

    - **`obligation` (required)**

      `string` — The obligation/instruction that applies when conditions are met.

  - **`createdDate`**

    `string`, format: `date-time` — Creation timestamp in ISO-8601 format

  - **`description`**

    `string` — The description of the Agent

  - **`id`**

    `string`, format: `uuid` — The public UUID for this configuration

  - **`modifiedDate`**

    `string`, format: `date-time` — Last modification timestamp in ISO-8601 format

  - **`numberOfItemsToConsider`**

    `integer`, format: `int32` — The maximum number of items/documents to consider for the Passage Retrieval model

  - **`status`**

    `string` — Overall status of the Agent. Possible values: - ACTIVE: The agent is active and can be queried. - SOON_TO_BE_ARCHIVED: The agent is still available, but will be archived soon if it is not queried. - INACTIVE: The agent is not ready to be queried yet. - LIMITED: The latest build completed with issues that may affect performance. - ARCHIVED: The agent has been archived and is no longer active. - BUILD_IN_PROGRESS: A build or rebuild is currently in progress. - ERROR: The latest build failed and the issue is customer-visible. - NO_MODELS_DEFINED: No underlying models are configured for this agent. - NOT_FETCHED: The status property was not fetched from the server.

- **`pagination`**

  `object`

  - **`page`**

    `integer`, format: `int32`

  - **`perPage`**

    `integer`, format: `int32`

  - **`totalItems`**

    `integer`, format: `int32`

  - **`totalPages`**

    `integer`, format: `int32`

**Example:**

```json
{
  "items": [
    {
      "agentType": "",
      "behaviors": [],
      "createdDate": "",
      "description": "",
      "followUpEnabled": true,
      "id": "",
      "modifiedDate": "",
      "name": "",
      "numberOfItemsToConsider": 1,
      "passageRetrievalModelId": "",
      "status": ""
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 1,
    "totalItems": 1,
    "totalPages": 1
  }
}
```

### Create an agent

- **Method:** `POST`
- **Path:** `/api/v1/organizations/{organizationId}/agents`
- **Tags:** Agent Configuration API

Privilege required

\`\`\` {"owner":"COVEO_ML","targetDomain":"AGENT_CONFIGURATION","type":"CREATE","targetId":"\*"} \`\`\`

#### Parameters

##### `organizationId` required

- **In:** `path`

`string` — Organization identifier

#### Request Body

##### Content-Type: application/json

- **`agentType` (required)**

  `string` — Agent type

- **`followUpEnabled` (required)**

  `boolean` — Does the model support follow-up questions.

- **`name` (required)**

  `string` — The name of the Agent

- **`passageRetrievalModelId` (required)**

  `string` — Passage retrieval model identifier

- **`behaviors`**

  `array` — Optional behaviors to persist with the created agent.

  **Items:**

  - **`conditions` (required)**

    `array` — The list of conditions that must be met for this behavior to apply.

    **Items:**

    `string` — The list of conditions that must be met for this behavior to apply.

  - **`obligation` (required)**

    `string` — The obligation/instruction that applies when conditions are met.

- **`description`**

  `string` — The description of the Agent

- **`numberOfItemsToConsider`**

  `integer`, format: `int32` — The maximum number of items/documents to consider for the Passage Retrieval model

**Example:**

```json
{
  "agentType": "",
  "behaviors": [
    {
      "conditions": [
        ""
      ],
      "obligation": ""
    }
  ],
  "description": "",
  "followUpEnabled": true,
  "name": "",
  "numberOfItemsToConsider": 1,
  "passageRetrievalModelId": ""
}
```

#### Responses

##### Status: 200 OK

###### Content-Type: \*/\*

- **`agentType` (required)**

  `string` — Agent type

- **`followUpEnabled` (required)**

  `boolean` — Does the model support follow-up questions.

- **`name` (required)**

  `string` — The name of the Agent

- **`passageRetrievalModelId` (required)**

  `string` — Passage retrieval model identifier

- **`behaviors`**

  `array` — Optional behaviors to persist with the created agent.

  **Items:**

  - **`conditions` (required)**

    `array` — The list of conditions that must be met for this behavior to apply.

    **Items:**

    `string` — The list of conditions that must be met for this behavior to apply.

  - **`obligation` (required)**

    `string` — The obligation/instruction that applies when conditions are met.

- **`createdDate`**

  `string`, format: `date-time` — Creation timestamp in ISO-8601 format

- **`description`**

  `string` — The description of the Agent

- **`id`**

  `string`, format: `uuid` — The public UUID for this configuration

- **`modifiedDate`**

  `string`, format: `date-time` — Last modification timestamp in ISO-8601 format

- **`numberOfItemsToConsider`**

  `integer`, format: `int32` — The maximum number of items/documents to consider for the Passage Retrieval model

- **`status`**

  `string` — Overall status of the Agent. Possible values: - ACTIVE: The agent is active and can be queried. - SOON_TO_BE_ARCHIVED: The agent is still available, but will be archived soon if it is not queried. - INACTIVE: The agent is not ready to be queried yet. - LIMITED: The latest build completed with issues that may affect performance. - ARCHIVED: The agent has been archived and is no longer active. - BUILD_IN_PROGRESS: A build or rebuild is currently in progress. - ERROR: The latest build failed and the issue is customer-visible. - NO_MODELS_DEFINED: No underlying models are configured for this agent. - NOT_FETCHED: The status property was not fetched from the server.

**Example:**

```json
{
  "agentType": "",
  "behaviors": [
    {
      "conditions": [
        ""
      ],
      "obligation": ""
    }
  ],
  "createdDate": "",
  "description": "",
  "followUpEnabled": true,
  "id": "",
  "modifiedDate": "",
  "name": "",
  "numberOfItemsToConsider": 1,
  "passageRetrievalModelId": "",
  "status": ""
}
```

### Delete an agent

- **Method:** `DELETE`
- **Path:** `/api/v1/organizations/{organizationId}/agents/{agentId}`
- **Tags:** Agent Configuration API

Privilege required

\`\`\` {"owner":"COVEO_ML","targetDomain":"AGENT_CONFIGURATION","type":"EDIT","targetId":"\*"} \`\`\`

#### Parameters

##### `organizationId` required

- **In:** `path`

`string` — Organization identifier

##### `agentId` required

- **In:** `path`

`string`, format: `uuid`

#### Responses

##### Status: 204 No Content

### Get an agent by agentId

- **Method:** `GET`
- **Path:** `/api/v1/organizations/{organizationId}/agents/{agentId}`
- **Tags:** Agent Configuration API

Privilege required

\`\`\` {"owner":"COVEO_ML","targetDomain":"AGENT_CONFIGURATION","type":"VIEW","targetId":"\*"} \`\`\`

#### Parameters

##### `organizationId` required

- **In:** `path`

`string` — Organization identifier

##### `agentId` required

- **In:** `path`

`string`, format: `uuid`

#### Responses

##### Status: 200 OK

###### Content-Type: \*/\*

- **`agentType` (required)**

  `string` — Agent type

- **`followUpEnabled` (required)**

  `boolean` — Does the model support follow-up questions.

- **`name` (required)**

  `string` — The name of the Agent

- **`passageRetrievalModelId` (required)**

  `string` — Passage retrieval model identifier

- **`behaviors`**

  `array` — Optional behaviors to persist with the created agent.

  **Items:**

  - **`conditions` (required)**

    `array` — The list of conditions that must be met for this behavior to apply.

    **Items:**

    `string` — The list of conditions that must be met for this behavior to apply.

  - **`obligation` (required)**

    `string` — The obligation/instruction that applies when conditions are met.

- **`createdDate`**

  `string`, format: `date-time` — Creation timestamp in ISO-8601 format

- **`description`**

  `string` — The description of the Agent

- **`id`**

  `string`, format: `uuid` — The public UUID for this configuration

- **`modifiedDate`**

  `string`, format: `date-time` — Last modification timestamp in ISO-8601 format

- **`numberOfItemsToConsider`**

  `integer`, format: `int32` — The maximum number of items/documents to consider for the Passage Retrieval model

- **`status`**

  `string` — Overall status of the Agent. Possible values: - ACTIVE: The agent is active and can be queried. - SOON_TO_BE_ARCHIVED: The agent is still available, but will be archived soon if it is not queried. - INACTIVE: The agent is not ready to be queried yet. - LIMITED: The latest build completed with issues that may affect performance. - ARCHIVED: The agent has been archived and is no longer active. - BUILD_IN_PROGRESS: A build or rebuild is currently in progress. - ERROR: The latest build failed and the issue is customer-visible. - NO_MODELS_DEFINED: No underlying models are configured for this agent. - NOT_FETCHED: The status property was not fetched from the server.

**Example:**

```json
{
  "agentType": "",
  "behaviors": [
    {
      "conditions": [
        ""
      ],
      "obligation": ""
    }
  ],
  "createdDate": "",
  "description": "",
  "followUpEnabled": true,
  "id": "",
  "modifiedDate": "",
  "name": "",
  "numberOfItemsToConsider": 1,
  "passageRetrievalModelId": "",
  "status": ""
}
```

### Update an agent

- **Method:** `PATCH`
- **Path:** `/api/v1/organizations/{organizationId}/agents/{agentId}`
- **Tags:** Agent Configuration API

Privilege required

\`\`\` {"owner":"COVEO_ML","targetDomain":"AGENT_CONFIGURATION","type":"EDIT","targetId":"\*"} \`\`\`

#### Parameters

##### `organizationId` required

- **In:** `path`

`string` — Organization identifier

##### `agentId` required

- **In:** `path`

`string`, format: `uuid`

#### Request Body

##### Content-Type: application/json

- **`behaviors`**

  `array` — Optional behaviors to persist with the updated agent.

  **Items:**

  - **`conditions` (required)**

    `array` — The list of conditions that must be met for this behavior to apply.

    **Items:**

    `string` — The list of conditions that must be met for this behavior to apply.

  - **`obligation` (required)**

    `string` — The obligation/instruction that applies when conditions are met.

- **`description`**

  `string` — The description of the Agent

- **`name`**

  `string` — The name of the Agent

**Example:**

```json
{
  "behaviors": [
    {
      "conditions": [
        ""
      ],
      "obligation": ""
    }
  ],
  "description": "",
  "name": ""
}
```

#### Responses

##### Status: 200 OK

###### Content-Type: \*/\*

- **`agentType` (required)**

  `string` — Agent type

- **`followUpEnabled` (required)**

  `boolean` — Does the model support follow-up questions.

- **`name` (required)**

  `string` — The name of the Agent

- **`passageRetrievalModelId` (required)**

  `string` — Passage retrieval model identifier

- **`behaviors`**

  `array` — Optional behaviors to persist with the created agent.

  **Items:**

  - **`conditions` (required)**

    `array` — The list of conditions that must be met for this behavior to apply.

    **Items:**

    `string` — The list of conditions that must be met for this behavior to apply.

  - **`obligation` (required)**

    `string` — The obligation/instruction that applies when conditions are met.

- **`createdDate`**

  `string`, format: `date-time` — Creation timestamp in ISO-8601 format

- **`description`**

  `string` — The description of the Agent

- **`id`**

  `string`, format: `uuid` — The public UUID for this configuration

- **`modifiedDate`**

  `string`, format: `date-time` — Last modification timestamp in ISO-8601 format

- **`numberOfItemsToConsider`**

  `integer`, format: `int32` — The maximum number of items/documents to consider for the Passage Retrieval model

- **`status`**

  `string` — Overall status of the Agent. Possible values: - ACTIVE: The agent is active and can be queried. - SOON_TO_BE_ARCHIVED: The agent is still available, but will be archived soon if it is not queried. - INACTIVE: The agent is not ready to be queried yet. - LIMITED: The latest build completed with issues that may affect performance. - ARCHIVED: The agent has been archived and is no longer active. - BUILD_IN_PROGRESS: A build or rebuild is currently in progress. - ERROR: The latest build failed and the issue is customer-visible. - NO_MODELS_DEFINED: No underlying models are configured for this agent. - NOT_FETCHED: The status property was not fetched from the server.

**Example:**

```json
{
  "agentType": "",
  "behaviors": [
    {
      "conditions": [
        ""
      ],
      "obligation": ""
    }
  ],
  "createdDate": "",
  "description": "",
  "followUpEnabled": true,
  "id": "",
  "modifiedDate": "",
  "name": "",
  "numberOfItemsToConsider": 1,
  "passageRetrievalModelId": "",
  "status": ""
}
```

### Generates an answer for the given configuration

- **Method:** `POST`
- **Path:** `/api/v1/organizations/{organizationId}/agents/{agentId}/answer`
- **Tags:** Agent Orchestration API

Clients should send `Accept: text/event-stream, application/json` to receive streamed responses (`text/event-stream`) and JSON error responses for requests rejected before streaming begins (e.g., validation/auth errors).

#### Parameters

##### `organizationId` required

- **In:** `path`

The organization id

`string` — Organization identifier

##### `agentId` required

- **In:** `path`

The agent id

`string`, format: `uuid` — The agent id

#### Request Body

##### Content-Type: application/json

- **`q` (required)**

  `string` — The user question.

- **`analytics`**

  `object | null` — Analytics parameters to forward to the search API.

  - **`capture`**

    `boolean | null` — Whether the search API call should be tracked for analytics and ML purposes.

  - **`clientId`**

    `string | null` — A GUID representing the current client.

- **`aq`**

  `string` — The advanced query expression.

- **`citationsFieldToInclude`**

  `array` — The citation fields to include in the response.

  **Items:**

  `string` — The citation fields to include in the response.

- **`context`**

  `object`

- **`cq`**

  `string` — The constant query expression.

- **`facets`**

  `array` — The list of facets.

  **Items:**

  **One of:**

  - **`currentValues`**

    `array` — The values displayed by the facet in the search interface at the moment of the request.

    **Items:**

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

    - **`value`**

      `string` — The facet value name.

  - **`customSort`**

    `array` — Facet values that must appear at the top, in this order.

    **Items:**

    `string` — Facet values that must appear at the top, in this order.

  - **`facetId`**

    `string` — The unique identifier of the facet in the search interface.

  - **`field`**

    `string` — The name of the field on which to base the facet request.

  - **`filterFacetCount`**

    `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

  - **`freezeCurrentValues`**

    `boolean` — Whether to include the facet request's currentValues in corresponding facet response's values array.

  - **`injectionDepth`**

    `integer`, format: `int32` — The maximum number of items to scan for facet values.

  - **`isFieldExpanded`**

    `boolean` — Whether to make this facet request in the context of requesting more facet values.

  - **`numberOfValues`**

    `integer`, format: `int32` — The maximum number of facet values to fetch.

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting values.

  - **`resultsMustMatch`**

    `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

  - **`sortCriteria`**

    `string`, possible values: `"score", "alphanumeric", "alphanumericNatural", "occurrences", "score", "alphanumeric", "alphanumericNatural", "occurrences"` — The sort criterion to apply to the returned facet values. Values outside the documented list are accepted but treated as unsupported and deserialized to null, which causes the sort criterion to be omitted and the default behavior to apply.

  - **`type`**

    `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

  * **`basePath`**

    `array` — The base path shared by all values for the facet.

    **Items:**

    `string` — The base path shared by all values for the facet.

  * **`currentValues`**

    `array` — The values displayed by the facet in the search interface at the moment of the request.

    **Items:**

    - **`children`**

      `array` — The children of this hierarchical facet value.

      **Items:**

      - **`children`**

        `array` — The children of this hierarchical facet value.

        **Items:**

        - **`children`**

          `array` — The children of this hierarchical facet value.

          **Items:**

          - **`children`**

            `array` — The children of this hierarchical facet value.

            **Items:**

            - **`children`**

              `array` — The children of this hierarchical facet value.

              **Items:**

              - **`children`**

                `array` — The children of this hierarchical facet value.

                **Items:**

                - **`children`**

                  `array` — The children of this hierarchical facet value.

                  **Items:**

                  *[Circular Reference]*

                - **`preventAutoSelect`**

                  `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

                - **`previousState`**

                  `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

                - **`retrieveChildren`**

                  `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

                - **`retrieveCount`**

                  `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

                - **`state`**

                  `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

                - **`value`**

                  `string` — This represents a single path segment.

              - **`preventAutoSelect`**

                `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

              - **`previousState`**

                `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

              - **`retrieveChildren`**

                `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

              - **`retrieveCount`**

                `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

              - **`state`**

                `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

              - **`value`**

                `string` — This represents a single path segment.

            - **`preventAutoSelect`**

              `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

            - **`previousState`**

              `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

            - **`retrieveChildren`**

              `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

            - **`retrieveCount`**

              `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

            - **`state`**

              `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

            - **`value`**

              `string` — This represents a single path segment.

          - **`preventAutoSelect`**

            `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

          - **`previousState`**

            `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

          - **`retrieveChildren`**

            `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

          - **`retrieveCount`**

            `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

          - **`state`**

            `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

          - **`value`**

            `string` — This represents a single path segment.

        - **`preventAutoSelect`**

          `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

        - **`previousState`**

          `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

        - **`retrieveChildren`**

          `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

        - **`retrieveCount`**

          `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

        - **`state`**

          `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

        - **`value`**

          `string` — This represents a single path segment.

      - **`preventAutoSelect`**

        `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

      - **`previousState`**

        `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

      - **`retrieveChildren`**

        `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

      - **`retrieveCount`**

        `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

      - **`state`**

        `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

      - **`value`**

        `string` — This represents a single path segment.

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`retrieveChildren`**

      `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

    - **`retrieveCount`**

      `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

    - **`value`**

      `string` — This represents a single path segment.

  * **`delimitingCharacter`**

    `string`, default: `";"` — The character to use to split field values into a hierarchical sequence.

  * **`facetId`**

    `string` — The unique identifier of the facet in the search interface.

  * **`field`**

    `string` — The name of the field on which to base the facet request.

  * **`filterByBasePath`**

    `boolean` — Whether to use basePath as a filter for the results.

  * **`filterFacetCount`**

    `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

  * **`injectionDepth`**

    `integer`, format: `int32` — The maximum number of items to scan for facet values.

  * **`isFieldExpanded`**

    `boolean` — Whether to make this facet request in the context of requesting more facet values.

  * **`numberOfValues`**

    `integer`, format: `int32` — The maximum number of facet values to fetch.

  * **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting values.

  * **`resultsMustMatch`**

    `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

  * **`sortCriteria`**

    `string`, possible values: `"score", "ascending", "descending", "alphanumeric", "alphanumericNatural", "occurrences", "score", "ascending", "descending", "alphanumeric", "alphanumericNatural", "occurrences"` — The criterion to use for sorting returned facet values. Unsupported values are deserialized to null and treated as if no sort criteria was specified (ignored).

  * **`type`**

    `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

  - **`currentValues`**

    `array` — The values displayed by the facet in the search interface at the moment of the request.

    **Items:**

    - **`end`**

      `string` — The value to end the range at. Must be later than the start value.

    - **`endInclusive`**

      `boolean` — Whether to include the end value in the range.

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`start`**

      `string` — The value to start the range at.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

  - **`facetId`**

    `string` — The unique identifier of the facet in the search interface.

  - **`field`**

    `string` — The name of the field on which to base the facet request.

  - **`filterFacetCount`**

    `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

  - **`freezeCurrentValues`**

    `boolean` — Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.

  - **`generateAutomaticRanges`**

    `boolean` — Whether to automatically generate range values for this facet.

  - **`injectionDepth`**

    `integer`, format: `int32` — The maximum number of items to scan for facet values.

  - **`isFieldExpanded`**

    `boolean` — Whether to make this facet request in the context of requesting more facet values.

  - **`numberOfValues`**

    `integer`, format: `int32` — The maximum number of facet values to fetch.

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting values.

  - **`resultsMustMatch`**

    `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

  - **`sortCriteria`**

    `string`, possible values: `"ascending", "descending", "occurrences", "ascending", "descending", "occurrences"` — The criterion to use for sorting returned facet values.

  - **`type`**

    `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

  * **`currentValues`**

    `array` — The values displayed by the facet in the search interface at the moment of the request.

    **Items:**

    - **`end`**

      `number` — The value to end the range at. Must be greater than the start value.

    - **`endInclusive`**

      `boolean` — Whether to include the end value in the range.

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`start`**

      `number` — The value to start the range at.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

  * **`facetId`**

    `string` — The unique identifier of the facet in the search interface.

  * **`field`**

    `string` — The name of the field on which to base the facet request.

  * **`filterFacetCount`**

    `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

  * **`freezeCurrentValues`**

    `boolean` — Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.

  * **`generateAutomaticRanges`**

    `boolean` — Whether to automatically generate range values for this facet.

  * **`injectionDepth`**

    `integer`, format: `int32` — The maximum number of items to scan for facet values.

  * **`isFieldExpanded`**

    `boolean` — Whether to make this facet request in the context of requesting more facet values.

  * **`numberOfValues`**

    `integer`, format: `int32` — The maximum number of facet values to fetch.

  * **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting values.

  * **`rangeAlgorithm`**

    `string`, possible values: `"equiprobable", "even"` — Determines which algorithm is used to generate the ranges if generateAutomaticRanges is enabled.

  * **`resultsMustMatch`**

    `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

  * **`sortCriteria`**

    `string`, possible values: `"ascending", "descending", "occurrences", "ascending", "descending", "occurrences"` — The criterion to use for sorting returned facet values.

  * **`type`**

    `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

- **`locale`**

  `string` — The user locale preferences.

- **`pipeline`**

  `string` — The query pipeline name.

- **`recordDebugSession`**

  `boolean`, default: `false` — Optional. Whether to record debug session data for this conversation. Defaults to false when omitted.

- **`referrer`**

  `string | null` — The URL of the referrer page.

- **`searchHub`**

  `string` — The search hub.

- **`tab`**

  `string` — The name or identifier of the search tab.

**Example:**

```json
{
  "analytics": {
    "capture": null,
    "clientId": null
  },
  "aq": "",
  "citationsFieldToInclude": [
    ""
  ],
  "context": {},
  "cq": "",
  "facets": [
    {
      "currentValues": [],
      "customSort": [
        ""
      ],
      "facetId": "author-1",
      "field": "author",
      "filterFacetCount": true,
      "freezeCurrentValues": true,
      "injectionDepth": 1,
      "isFieldExpanded": true,
      "numberOfValues": 1,
      "preventAutoSelect": true,
      "resultsMustMatch": "atLeastOneValue",
      "sortCriteria": "score",
      "type": "specific"
    }
  ],
  "locale": "",
  "pipeline": "",
  "q": "",
  "recordDebugSession": false,
  "referrer": null,
  "searchHub": "",
  "tab": ""
}
```

#### Responses

##### Status: 200 OK

###### Content-Type: application/json

- **`timeout`**

  `integer | null`, format: `int64`

**Example:**

```json
{
  "timeout": null
}
```

###### Content-Type: text/event-stream

- **`timeout`**

  `integer | null`, format: `int64`

**Example:**

```json
{
  "timeout": null
}
```

### Generates an answer to the follow-up question for the given configuration

- **Method:** `POST`
- **Path:** `/api/v1/organizations/{organizationId}/agents/{agentId}/follow-up`
- **Tags:** Agent Orchestration API

Clients should send `Accept: text/event-stream, application/json` to receive streamed responses (`text/event-stream`) and JSON error responses for requests rejected before streaming begins (e.g., validation/auth errors).

#### Parameters

##### `organizationId` required

- **In:** `path`

The organization id

`string` — Organization identifier

##### `agentId` required

- **In:** `path`

The agent id

`string`, format: `uuid` — The agent id

#### Request Body

##### Content-Type: application/json

- **`conversationId` (required)**

  `string` — Conversation identifier

- **`conversationToken` (required)**

  `string` — The conversation token received from the /answer response.

- **`q` (required)**

  `string` — The query string.

- **`analytics`**

  `object | null` — Analytics parameters to forward to the search API.

  - **`capture`**

    `boolean | null` — Whether the search API call should be tracked for analytics and ML purposes.

  - **`clientId`**

    `string | null` — A GUID representing the current client.

**Example:**

```json
{
  "analytics": {
    "capture": null,
    "clientId": null
  },
  "conversationId": "",
  "conversationToken": "",
  "q": ""
}
```

#### Responses

##### Status: 200 OK

###### Content-Type: application/json

- **`timeout`**

  `integer | null`, format: `int64`

**Example:**

```json
{
  "timeout": null
}
```

###### Content-Type: text/event-stream

- **`timeout`**

  `integer | null`, format: `int64`

**Example:**

```json
{
  "timeout": null
}
```

## Schemas

### AgentUpdate_Request

- **Type:**`object`

A partial agent update containing only the mutable metadata fields

- **`behaviors`**

  `array` — Optional behaviors to persist with the updated agent.

  **Items:**

  - **`conditions` (required)**

    `array` — The list of conditions that must be met for this behavior to apply.

    **Items:**

    `string` — The list of conditions that must be met for this behavior to apply.

  - **`obligation` (required)**

    `string` — The obligation/instruction that applies when conditions are met.

- **`description`**

  `string` — The description of the Agent

- **`name`**

  `string` — The name of the Agent

**Example:**

```json
{
  "behaviors": [
    {
      "conditions": [
        ""
      ],
      "obligation": ""
    }
  ],
  "description": "",
  "name": ""
}
```

### Agent_Request

- **Type:**`object`

An agent configuration

- **`agentType` (required)**

  `string` — Agent type

- **`followUpEnabled` (required)**

  `boolean` — Does the model support follow-up questions.

- **`name` (required)**

  `string` — The name of the Agent

- **`passageRetrievalModelId` (required)**

  `string` — Passage retrieval model identifier

- **`behaviors`**

  `array` — Optional behaviors to persist with the created agent.

  **Items:**

  - **`conditions` (required)**

    `array` — The list of conditions that must be met for this behavior to apply.

    **Items:**

    `string` — The list of conditions that must be met for this behavior to apply.

  - **`obligation` (required)**

    `string` — The obligation/instruction that applies when conditions are met.

- **`description`**

  `string` — The description of the Agent

- **`numberOfItemsToConsider`**

  `integer`, format: `int32` — The maximum number of items/documents to consider for the Passage Retrieval model

**Example:**

```json
{
  "agentType": "",
  "behaviors": [
    {
      "conditions": [
        ""
      ],
      "obligation": ""
    }
  ],
  "description": "",
  "followUpEnabled": true,
  "name": "",
  "numberOfItemsToConsider": 1,
  "passageRetrievalModelId": ""
}
```

### Agent_Response

- **Type:**`object`

An agent configuration

- **`agentType` (required)**

  `string` — Agent type

- **`followUpEnabled` (required)**

  `boolean` — Does the model support follow-up questions.

- **`name` (required)**

  `string` — The name of the Agent

- **`passageRetrievalModelId` (required)**

  `string` — Passage retrieval model identifier

- **`behaviors`**

  `array` — Optional behaviors to persist with the created agent.

  **Items:**

  - **`conditions` (required)**

    `array` — The list of conditions that must be met for this behavior to apply.

    **Items:**

    `string` — The list of conditions that must be met for this behavior to apply.

  - **`obligation` (required)**

    `string` — The obligation/instruction that applies when conditions are met.

- **`createdDate`**

  `string`, format: `date-time` — Creation timestamp in ISO-8601 format

- **`description`**

  `string` — The description of the Agent

- **`id`**

  `string`, format: `uuid` — The public UUID for this configuration

- **`modifiedDate`**

  `string`, format: `date-time` — Last modification timestamp in ISO-8601 format

- **`numberOfItemsToConsider`**

  `integer`, format: `int32` — The maximum number of items/documents to consider for the Passage Retrieval model

- **`status`**

  `string` — Overall status of the Agent. Possible values: - ACTIVE: The agent is active and can be queried. - SOON_TO_BE_ARCHIVED: The agent is still available, but will be archived soon if it is not queried. - INACTIVE: The agent is not ready to be queried yet. - LIMITED: The latest build completed with issues that may affect performance. - ARCHIVED: The agent has been archived and is no longer active. - BUILD_IN_PROGRESS: A build or rebuild is currently in progress. - ERROR: The latest build failed and the issue is customer-visible. - NO_MODELS_DEFINED: No underlying models are configured for this agent. - NOT_FETCHED: The status property was not fetched from the server.

**Example:**

```json
{
  "agentType": "",
  "behaviors": [
    {
      "conditions": [
        ""
      ],
      "obligation": ""
    }
  ],
  "createdDate": "",
  "description": "",
  "followUpEnabled": true,
  "id": "",
  "modifiedDate": "",
  "name": "",
  "numberOfItemsToConsider": 1,
  "passageRetrievalModelId": "",
  "status": ""
}
```

### Analytics_Request

- **Type:**`[ "object", "null" ]`

Analytics parameters to forward to the search API.

**Example:**

### Behavior_Request

- **Type:**`object`

A behavior that the agent should follow.

- **`conditions` (required)**

  `array` — The list of conditions that must be met for this behavior to apply.

  **Items:**

  `string` — The list of conditions that must be met for this behavior to apply.

- **`obligation` (required)**

  `string` — The obligation/instruction that applies when conditions are met.

**Example:**

```json
{
  "conditions": [
    ""
  ],
  "obligation": ""
}
```

### Behavior_Response

- **Type:**`object`

A behavior that the agent should follow.

- **`conditions` (required)**

  `array` — The list of conditions that must be met for this behavior to apply.

  **Items:**

  `string` — The list of conditions that must be met for this behavior to apply.

- **`obligation` (required)**

  `string` — The obligation/instruction that applies when conditions are met.

**Example:**

```json
{
  "conditions": [
    ""
  ],
  "obligation": ""
}
```

### CompositeModelAnswerPayload_Request

- **Type:**`object`

Request body must not exceed 204,800 bytes (200 KB).

- **`q` (required)**

  `string` — The user question.

- **`analytics`**

  `object | null` — Analytics parameters to forward to the search API.

  - **`capture`**

    `boolean | null` — Whether the search API call should be tracked for analytics and ML purposes.

  - **`clientId`**

    `string | null` — A GUID representing the current client.

- **`aq`**

  `string` — The advanced query expression.

- **`citationsFieldToInclude`**

  `array` — The citation fields to include in the response.

  **Items:**

  `string` — The citation fields to include in the response.

- **`context`**

  `object`

- **`cq`**

  `string` — The constant query expression.

- **`facets`**

  `array` — The list of facets.

  **Items:**

  **One of:**

  - **`currentValues`**

    `array` — The values displayed by the facet in the search interface at the moment of the request.

    **Items:**

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

    - **`value`**

      `string` — The facet value name.

  - **`customSort`**

    `array` — Facet values that must appear at the top, in this order.

    **Items:**

    `string` — Facet values that must appear at the top, in this order.

  - **`facetId`**

    `string` — The unique identifier of the facet in the search interface.

  - **`field`**

    `string` — The name of the field on which to base the facet request.

  - **`filterFacetCount`**

    `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

  - **`freezeCurrentValues`**

    `boolean` — Whether to include the facet request's currentValues in corresponding facet response's values array.

  - **`injectionDepth`**

    `integer`, format: `int32` — The maximum number of items to scan for facet values.

  - **`isFieldExpanded`**

    `boolean` — Whether to make this facet request in the context of requesting more facet values.

  - **`numberOfValues`**

    `integer`, format: `int32` — The maximum number of facet values to fetch.

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting values.

  - **`resultsMustMatch`**

    `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

  - **`sortCriteria`**

    `string`, possible values: `"score", "alphanumeric", "alphanumericNatural", "occurrences", "score", "alphanumeric", "alphanumericNatural", "occurrences"` — The sort criterion to apply to the returned facet values. Values outside the documented list are accepted but treated as unsupported and deserialized to null, which causes the sort criterion to be omitted and the default behavior to apply.

  - **`type`**

    `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

  * **`basePath`**

    `array` — The base path shared by all values for the facet.

    **Items:**

    `string` — The base path shared by all values for the facet.

  * **`currentValues`**

    `array` — The values displayed by the facet in the search interface at the moment of the request.

    **Items:**

    - **`children`**

      `array` — The children of this hierarchical facet value.

      **Items:**

      - **`children`**

        `array` — The children of this hierarchical facet value.

        **Items:**

        - **`children`**

          `array` — The children of this hierarchical facet value.

          **Items:**

          - **`children`**

            `array` — The children of this hierarchical facet value.

            **Items:**

            - **`children`**

              `array` — The children of this hierarchical facet value.

              **Items:**

              - **`children`**

                `array` — The children of this hierarchical facet value.

                **Items:**

                - **`children`**

                  `array` — The children of this hierarchical facet value.

                  **Items:**

                  *[Circular Reference]*

                - **`preventAutoSelect`**

                  `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

                - **`previousState`**

                  `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

                - **`retrieveChildren`**

                  `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

                - **`retrieveCount`**

                  `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

                - **`state`**

                  `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

                - **`value`**

                  `string` — This represents a single path segment.

              - **`preventAutoSelect`**

                `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

              - **`previousState`**

                `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

              - **`retrieveChildren`**

                `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

              - **`retrieveCount`**

                `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

              - **`state`**

                `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

              - **`value`**

                `string` — This represents a single path segment.

            - **`preventAutoSelect`**

              `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

            - **`previousState`**

              `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

            - **`retrieveChildren`**

              `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

            - **`retrieveCount`**

              `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

            - **`state`**

              `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

            - **`value`**

              `string` — This represents a single path segment.

          - **`preventAutoSelect`**

            `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

          - **`previousState`**

            `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

          - **`retrieveChildren`**

            `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

          - **`retrieveCount`**

            `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

          - **`state`**

            `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

          - **`value`**

            `string` — This represents a single path segment.

        - **`preventAutoSelect`**

          `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

        - **`previousState`**

          `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

        - **`retrieveChildren`**

          `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

        - **`retrieveCount`**

          `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

        - **`state`**

          `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

        - **`value`**

          `string` — This represents a single path segment.

      - **`preventAutoSelect`**

        `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

      - **`previousState`**

        `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

      - **`retrieveChildren`**

        `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

      - **`retrieveCount`**

        `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

      - **`state`**

        `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

      - **`value`**

        `string` — This represents a single path segment.

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`retrieveChildren`**

      `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

    - **`retrieveCount`**

      `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

    - **`value`**

      `string` — This represents a single path segment.

  * **`delimitingCharacter`**

    `string`, default: `";"` — The character to use to split field values into a hierarchical sequence.

  * **`facetId`**

    `string` — The unique identifier of the facet in the search interface.

  * **`field`**

    `string` — The name of the field on which to base the facet request.

  * **`filterByBasePath`**

    `boolean` — Whether to use basePath as a filter for the results.

  * **`filterFacetCount`**

    `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

  * **`injectionDepth`**

    `integer`, format: `int32` — The maximum number of items to scan for facet values.

  * **`isFieldExpanded`**

    `boolean` — Whether to make this facet request in the context of requesting more facet values.

  * **`numberOfValues`**

    `integer`, format: `int32` — The maximum number of facet values to fetch.

  * **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting values.

  * **`resultsMustMatch`**

    `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

  * **`sortCriteria`**

    `string`, possible values: `"score", "ascending", "descending", "alphanumeric", "alphanumericNatural", "occurrences", "score", "ascending", "descending", "alphanumeric", "alphanumericNatural", "occurrences"` — The criterion to use for sorting returned facet values. Unsupported values are deserialized to null and treated as if no sort criteria was specified (ignored).

  * **`type`**

    `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

  - **`currentValues`**

    `array` — The values displayed by the facet in the search interface at the moment of the request.

    **Items:**

    - **`end`**

      `string` — The value to end the range at. Must be later than the start value.

    - **`endInclusive`**

      `boolean` — Whether to include the end value in the range.

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`start`**

      `string` — The value to start the range at.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

  - **`facetId`**

    `string` — The unique identifier of the facet in the search interface.

  - **`field`**

    `string` — The name of the field on which to base the facet request.

  - **`filterFacetCount`**

    `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

  - **`freezeCurrentValues`**

    `boolean` — Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.

  - **`generateAutomaticRanges`**

    `boolean` — Whether to automatically generate range values for this facet.

  - **`injectionDepth`**

    `integer`, format: `int32` — The maximum number of items to scan for facet values.

  - **`isFieldExpanded`**

    `boolean` — Whether to make this facet request in the context of requesting more facet values.

  - **`numberOfValues`**

    `integer`, format: `int32` — The maximum number of facet values to fetch.

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting values.

  - **`resultsMustMatch`**

    `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

  - **`sortCriteria`**

    `string`, possible values: `"ascending", "descending", "occurrences", "ascending", "descending", "occurrences"` — The criterion to use for sorting returned facet values.

  - **`type`**

    `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

  * **`currentValues`**

    `array` — The values displayed by the facet in the search interface at the moment of the request.

    **Items:**

    - **`end`**

      `number` — The value to end the range at. Must be greater than the start value.

    - **`endInclusive`**

      `boolean` — Whether to include the end value in the range.

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`start`**

      `number` — The value to start the range at.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

  * **`facetId`**

    `string` — The unique identifier of the facet in the search interface.

  * **`field`**

    `string` — The name of the field on which to base the facet request.

  * **`filterFacetCount`**

    `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

  * **`freezeCurrentValues`**

    `boolean` — Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.

  * **`generateAutomaticRanges`**

    `boolean` — Whether to automatically generate range values for this facet.

  * **`injectionDepth`**

    `integer`, format: `int32` — The maximum number of items to scan for facet values.

  * **`isFieldExpanded`**

    `boolean` — Whether to make this facet request in the context of requesting more facet values.

  * **`numberOfValues`**

    `integer`, format: `int32` — The maximum number of facet values to fetch.

  * **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting values.

  * **`rangeAlgorithm`**

    `string`, possible values: `"equiprobable", "even"` — Determines which algorithm is used to generate the ranges if generateAutomaticRanges is enabled.

  * **`resultsMustMatch`**

    `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

  * **`sortCriteria`**

    `string`, possible values: `"ascending", "descending", "occurrences", "ascending", "descending", "occurrences"` — The criterion to use for sorting returned facet values.

  * **`type`**

    `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

- **`locale`**

  `string` — The user locale preferences.

- **`pipeline`**

  `string` — The query pipeline name.

- **`recordDebugSession`**

  `boolean`, default: `false` — Optional. Whether to record debug session data for this conversation. Defaults to false when omitted.

- **`referrer`**

  `string | null` — The URL of the referrer page.

- **`searchHub`**

  `string` — The search hub.

- **`tab`**

  `string` — The name or identifier of the search tab.

**Example:**

```json
{
  "analytics": {
    "capture": null,
    "clientId": null
  },
  "aq": "",
  "citationsFieldToInclude": [
    ""
  ],
  "context": {},
  "cq": "",
  "facets": [
    {
      "currentValues": [],
      "customSort": [
        ""
      ],
      "facetId": "author-1",
      "field": "author",
      "filterFacetCount": true,
      "freezeCurrentValues": true,
      "injectionDepth": 1,
      "isFieldExpanded": true,
      "numberOfValues": 1,
      "preventAutoSelect": true,
      "resultsMustMatch": "atLeastOneValue",
      "sortCriteria": "score",
      "type": "specific"
    }
  ],
  "locale": "",
  "pipeline": "",
  "q": "",
  "recordDebugSession": false,
  "referrer": null,
  "searchHub": "",
  "tab": ""
}
```

### CompositeModelFollowUpPayload_Request

- **Type:**`object`

Request body must not exceed 204,800 bytes (200 KB).

- **`conversationId` (required)**

  `string` — Conversation identifier

- **`conversationToken` (required)**

  `string` — The conversation token received from the /answer response.

- **`q` (required)**

  `string` — The query string.

- **`analytics`**

  `object | null` — Analytics parameters to forward to the search API.

  - **`capture`**

    `boolean | null` — Whether the search API call should be tracked for analytics and ML purposes.

  - **`clientId`**

    `string | null` — A GUID representing the current client.

**Example:**

```json
{
  "analytics": {
    "capture": null,
    "clientId": null
  },
  "conversationId": "",
  "conversationToken": "",
  "q": ""
}
```

### DateRangeFacetRequest_Request

- **Type:**`object`

Request facet values representing ranges of dates.

- **`currentValues`**

  `array` — The values displayed by the facet in the search interface at the moment of the request.

  **Items:**

  - **`end`**

    `string` — The value to end the range at. Must be later than the start value.

  - **`endInclusive`**

    `boolean` — Whether to include the end value in the range.

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

  - **`previousState`**

    `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

  - **`start`**

    `string` — The value to start the range at.

  - **`state`**

    `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

- **`facetId`**

  `string` — The unique identifier of the facet in the search interface.

- **`field`**

  `string` — The name of the field on which to base the facet request.

- **`filterFacetCount`**

  `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

- **`freezeCurrentValues`**

  `boolean` — Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.

- **`generateAutomaticRanges`**

  `boolean` — Whether to automatically generate range values for this facet.

- **`injectionDepth`**

  `integer`, format: `int32` — The maximum number of items to scan for facet values.

- **`isFieldExpanded`**

  `boolean` — Whether to make this facet request in the context of requesting more facet values.

- **`numberOfValues`**

  `integer`, format: `int32` — The maximum number of facet values to fetch.

- **`preventAutoSelect`**

  `boolean` — Whether to prevent Coveo ML from automatically selecting values.

- **`resultsMustMatch`**

  `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

- **`sortCriteria`**

  `string`, possible values: `"ascending", "descending", "occurrences", "ascending", "descending", "occurrences"` — The criterion to use for sorting returned facet values.

- **`type`**

  `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

**Example:**

```json
{
  "currentValues": [
    {
      "end": "2019/12/31@23:59:59",
      "endInclusive": true,
      "preventAutoSelect": true,
      "previousState": "idle",
      "start": "2019/01/01@00:00:00",
      "state": "idle"
    }
  ],
  "facetId": "author-1",
  "field": "author",
  "filterFacetCount": true,
  "freezeCurrentValues": true,
  "generateAutomaticRanges": true,
  "injectionDepth": 1,
  "isFieldExpanded": true,
  "numberOfValues": 1,
  "preventAutoSelect": true,
  "resultsMustMatch": "atLeastOneValue",
  "sortCriteria": "ascending",
  "type": "specific"
}
```

### DateRangeFacetValue_Request

- **Type:**`object`

A date range facet value.

- **`end`**

  `string` — The value to end the range at. Must be later than the start value.

- **`endInclusive`**

  `boolean` — Whether to include the end value in the range.

- **`preventAutoSelect`**

  `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

- **`previousState`**

  `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

- **`start`**

  `string` — The value to start the range at.

- **`state`**

  `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

**Example:**

```json
{
  "end": "2019/12/31@23:59:59",
  "endInclusive": true,
  "preventAutoSelect": true,
  "previousState": "idle",
  "start": "2019/01/01@00:00:00",
  "state": "idle"
}
```

### FacetRequest_Request

- **Type:**`object`

A facet request. The type property determines the kind of facet values to request.

**One of:**

- **`currentValues`**

  `array` — The values displayed by the facet in the search interface at the moment of the request.

  **Items:**

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

  - **`previousState`**

    `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

  - **`state`**

    `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

  - **`value`**

    `string` — The facet value name.

- **`customSort`**

  `array` — Facet values that must appear at the top, in this order.

  **Items:**

  `string` — Facet values that must appear at the top, in this order.

- **`facetId`**

  `string` — The unique identifier of the facet in the search interface.

- **`field`**

  `string` — The name of the field on which to base the facet request.

- **`filterFacetCount`**

  `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

- **`freezeCurrentValues`**

  `boolean` — Whether to include the facet request's currentValues in corresponding facet response's values array.

- **`injectionDepth`**

  `integer`, format: `int32` — The maximum number of items to scan for facet values.

- **`isFieldExpanded`**

  `boolean` — Whether to make this facet request in the context of requesting more facet values.

- **`numberOfValues`**

  `integer`, format: `int32` — The maximum number of facet values to fetch.

- **`preventAutoSelect`**

  `boolean` — Whether to prevent Coveo ML from automatically selecting values.

- **`resultsMustMatch`**

  `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

- **`sortCriteria`**

  `string`, possible values: `"score", "alphanumeric", "alphanumericNatural", "occurrences", "score", "alphanumeric", "alphanumericNatural", "occurrences"` — The sort criterion to apply to the returned facet values. Values outside the documented list are accepted but treated as unsupported and deserialized to null, which causes the sort criterion to be omitted and the default behavior to apply.

- **`type`**

  `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

* **`basePath`**

  `array` — The base path shared by all values for the facet.

  **Items:**

  `string` — The base path shared by all values for the facet.

* **`currentValues`**

  `array` — The values displayed by the facet in the search interface at the moment of the request.

  **Items:**

  - **`children`**

    `array` — The children of this hierarchical facet value.

    **Items:**

    - **`children`**

      `array` — The children of this hierarchical facet value.

      **Items:**

      - **`children`**

        `array` — The children of this hierarchical facet value.

        **Items:**

        - **`children`**

          `array` — The children of this hierarchical facet value.

          **Items:**

          - **`children`**

            `array` — The children of this hierarchical facet value.

            **Items:**

            - **`children`**

              `array` — The children of this hierarchical facet value.

              **Items:**

              - **`children`**

                `array` — The children of this hierarchical facet value.

                **Items:**

                - **`children`**

                  `array` — The children of this hierarchical facet value.

                  **Items:**

                  *[Circular Reference]*

                - **`preventAutoSelect`**

                  `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

                - **`previousState`**

                  `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

                - **`retrieveChildren`**

                  `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

                - **`retrieveCount`**

                  `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

                - **`state`**

                  `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

                - **`value`**

                  `string` — This represents a single path segment.

              - **`preventAutoSelect`**

                `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

              - **`previousState`**

                `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

              - **`retrieveChildren`**

                `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

              - **`retrieveCount`**

                `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

              - **`state`**

                `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

              - **`value`**

                `string` — This represents a single path segment.

            - **`preventAutoSelect`**

              `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

            - **`previousState`**

              `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

            - **`retrieveChildren`**

              `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

            - **`retrieveCount`**

              `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

            - **`state`**

              `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

            - **`value`**

              `string` — This represents a single path segment.

          - **`preventAutoSelect`**

            `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

          - **`previousState`**

            `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

          - **`retrieveChildren`**

            `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

          - **`retrieveCount`**

            `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

          - **`state`**

            `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

          - **`value`**

            `string` — This represents a single path segment.

        - **`preventAutoSelect`**

          `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

        - **`previousState`**

          `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

        - **`retrieveChildren`**

          `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

        - **`retrieveCount`**

          `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

        - **`state`**

          `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

        - **`value`**

          `string` — This represents a single path segment.

      - **`preventAutoSelect`**

        `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

      - **`previousState`**

        `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

      - **`retrieveChildren`**

        `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

      - **`retrieveCount`**

        `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

      - **`state`**

        `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

      - **`value`**

        `string` — This represents a single path segment.

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`retrieveChildren`**

      `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

    - **`retrieveCount`**

      `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

    - **`value`**

      `string` — This represents a single path segment.

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

  - **`previousState`**

    `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

  - **`retrieveChildren`**

    `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

  - **`retrieveCount`**

    `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

  - **`state`**

    `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

  - **`value`**

    `string` — This represents a single path segment.

* **`delimitingCharacter`**

  `string`, default: `";"` — The character to use to split field values into a hierarchical sequence.

* **`facetId`**

  `string` — The unique identifier of the facet in the search interface.

* **`field`**

  `string` — The name of the field on which to base the facet request.

* **`filterByBasePath`**

  `boolean` — Whether to use basePath as a filter for the results.

* **`filterFacetCount`**

  `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

* **`injectionDepth`**

  `integer`, format: `int32` — The maximum number of items to scan for facet values.

* **`isFieldExpanded`**

  `boolean` — Whether to make this facet request in the context of requesting more facet values.

* **`numberOfValues`**

  `integer`, format: `int32` — The maximum number of facet values to fetch.

* **`preventAutoSelect`**

  `boolean` — Whether to prevent Coveo ML from automatically selecting values.

* **`resultsMustMatch`**

  `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

* **`sortCriteria`**

  `string`, possible values: `"score", "ascending", "descending", "alphanumeric", "alphanumericNatural", "occurrences", "score", "ascending", "descending", "alphanumeric", "alphanumericNatural", "occurrences"` — The criterion to use for sorting returned facet values. Unsupported values are deserialized to null and treated as if no sort criteria was specified (ignored).

* **`type`**

  `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

- **`currentValues`**

  `array` — The values displayed by the facet in the search interface at the moment of the request.

  **Items:**

  - **`end`**

    `string` — The value to end the range at. Must be later than the start value.

  - **`endInclusive`**

    `boolean` — Whether to include the end value in the range.

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

  - **`previousState`**

    `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

  - **`start`**

    `string` — The value to start the range at.

  - **`state`**

    `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

- **`facetId`**

  `string` — The unique identifier of the facet in the search interface.

- **`field`**

  `string` — The name of the field on which to base the facet request.

- **`filterFacetCount`**

  `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

- **`freezeCurrentValues`**

  `boolean` — Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.

- **`generateAutomaticRanges`**

  `boolean` — Whether to automatically generate range values for this facet.

- **`injectionDepth`**

  `integer`, format: `int32` — The maximum number of items to scan for facet values.

- **`isFieldExpanded`**

  `boolean` — Whether to make this facet request in the context of requesting more facet values.

- **`numberOfValues`**

  `integer`, format: `int32` — The maximum number of facet values to fetch.

- **`preventAutoSelect`**

  `boolean` — Whether to prevent Coveo ML from automatically selecting values.

- **`resultsMustMatch`**

  `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

- **`sortCriteria`**

  `string`, possible values: `"ascending", "descending", "occurrences", "ascending", "descending", "occurrences"` — The criterion to use for sorting returned facet values.

- **`type`**

  `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

* **`currentValues`**

  `array` — The values displayed by the facet in the search interface at the moment of the request.

  **Items:**

  - **`end`**

    `number` — The value to end the range at. Must be greater than the start value.

  - **`endInclusive`**

    `boolean` — Whether to include the end value in the range.

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

  - **`previousState`**

    `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

  - **`start`**

    `number` — The value to start the range at.

  - **`state`**

    `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

* **`facetId`**

  `string` — The unique identifier of the facet in the search interface.

* **`field`**

  `string` — The name of the field on which to base the facet request.

* **`filterFacetCount`**

  `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

* **`freezeCurrentValues`**

  `boolean` — Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.

* **`generateAutomaticRanges`**

  `boolean` — Whether to automatically generate range values for this facet.

* **`injectionDepth`**

  `integer`, format: `int32` — The maximum number of items to scan for facet values.

* **`isFieldExpanded`**

  `boolean` — Whether to make this facet request in the context of requesting more facet values.

* **`numberOfValues`**

  `integer`, format: `int32` — The maximum number of facet values to fetch.

* **`preventAutoSelect`**

  `boolean` — Whether to prevent Coveo ML from automatically selecting values.

* **`rangeAlgorithm`**

  `string`, possible values: `"equiprobable", "even"` — Determines which algorithm is used to generate the ranges if generateAutomaticRanges is enabled.

* **`resultsMustMatch`**

  `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

* **`sortCriteria`**

  `string`, possible values: `"ascending", "descending", "occurrences", "ascending", "descending", "occurrences"` — The criterion to use for sorting returned facet values.

* **`type`**

  `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

**Example:**

```json
{
  "type": "specific",
  "currentValues": [],
  "customSort": [
    ""
  ],
  "facetId": "author-1",
  "field": "author",
  "filterFacetCount": true,
  "freezeCurrentValues": true,
  "injectionDepth": 1,
  "isFieldExpanded": true,
  "numberOfValues": 1,
  "preventAutoSelect": true,
  "resultsMustMatch": "atLeastOneValue",
  "sortCriteria": "score"
}
```

### HierarchicalFacetRequest_Request

- **Type:**`object`

Request facet values representing hierarchically structured categories.

- **`basePath`**

  `array` — The base path shared by all values for the facet.

  **Items:**

  `string` — The base path shared by all values for the facet.

- **`currentValues`**

  `array` — The values displayed by the facet in the search interface at the moment of the request.

  **Items:**

  - **`children`**

    `array` — The children of this hierarchical facet value.

    **Items:**

    - **`children`**

      `array` — The children of this hierarchical facet value.

      **Items:**

      - **`children`**

        `array` — The children of this hierarchical facet value.

        **Items:**

        - **`children`**

          `array` — The children of this hierarchical facet value.

          **Items:**

          - **`children`**

            `array` — The children of this hierarchical facet value.

            **Items:**

            - **`children`**

              `array` — The children of this hierarchical facet value.

              **Items:**

              - **`children`**

                `array` — The children of this hierarchical facet value.

                **Items:**

                - **`children`**

                  `array` — The children of this hierarchical facet value.

                  **Items:**

                  - **`children`**

                    `array` — The children of this hierarchical facet value.

                    **Items:**

                    *[Circular Reference]*

                  - **`preventAutoSelect`**

                    `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

                  - **`previousState`**

                    `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

                  - **`retrieveChildren`**

                    `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

                  - **`retrieveCount`**

                    `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

                  - **`state`**

                    `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

                  - **`value`**

                    `string` — This represents a single path segment.

                - **`preventAutoSelect`**

                  `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

                - **`previousState`**

                  `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

                - **`retrieveChildren`**

                  `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

                - **`retrieveCount`**

                  `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

                - **`state`**

                  `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

                - **`value`**

                  `string` — This represents a single path segment.

              - **`preventAutoSelect`**

                `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

              - **`previousState`**

                `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

              - **`retrieveChildren`**

                `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

              - **`retrieveCount`**

                `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

              - **`state`**

                `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

              - **`value`**

                `string` — This represents a single path segment.

            - **`preventAutoSelect`**

              `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

            - **`previousState`**

              `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

            - **`retrieveChildren`**

              `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

            - **`retrieveCount`**

              `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

            - **`state`**

              `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

            - **`value`**

              `string` — This represents a single path segment.

          - **`preventAutoSelect`**

            `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

          - **`previousState`**

            `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

          - **`retrieveChildren`**

            `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

          - **`retrieveCount`**

            `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

          - **`state`**

            `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

          - **`value`**

            `string` — This represents a single path segment.

        - **`preventAutoSelect`**

          `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

        - **`previousState`**

          `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

        - **`retrieveChildren`**

          `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

        - **`retrieveCount`**

          `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

        - **`state`**

          `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

        - **`value`**

          `string` — This represents a single path segment.

      - **`preventAutoSelect`**

        `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

      - **`previousState`**

        `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

      - **`retrieveChildren`**

        `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

      - **`retrieveCount`**

        `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

      - **`state`**

        `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

      - **`value`**

        `string` — This represents a single path segment.

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`retrieveChildren`**

      `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

    - **`retrieveCount`**

      `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

    - **`value`**

      `string` — This represents a single path segment.

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

  - **`previousState`**

    `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

  - **`retrieveChildren`**

    `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

  - **`retrieveCount`**

    `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

  - **`state`**

    `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

  - **`value`**

    `string` — This represents a single path segment.

- **`delimitingCharacter`**

  `string`, default: `";"` — The character to use to split field values into a hierarchical sequence.

- **`facetId`**

  `string` — The unique identifier of the facet in the search interface.

- **`field`**

  `string` — The name of the field on which to base the facet request.

- **`filterByBasePath`**

  `boolean` — Whether to use basePath as a filter for the results.

- **`filterFacetCount`**

  `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

- **`injectionDepth`**

  `integer`, format: `int32` — The maximum number of items to scan for facet values.

- **`isFieldExpanded`**

  `boolean` — Whether to make this facet request in the context of requesting more facet values.

- **`numberOfValues`**

  `integer`, format: `int32` — The maximum number of facet values to fetch.

- **`preventAutoSelect`**

  `boolean` — Whether to prevent Coveo ML from automatically selecting values.

- **`resultsMustMatch`**

  `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

- **`sortCriteria`**

  `string`, possible values: `"score", "ascending", "descending", "alphanumeric", "alphanumericNatural", "occurrences", "score", "ascending", "descending", "alphanumeric", "alphanumericNatural", "occurrences"` — The criterion to use for sorting returned facet values. Unsupported values are deserialized to null and treated as if no sort criteria was specified (ignored).

- **`type`**

  `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

**Example:**

```json
{
  "basePath": [
    "Doors",
    "Metal"
  ],
  "currentValues": [
    {
      "children": [],
      "preventAutoSelect": true,
      "previousState": "idle",
      "retrieveChildren": true,
      "retrieveCount": 1,
      "state": "idle",
      "value": "electronics"
    }
  ],
  "delimitingCharacter": ";",
  "facetId": "author-1",
  "field": "author",
  "filterByBasePath": true,
  "filterFacetCount": true,
  "injectionDepth": 1,
  "isFieldExpanded": true,
  "numberOfValues": 1,
  "preventAutoSelect": true,
  "resultsMustMatch": "atLeastOneValue",
  "sortCriteria": "score",
  "type": "specific"
}
```

### HierarchicalFacetValue_Request

- **Type:**`object`

A hierarchical facet value.

- **`children`**

  `array` — The children of this hierarchical facet value.

  **Items:**

  - **`children`**

    `array` — The children of this hierarchical facet value.

    **Items:**

    - **`children`**

      `array` — The children of this hierarchical facet value.

      **Items:**

      - **`children`**

        `array` — The children of this hierarchical facet value.

        **Items:**

        - **`children`**

          `array` — The children of this hierarchical facet value.

          **Items:**

          - **`children`**

            `array` — The children of this hierarchical facet value.

            **Items:**

            - **`children`**

              `array` — The children of this hierarchical facet value.

              **Items:**

              - **`children`**

                `array` — The children of this hierarchical facet value.

                **Items:**

                - **`children`**

                  `array` — The children of this hierarchical facet value.

                  **Items:**

                  - **`children`**

                    `array` — The children of this hierarchical facet value.

                    **Items:**

                    *[Circular Reference]*

                  - **`preventAutoSelect`**

                    `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

                  - **`previousState`**

                    `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

                  - **`retrieveChildren`**

                    `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

                  - **`retrieveCount`**

                    `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

                  - **`state`**

                    `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

                  - **`value`**

                    `string` — This represents a single path segment.

                - **`preventAutoSelect`**

                  `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

                - **`previousState`**

                  `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

                - **`retrieveChildren`**

                  `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

                - **`retrieveCount`**

                  `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

                - **`state`**

                  `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

                - **`value`**

                  `string` — This represents a single path segment.

              - **`preventAutoSelect`**

                `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

              - **`previousState`**

                `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

              - **`retrieveChildren`**

                `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

              - **`retrieveCount`**

                `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

              - **`state`**

                `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

              - **`value`**

                `string` — This represents a single path segment.

            - **`preventAutoSelect`**

              `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

            - **`previousState`**

              `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

            - **`retrieveChildren`**

              `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

            - **`retrieveCount`**

              `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

            - **`state`**

              `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

            - **`value`**

              `string` — This represents a single path segment.

          - **`preventAutoSelect`**

            `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

          - **`previousState`**

            `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

          - **`retrieveChildren`**

            `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

          - **`retrieveCount`**

            `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

          - **`state`**

            `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

          - **`value`**

            `string` — This represents a single path segment.

        - **`preventAutoSelect`**

          `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

        - **`previousState`**

          `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

        - **`retrieveChildren`**

          `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

        - **`retrieveCount`**

          `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

        - **`state`**

          `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

        - **`value`**

          `string` — This represents a single path segment.

      - **`preventAutoSelect`**

        `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

      - **`previousState`**

        `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

      - **`retrieveChildren`**

        `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

      - **`retrieveCount`**

        `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

      - **`state`**

        `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

      - **`value`**

        `string` — This represents a single path segment.

    - **`preventAutoSelect`**

      `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

    - **`previousState`**

      `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

    - **`retrieveChildren`**

      `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

    - **`retrieveCount`**

      `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

    - **`state`**

      `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

    - **`value`**

      `string` — This represents a single path segment.

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

  - **`previousState`**

    `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

  - **`retrieveChildren`**

    `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

  - **`retrieveCount`**

    `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

  - **`state`**

    `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

  - **`value`**

    `string` — This represents a single path segment.

- **`preventAutoSelect`**

  `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

- **`previousState`**

  `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

- **`retrieveChildren`**

  `boolean` — Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.

- **`retrieveCount`**

  `integer`, format: `int32` — The maximum number of children to retrieve for this hierarchical facet value.

- **`state`**

  `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

- **`value`**

  `string` — This represents a single path segment.

**Example:**

```json
{
  "children": [
    {
      "preventAutoSelect": true,
      "previousState": "idle",
      "retrieveChildren": true,
      "retrieveCount": 1,
      "state": "idle",
      "value": "electronics"
    }
  ],
  "preventAutoSelect": true,
  "previousState": "idle",
  "retrieveChildren": true,
  "retrieveCount": 1,
  "state": "idle",
  "value": "electronics"
}
```

### NumericalRangeFacetRequest_Request

- **Type:**`object`

Request facet values representing ranges of numbers.

- **`currentValues`**

  `array` — The values displayed by the facet in the search interface at the moment of the request.

  **Items:**

  - **`end`**

    `number` — The value to end the range at. Must be greater than the start value.

  - **`endInclusive`**

    `boolean` — Whether to include the end value in the range.

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

  - **`previousState`**

    `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

  - **`start`**

    `number` — The value to start the range at.

  - **`state`**

    `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

- **`facetId`**

  `string` — The unique identifier of the facet in the search interface.

- **`field`**

  `string` — The name of the field on which to base the facet request.

- **`filterFacetCount`**

  `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

- **`freezeCurrentValues`**

  `boolean` — Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.

- **`generateAutomaticRanges`**

  `boolean` — Whether to automatically generate range values for this facet.

- **`injectionDepth`**

  `integer`, format: `int32` — The maximum number of items to scan for facet values.

- **`isFieldExpanded`**

  `boolean` — Whether to make this facet request in the context of requesting more facet values.

- **`numberOfValues`**

  `integer`, format: `int32` — The maximum number of facet values to fetch.

- **`preventAutoSelect`**

  `boolean` — Whether to prevent Coveo ML from automatically selecting values.

- **`rangeAlgorithm`**

  `string`, possible values: `"equiprobable", "even"` — Determines which algorithm is used to generate the ranges if generateAutomaticRanges is enabled.

- **`resultsMustMatch`**

  `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

- **`sortCriteria`**

  `string`, possible values: `"ascending", "descending", "occurrences", "ascending", "descending", "occurrences"` — The criterion to use for sorting returned facet values.

- **`type`**

  `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

**Example:**

```json
{
  "currentValues": [
    {
      "end": 100,
      "endInclusive": true,
      "preventAutoSelect": true,
      "previousState": "idle",
      "start": 0,
      "state": "idle"
    }
  ],
  "facetId": "author-1",
  "field": "author",
  "filterFacetCount": true,
  "freezeCurrentValues": true,
  "generateAutomaticRanges": true,
  "injectionDepth": 1,
  "isFieldExpanded": true,
  "numberOfValues": 1,
  "preventAutoSelect": true,
  "rangeAlgorithm": "equiprobable",
  "resultsMustMatch": "atLeastOneValue",
  "sortCriteria": "ascending",
  "type": "specific"
}
```

### NumericalRangeFacetValue_Request

- **Type:**`object`

A numerical range facet value.

- **`end`**

  `number` — The value to end the range at. Must be greater than the start value.

- **`endInclusive`**

  `boolean` — Whether to include the end value in the range.

- **`preventAutoSelect`**

  `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

- **`previousState`**

  `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

- **`start`**

  `number` — The value to start the range at.

- **`state`**

  `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

**Example:**

```json
{
  "end": 100,
  "endInclusive": true,
  "preventAutoSelect": true,
  "previousState": "idle",
  "start": 0,
  "state": "idle"
}
```

### PaginatedResponseAgent_Response

- **Type:**`object`

* **`items`**

  `array`

  **Items:**

  - **`agentType` (required)**

    `string` — Agent type

  - **`followUpEnabled` (required)**

    `boolean` — Does the model support follow-up questions.

  - **`name` (required)**

    `string` — The name of the Agent

  - **`passageRetrievalModelId` (required)**

    `string` — Passage retrieval model identifier

  - **`behaviors`**

    `array` — Optional behaviors to persist with the created agent.

    **Items:**

    - **`conditions` (required)**

      `array` — The list of conditions that must be met for this behavior to apply.

      **Items:**

      `string` — The list of conditions that must be met for this behavior to apply.

    - **`obligation` (required)**

      `string` — The obligation/instruction that applies when conditions are met.

  - **`createdDate`**

    `string`, format: `date-time` — Creation timestamp in ISO-8601 format

  - **`description`**

    `string` — The description of the Agent

  - **`id`**

    `string`, format: `uuid` — The public UUID for this configuration

  - **`modifiedDate`**

    `string`, format: `date-time` — Last modification timestamp in ISO-8601 format

  - **`numberOfItemsToConsider`**

    `integer`, format: `int32` — The maximum number of items/documents to consider for the Passage Retrieval model

  - **`status`**

    `string` — Overall status of the Agent. Possible values: - ACTIVE: The agent is active and can be queried. - SOON_TO_BE_ARCHIVED: The agent is still available, but will be archived soon if it is not queried. - INACTIVE: The agent is not ready to be queried yet. - LIMITED: The latest build completed with issues that may affect performance. - ARCHIVED: The agent has been archived and is no longer active. - BUILD_IN_PROGRESS: A build or rebuild is currently in progress. - ERROR: The latest build failed and the issue is customer-visible. - NO_MODELS_DEFINED: No underlying models are configured for this agent. - NOT_FETCHED: The status property was not fetched from the server.

* **`pagination`**

  `object`

  - **`page`**

    `integer`, format: `int32`

  - **`perPage`**

    `integer`, format: `int32`

  - **`totalItems`**

    `integer`, format: `int32`

  - **`totalPages`**

    `integer`, format: `int32`

**Example:**

```json
{
  "items": [
    {
      "agentType": "",
      "behaviors": [],
      "createdDate": "",
      "description": "",
      "followUpEnabled": true,
      "id": "",
      "modifiedDate": "",
      "name": "",
      "numberOfItemsToConsider": 1,
      "passageRetrievalModelId": "",
      "status": ""
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 1,
    "totalItems": 1,
    "totalPages": 1
  }
}
```

### Pagination_Response

- **Type:**`object`

* **`page`**

  `integer`, format: `int32`

* **`perPage`**

  `integer`, format: `int32`

* **`totalItems`**

  `integer`, format: `int32`

* **`totalPages`**

  `integer`, format: `int32`

**Example:**

```json
{
  "page": 1,
  "perPage": 1,
  "totalItems": 1,
  "totalPages": 1
}
```

### SpecificFacetRequest_Request

- **Type:**`object`

Request facet values representing specific values (e.g., Alice Smith, Bob Jones, etc.).

- **`currentValues`**

  `array` — The values displayed by the facet in the search interface at the moment of the request.

  **Items:**

  - **`preventAutoSelect`**

    `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

  - **`previousState`**

    `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

  - **`state`**

    `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

  - **`value`**

    `string` — The facet value name.

- **`customSort`**

  `array` — Facet values that must appear at the top, in this order.

  **Items:**

  `string` — Facet values that must appear at the top, in this order.

- **`facetId`**

  `string` — The unique identifier of the facet in the search interface.

- **`field`**

  `string` — The name of the field on which to base the facet request.

- **`filterFacetCount`**

  `boolean` — Whether to exclude folded result parents when estimating the result count for each facet value.

- **`freezeCurrentValues`**

  `boolean` — Whether to include the facet request's currentValues in corresponding facet response's values array.

- **`injectionDepth`**

  `integer`, format: `int32` — The maximum number of items to scan for facet values.

- **`isFieldExpanded`**

  `boolean` — Whether to make this facet request in the context of requesting more facet values.

- **`numberOfValues`**

  `integer`, format: `int32` — The maximum number of facet values to fetch.

- **`preventAutoSelect`**

  `boolean` — Whether to prevent Coveo ML from automatically selecting values.

- **`resultsMustMatch`**

  `string`, possible values: `"atLeastOneValue", "allValues"` — Specifies how a result must match the selected values.

- **`sortCriteria`**

  `string`, possible values: `"score", "alphanumeric", "alphanumericNatural", "occurrences", "score", "alphanumeric", "alphanumericNatural", "occurrences"` — The sort criterion to apply to the returned facet values. Values outside the documented list are accepted but treated as unsupported and deserialized to null, which causes the sort criterion to be omitted and the default behavior to apply.

- **`type`**

  `string`, possible values: `"specific", "dateRange", "numericalRange", "hierarchical"`, default: `"specific"` — The kind of values to request for the facet.

**Example:**

```json
{
  "currentValues": [],
  "customSort": [
    ""
  ],
  "facetId": "author-1",
  "field": "author",
  "filterFacetCount": true,
  "freezeCurrentValues": true,
  "injectionDepth": 1,
  "isFieldExpanded": true,
  "numberOfValues": 1,
  "preventAutoSelect": true,
  "resultsMustMatch": "atLeastOneValue",
  "sortCriteria": "score",
  "type": "specific"
}
```

### SpecificFacetValue_Request

- **Type:**`object`

A specific facet value.

- **`preventAutoSelect`**

  `boolean` — Whether to prevent Coveo ML from automatically selecting the facet value.

- **`previousState`**

  `string`, possible values: `"idle", "selected", "excluded"` — The previous facet value state in the search interface.

- **`state`**

  `string`, possible values: `"idle", "selected", "excluded"` — The current facet value state in the search interface.

- **`value`**

  `string` — The facet value name.

**Example:**

```json
{
  "preventAutoSelect": true,
  "previousState": "idle",
  "state": "idle",
  "value": "Alice Smith"
}
```

### SseEmitter_Response

- **Type:**`object`

* **`timeout`**

  `integer | null`, format: `int64`

**Example:**

```json
{
  "timeout": null
}
```