FAQ API Documentation

Alterra.ai FAQ search and chatbot API

Free-text search for FAQs, help centers, knowledge bases, user guides, canned support responses… A chatbot that answers straightforward questions. If the answer is in the FAQ file the bot shall be able to answer it.

Using this API you may build your own conversational virtual agents, messenger bots, embed the functionality in site search, pair it up with live sales or support agents, etc.

This API performs natural-language search against a set of FAQ articles. An article contains a title and full-text answer. An article may also have a short snippet attached to it, to be shown where the dialog space is constrained (think small chat windows or text messages).

You also have an option to load a set of past queries and then assign the correct answers (article ids) to them. This greatly benefits future searches.

Alterra.ai keeps a log of queries it receives. These may also be assigned correct answers, forming a training corpus.

The API has four main parts: 1. uploading (and editing) the FAQ articles, 2. working with the queries, 3. working with the query log, and 4. performing search The first three parts are used off-line, ahead of time, to upload and edit data, and train machine learning.

The fourth part is used during the serving time. It performs actual search. The user asks a question or performs a search, you pass the query to this API, and it returns the search results, ordered by relevancy.

The API may return more than one search result. If your application is a fully automated bot you would display only the first result. If it is site search you may display several results. If you have a human agent in the loop you may display several results to the agent and let him manually select which one to send to the user.

Minimally, a client would upload FAQ articles, then use the search API in their message flow.

All APIs define here follow the REST paradigm.

All methods require an API key. API key is passed as “Authorization” header in the request.

All GET methods take arguments as CGI parameters in the url.

All POST and PUT requests take arguments in the request body, which should be in JSON format.

All methods return JSON which may be empty if the only result is an operation status which is reported as HTTP status code.

Entities

Each entity is represented by a JSON object.

Article

One article from a FAQ document

Field name Type Always present Description
id int Y
question string Y Title of the article (aka canonical question)
answer string Y Full answer (can contain HTML formatting)
answers list of string N Other formulations of the answer (can contain HTML formatting)
pos_regex string N Regexp (matched against the query) that forcedly selects this answer
neg_regex string N Regexp (matched against the query) that cancels the pos_regex
snippet string N Short summary of the answer (can contain HTML formatting)
comment string N Private comment, not visible to end-users

Example:

{
    "id": 42,
    "question": "Where can I find more bots?",
    "snippet": "There is no official store yet",
    "answer": "There is no official store at the moment, so you‘ll have to ask your friends or search the web for now. We’re pretty sure you'll find some bots to play with."
}

Query

A user query stored in the system and used for training.

Field name Type Always present Description
hash string N A hash of this query’s context, used as ID.
article_id int N Id of FAQ article that answers this question, if known. A special value of -1 is used when there is no good answer in the FAQ (and the query should be forwarded to a human)
text string Y Query text

Example:

{
    "id":  1138,
    "text": "Where's the money Lebowski?",
    "article_id": -1
}

Log entry

A user query that the system saw in the past.

Field name Type Always present Description
query string Y User query
search_id string Y The ID of the search assigned when the search was performed
timestamp datetime Y Date and time in ISO 8601 format
result_ids list of ints N Same semantics as article_id field in query

Example:

{
    "query_text": "Where's the money Lebowski?",
    "timestamp": "2017-03-29T12:00:35+00:00",
    "results_ids": [1, 17, 5]
}

Feedback

A data type to provide feedback about the search results, e.g. when a live agent selects one of the suggested answers for sending to user.

Field name Type Always present Description
search_id string Y The ID of the search
article_id int Y Same semantics as article_id field in query

Example:

{
    "search_id": "05F4F53B-4F5D8162-7852A351-4B90F22E",
    "article_id": 3
}

Search response

Set of all results matching given search query, ordered by relevancy (in websearch it would be called SERP)

Field name Type Always present Description
search_id string Y The ID of the search performed (for logging/debugging)
results list of search result objects Y Results themselves (see search result object)

Example:

{
    "article_id": 42,
    "question": "Where can I find more bots?"
}

Search result

One result of FAQ search, represented by one FAQ article.

Field name Type Always present Description
article_id int Y Article ID of the result
question string Y Article title (aka canonical question)
snippet string N A short snippet of the article text (can contain HTML formatting)

Comment: search result does NOT contain the full answer (it may be too long, contain images, etc.). If you want to display the full answer (answer), you would have to call this API again, by article ID.

Example:

{
    "article_id": 42,
    "question": "Where can I find more bots?"
}

Articles API

Add new articles: POST to /api/faq/v1/articles/

Arguments

Field name Type Always present Description
body list of article objects Y You souldn’t fill id fields, they will be generated by the server

Example:

"body": [
    {
        "question": "Where can I find more bots?",
        "snippet": "There is no official store yet",
        "answer": "There is no official store at the moment, so you‘ll have to ask your friends or search the web for now. We’re pretty sure you'll find some bots to play with."
    },
    {
        "question": "Who can see me ‘online’?",
        "answer": "People can only see you online if you're sharing your last seen status with them. There is one exception to this: people will be able to see you online for a brief period when you send them a message in a one-on-one chat or in a group where you both are members."
    }
]

Server reply

List of identifiers of articles

Example:

[42,43]

Update article data for a bunch of articles: PUT to /api/faq/v1/articles/

Arguments

Field name Type Always present Description
body list of article objects Y You must fill id fields

Example:

"body": [
    {
        "id": 42,
        "question": "Where can I find more bots?",
        "snippet": "There is no official store yet",
        "answer": "There is no official store at the moment, so you‘ll have to ask your friends or search the web for now. We’re pretty sure you'll find some bots to play with."
    },
    {
        "id": 54,
        "question": "Who can see me ‘online’?",
        "answer": "People can only see you online if you're sharing your last seen status with them. There is one exception to this: people will be able to see you online for a brief period when you send them a message in a one-on-one chat or in a group where you both are members."
    }
]

Server reply

List of replaced article ids

Example:

[42,54]

Get a list of articles with pagination: GET from /api/faq/v1/articles/

Arguments

Field name Type Required Description
offset int N First article to return; zero-based; default value is unsurprisingly 0
limit int N Maximum number of articles to return. Default value 10. Max value 1000

Example: /api/faq/v1/articles?offset=42&num=2

Server reply

List of article objects

Example:

[
    {
        "article_id": 42,
        "question": "Where can I find more bots?"
    },
    {
        "article_id": 43,
        "question": "Who can see me ‘online’?",
        "snippet": "People can only see you online if you're sharing your last seen status with them."
    }
]

Get article by id: GET from /api/faq/v1/articles/{article_id}

Server reply

An article object or an appropriate HTTP status and error message

Remove the article: DELETE /api/faq/v1/articles/{article_id}

Server reply

Appropriate HTTP status

Query API

List stored queries with pagination: GET from /api/faq/v1/queries/

Arguments

Field name Type Required Description
offset int N zero-based
limit int N default value 10. Max value 1000

Example: /api/faq/v1/queries?offset=1138&num=1

Server reply

List of query objects

Example:

[
    {
        "hash": "23db4",
        "text": "Who should I contact about my booking?",
        "article_id": 2
    }
]

Add queries data: POST to /api/faq/v1/queries/

Add new queries associated with articles. Only unique queries will be actually added, duplicate queries will be skipped. The result will contain new hashes for added queries and old hashes for existing ones. article_id field must be set in all queries

Arguments

Field name Type Required Description
body list of Query objects N article_id field must be set in all queries

Example:

"body": [
    {
        "text": "Who should I contact about my booking?",
        "article_id": 2
    },
    {
        "text": "Where is my confirmation?"
        "article_id": 5
    },
]

Server reply

List of assigned query hashes.

Example:

["4e3def3", "1ebc54"]

Replace queries data: PUT to /api/faq/v1/queries/

Replace existing queries

Arguments

Field name Type Required Description
body list of Query objects N article_id field must be set in all queries

Example:

"body": [
    {
        "text": "Who should I contact about my booking?",
        "article_id": 2
    },
    {
        "text": "Where is my confirmation?"
        "article_id": 5
    },
]

Server reply

List of replaced query hashes.

Example:

["4e3def3", "1ebc54"]

Get user query by hash: GET from /api/faq/v1/queries/{query_hash}

Server reply

A query object

Example:

{
    "hash": "34512",
    "text": "Where is my confirmation?",
    "article_id": -1
}

Delete user query by hash: DELETE /api/faq/v1/queries/{query_hash}

Server reply

Appropriate HTTP status

API for queries attached to FAQ articles

The queries for which the correct article is known can be retrieved and managed through this additional API which is article-based. These queries are “attached” to the appropriate article.

List user queries attached to the article, with pagination: GET from /api/faq/v1/articles/{article_id}/queries/

Arguments

Field name Type Required Description
offset int N zero-based
limit int N default value 100. Max value 1000

Example: /api/faq/v1/articles/1/queries?offset=1138&num=2

Server reply

List of query objects

Example:

[
    {
    "hash": "123e4",
    "article_id": 1,
    "text": "Where's the money Lebowski?"
    },
    {
    "id": "9ffc94",
    "article_id": 1,
    "text": "Who should I contact about my booking?"
    }
]

Add new queries to the article: POST to /api/faq/v1/articles/{article_id}/queries/

Arguments

Field name Type Required Description
body list of Query objects N hash and article_id are ignored.

Example:

[
    {
    "text": "Where is my booking confirmation?"
    }
]

Server reply

List of added query hashes

Example:

["2345ff"]

Replace existing queries for the article: PUT to /api/faq/v1/articles/{article_id}/queries/

Arguments

Field name Type Required Description
body list of Query objects N hash and article_id are ignored.

Example:

[
    {
    "text": "Where is my booking confirmation?"
    }
]

Server reply

List of added query hashes

Example:

["2345ff"]

Get attached query by hash: GET from /api/faq/v1/articles/{article_id}/queries/{query_hash}

Server reply

query object

Delete attached query: DELETE /api/faq/v1/articles/{article_id}/queries/{query_id}

Server reply

Appropriate HTTP status

Search API

Given a user query, find relevant answer(s) in the FAQ: GET from /api/faq/v1/search

This part is used during the serving time. It performs actual search. The user queries your application, you pass the query to this API, which returns the search results, ordered by relevancy.

Arguments

Field name Type Required Description
query string Y user query

Example: /api/faq/v1/search?query=How+can+I+contact+you

Server reply

A search response object (set of search results, ordered by relevancy)

Example:

{
  "search_id": "73b61636-29b1-4bee-8845-3bc0ffe9a86a",
  "results":
    [
        {
            "article_id": 42,
            "question": "Where can I find more bots?"
        },
        {
            "article_id": 43,
            "question": "Who can see me ‘online’?",
            "snippet": "People can only see you online if you're sharing your last seen status with them."
        }
    ]
}

Report which answer returned by a search is correct (clicked by user, selected by human agent etc.) : POST to /api/faq/v1/feedback/

Arguments

Field name Type Required Description
body list of feedback objects Y

Example:

body: [{
"search_id": "73b61636-29b1-4bee-8845-3bc0ffe9a86a",
"article_id": 42
}]

List log entries: GET from /api/faq/v1/log/

Arguments

Field name Type Required Description
offset int N zero-based
count int N default value 10. Max value 1000

Example: /api/faq/v1/log?timestamp=2017-03-21&offset=4238&num=1

Server reply

List of log entry objects

Example:

[
    {
        "query": "Can I pay ",
        "search_id": "DEAD-BEEF-DEAD-BEEF",
        "timestamp": "2017-03-21T13:23:53+00:00",
        "result_ids": [ 3, 5, 8 ]
    }
]

Navigation