Cognitive Search API

Cognitive Search API makes it possible for the system to read, infer meaning, and deliver precise answers from large sets of documents 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 the API KEY

Please provide your API key in the request header API-KEY. Your API key can be found in 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 in your dashboard Settings menu, under the General tab.
Body Parameters
query
optional
string
This is a query string.
format
optional
string
html or text. If it's text, the return value will be in 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 with 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 that 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 would 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 and even from complex tables.
Request
Response
Request
Headers
API-KEY
required
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Body Parameters
query
required
string
This is a query string.
hashtags
optional
array
Documents you uploaded to 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 in 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 with 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 in your dashboard Settings menu, under the General tab.
Body Parameters
offset
optional
integer
offset allows you to specify the ranking number of the first item on the page.
limit
optional
integer
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 with 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 in your dashboard Settings menu, under the General tab.
Body 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 with 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 customers. They're called Candidates.
Request
Response
Request
Headers
API-KEY
required
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Body 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
integer
offset allows you to specify the ranking number of the first item on the page.
limit
optional
integer
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 with 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 in your dashboard Settings menu, under the General tab.
Body Parameters
offset
optional
integer
offset allows you to specify the ranking number of the first item on the page.
limit
optional
integer
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 with 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 in your dashboard Settings menu, under the General tab.
Body 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 with 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
}
}
}

post
Upload Documents

https://backend.alli.ai/webapi/upload_file
This API method allows you to upload documents for Cognitive Search.
Request
Response
Request
Headers
API-KEY
required
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Body Parameters
file
required
string
Your local file location
hashtags
optional
string
Hashtags for the uploading file
Response
200: OK
You will get the result in the following JSON format. id: The ID of the uploaded document. file_name: The filename of the uploaded document.
{"result": {"id": "DOCUMENT_ID",
"file_name": "YOUR_FILE_NAME"}}

Request Example

Please replace file=@/location/to/your_file with the location and the name of the file you are uploading, and YOUR_HASH_TAG with the hashtag you want to add to the file. Also, please replace YOUR_API_KEY with your actual API key. To get the api key, please see getting-api-key section.

curl -F 'file=@/location/to/your_file' \
-F "hashtags=YOUR_HASH_TAG" \
-H 'API-KEY: YOUR_API_KEY' https://backend.alli.ai/webapi/upload_file

Response Example

{"result":
{"id": "S25vd2xlZGdlQmFzZTo1ZWM1YmJiZTczNmUxNmM0NDRjZDI2ZGM",
"file_name": "policy.docx"}}                                                                                                             

get
Check Document Status

https://backend.alli.ai/webapi/check_file_status
Once you upload documents through API, it is converted, parsed, and embedded as vectors. This API shows the status of the process for a document being uploaded.
Request
Response
Request
Headers
API-KEY
required
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Body Parameters
id
required
string
The document id to check the status
Response
200: OK
You will get the result in the following JSON format. id: The ID of the document being checked. status: Status of the document. Please see Response Example below for possible values.
{"result":
{"id": "YOUR DOCUMENT ID",
"status": "initializing"}}

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 accordingly as well. About getting document id, please take a look at Search from Documents or the Documents Feedbacks section.

curl -X GET https://backend.alli.ai/webapi/check_file_status \
-d '{"id": "DOCUMENT_ID"}' \
-H "API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json"

Response Example

{"result":
{"id": "S25vd2xlZGdlQmFzZTo1ZWM1YmJiZTczNmUxNmM0NDRjZDI2ZGM",
"status": "initializing"}}

Status contains one of the following values.

'initializing : preparing for the processing or waiting
'converting': converting the files
'conversion_complete'
'conversion_fail'
'parsing': parsing for retrievers
'parsing_fail'
'completed': parsing and embedding are done

post
Delete Documents

https://backend.alli.ai/webapi/delete_file
This API lets you delete uploaded files.
Request
Response
Request
Headers
API-KEY
required
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Body Parameters
ids
required
array
The document IDs that you want to delete in the array format
Response
200: OK
You will get the result in the following JSON format. result: true if the deletion completes successfully. If the deletion fails, the result will be false and errors will contain an error message.
{"errors": null, "result": true}]

Request Example

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

curl -d '{"ids": ["DOCUMENT_ID"]}' \
-H "API-KEY: YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://backend.alli.ai/webapi/delete_file

Response Example

{"errors": null, "result": true}

get
List Documents

https://backend.alli.ai/webapi/knowledge_bases
This API lets you list out the uploaded documents.
Request
Response
Request
Headers
API-KEY
required
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Body Parameters
status
optional
boolean
The on/off status of the document to filter the list.
searchTerm
optional
string
Search query to filter the list.
hashtags
optional
array
Hashtag information to filter the list.
order
optional
string
The order type of the list. Please see Request Example below to find possible order types.
offset
optional
integer
offset allows you to specify the ranking number of the first item on the page.
limit
optional
integer
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 in the following JSON format. id: The ID of the listed document. fileName: The filename of the list document.
{"result":[
{"id": "DOCUMENT_ID1", "fileName": "FILE1.docx"},
{"id": "DOCUMENT_ID2", "fileName": "FILE2.docx"}, ...],
"errors": null}

Request Example

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

curl -X GET -d '{"status": true,
"offset": 0,
"limit": 10,
"order": "FILE_NAME_ASC",
"hashtags": ["policy", "insurance"]}' \
-H 'API-KEY: YOUR_API_KEY' \
https://backend.alli.ai/webapi/knowledge_bases

You can use one of the following values for the order parameter.

Value

Description

FILE_NAME_ASC

Ascending order by file name.

FILE_NAME_DESC

Descending order by file name.

TYPE_ASC

Ascending order by file type.

TYPE_DESC

Descending order by file type.

STATUS_ASC

Ascending order by on/off status.

STATUS_DESC

Descending order by on/off status.

CREATED_AT_ASC

Ascending order by uploaded date&time.

CREATED_AT_DESC

Descending order by uploaded date&time.

Response Example

{"result": [
{"id": "S23wd2xlZGdlQmRzZTo1ZmFmMzYwZ3IyYjliMTI2OTAyMWVmMDQ=",
"fileName": "policy1.docx"},
{"id": "S75vd2elZGdlQmFzZTo1ZmFlMjdhYmMx22E3MWM1MzA0NDI3ZWQ=",
"fileName": "insurance_policy.pdf"}],
"errors": null}