Cognitive Search API

Cognitive Search API makes it possible for the system to read, infer meaning, and deliver precise answers from large corpora with high accuracy.

Uploading Q&A and Documents

Please sign up and sign in to the Alli dashboard first. You must select 'Cognitive Search' for the Project Type when you sign up. Go to the Q&A tab on the dashboard to upload question-answer pairs. If you want to upload unstructured text data such as Word, PDF, Powerpoint, and Excel file, go to the Documents tab in the dashboard and upload the documents.

If you want to automatically sync with your data source, such as MS OneDrive, please go to the Source tab.

Getting API KEY

Please provide your API key in the request header API-KEY. Your API key can be found on your dashboard Settings menu, under the General tab.

Error Messages

Please read the error message you get if you don't get the response that you expected. For example, if you don't use the right HTTP method for the API, you'll get this type of error as response:

{“error”: “Method Not Allowed POST: /webapi/faq_feedbacks”}

post
Search from Q&A

https://backend.alli.ai/webapi/faq
This API lets you find the most relevant question and answer pairs from your Q&A knowledge base.
Request
Response
Request
Headers
API-KEY
required
string
Your API key can be found on your dashboard Settings menu, under the General tab.
Query Parameters
query
required
string
This is a query string.
format
optional
string
html or text. If it's text, the return value will be a plain text. If it's html, it will return html. If your answer contains styled html, such as different font size and color, you can use html. If you simply want to get an answer as a text, you can use the text. The default value is html.
Response
200: OK
The API will find the most relevant question and answers from your Q&A database. confidence: It shows the confidence value from AI model. Shown as a number value between 0 and 1. effective_confidence: When you provide feedback to the query result, it automatically trains the AI model. Effective confidence is the adjusted score with these users' and agents' feedback. Shown as a number value between 0 and 1. question: This is the question part of the selected Q&A pair. answer: This is the answer part of the selected Q&A pair. id: This is used to identify the result to give or cancel feedback. The number of search results and the threshold follows your dashboard setting. Please check your settings in Q&A > Settings.
{"result":
[
{
"confidence": CONFIDENCE_VALUE,
"effective_confidence": EFFECTIVE_CONFIDENCE_VALUE,
"question": "QUESTION_1",
"answer": "ANSWER_1",
"id": "ID_1"
}, ...
]
}

Request Example

Please replace YOUR_API_KEY to your one in the example below. Please see getting-api-key section.

curl -d '{"query": "How much is it?", "format": "text"}' \
-H 'API-KEY: YOUR API KEY' \
-H 'Content-Type: application/json' \
https://backend.alli.ai/webapi/faq

Response Example

{
"result": [
{
"confidence": 0.8371959004827834,
"effective_confidence": 0.9698303406362148,
"question": "How is the product priced?",
"answer": "We have a pricing table includes a free plan.",
"id": "ClMVIjCoNDAiZDLyNWZhM1O3YTUIIKZjPPRcER=="
},
{
"confidence": 0.6119840535714456,
"effective_confidence": 0.7738889000171243,
"question": "Do you have a pricing table?",
"answer": "Yes we do.",
"id": "RkFROjVmNDAwZDMyNWZhM2Y4YTA1ZDZjNWUwMQ=="
},
{
"confidence": 0.5593920101123455,
"effective_confidence": 0.5593920101123455,
"question": "How do you describe the product?",
"answer": "We have multiple SaaS products being serviced.",
"id": "MpKFOeMeOIIwZDMyNWZhM5Y1YTA8RRHoCERuPQ=="
}
]
}

post
Search from Documents

https://backend.alli.ai/webapi/mrc
Documents API finds an answer from your unstructured text documents even from the complex tables.
Request
Response
Request
Headers
API-KEY
required
string
Your API key can be found on your dashboard Settings menu, under the General tab.
Query Parameters
query
required
string
This is a query string.
hashtags
optional
array
Documents you uploaded on the dashboard have hashtags. You can set the search scope to these hash-tagged documents.
format
optional
string
It can be 'html' or 'text'. If it's text, the return value will be a plain text. If it's html, it will return html. If your answer contains styled html, such as different font size and color, you can use html. If you simply want to get an answer as a text, you can use the text.
Response
200: OK
You will get the result as the following JSON format. answer: It's the answer extracted from uploaded documents in the dashboard. answer_hash: This is used to identify the answer to give or cancel feedback. confidence: It shows the confidence value from AI model. Shown as a number value between 0 and 1. effective_confidence: When you provide feedback to the query result, it automatically trains the AI model. Effective confidence is the adjusted score with these users' and agents' feedback. Shown as a number value between 0 and 1. document_id: The document's ID where the answer is extracted from. document_name: The document's name where the answer is extracted from. The number of search results and the threshold follows your dashboard setting. Please check your setting in Documents > Settings.
{"result":
[
{
"answer": "ANSWER_1",
"answer_hash": "ANSWER_HASH_1",
"confidence": CONFIDENCE_1,
"effective_confidence": EFFECTIVE_CONFIDENCE_1,
"document_id": "DOCUMENT_ID_1",
"document_name" "DOCUMENT_NAME_1"
}, ...
]
}

Request Example

Please replace YOUR_API_KEY to your one in the example below. Please see getting-api-key section.

curl -d '{
"query": "can I disclose the composite ratings?",
"hashtags": ["wiki"],
"format": "text"}' \
-H 'API-KEY: YOUR API KEY' \
-H 'Content-Type: application/json' \
https://backend.alli.ai/webapi/mrc

Response Example

{"result":
[
{
"answer": "an institution’s board of directors and senior management",
"answer_hash": "8430cf3b9af628abc1bb063802db39be",
"confidence": 0.9998937845230103,
"effective_confidence": 1,
"document_id": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U=",
"document_name": "Policy document 1.docx"
},
{
"answer": "banks cannot, except in very limited circumstances",
"answer_hash": "d849a49662a4f21df51de24d06196547",
"confidence": 0.9998629689216614,
"effective_confidence": 0.9998629689216614,
"document_id": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U=",
"document_name": "Bank policy 2020.pdf"
}
]
}

get
Q&A Feedbacks

https://backend.alli.ai/webapi/faq_feedbacks
This API lets you get the list of feedbacks given to Q&A pairs for each search query.
Request
Response
Request
Headers
API-KEY
required
string
Your API key can be found on your dashboard Settings menu, under the General tab.
Query Parameters
offset
optional
number
offset allows you to specify the ranking number of the first item on the page.
limit
optional
number
limit allows you to set the number of objects returned on one page. The maximum value is 100.
Response
200: OK
You will get the result as the following JSON format. query: It's the search query that has feedback for Q&A search results. feedbacks: It contains detailed feedback information for the query, faq_id and postive. faq_id: The Q&A pair's ID that has the feedback information. positive: true or false. true indicates that the Q&A pair has positive feedback upon the search, and false indicates negative feedback. count: The total number of feedbacks listed.
{
"result": [
{
"query": "QUERY_1",
"feedbacks": [
{
"faq_id": "FAQ_ID_1_1",
"positive": true or false
}, ...
]
}, ...
],
"count": COUNT_1
}

Request Example

Please replace YOUR_API_KEY to your one in the example below. Please see getting-api-key section to get the api key.

curl -X GET \
-d '{"offset": 0, "limit": 10}' \
-H "API-KEY: YOUR API KEY" \
https://backend.alli.ai/webapi/faq_feedbacks

Response Example

{
"result": [
{
"query": "where is the office?",
"feedbacks": [
{
"faq_id": "RkFROjVmNDA1MWVkMTFmOWJjMTJjOGUwMTg5YQ==",
"positive": true
},
{
"faq_id": "RkFROjVmNDA1MWVkMTFmOWJjMTJjOGUwMThhNA==",
"positive": false
},
{
"faq_id": "RkFROjVmNDA1MWVjMTFmOWJjMTJjOGUwMTgyYw==",
"positive": true
}
]
},
{
"query": "Are you funded?",
"feedbacks": [
{
"faq_id": "RkFROjVmNDA1MWVjMTFmOWJjMTJjOGUwMTgyNw==",
"positive": true
}
]
}
],
"count": 4
}

post
Q&A Feedback

https://backend.alli.ai/webapi/faq_feedback
This API lets you give or cancel feedback given to a Q&A pair for a search query.
Request
Response
Request
Headers
API-KEY
required
string
Your API key can be found on your dashboard Settings menu, under the General tab.
Query Parameters
query
required
string
The query you want to give or cancel feedback for, toward the FAQ.
id
required
string
The ID for the FAQ you want to give or cancel feedback for the query. It is created whenever a Q&A search happens and bound to the query and the Q&A pair. It can be retrieved using the Q&A API above.
isPositive
required
boolean
When the value is true, positive feedback is given to the Q&A for the query. When it's false, negative feedback is given. When it's null, it cancels the feedback.
Response
200: OK
You will get the result as the following JSON format. id: The ID for the FAQ you want to give or cancel feedback for the query. It's the same one you used for the request. positiveCount: The total number of positive feedbacks after the request is processed. negativeCount: The total number of negative feedbacks after the request is processed.
{
"errors": null,
"result": {
"faq": {
"id": "ID_1"
},
"agentFeedback": {
"positiveCount": NUMBER,
"negativeCount": NUMBER
}
}
}

Request Example

Please replace YOUR_API_KEY to your one in the example below. Please see getting-api-key section to get the api key.

Please replace Q&A_ID accordingly. About getting Q&A_ID, please take a look at Search from Q&A or Q&A Feedbacks section. It's id in Response Example of Search from Q&A section, or faq_id in Response Example of Q&A Feedbacks.

curl https://backend.alli.ai/webapi/faq_feedback \
-d '{"query": "where are you?",
"id": "Q&A_ID",
"isPositive": true}' \
-H "API-KEY: YOUR API KEY" \
-H "Content-Type: application/json"

Response Example

{
"errors": null,
"result": {
"faq": {
"id": "RkFROjVmNDA1MWVjMTFmOWJjMTJjOGUwMTgyNw=="
},
"agentFeedback": {
"positiveCount": 3,
"negativeCount": 1
}
}
}

get
Q&A Candidates

https://backend.alli.ai/webapi/faq_candidates
Using this API, you can get the list of unanswered questions from the customers what's called Candidates.
Request
Response
Request
Headers
API-KEY
required
string
Your API key can be found on your dashboard Settings menu, under the General tab.
Query Parameters
hashtags
optional
array
Hashtag array if you want to limit the search scope to the given hashtags
searchTerm
optional
string
Search query to filter the candidates to see.
order
optional
string
How to order the candidates. You can use ATTRIBUTE_[DESC or ASC] format. ATTRIBUTE can be FREQUENCY or CREATED_AT.
state
optional
string
Status of the candidates to see. It can be ALL or ACTIVE or ARCHIVED.
offset
optional
number
offset allows you to specify the ranking number of the first item on the page.
limit
optional
number
limit allows you to set the number of objects returned on one page. The maximum value is 100.
Response
200: OK
You will get the result as the following JSON format. count: The total number of candidates. id: The ID of the extracted answer to the unanswered question. Whenever there is a new unanswered question registered, Alli tries to extract and add an answer from uploaded documents automatically. frequency: Sum of all the frequency numbers under the questions. textAnswer: The answer extracted from the uploaded documents for the question. state: The status of the candidate. ACTIVE if the candidate is not added to the Q&A database yet. ARCHIVED if the candidate is added to the Q&A database. createdAt: The timestamp of when the candidate was created. questions: Multiple similar questions can have the same answer. Information about all the questions for the answer is under here. id (under questions): The ID of the unanswered question from customers. question (under questions): The unanswered question from customers. frequency (under questions): How many times the question was asked by customers. id (under history): The ID of the history information of the unanswered question. The history is the customers' log when the question was asked.
{
"count": NUMBER,
"result": [
{
"id": "ID_ANSWER_1",
"frequency": 1,
"textAnswer": "ANSWER_1",
"state": "ACTIVE",
"createdAt": NUMBER,
"questions": [
{
"id": "ID_QUESTION_1",
"question": "QUESTION_1",
"frequency": 1,
"history": {
"id": "ID_HISTORY_1"
}
}, ...
]
}, ...
],
"errors": null
}

Request Example

Please replace YOUR_API_KEY to your one in the example below. To get the api key, please see getting-api-key section.

curl -X GET \
-d '{ "hashtags": ["wiki"],
"searchTerm": "user",
"order": "FREQUENCY_DESC",
"state": "ALL",
"offset": 0,
"limit": 10}' \
-H "API-KEY: YOUR API KEY" \
https://backend.alli.ai/webapi/faq_candidates

Response Example

{
"count": 2,
"result": [
{
"id": "RkFRQ2FuZGlkYXRlOjVlYjA3OGU5MGFmZmMyM2QxZjc4ZTMzMQ==",
"frequency": 1,
"textAnswer": "This is how to use it, A from Z.\n— From User Guide.pdf",
"state": "ACTIVE",
"createdAt": 1588623593321,
"questions": [
{
"id": "RkFRQ2FuZGlkYXRlUXVlc3Rpb246NWViMDc4ZTkwYWZmYzIzZDFmNzhlMzMw",
"question": "User manual?",
"frequency": 1,
"history": {
"id": "Q29udmVyc2F0aW9uOjVlYjA3OGI2NWUyMTJlMTMzZDM4NDAzOA=="
}
}
]
},
{
"id": "RkFRQ2FuZGlkYXRlOjVlOWEzZWI2MmZlOTFkMzIwYjE2YWQyOQ==",
"frequency": 1,
"textAnswer": "You can cancel the policy in 15 days\n— From UserPolicy.pdf",
"state": "ACTIVE",
"createdAt": 1587166902114,
"questions": [
{
"id": "RkFRQ2FuZGlkYXRlUXVlc3Rpb246NWU5YTNlYjYyZmU5MWQzMjBiMTZhZDI4",
"question": "Can I cancel?",
"frequency": 1,
"history": {
"id": "Q29udmVyc2F0aW9uOjVlOWEzZDliNjU5YmM2NTEyMTk5MDQ3Ng=="
}
}
]
}
],
"errors": null
}

get
Documents Feedbacks

https://backend.alli.ai/webapi/mrc_feedbacks
This API lets you get the list of feedbacks given to Document search results (AI-extracted answers from uploaded documents) for each search query.
Request
Response
Request
Headers
API_KEY
required
string
Your API key can be found on your dashboard Settings menu, under the General tab.
Query Parameters
offset
optional
number
offset allows you to specify the ranking number of the first item on the page.
limit
optional
number
limit allows you to set the number of objects returned on one page. The maximum value is 100.
Response
200: OK
You will get the result as the following JSON format. query: The search query for the extracted answer. document_id: The ID of the document where the answer was extracted from. answer: The answer part extracted from the document for the query. answer_hash: The ID for the answer part extracted from the document for the query. It is created whenever a Documents search happens and bound to the query and the answer pair. It's the same value from the POST Documents API above. positive: true or false. true indicates that the extracted answer has positive feedback upon the search, and false indicates negative feedback. count: The total number of feedbacks listed.
{
"result": [
{
"query": "QUERY_1",
"feedbacks": [
{
"document_id": "DOCUMENT_ID_1",
"answer": "ANSWER_1",
"answer_hash": "ANSWER_HASH_1",
"positive": true or false
}, ...
]
}
],
"count": NUMBER
}

Request Example

Please replace YOUR_API_KEY to your one in the example below. To get the api key, please see getting-api-key section.

curl -X GET \
-d '{"offset": 0, "limit": 10}' \
-H "API-KEY: YOUR API KEY" \
https://backend.alli.ai/webapi/mrc_feedbacks

Response Example

{
"result": [
{
"query": "cancel the policy",
"feedbacks": [
{
"document_id": "S25vd2xlZGdlQmFzZTo1ZWM1YmJiZTczNmUxNmM0NDRjZDI2ZGM=",
"answer": "You can cancel the policy in 30 days.",
"answer_hash": "44094c4a281484daadf28e67a4745747",
"positive": true
},
{
"document_id": "S25vd2xlZGdlQmFzZTo1ZWM1YmJiZTczNmUxNmM0NDRjZDI2ZGM=",
"answer": "This is how you enroll the policy.",
"answer_hash": "296ffa9691166c583b00365fb6839a06",
"positive": false
},
{
"document_id": "S25vd2xlZGdlQmFzZTo1ZWM1YmJiZTczNmUxNmM0NDRjZDI2ZGM=",
"answer": "You cannot get refunded upon cancelation after 30 days.",
"answer_hash": "48e5273910c913dbf0fc08482f7cd22c",
"positive": true
}
]
}
],
"count": 3
}

post
Documents Search Feedback

https://backend.alli.ai/webapi/mrc_feedback
This API lets you give or cancel feedback given to a Document search result for a search query.
Request
Response
Request
Headers
API-KEY
required
string
Your API key can be found on your dashboard Settings menu, under the General tab.
Query Parameters
query
required
string
The query you want to give or cancel feedback for, toward the extracted search result.
id
required
string
The ID for the document where the answer was extracted from.
answerHash
required
string
The ID of the Document search result you want to give or cancel feedback for the query. It is created whenever a Documents search happens and bound to the query and the answer pair. It can be retrieved using the Documents API above.
isPositive
required
boolean
When the value is true, positive feedback is given to the extracted answer for the query. When it's false, negative feedback is given. When it's null, it cancels the feedback.
Response
200: OK
You will get the result as the following JSON format. positiveCount: The total number of positive feedbacks after the request is processed. negativeCount: The total number of negative feedbacks after the request is processed.
{
"errors": null,
"result": {
"agentFeedback": {
"positiveCount": NUMBER,
"negativeCount": NUMBER
}
}
}

Request Example

Please replace YOUR_API_KEY to your one in the example below. To get the api key, please see getting-api-key section. Please replace DOCUMENT_ID and ANSWER_HASH accordingly. About getting document id and answer hash, please take a look at Search from Documents or Documents Feedbacks section.

curl https://backend.alli.ai/webapi/mrc_feedback \
-d '{"query": "How to cancel the policy?",
"id": "DOCUMENT_ID",
"answerHash": "ANSWER_HASH",
"isPositive": true}' \
-H "Content-Type: application/json" \
-H "API-KEY: YOUR_API_KEY"

Response Example

{
"errors": null,
"result": {
"agentFeedback": {
"positiveCount": 2,
"negativeCount": 1
}
}
}