Introduction

Use our REST like api to index documents and FAQs, ask questions and perform semantic searches.

Contents

1. Introduction
2. Authentication & authorization
3. Stubbed endpoints
4. Submitting vs indexing documents
5. Question answering vs searching

Tenancy

During the onboarding process you will be assigned a tenancy. This is typically a 10 digit alphanumeric string. Your tenancy id must be specified for all endpoints as a path prefix:

https://api.viko.ai/v1-beta/{tenancy}/

Authentication and authorization

All calls (including read only calls) require authentication. You must pass a valid X-Api-Key header.

You can use the Viko console to generate API keys with read only or write permissions. Be sure to use use a read only key in any client side code. Our Javascript widgets will warn you if you attempt to use a key with write permissions.

Stubbed endpoints

Developing against a live endpoint is not ideal. Real credentials must be used, data must be submitted and indexed before querying etc. To aid development we’ve provided a stubbed API which validates requests, but returns constant, stubbed responses:

https://stub.viko.ai/v1-beta/{tenancy}/

The tenancy path parameter and X-Api-Key header must be sent but they aren’t checked, so you can pass anything.

For example this is a valid request:

$ curl -X GET --location \
  -H 'X-Api-Key: todo' \
  'https://stub.viko.ai/v1-beta/todo/document/'

Submitting vs Indexing documents

When you submit a document through our API it is queued and subsequently indexed. The time taken to index a document varies depending on the complexity of the document itself, along with the workload at the time. It could take anything from a couple of seconds through to one hour.

Indexing is eventually consistent therefore you should not assume that a document can be queried immediately after it was submitted. This is one reason to use the stubbed endpoints during development.

Question answering vs searching

Viko supports two modes of query: searching and question answering.

Searching

Semantic search is similar to a typical full text search operation. Given a phrase, Viko will return the most relevant fragment or document. For example, given the search phrase “shipping rates”, Viko might return the pricing section of the shipping document.

However, unlike most full text search engines, Viko uses powerful Natural Language Processing (NLP) to perform a semantic search instead of a regular keyword search.

Question answering

Question answering goes deeper than semantic search. Given a question, Viko will first find the most relevant fragments then extract or generate an answer based on the information (context) within the fragments. For example given the question “how much is next day shipping?”, Viko might answer “$4.95”