# 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>

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.conva.ai/conva-omni/creating-and-configuring-the-omni-copilot.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.