> For the complete documentation index, see [llms.txt](https://docs.conva.ai/conva-omni/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.conva.ai/conva-omni/creating-and-configuring-the-omni-copilot.md).

# Creating and Configuring the Omni Copilot

The Omni Copilot can be created and configured through the Omni console, which will be hosted on conva.ai. The console will provide a UI to allow users to:

* Provide information regarding the details of the app
* Configure the knowledge-base which would augment the Copilot's internal knowledge
* Control other behavioral aspects of the Copilot, such as the grounding policy.

While the console would provide a UI for configuring the knowledge-base, the following APIs should provide more context around what goes on under the hood.

## Knowledge-base Management APIs

{% hint style="info" %}
Note: These APIs are under active development and could change
{% endhint %}

## Creates a new knowledge-base configuration for the given copilot-id

<mark style="color:green;">`POST`</mark> `https://omni.conva.ai/v1/copilots/{copilot_id}/kb`

Provides an interface for configuring knowledge-base ingestion that could be used to augment the Omni Copilot's knowledge of the app's filters, sort\_keys, FAQs and vocabulary.

#### Path Parameters

| Name                                          | Type   | Description                                            |
| --------------------------------------------- | ------ | ------------------------------------------------------ |
| copilot\_id<mark style="color:red;">\*</mark> | String | The ID of the copilot received during copilot creation |

#### Headers

| Name                                       | Type   | Description                                  |
| ------------------------------------------ | ------ | -------------------------------------------- |
| api\_key<mark style="color:red;">\*</mark> | String | The API key received during copilot creation |

#### Request Body

| Name                                              | Type    | Description                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| kb\_type<mark style="color:red;">\*</mark>        | String  | The type of knowledge-base. Should be one of \["filters", "sort\_keys", "faqs", "vocabulary"]                                                                                                                                                                                                                                                                                  |
| ingestion\_type<mark style="color:red;">\*</mark> | String  | The ingestion mechanism. Presently, the only supported option is "pull", which means that Omni will pull the data from the endpoints you provide and ingest them.                                                                                                                                                                                                              |
| kb\_source<mark style="color:red;">\*</mark>      | Object  | <p>An object describing the knowledge-base source. Properties required in this object are:</p><p>"source\_type": should be "json"</p><p>"source\_path": should be a URL from which the knowledge-base data can be pulled using a GET request.</p><p>See below for the format in which the knowledge-base data is expected to be returned in, for each knowledge-base type.</p> |
| refresh\_interval                                 | Integer | <p>Number of hours between refreshes. Setting to -1 disables refreshes.</p><p></p><p>Default value: -1</p>                                                                                                                                                                                                                                                                     |

{% tabs %}
{% tab title="201: Created " %}
Returns an object with property `kb_id` denoting the ID of the created resource.
{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}
{% endtabs %}

## Updates the knowledge-base configuration for the given copilot-id and kb-id

<mark style="color:orange;">`PUT`</mark> `https://omni.conva.ai/v1/copilots/{copilot_id}/kb/{kb_id}`

#### Path Parameters

| Name                                          | Type   | Description                                                          |
| --------------------------------------------- | ------ | -------------------------------------------------------------------- |
| copilot\_id<mark style="color:red;">\*</mark> | String | <p>The ID of the copilot received during copilot creation</p><p></p> |
| kb\_id<mark style="color:red;">\*</mark>      | String | The ID of the knowledge-base received during knowledge base creation |

#### Headers

| Name                                       | Type   | Description                                  |
| ------------------------------------------ | ------ | -------------------------------------------- |
| api\_key<mark style="color:red;">\*</mark> | String | The API key received during copilot creation |

#### Request Body

| Name                                              | Type    | Description                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ingestion\_type<mark style="color:red;">\*</mark> | String  | The ingestion mechanism. Presently, the only supported option is "pull", which means that Omni will pull the data from the endpoints you provide and ingest them.                                                                                                                                                                                                              |
| kb\_type<mark style="color:red;">\*</mark>        | String  | The type of knowledge-base. Should be one of \["filters", "sort\_keys", "faqs", "vocabulary"]                                                                                                                                                                                                                                                                                  |
| kb\_source<mark style="color:red;">\*</mark>      | String  | <p>An object describing the knowledge-base source. Properties required in this object are:</p><p>"source\_type": should be "json"</p><p>"source\_path": should be a URL from which the knowledge-base data can be pulled using a GET request.</p><p>See below for the format in which the knowledge-base data is expected to be returned in, for each knowledge-base type.</p> |
| refresh\_interval                                 | Integer | <p>Number of hours between refreshes. Setting to -1 disables refreshes.</p><p></p><p>Default value: -1</p>                                                                                                                                                                                                                                                                     |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}
{% endtabs %}

## Deletes the knowledge-base configuration for the given copilot-id and kb-id

<mark style="color:red;">`DELETE`</mark> `https://omni.conva.ai/v1/copilots/{copilot_id}/kb/{kb_id}`

#### Path Parameters

| Name                                          | Type   | Description                                                          |
| --------------------------------------------- | ------ | -------------------------------------------------------------------- |
| copilot\_id<mark style="color:red;">\*</mark> | String | The ID of the copilot received during copilot creation.              |
| kb\_id<mark style="color:red;">\*</mark>      | String | The ID of the knowledge-base received during knowledge-base creation |

#### Headers

| Name                                       | Type   | Description                                  |
| ------------------------------------------ | ------ | -------------------------------------------- |
| api\_key<mark style="color:red;">\*</mark> | String | The API key received during copilot creation |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}
{% endtabs %}

## Returns the status of the knowledge-base ingestion for the given copilot-id and kb-id

<mark style="color:blue;">`GET`</mark> `https://omni.conva.ai/v1/copilots/{copilot_id}/kb/{kb_id}/status`

#### Path Parameters

| Name                                          | Type   | Description                                        |
| --------------------------------------------- | ------ | -------------------------------------------------- |
| copilot\_id<mark style="color:red;">\*</mark> | String | ID of the copilot received during copilot creation |

#### Query Parameters

| Name                                     | Type   | Description                                                      |
| ---------------------------------------- | ------ | ---------------------------------------------------------------- |
| kb\_id<mark style="color:red;">\*</mark> | String | ID of the knowledge-base received during knowledge-base creation |

#### Headers

| Name                                       | Type   | Description                                  |
| ------------------------------------------ | ------ | -------------------------------------------- |
| api\_key<mark style="color:red;">\*</mark> | String | The API key received during copilot creation |

{% tabs %}
{% tab title="200: OK " %}
Returns an object describing the status of ingestion with the following properties:

status: one of \["success", "failure", "pending"]

reason: reason for failure, if any

last\_attempt\_timestamp: timestamp of the latest ingestion attempt

next\_attempt\_timestamp: timestamp at which the next ingestion will be attempted
{% endtab %}
{% endtabs %}

<details>

<summary>Knowledge-base Ingestion Format</summary>

In order for the Omni Copilot to successfully ingest the various types of knowledge-bases, the knowledge-base source must return raw data in the below formats

#### Filters

The knowledge-base source for `filters` should be returned as a JSON array where each object contains the following fields:

* `app_category` (required): the name of the category, such as "electronics", "fashion", etc to which the filters belong. If your app only supports a single category, you can use "default" as the category
* `app_brands` (optional): the brands of the app that support the given app\_category
* `filter_category` (required): the category of filters to which this filter set belongs. For example, for filter labels such as "Nike", "Reebok", "Asics", etc, the filter\_category would be "brand"
* `filter_labels` (required): a list of labels corresponding to the filter\_category
* `filter_ids` (optional): a list of ids corresponding to the list labels. If this field is provided, the length of this list should be equal to the length of filter\_labels and the id at each index should correspond to the label at the same index in filter\_labels.&#x20;

Sample response for "`filters`":&#x20;

`[{ "app_category": "grocery", "filter_category": "Allergen Info", "filter_labels": ["Gluten Free", "Dairy Free", "Lactose Free", "Contains Nuts"] }]`

***

#### Sort Keys

The knowledge-base source for `sort_keys` should be returned as a JSON array where each object contains the following fields:

* `app_category` (required): the name of the category, such as "electronics", "fashion", etc to which the filters belong. If your app only supports a single category, you can use "default" as the category
* `app_brands` (optional): the brands of the app that support the given app\_category
* `sort_labels` (required): the list of labels corresponding to the sort keys for the given `app_category`

Sample response for "`sort_keys`":

`[{ "app_category": "grocery", "sort_labels": ["Relevance", "Popularity", "Price"] }]`

***

#### FAQs

The knowledge-base source for `faqs` should be returned as a JSON array where each object contains the following fields:

* `app_category` (required): the name of the category, such as "electronics", "fashion", etc to which the filters belong. If your app only supports a single category, you can use "default" as the category
* `app_brands` (optional): the brands of the app that support the given app\_category
* `sources`(required): a list of objects, each of which contains an optional URL pointing to the FAQ source, and a required contents, containing the FAQ contents

Sample response for "`faqs`":

`[{ "app_category": "grocery", "sources": [{"url": "https://foo.bar", "contents": "<FAQ contents>"]}]`

***

#### Vocabulary

The knowledge-base source for `vocabulary` should be returned as a JSON array where each object contains the following fields:

* `app_category` (required): the name of the category, such as "electronics", "fashion", etc to which the filters belong. If your app only supports a single category, you can use "default" as the category
* `app_brands` (optional): the brands of the app that support the given app\_category
* `sources`(required): a list of objects, each of which contains an optional URL pointing to the vocabulary source, and a required contents, containing the vocabulary contents

Sample response for "`vocabulary`":

`[{ "app_category": "grocery", "sources": [{"url": "https://foo.bar", "contents": "<FAQ contents>"]}]`

</details>

***