Submitting documents for indexing
Last updated: 16 June 2022
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
The examples in this document use the stubbed endpoint. Remember to switch over to the real endpoint !
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
.
Firstly we already require a custom header for authentication & authorisation. Adding additional headers should require little effort. Secondly multipart uploads can be tricky and are better suited for traditional web applications vs REST endpoints.
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
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)
}
$ 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"
}
Overwrite an existing document.
The document, metadata or both can be updated using this endpoint.
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)
Status: 202 (Accepted)
Body: JSON object
{
length: number (required)
title: string (optional)
canonical_url: url (optional)
}
$ 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 https://api.viko.ai/v1-beta/{tenancy}/document/{folder}/{id}
Parameters: tenancy, folder, id (document id)
Header: X-Api-Key (required)
Status: 202 (Accepted)
Body: JSON object
{
id: string (required)
}
$ curl \
--header 'X-Api-Key: replaceme' \
--request DELETE 'https://stub.viko.ai/v1-beta/acme/document/shipping/1'
{
"id": "1"
}
GET https://api.viko.ai/v1-beta/{tenancy}/document/{folder}/{id}
Parameters: tenancy, folder, id (document id)
Header: X-Api-Key (required)
Status: 200
Content-Type: text/plain | text/html | application/pdf
Body: Raw document content
$ 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
GET https://api.viko.ai/v1-beta/{tenancy}/document/
Parameters: tenancy
Header: X-Api-Key (required)
Status: 200
Body: JSON object
{
folders: [
{
name: string (required)
}
]
}
$ curl \
--header 'X-Api-Key: replaceme' \
--request GET 'https://stub.viko.ai/v1-beta/acme/document/'
{
"folders": [
{
"name": "shipping"
}
]
}
GET https://api.viko.ai/v1-beta/{tenancy}/document/{folder}/
Parameters: tenancy, folder (folder name)
Header: X-Api-Key (required)
Status: 200
Body: JSON object
{
folder: string (required)
documents: [
{
id: string (required)
title: string (optional)
}
]
}
$ 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"
}
]
}