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. Submit document
2. Update document
3. Delete document
4. Get document
5. List document folders
6. List documents

Submit document

Submit a new document for indexing. The appropriate folder will be created if it does not already exist.

The document itself should be posted in raw format with an appropriate Content-Type header. Valid content types are text/plain, text/html and application/pdf. Textual content should be UTF-8 encoded.

Metadata (document title, canonical url) should be supplied via custom headers: X-Title and X-Canonical-Url.

Request

POST https://api.viko.ai/v1-beta/{tenancy}/document/{folder}/
Parameters: tenancy, folder
Header: X-Api-Key (required)
Header: X-Title (Optional)
Header: X-Canonical-Url (Optional)
Content-Type: text/plain | text/html | application/pdf
Body: Raw text or binary data

Response

Status: 202 (Accepted)
Body: JSON object

{
  id: string (required) // generated document id
  length: number (required) // document length in bytes
  title: string (optional)
  canonical_url: url (optional)
}

Example

$ curl \
  --header 'X-Api-Key: replaceme' \
  --header 'Content-Type: text/plain' \
  --header 'X-Title: Shipping prices' \
  --header 'X-Canonical-Url: https://acme.com/shipping.html' \
  --request POST 'https://stub.viko.ai/v1-beta/acme/document/shipping/' \
  --data-raw 'Lorem ipsum next day shipping is available for $4.95 Lorem ipsum'

{
  "id": "1",
  "length": 1024,
  "title": "Shipping prices",
  "canonical_url": "https://acme.com/shipping.html"
}

Update document

Overwrite an existing document.

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

Request

PUT https://api.viko.ai/v1-beta/{tenancy}/document/{folder}/{id}
Parameters: tenancy, folder, id (document id)
Header: X-Api-Key (required)
Header: X-Title (Optional)
Header: X-Canonical-Url (Optional)
Content-Type: text/plain | text/html | application/pdf
Body: Raw text or binary data (Optional)

Response

Status: 202 (Accepted)
Body: JSON object

{
  length: number (required)
  title: string (optional)
  canonical_url: url (optional)
}

Example

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

{
  "length": 1024,
  "title": "Updated shipping prices",
  "canonical_url": "https://acme.com/shipping.html"
}

Delete document

Request

DELETE https://api.viko.ai/v1-beta/{tenancy}/document/{folder}/{id}
Parameters: tenancy, folder, id (document id)
Header: X-Api-Key (required)

Response

Status: 202 (Accepted)
Body: JSON object

{
  id: string (required)
}

Example

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

{
  "id": "1"
}

Get document

Request

GET https://api.viko.ai/v1-beta/{tenancy}/document/{folder}/{id}
Parameters: tenancy, folder, id (document id)
Header: X-Api-Key (required)

Response

Status: 200
Content-Type: text/plain | text/html | application/pdf
Body: Raw document content

Example

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

Content-Type: text/plain; charset=utf-8
Lorem ipsum next day shipping is available for $4.95 Lorem ipsum

List document folders

Request

GET https://api.viko.ai/v1-beta/{tenancy}/document/
Parameters: tenancy
Header: X-Api-Key (required)

Response

Status: 200
Body: JSON object

{
  folders: [
    {
      name: string (required)
    }
  ]
}

Example

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

{
  "folders": [
    {
      "name": "shipping"
    }
  ]
}

List documents

Request

GET https://api.viko.ai/v1-beta/{tenancy}/document/{folder}/
Parameters: tenancy, folder (folder name)
Header: X-Api-Key (required)

Response

Status: 200
Body: JSON object

{
  folder: string (required)
  documents: [
    {
      id: string (required)
      title: string (optional)
    }
  ]
}

Example

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

{
  "folder": "shipping",
  "documents": [
    {
      "id": "1",
      "title": "Updated shipping prices"
    }
  ]
}