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

Note: These APIs are under active development and could change

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

POST 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*	String	The ID of the copilot received during copilot creation

Headers

Name	Type	Description
api_key*	String	The API key received during copilot creation

Request Body

Name	Type	Description
kb_type*	String	The type of knowledge-base. Should be one of ["filters", "sort_keys", "faqs", "vocabulary"]
ingestion_type*	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*	Object	An object describing the knowledge-base source. Properties required in this object are: "source_type": should be "json" "source_path": should be a URL from which the knowledge-base data can be pulled using a GET request. See below for the format in which the knowledge-base data is expected to be returned in, for each knowledge-base type.
refresh_interval	Integer	Number of hours between refreshes. Setting to -1 disables refreshes. Default value: -1

201: Created

Returns an object with property kb_id denoting the ID of the created resource.

400: Bad Request

401: Unauthorized

404: Not Found

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

PUT https://omni.conva.ai/v1/copilots/{copilot_id}/kb/{kb_id}

Path Parameters

Name	Type	Description
copilot_id*	String	The ID of the copilot received during copilot creation
kb_id*	String	The ID of the knowledge-base received during knowledge base creation

Headers

Name	Type	Description
api_key*	String	The API key received during copilot creation

Request Body

Name	Type	Description
ingestion_type*	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*	String	The type of knowledge-base. Should be one of ["filters", "sort_keys", "faqs", "vocabulary"]
kb_source*	String	An object describing the knowledge-base source. Properties required in this object are: "source_type": should be "json" "source_path": should be a URL from which the knowledge-base data can be pulled using a GET request. See below for the format in which the knowledge-base data is expected to be returned in, for each knowledge-base type.
refresh_interval	Integer	Number of hours between refreshes. Setting to -1 disables refreshes. Default value: -1

200: OK

400: Bad Request

401: Unauthorized

404: Not Found

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

DELETE https://omni.conva.ai/v1/copilots/{copilot_id}/kb/{kb_id}

Path Parameters

Name	Type	Description
copilot_id*	String	The ID of the copilot received during copilot creation.
kb_id*	String	The ID of the knowledge-base received during knowledge-base creation

Headers

Name	Type	Description
api_key*	String	The API key received during copilot creation

200: OK

401: Unauthorized

404: Not Found

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

GET https://omni.conva.ai/v1/copilots/{copilot_id}/kb/{kb_id}/status

Path Parameters

Name	Type	Description
copilot_id*	String	ID of the copilot received during copilot creation

Query Parameters

Name	Type	Description
kb_id*	String	ID of the knowledge-base received during knowledge-base creation

Headers

Name	Type	Description
api_key*	String	The API key received during copilot creation

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

Knowledge-base Ingestion Format

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.

Sample response for "filters":

[{ "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>"]}]

---