Indexing documents

Learn how to submit documents for indexing.

Note: Existing, predefined FAQs can also be indexed (and queried), however FAQs should be indexed using the dedicated FAQ endpoints. Read more about how to structure your content

Contents

1. Put document
2. Get document
3. Delete document
4. List document folders
5. List documents

Put document

Overwrite an existing document, or index a document with a developer provided id.

The document contents, metadata or both can be updated using this endpoint.

Request

PUT https://api.viko.ai/v1-beta/{tenancy}/documents/{folder}/{id} (note: no trailing slash)

Request headers

Content-Type text/plain | text/html | application/pdf (required)
X-Api-Key (required)
X-Title Document title (optional)
X-Link URL e.g. to the public version of the document (optional)

Request body

Raw text or binary data

Response

Status: 202 (Accepted)

Response body

{
  content: string (required) // trimmed textual content
  length: number (required) // document length in bytes
  title: string (optional)
  link: url (optional)
}

Example

$ curl \
  --header 'Content-Type: text/plain' \
  --header 'X-Api-Key: replaceme' \
  --header 'X-Title: Updated shipping prices' \
  --header 'X-Link: https://acme.com/shipping.html' \
  --request PUT 'https://stub.viko.ai/v1-beta/acme/documents/shipping/1' \
  --data-raw 'Lorem ipsum next day shipping is available for $3.95 Lorem ipsum'

{
  "content": "Lorem ipsum next day shipping is available for $3.95 Lorem ipsum",
  "length": 1024,
  "title": "Updated shipping prices",
  "link": "https://acme.com/shipping.html"
}

Get document

Fetch the document and metadata. Note: this endpoint doesn’t return a JSON document. Similar to the POST & PUT endpoints we use custom headers for the metadata and the document contents is sent in the HTTP response body.

Request

GET https://api.viko.ai/v1-beta/{tenancy}/documents/{folder}/{id}

Request headers

X-Api-Key (required)

Response

Status 200

Response headers

Content-Type text/plain | text/html | application/pdf
Content-Length Document length in bytes
X-Title Document title (optional)
X-Link URL e.g. to the public version of the document (optional)

Response body

Raw text or binary data

Example

$ curl -v \
  --header 'X-Api-Key: replaceme' \
  'https://stub.viko.ai/v1-beta/acme/documents/shipping/1'

...
< Content-Type: text/plain; charset=utf-8
< X-Title: Shipping prices
< X-Link: https://acme.com/shipping.html
...
Content-Type: text/plain; charset=utf-8
Lorem ipsum next day shipping is available for $4.95 Lorem ipsum

Delete document

Request

DELETE https://api.viko.ai/v1-beta/{tenancy}/documents/{folder}/{id} (note: no trailing slash)

Request headers

X-Api-Key (required)

Response

Status 202 (Accepted)

Response body

{
  status: "deleted" (required)
  id: string (required)
}

Example

$ curl \
  --header 'X-Api-Key: replaceme' \
  --request DELETE 'https://stub.viko.ai/v1-beta/acme/documents/shipping/1'

{
  "status": "deleted",
  "id": "1"
}

List document folders

Request

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

Request headers

X-Api-Key (required)

Response

Status 200

Response body

{
  folders: [
    {
      name: string (required)
      count: number (required)
    }
  ],
  total: number (required) // total documents in the index
}

Example

$ curl \
  --header 'X-Api-Key: replaceme' \
  'https://stub.viko.ai/v1-beta/acme/documents/'

{
  "folders": [
    { 
      "name": "shipping", 
      "count": 1 
    }
  ],
  "total": 1
}

List documents

Request

GET https://api.viko.ai/v1-beta/{tenancy}/documents/{folder}/ (note: trailing slash)

Query parameters

limit (optional - integer)
offset (optional - integer)

Request headers

X-Api-Key (required)

Response

Status 200

Response body

{
  folder: string (required)
  documents: [
    {
      id: string (required)
      title: string (optional)
      link: string (optional)
    }
  ],
  total: number
}

Example

$ curl \
  --header 'X-Api-Key: replaceme' \
  'https://stub.viko.ai/v1-beta/acme/documents/shipping/?limit=10&offset=0'

{
  "folder": "shipping",
  "documents": [
    {
      "id": "1",
      "title": "Updated shipping prices",
      "link": "https://acme.com/shipping.html"
    }
  ],
  "total": 1
}