Answer Bot API
Answer Bot API makes it possible for the system to read, infer meaning, and deliver precise answers from large sets of documents with high accuracy.
Search from Q&A
POST https://backend.alli.ai/webapi/faq
This API lets you find the most relevant question and answer pairs from your Q&A knowledge base.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
OWN-USER-ID
string
If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard.
USER-EMAIL
string
If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.
Request Body
autoRegisterCandidates
boolean
The default value is true. When this option has set false, it'll not automatically register the query to candidates when there was no answer for the given query.
hashtagsOperator
string
Either AND or OR. Choose AND if you want each returned result to contain all hashtags. Choose OR if you want each returned result to contain at least one of the hashtags.
hashtags
array
An array of all the hashtags that you would like to appear.
maxResults
integer
The maximum number of results to be returned.
query
string
This is a query string.
format
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.
Search from Documents
POST https://backend.alli.ai/webapi/mrc
Documents API finds an answer from your unstructured text documents and even from complex tables.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
OWN-USER-ID
string
If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard.
USER-EMAIL
string
If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.
Request Body
returnPreview
boolean
If true, the html body and css will be returned for each search result. The default value is false. Note: This parameter will be deprecated on 12/9/2021 due to technical changes made to the preview feature.
autoRegisterCandidates
boolean
The default value is true. When this option has set false, it'll not automatically register the query to candidates when there was no answer for the given query.
hashtagsOperator
string
Either AND or OR. Choose AND if you want each returned result's document to have all of the specified hashtags. Choose OR if you want each returned result's document to have at least one of the specified hashtag.
maxResults
integer
Number of results to see
query
string
This is a query string.
hashtags
array
Documents you uploaded to the dashboard have hashtags. You can set the search scope to these hash-tagged documents.
format
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.
Get Single Q&A
GET https://backend.alli.ai/webapi/single_faq
This is the method to get all the details of a single Q&A.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
id
string
The id of the FAQ you are looking for.
format
string
The format of the answer value for this FAQ. Default is HTML.
Get Single Document
GET https://backend.alli.ai/webapi/single_document
This is the method to get all details of a single document.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
id
string
The id of the document.
Q&A Feedbacks
GET 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.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to only see feedbacks given by a specific agent, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
OWN-USER-ID
string
If you want to only see feedbacks given by a specific user, you can provide the user's ID here. It can be found in the Conversations menu in your dashboard.
Request Body
offset
integer
offset allows you to specify the ranking number of the first item on the page.
limit
integer
limit allows you to set the number of objects returned on one page. The maximum value is 100.
Q&A Feedback
POST 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.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
Request Body
query
string
The query you want to give or cancel feedback for, toward the Q&A.
id
string
The ID for the Q&A 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
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.
Q&A User Feedback
POST https://backend.alli.ai/webapi/faq/user_feedback
The feedback registered with the above API will be submitted as user feedback. This API registers user feedback (user feedback is what the users who use the Alli chatbot and approve or disprove of answers submit).
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
OWN-USER-ID
string
If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard.
USER-EMAIL
string
If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.
Request Body
prev
boolean
A boolean as to the previous feedback you'd assigned this query (only should be used to modify previous feedback)
positive
boolean
A boolean as to whether the feedback is positive or negative
query
string
The query that you made, that you're providing feedback for
id
string
The ID of the Q&A object you want to provide feedback (can be found in the "faq" field of the /webapi/faq response).
Upload Q&As
POST https://backend.alli.ai/webapi/upload_faq_file
You can upload multiple Q&As in the tsv, csv, xlsx, and zip format using this API.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
Request Body
file
string
Your local Q&A file location. xlsx, tsv, csv, and zip files are supported.
Add Q&A
POST https://backend.alli.ai/webapi/register_faq
You can add a new Q&A or update an existing Q&A using this API.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
Request Body
status
string
ON or OFF. When on, registered Q&A will be turned on for Q&A search.
question
string
The question part of the Q&A.
similarQuestions
array
Similar questions that has the same answer. You can add multiple similar questions.
answer
string
The answer part of the Q&A. If the same question exists in the database, this answer will replace the existing one.
hashtags
array
Hashtags added to the Q&A. You can add multiple hashtags.
memo
string
Memo on the Q&A to share with agents.
Delete Q&A
POST https://backend.alli.ai/webapi/delete_faq
You can delete a Q&A using this API.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
id
string
The ID of the Q&A you want to delete.
List Q&As
GET https://backend.alli.ai/webapi/faqs
You can list Q&As in the Knowledge Base using this API.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
searchTerm
string
Keyword search query to filter the list. You can use operators to run advanced searches. "TERM1 TERM2" for AND, "TERM1 OR TERM2" for OR, and "\"TERM\"" for exact match.
isUsed
boolean
If true, only turned-on Q&As will be listed, If false, only turned-off Q&As will.
hashtags
array
Hashtags to filter the list. You can add multiple hashtags.
hashtagsOperator
string
and or or. If it's and, hashtags filter for multiple hashtags works with AND logic. If or, OR logic.
createdByAgent
boolean
If true, the list will only include Q&As created by agents. If false, only the other Q&As will be included.
Please note that createdByAgent, answeredByMrc, autoGenerated, editedByAgent filters are mutually exclusive, and OR logic is applied if two or more of them are used.
answeredByMrc
boolean
If true, the list will only include Q&As that are the answers are automatically extracted from uploaded Documents. If false, only the other Q&As will be included.
autoGenerated
boolean
If true, the list will only include auto-generated Q&As. If false, only the other Q&As will be included.
editedByAgent
boolean
If true, the list will only include Q&A's edited by any agent after registered. If false, only the other Q&As will be included.
format
string
html or text. If your answers contain styled html, such as different font size or color, you can use html to get answers in html format. If you simply want to get answers as a text, you can use the text. The default value is html.
offset
integer
offset allows you to specify the ranking number of the first item on the page.
limit
integer
limit allows you to set the number of objects returned on one page. The maximum and the default value is 1000.
Q&A Candidates
GET https://backend.alli.ai/webapi/faq_candidates
Using this API, you can get the list of unanswered questions from customers. They're called Candidates.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
hashtags
array
Hashtag array if you want to limit the search scope to the given hashtags
searchTerm
string
Search query to filter the candidates to see. You can use operators to run advanced searches. "TERM1 TERM2" for AND, "TERM1 OR TERM2" for OR, and "\"TERM\"" for exact match.
order
string
How to order the candidates. You can use ATTRIBUTE_[DESC or ASC] format. ATTRIBUTE can be FREQUENCY or CREATED_AT.
state
string
Status of the candidates to see. It can be ALL or ACTIVE or ARCHIVED.
offset
integer
offset allows you to specify the ranking number of the first item on the page.
limit
integer
limit allows you to set the number of objects returned on one page. The maximum value is 100.
Q&A Candidates
POST https://backend.alli.ai/webapi/add_faq_candidates
Registers a new Q&A Candidate with the system.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
OWN-USER-ID
string
If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard.
USER-EMAIL
string
If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.
Request Body
queries
string
The list of all queries you would like to register
Documents Feedbacks
GET 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.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to only see feedbacks given by a specific agent, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
OWN-USER-ID
string
If you want to only see feedbacks given by a specific user, you can provide the user's ID here. It can be found in the Conversations menu in your dashboard.
Request Body
offset
integer
offset allows you to specify the ranking number of the first item on the page.
limit
integer
limit allows you to set the number of objects returned on one page. The maximum value is 100.
Documents Search Feedback
POST 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.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
Request Body
query
string
The query you want to give or cancel feedback for, toward the extracted search result.
id
string
The ID for the document where the answer was extracted from.
answerHash
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
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.
Documents Search User Feedback
POST https://backend.alli.ai/webapi/mrc/user_feedback
Provide user feedback to the Documents search result.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
OWN-USER-ID
string
If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard.
USER-EMAIL
string
If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.
Request Body
answerHash
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.
answer
string
The answer that you received to your query from this document.
id
string
The ID for the document where the answer was extracted from.
positive
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.
query
string
The query you want to give or cancel feedback for, toward the extracted search result.
Upload Documents
POST https://backend.alli.ai/webapi/upload_file
This API method allows you to upload documents for Cognitive Search. Available file formats for the upload: PDF, TXT, MS Word, PowerPoint, Excel, HTM and HTML. To upload a HTML file with linked resources, please compress in a ZIP file along with any relative linked resources before uploading.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
Request Body
file
string
Your local file location
hashtags
array
Hashtags for the uploading file
footerTitle
string
You can type in the source of the answer as a footer for search results from the uploaded file. The footer text will appear next to 'From' in search results.
footerUrl
string
You can put the URL you want to link to the footerTitle.
Upload Documents from S3
POST https://backend.alli.ai/webapi/upload_from_s3
This API lets you transfer documents stored in S3 into Cognitive Search. They will appear as Knowledge Base documents in the dashboard. Available file formats are same in the section of Upload Documents.
Headers
API-KEY
string
Your API KEY can be found in your dashboard settings menu under the General Tab. Please keep in mind that you need to have a Cognitive Search API Key.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
Request Body
footerTitle
string
You can type in the source of the answer as a footer for search results from the uploaded file. The footer text will appear next to 'From' in search results.
footerUrl
string
You can put the URL you want to link to the footerTitle.
hashtags
array
Hashtags for the document.
path
string
S3 path of the file. It should end with the file name. Don't include the bucket name
secretKey
string
Your S3 Secret Key.
accessKey
string
Your S3 Access Key.
bucket
string
Name of S3 bucket containing your file.
Check Document Status
GET 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.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
id
string
The document id to check the status
Delete Documents
POST https://backend.alli.ai/webapi/delete_file
This API lets you delete uploaded files.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
ids
array
The document IDs that you want to delete in the array format
List Documents
GET https://backend.alli.ai/webapi/knowledge_bases
This API lets you list out the uploaded documents.
Query Parameters
hashtagsSearchOperator
string
Either AND or OR, logical operator used to match multiple hashtags. Defaults to OR.
status
boolean
The on/off status of the document to filter the list.
searchTerm
string
Keyword search query to filter the list. You can use operators to run advanced searches. "TERM1 TERM2" for AND, "TERM1 OR TERM2" for OR, and "\"TERM\"" for exact match.
hashtags
array
Hashtag information to filter the list.
order
string
The order type of the list. Please see Request Example below to find possible order types.
offset
integer
offset allows you to specify the ranking number of the first item on the page.
limit
integer
limit allows you to set the number of objects returned on one page. The maximum value is 100.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Rename Documents (Knowledge Base)
POST https://backend.alli.ai/webapi/update_kb_name
This API lets you update the name for an uploaded document.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
filename
string
The new name for the specified document.
id
string
The document ID that you want to rename.
Update Documents
POST https://backend.alli.ai/webapi/update_document
This API lets you update hashtags, footer title, and footer title link for a document.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
footerTitle
string
You can type in the source of the answer as a footer for search results from the uploaded file. The footer text will appear next to 'From' in search results.
footerUrl
string
You can put the URL you want to link to the footerTitle.
hashtags
array
List of string hashtags you want to add to the document
id
string
The id of the document you want to update
Knowledge Base Toggle Status
POST https://backend.alli.ai/webapi/toggle_documents
This API lets you change the status of many documents (AKA knowledge bases) at once
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu under the General tab
Request Body
use
boolean
Whether to turn all the status of all the knowledge bases to on (True) or off (False)
ids
array
This is a list of the ids of the knowledge bases that you want to toggle.
Knowledge Base Auto Hashtag (Classification)
POST https://backend.alli.ai/webapi/kb_auto_hashtag
This API lets you get the hashtag list with classification keywords for the documents.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
ids
array
The document ids you want to retrieve auto hashtags for
Knowledge Base Auto Hashtag Feedback (Classification)
POST https://backend.alli.ai/webapi/kb_auto_hashtag_feedback
This API lets you approve or decline classification hashtags for documents
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
autoHashtagFeedbacks
array
List of JSON objects containing hashtag id/state pairs. 'state' can be one of: 'accepted', 'declined', 'suggested'
Select Answer
POST https://backend.alli.ai/webapi/faq/select_answer
This method should be used to simulate a user looking up a specific FAQ
Path Parameters
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
hashId
string
The id of the Q&A search return result
id
string
The id of the FAQ that you would like to select.
Agent Management
POST https://backend.alli.ai/webapi/agent_management
Used to create and delete agents from the project.
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
locale
string
The language setting of the account being created. Use a two-letter ISO 639-1 code.
password
string
Required when creating a new agent. Password must be valid (contain 3 out 4 following characters: lowercase, uppercase, numeric, non-alphanumeric)
deleteFlag
boolean
True if you want to delete an agent, False if you want to create
string
The email of the agent you want to create or delete
Get All Hashtags
GET https://backend.alli.ai/webapi/hashtags
Gets all hashtags from both FAQs and MRCs
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Q&A Query History
GET https://backend.alli.ai/webapi/faq_histories
Returns the past Q&A Searches that have been done, both through the REST API and the Alli dashboard.
Query Parameters
limit
integer
A limit on the number of results to show (used for pagination)
offset
integer
In the list of all results, the index from which to start listing results (used for pagination)
endDate
string
The latest date from which you want to get history (dates should be in the form YYYY-MM-DD)
startDate
string
The earliest date from which you want to get history (dates should be in the form YYYY-MM-DD)
order
string
Can either be DESC (meaning latest queries come first), or ASC (meaning earliest queries come first)
searchTerm
string
The term that should have appeared in the query
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to only see the query history of a specific agent, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
OWN-USER-ID
string
If you want to only see the query history of a specific user, you can provide the user's ID here. It can be found in the Conversations menu in your dashboard.
Documents Query History
GET https://backend.alli.ai/webapi/mrc_histories
Returns the past Documents Searches that have been done, both through the REST API and the Alli dashboard.
Query Parameters
searchTerm
string
The term that should have appeared in the query
order
string
Can either be DESC (meaning latest queries come first), or ASC (meaning earliest queries come first)
endDate
string
The latest date from which you want to get history (dates should be in the form YYYY-MM-DD)
startDate
string
The earliest date from which you want to get history (dates should be in the form YYYY-MM-DD)
limit
integer
A limit on the number of results to show (used for pagination)
offset
integer
In the list of all results, the index from which to start listing results (used for pagination)
Headers
API-KEY
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to only see the query history of a specific agent, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
OWN-USER-ID
string
If you want to only see the query history of a specific user, you can provide the user's ID here. It can be found in the Conversations menu in your dashboard.
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. Uploading the document via API is in the Upload Document section in this page.
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.
Providing Agent or User Information
For certain endpoints, you can add agent or user information in the request header to specify who makes the call.
Agent information can be provided in the request header AGENT-EMAIL. You can find your agents' email information in your dashboard Settings > Agent menu. Below is an example.
A user ID can be provided in the request header OWN-USER-ID. The user ID can be either a new one or an existing one, and if a new user ID is provided, Alli will create a new user with that ID. Any future API calls with the same OWN-USER-ID header will be considered as they're from the same user.
If you want to update the user's email address at the same time, you can provide the email address in the request header USER-EMAIL. Below is an example.
You cannot use non-ASCII characters for OWN-USER-ID. If the user ID includes any non-ASCII characters, you can encode the ID to base64 and use base64:CONVERTED_ID.
You can find saved user ID and email information in your Alli dashboard Customers menu.
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:
Search from Q&A
POST https://backend.alli.ai/webapi/faq
This API lets you find the most relevant question and answer pairs from your Q&A knowledge base.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
OWN-USER-ID
string
If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard.
USER-EMAIL
string
If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.
Request Body
autoRegisterCandidates
boolean
The default value is true. When this option has set false, it'll not automatically register the query to candidates when there was no answer for the given query.
hashtagsOperator
string
Either AND or OR. Choose AND if you want each returned result to contain all hashtags. Choose OR if you want each returned result to contain at least one of the hashtags.
hashtags
array
An array of all the hashtags that you would like to appear.
maxResults
integer
The maximum number of results to be returned.
query*
string
This is a query string.
format
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.
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.
effectiveConfidence: 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.
hashtags: Hashtags registered for the Q&A.
lastUpdatedDate: The date when the Q&A is last updated.
agentFeedback: The feedback from agents (through dashboard and REST calls) about this Q&A.
userFeedback: The feedback from users (through conversation) about this Q&A.
count: The number of suggested Q&As.
hashId: This hash id is being used when you call select_answer later.
The number of search results and the threshold follows your dashboard setting. Please check your settings in Q&A > Settings.
Request Example
Please replace YOUR_API_KEY with your one in the example below. Please see getting-api-key section.
Response Example
Search from Documents
POST https://backend.alli.ai/webapi/mrc
Documents API finds an answer from your unstructured text documents and even from complex tables.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard. The permission settings for the agent to access documents or folders are applied by sending this info.
OWN-USER-ID
string
If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard. The permission settings for non-agent users to access documents or folders are applied by sending this info.
USER-EMAIL
string
If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.
Request Body
returnPreview
boolean
If true, the html body and css for the html type preview will be returned for each search result. The default value is false.
autoRegisterCandidates
boolean
The default value is true. When this option has set false, it'll not automatically register the query to candidates when there was no answer for the given query.
hashtagsOperator
string
Either AND or OR. Choose AND if you want each returned result's document to have all of the specified hashtags. Choose OR if you want each returned result's document to have at least one of the specified hashtag.
maxResults
integer
Number of results to see
query*
string
This is a query string.
hashtags
array
Documents you uploaded to the dashboard have hashtags. You can set the search scope to these hash-tagged documents.
format
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.
returnPdfPreview
boolean
If true, the pdfPreview field will be returned for each search result. The default value is false.
returnPdfPreviewRawData
boolean
If true, the pdfPreviewRawData field will be returned for each search result. The default value is false.
sortKey
String
This is a secondary sort key where you set in Document's custom properties
sortDirection
String
This is a secondary sorting order. The value will be "asc" or "desc"
combinedHashtags
array
Documents you uploaded to the dashboard have hashtags. You can set the search scope to allow for groups of hashtags. Note: If "combinedHashtags" are used, you must keep the "hashtags" parameter empty.
combinedHashtagsOperator
string
Either AND or OR. Choose AND if you want both of the combined hashtags in the results.
Choose OR if you want at least one of the combined hashtags in the results.
You will get the result as the following JSON format:
answer: It's the answer extracted from uploaded documents in the dashboard.answerHash: This is used to identify the answer to give or cancel feedback.
answerHash: 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.
effectiveConfidence: 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.
documentId: The document's ID where the answer is extracted from.
documentName: The document's name where the answer is extracted from.hashtags: The hashtags attached to the document.
pageNo: The page number in the document where the answer was derived.
createdDate: The date when the document was uploaded.
agentFeedback: The feedback from agents (through dashboard and REST calls) about this document
userFeedback: The feedback from users about this document
body: If returnPreview is true in the request, the html body of the document search preview is displayed.
css: If returnPreview is true in the request, the css of the document search preview is displayed.
pdfPreview: If returnPdfPreview is true in the request, the URL to a PDF preview of the document with the answer highlighted is displayed. Note that the URL can be restricted using the Download IP Allowlist setting.
folder: If the answer is found from a folder under the Documents database, the folder name will be returned here.
editor: List of the agents' email who has the editor access to the documents (if they're set in the Alli dashboard).
viewer: List of the agents' email who has the viewer access to the documents. (if they're set in the Alli dashboard).
paragraphIndex: This value is needed to highlight a specific area when requesting a preview. It is used as parameters for the preview API.
The number of search results and the threshold follows your dashboard setting. Please check your setting in Documents > Settings.
Request Example (hashtags)
Please replace YOUR_API_KEY with your one in the example below. Please see getting-api-key section.
Request Example (combinedHashtags)
Please replace YOUR_API_KEY with your one in the example below. Please see getting-api-key section.
Response Example
Get Single Q&A
GET https://backend.alli.ai/webapi/single_faq
This is the method to get all the details of a single Q&A.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
id*
string
The id of the FAQ you are looking for.
format
string
The format of the answer value for this FAQ. Default is HTML.
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.
Response Example
Get Single Document
GET https://backend.alli.ai/webapi/single_document
This is the method to get all details of a single document.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
id*
string
The id of the document.
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.
Response Example
Q&A Feedbacks
GET 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.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to only see feedbacks given by a specific agent, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
OWN-USER-ID
string
If you want to only see feedbacks given by a specific user, you can provide the user's ID here. It can be found in the Conversations menu in your dashboard.
Request Body
offset
integer
offset allows you to specify the ranking number of the first item on the page.
limit
integer
limit allows you to set the number of objects returned on one page. The maximum value is 100.
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.
If you'd like to get a feedback list from a specific user, please put OWN-USER-ID in the header. If you'd like to get a feedback list from a specific agent, please put AGENT-EMAIL in the header. Without OWN-USER-ID or AGENT-EMAIL, all the feedbacks will be returned.
Response Example
Q&A Feedback
POST 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.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
Request Body
query*
string
The query you want to give or cancel feedback for, toward the Q&A.
id*
string
The ID for the Q&A 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*
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.
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.
Response Example
Q&A User Feedback
POST https://backend.alli.ai/webapi/faq/user_feedback
The feedback registered with the above API will be submitted as user feedback. This API registers user feedback (user feedback is what the users who use the Alli chatbot and approve or disprove of answers submit).
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
OWN-USER-ID
string
If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard.
USER-EMAIL
string
If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.
Request Body
prev
boolean
A boolean as to the previous feedback you'd assigned this query (only should be used to modify previous feedback)
positive*
boolean
A boolean as to whether the feedback is positive or negative
query*
string
The query that you made, that you're providing feedback for
id*
string
The ID of the Q&A object you want to provide feedback (can be found in the "faq" field of the /webapi/faq response).
analyticsHashtags
array
An array of all the hashtags that you would like to register as a scope, used in analytics by hashtag
Request Example
Response Example
Upload Q&As
POST https://backend.alli.ai/webapi/upload_faq_file
You can upload multiple Q&As in the tsv, csv, xlsx, and zip format using this API.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
Request Body
file*
string
Your local Q&A file location. xlsx, tsv, csv, and zip files are supported.
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.
Response Example
Add Q&A
POST https://backend.alli.ai/webapi/register_faq
You can add a new Q&A or update an existing Q&A using this API.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
Request Body
status
string
ON or OFF. When on, registered Q&A will be turned on for Q&A search.
question*
string
The question part of the Q&A.
similarQuestions
array
Similar questions that has the same answer. You can add multiple similar questions.
answer*
string
The answer part of the Q&A. If the same question exists in the database, this answer will replace the existing one.
hashtags
array
Hashtags added to the Q&A. You can add multiple hashtags.
memo
string
Memo on the Q&A to share with agents.
followFolderPermission
boolean
When uploading, if there is a folder to which it belongs, the permission of the folder is inherited or not inherited. (Default value: True) If not inherited, the permissions specified below are used. Unless otherwise specified, all agents and users have the privilege.
agentEditor
array
Register an agent with permission to edit the file
agentViewer
array
Register an agent with permission to view the file
userViewer
object
Register a user with permission to view the file. You can register using customer_id, customer_group. customer_id is the same as own-user-id, and customer_group's id (categoryElementsId) can be obtained through the CUSTOMER GROUP inquiry API.
allowOtherAgentsView
boolean
Agents who are not in the editor/viewer list can also view
allowOtherUsersView
boolean
Users who are not in the editor/viewer list can also view
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.
Response Example
Delete Q&A
POST https://backend.alli.ai/webapi/delete_faq
You can delete a Q&A using this API.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
id*
string
The ID of the Q&A you want to delete.
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.
Response Example
List Q&As
GET https://backend.alli.ai/webapi/faqs
You can list Q&As in the Knowledge Base using this API.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
searchTerm
string
Keyword search query to filter the list. You can use operators to run advanced searches. "TERM1 TERM2" for AND, "TERM1 OR TERM2" for OR, and "\"TERM\"" for exact match.
isUsed
boolean
If true, only turned-on Q&As will be listed, If false, only turned-off Q&As will.
hashtags
array
Hashtags to filter the list. You can add multiple hashtags.
hashtagsOperator
string
and or or. If it's and, hashtags filter for multiple hashtags works with AND logic. If or, OR logic.
createdByAgent
boolean
If true, the list will only include Q&As created by agents. If false, only the other Q&As will be included.
Please note that createdByAgent, answeredByMrc, autoGenerated, editedByAgent filters are mutually exclusive, and OR logic is applied if two or more of them are used.
answeredByMrc
boolean
If true, the list will only include Q&As that are the answers are automatically extracted from uploaded Documents. If false, only the other Q&As will be included.
autoGenerated
boolean
If true, the list will only include auto-generated Q&As. If false, only the other Q&As will be included.
editedByAgent
boolean
If true, the list will only include Q&A's edited by any agent after registered. If false, only the other Q&As will be included.
format
string
html or text. If your answers contain styled html, such as different font size or color, you can use html to get answers in html format. If you simply want to get answers as a text, you can use the text. The default value is html.
offset
integer
offset allows you to specify the ranking number of the first item on the page.
limit
integer
limit allows you to set the number of objects returned on one page. The maximum and the default value is 1000.
offset: The same offset value with the offset request parameter.
count: Total number of Q&As listed after limit is applied.
totalCount: Total number of Q&As as the result of applied filters.
id: The ID of the Q&A.
question: The question part of the Q&A.
answer: The answer part of the Q&A.
hashtags: The hashtags added on the Q&A.
userFeedback: Number of positive and negative user feedbacks. User feedbacks affects the search result for future queries.
agentFeedback: Number of positive and negative agent feedbacks. Agent feedbacks affects the search result for future queries.
lastUpdatedDate: The date when the Q&A is last updated.
createdDate: The date when the Q&A is created.
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.
Response Example
Q&A Candidates
GET https://backend.alli.ai/webapi/faq_candidates
Using this API, you can get the list of unanswered questions from customers. They're called Candidates.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
hashtags
array
Hashtag array if you want to limit the search scope to the given hashtags
searchTerm
string
Search query to filter the candidates to see. You can use operators to run advanced searches. "TERM1 TERM2" for AND, "TERM1 OR TERM2" for OR, and "\"TERM\"" for exact match.
order
string
How to order the candidates. You can use ATTRIBUTE_[DESC or ASC] format. ATTRIBUTE can be FREQUENCY or CREATED_AT.
state
string
Status of the candidates to see. It can be ALL or ACTIVE or ARCHIVED.
offset
integer
offset allows you to specify the ranking number of the first item on the page.
limit
integer
limit allows you to set the number of objects returned on one page. The maximum value is 100.
sources
array
Source array if you want to limit the search scope to the given sources. You can use SDK, QNA, DOCUMENTS and API as source.
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.
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.
Response Example
Q&A Candidates
POST https://backend.alli.ai/webapi/add_faq_candidates
Registers a new Q&A Candidate with the system.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
OWN-USER-ID
string
If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard.
USER-EMAIL
string
If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.
Request Body
queries*
string
The list of all queries you would like to register
analyticsHashtags
array
An array of all the hashtags that you would like to register as a scope, used in analytics by hashtag. Please note that these hashtags will not be registered as candidates' hashtags.
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.
Response Example
Documents Feedbacks
GET 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.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to only see feedbacks given by a specific agent, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
OWN-USER-ID
string
If you want to only see feedbacks given by a specific user, you can provide the user's ID here. It can be found in the Conversations menu in your dashboard.
Request Body
offset
integer
offset allows you to specify the ranking number of the first item on the page.
limit
integer
limit allows you to set the number of objects returned on one page. The maximum value is 100.
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.
If you'd like to get a feedback list from a specific user, please put OWN-USER-ID in the header. If you'd like to get a feedback list from a specific agent, please put AGENT-EMAIL in the header.
Response Example
Documents Search Feedback
POST 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.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
Request Body
query*
string
The query you want to give or cancel feedback for, toward the extracted search result.
id*
string
The ID for the document where the answer was extracted from.
answerHash*
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*
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.
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.
Response Example
Documents Search User Feedback
POST https://backend.alli.ai/webapi/mrc/user_feedback
Provide user feedback to the Documents search result.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
OWN-USER-ID
string
If you want to specify a user who makes this API call, you can provide the user's ID here. It can be a new one or be found in the Conversations menu in your dashboard.
USER-EMAIL
string
If you want to update the user's email when using OWN-USER-ID, you can provide the new email address here.
Request Body
answerHash*
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.
id*
string
The ID for the document where the answer was extracted from.
positive*
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.
query*
string
The query you want to give or cancel feedback for, toward the extracted search result.
analyticsHashtags
array
An array of all the hashtags that you would like to register as a scope, used in analytics by hashtag
Request Example
Response Example
Document Upload APIs
POST https://backend.alli.ai/webapi/upload_file
This API allows you to upload documents from your local storage for use in Cognitive Search. Upload PDF, TXT, MS Word, PowerPoint, Excel, HTM, and HTML files. To upload an HTML file with a linked resource, and upload the included ZIP file.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
Request Body
file*
string
The local location of the file to upload.
hashtags
array
Hashtags for the document.
footerTitle
string
You can type in the source of the answer as a footer for search results from the uploaded file. The footer text will appear next to 'From' in search results.
footerUrl
string
You can put the URL you want to link to the footerTitle.
folder
string
You can assign a folder to upload the documents to.
followFolderPermission
boolean
When it's true (default), the permission to access the file will follow the folder's permission settings. When it's false, the file uses separate permission settings defined by below two parameters. If the below parameters are not given, any agent gets full permission to the file.
agentsEditor
array
The agents who have editor permission to the file.
agentsViewer
array
The agents who have viewer permission to the file.
userViewer
object
Register a user with permission to view the file. You can register using customer_id, customer_group. customer_id is the same as own-user-id, and customer_group's id (categoryElementsId) can be obtained through the CUSTOMER GROUP inquiry API.
allowOtherAgentsView
boolean
Agents who are not in the editor/viewer list can also view.
allowOtherUsersView
boolean
Users who are not in the editor/viewer list can also view.
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.
Response Example
Upload Documents from S3
POST https://backend.alli.ai/webapi/upload_from_s3
This API lets you transfer documents stored in S3 into Cognitive Search. They will appear as Knowledge Base documents in the dashboard. Available file formats are same in the section of Upload Documents.
Headers
API-KEY*
string
Your API KEY can be found in your dashboard settings menu under the General Tab. Please keep in mind that you need to have a Cognitive Search API Key.
AGENT-EMAIL
string
If you want to specify an agent who makes this API call, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
Request Body
footerTitle
string
You can type in the source of the answer as a footer for search results from the uploaded file. The footer text will appear next to 'From' in search results.
footerUrl
string
You can put the URL you want to link to the footerTitle.
hashtags
array
Hashtags for the document.
path*
string
S3 path of the file. It should end with the file name. Don't include the bucket name
secretKey
string
Your S3 Secret Key.
accessKey
string
Your S3 Access Key.
bucket
string
Name of S3 bucket containing your file.
folder
string
You can assign a folder to upload the documents to.
followFolderPermission
boolean
When it's true (default), the permission to access the file will follow the folder's permission settings. When it's false, the file uses separate permission settings defined by below two parameters. If the below parameters are not given, any agent gets full permission to the file.
agentsEditor
array
The agents who have editor permission to the file.
agentsViewer
array
The agents who have viewer permission to the file.
userViewer
string
Register a user with permission to view the file. You can register using customer_id, customer_group. customer_id is the same as own-user-id, and customer_group's id (categoryElementsId) can be obtained through the CUSTOMER GROUP inquiry API.
allowOtherAgentsView
boolean
Agents who are not in the editor/viewer list can also view.
allowOtherUsersView
boolean
Users who are not in the editor/viewer list can also view.
id: The id for the transferred document.
fileName: The filename of the transferred document.
hashtags: The array of hashtags added to the uploaded document.
footer: The footer (source) info added to the uploaded document. It can be the default one or the one specified by footerTitle and footerUrl parameters.
folder: If the answer is found from a folder under the Documents database, the folder name will be returned here.
editor: List of the agents' email who has the editor access to the documents.
viewer: List of the agents' email who has the viewer access to the documents.
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.
Response Example
Check Document Status
GET 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.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
id*
string
The document id to check the status
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.
Response Example
Status contains one of the following values.
Delete Documents
POST https://backend.alli.ai/webapi/delete_file
This API lets you delete uploaded files.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
ids*
array
The document IDs that you want to delete in the array format
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.
Response Example
Preview Documents
GET https://backend.alli.ai/webapi/knowledge_base_preview
This API lets you preview the uploaded documents.
Query Parameters
id
string
The document ID that you want to preview
pageNo
string
Pages of the document you want to preview
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
id: The ID of the listed document.
fileName: The filename of the list document.
hashtags: The hashtags added on the document.
autoHashtags : The automatically generated hashtags added to the document.
downloadUrl: The URL to download the document.
footerUrl: The URL that's included in the document's footer.
folder: If the answer is found from a folder under the Documents database, the folder name will be returned here.
editor: List of the agents' email who has the editor access to the documents.
viewer: List of the agents' email who has the viewer access to the documents.
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.
Response Example
Please note that if there is an error, such as a pageNo that does not exist, the response will return null for "pdf" within the "result".
List Documents
GET https://backend.alli.ai/webapi/knowledge_bases
This API lets you list out the uploaded documents.
Query Parameters
hashtagsSearchOperator
string
Either AND or OR, logical operator used to match multiple hashtags. Defaults to OR.
status
boolean
The on/off status of the document to filter the list.
searchTerm
string
Keyword search query to filter the list. You can use operators to run advanced searches. "TERM1 TERM2" for AND, "TERM1 OR TERM2" for OR, and "\"TERM\"" for exact match.
hashtags
array
Hashtag information to filter the list.
combinedHashtags
array
Documents you uploaded to the dashboard have hashtags. You can set the search scope to allow for groups of hashtags.
Note: If "combinedHashtags" are used, you must keep the "hashtags" parameter empty.
combinedHashtagsOperator
string
Either AND or OR. Choose AND if you want both of the combined hashtags in the results.
Choose OR if you want at least one of the combined hashtags in the results.
order
string
The order type of the list. Please see Request Example below to find possible order types.
offset
integer
offset allows you to specify the ranking number of the first item on the page.
limit
integer
limit allows you to set the number of objects returned on one page. The maximum value is 100.
sortKey
string
This is a document custom property key that is used for a secondary sorting key. A primary sort is done by the order parameter
sortDirection
string
This is a secondary sorting order. The value will be "asc" or "desc"
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
id: The ID of the listed document.
fileName: The filename of the list document.
hashtags: The hashtags added on the document.
autoHashtags : The automatically generated hashtags added to the document.
downloadUrl: The URL to download the document.
footerUrl: The URL that's included in the document's footer.
folder: If the answer is found from a folder under the Documents database, the folder name will be returned here.
editor: List of the agents' email who has the editor access to the documents.
viewer: List of the agents' email who has the viewer access to the documents.
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.
You can use one of the following values for the order parameter.
SCORE
Descending order by score. It's a default value if a searchTerm value exists.
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
List Documents
POST https://backend.alli.ai/webapi/knowledge_bases
This API lets you list out the uploaded documents.
Query Parameters
hashtagsSearchOperator
string
Either AND or OR, logical operator used to match multiple hashtags. Defaults to OR.
status
boolean
The on/off status of the document to filter the list.
searchTerm
string
Keyword search query to filter the list. You can use operators to run advanced searches. "TERM1 TERM2" for AND, "TERM1 OR TERM2" for OR, and "\"TERM\"" for exact match.
hashtags
array
Hashtag information to filter the list.
combinedHashtags
array
Documents you uploaded to the dashboard have hashtags. You can set the search scope to allow for groups of hashtags.
Note: If "combinedHashtags" are used, you must keep the "hashtags" parameter empty.
combinedHashtagsOperator
string
Either AND or OR. Choose AND if you want both of the combined hashtags in the results.
Choose OR if you want at least one of the combined hashtags in the results.
order
string
The order type of the list. Please see Request Example below to find possible order types.
offset
integer
offset allows you to specify the ranking number of the first item on the page.
limit
integer
limit allows you to set the number of objects returned on one page. The maximum value is 100.
sortKey
string
This is a document custom property key that is used for a secondary sorting key. A primary sort is done by the order parameter
sortDirection
string
This is a secondary sorting order. The value will be "asc" or "desc"
excludingHashtagsOperator
string
and or or. If it's and, 'excludingHashtags' filter for multiple hashtags works with AND logic. If or, OR logic.
excludingHashtags
array
Hashtags to filter the list. Only the documents without these hashtags are searched. You can add multiple hashtags separated by a comma.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
id: The ID of the listed document.
fileName: The filename of the list document.
hashtags: The hashtags added on the document.
autoHashtags : The automatically generated hashtags added to the document.
downloadUrl: The URL to download the document.
footerUrl: The URL that's included in the document's footer.
folder: If the answer is found from a folder under the Documents database, the folder name will be returned here.
editor: List of the agents' email who has the editor access to the documents.
viewer: List of the agents' email who has the viewer access to the documents.
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.
You can use one of the following values for the order parameter.
SCORE
Descending order by score. It's a default value if a searchTerm value exists.
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
Document (Knowledge Base) Title Search
GET https://backend.alli.ai/webapi/search_document_by_title
This API lets you search the knowledge bases by title. This search is done by a trained vector not by a keyword. Please make sure you trained a model in Knowledge Base > Document menu.
Query Parameters
query*
string
Search Query
hashtags
array
Hashtags to filter the list. Only the documents with these hashtags are searched. You can add multiple hashtags separated by a comma.
hashtagsOperator
string
and or or. If it's and, 'hashtags' filter for multiple hashtags works with AND logic. If or, OR logic.
excludingHashtags
array
Hashtags to filter the list. Only the documents without these hashtags are searched. You can add multiple hashtags separated by a comma.
excludingHashtagsOperator
string
and or or. If it's and, 'excludingHashtags' filter for multiple hashtags works with AND logic. If or, OR logic.
combinedHashtags
array
Documents you uploaded to the dashboard have hashtags. You can set the search scope to allow for groups of hashtags.
Note: If "combinedHashtags" are used, you must keep the "hashtags" parameter empty.
combinedHashtagsOperator
string
Either AND or OR. Choose AND if you want both of the combined hashtags in the results.
Choose OR if you want at least one of the combined hashtags in the results.
order
string
Please take a look at the order in List Documents API. Default is descending order by score
limit
integer
limit allows you to set the number of objects returned on one page. The maximum value is 100
offset
integer
offset allows you to specify the ranking number of the first item on the page.
useVector
boolean
true / false or it can be omitted. Default is omission.
If this is true, it returns the result only by using a trained vector for the document title.
if this is false, it returns the result only by keyword based search.
if this parameter is omitted, the result will be the combination of the vector and the keyword search.
sortKey
string
This is a document custom property key that is used for a secondary sorting key. A primary sort is done by the order parameter
sortDirection
string
This is a secondary sorting order. The value will be "asc" or "desc"
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
id: The document's ID.
fileName: The document's filename.
hashtags: Hashtags added to the document.
score: The confidence score of the search result.
folder: If the answer is found from a folder under the Documents database, the folder name will be returned here.
editor: List of the agents' email who has the editor access to the documents.
viewer: List of the agents' email who has the viewer access to the documents.
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.
Response Example
Rename Documents (Knowledge Base)
POST https://backend.alli.ai/webapi/update_kb_name
This API lets you update the name for an uploaded document.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
filename*
string
The new name for the specified document.
id*
string
The document ID that you want to rename.
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.
Response Example
Update Documents
POST https://backend.alli.ai/webapi/update_document
This API lets you update hashtags, footer title, and footer title link for a document.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
footerTitle
string
You can type in the source of the answer as a footer for search results from the uploaded file. The footer text will appear next to 'From' in search results.
footerUrl
string
You can put the URL you want to link to the footerTitle.
hashtags
array
List of hashtags you want to update to the document. Prior hashtags will be removed and replaced with the new array of hashtags.
id*
string
The id of the document you want to update
folder
string
You can assign a folder to upload the documents to.
followFolderPermission
boolean
When it's true (default), the permission to access the file will follow the folder's permission settings. When it's false, the file uses separate permission settings defined by below two parameters. If the below parameters are not given, any agent gets full permission to the file.
agentsEditor
array
The agents who have editor permission to the file.
agentsViewer
array
The agents who have viewer permission to the file.
properties
json
key value pair of custom properties for this document. These properties can be used as a sorting criteria for the "Search from Documents"
userViewer
object
Register a user with permission to view the file. You can register using customer_id, customer_group. customer_id is the same as own-user-id, and customer_group's id (categoryElementsId) can be obtained through the CUSTOMER GROUP inquiry API.
allowOtherAgentsView
boolean
Agents who are not in the editor/viewer list can also view.
allowOtherUsersView
boolean
Users who are not in the editor/viewer list can also view.
id: The id of the document to which the hashtags correspond.
hashtags: Hashtags attached to the document after update.
footer: The footer (source) info added to the uploaded document. It can be the default one or the one specified by footerTitle and footerUrl parameters.
folder: If the answer is found from a folder under the Documents database, the folder name will be returned here.
editor: List of the agents' email who has the editor access to the documents.
viewer: List of the agents' email who has the viewer access to the documents.
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.
Response Example
Create/Read/Update/Delete Custom Properties
Create Custom Properties
If you'd like to create custom properties to a document, please use properties parameter.
Then, you will receive the following response.
Get Custom Properties
If you'd like to get the list of custom properties of a document, you can use "Get Single Document" API.
Update Customer Properties
If you'd like to update custom properties of a document, simply update the value of the property. Please be noted if you don't send the existing key for a property, it'll be deleted.
Then, you will receive the following response.
Delete Custom Properties
If you'd like to delete all of some of custom properties of a document, you can pass null value to a specific property.
Then, you will receive the following response.
Knowledge Base Toggle Status
POST https://backend.alli.ai/webapi/toggle_documents
This API lets you change the status of many documents (AKA knowledge bases) at once
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu under the General tab
Request Body
use*
boolean
Whether to turn all the status of all the knowledge bases to on (True) or off (False)
ids*
array
This is a list of the ids of the knowledge bases that you want to toggle.
Request Example
Response Example
Knowledge Base Auto Hashtag (Classification)
POST https://backend.alli.ai/webapi/kb_auto_hashtag
This API lets you get the hashtag list with classification keywords for the documents.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
ids*
array
The document ids you want to retrieve auto hashtags for
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.
Response Example
Knowledge Base Auto Hashtag Feedback (Classification)
POST https://backend.alli.ai/webapi/kb_auto_hashtag_feedback
This API lets you approve or decline classification hashtags for documents
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
autoHashtagFeedbacks*
array
List of JSON objects containing hashtag id/state pairs. 'state' can be one of: 'accepted', 'declined', 'suggested'
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 HASHTAG_ID accordingly as well. About getting hashtag ids, please take a look at Knowledge Base Auto Hashtag (Classification) section.
Response Example
Select Answer
POST https://backend.alli.ai/webapi/faq/select_answer
This method should be used to simulate a user looking up a specific FAQ
Path Parameters
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
hashId*
string
The id of the Q&A search return result
id*
string
The id of the FAQ that you would like to select.
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 FAQ_ID accordingly as well. About getting FAQ ids, please take a look at Search from Q&A section.
Response Example
Agent Management
POST https://backend.alli.ai/webapi/agent_management
Used to create and delete agents from the project.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
locale
string
The language setting of the account being created. Use a two-letter ISO 639-1 code.
password
string
Required when creating a new agent. Password must be valid (contain 3 out 4 following characters: lowercase, uppercase, numeric, non-alphanumeric)
deleteFlag*
boolean
True if you want to delete an agent, False if you want to create
email*
string
The email of the agent you want to create or delete
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.
Response Example
Get All Hashtags
GET https://backend.alli.ai/webapi/hashtags
Gets all hashtags from both FAQs and MRCs
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
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.
Response Example
Q&A Query History
GET https://backend.alli.ai/webapi/faq_histories
Returns the past Q&A Searches that have been done, both through the REST API and the Alli dashboard.
Query Parameters
limit
integer
A limit on the number of results to show (used for pagination)
offset
integer
In the list of all results, the index from which to start listing results (used for pagination)
endDate
string
The latest date from which you want to get history (dates should be in the form YYYY-MM-DD)
startDate
string
The earliest date from which you want to get history (dates should be in the form YYYY-MM-DD)
order
string
Can either be DESC (meaning latest queries come first), or ASC (meaning earliest queries come first)
searchTerm
string
The term that should have appeared in the query
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to only see the query history of a specific agent, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
OWN-USER-ID
string
If you want to only see the query history of a specific user, you can provide the user's ID here. It can be found in the Conversations menu in your dashboard.
Request Example
Response Example
Documents Query History
GET https://backend.alli.ai/webapi/mrc_histories
Returns the past Documents Searches that have been done, both through the REST API and the Alli dashboard.
Query Parameters
searchTerm
string
The term that should have appeared in the query
order
string
Can either be DESC (meaning latest queries come first), or ASC (meaning earliest queries come first)
endDate
string
The latest date from which you want to get history (dates should be in the form YYYY-MM-DD)
startDate
string
The earliest date from which you want to get history (dates should be in the form YYYY-MM-DD)
limit
integer
A limit on the number of results to show (used for pagination)
offset
integer
In the list of all results, the index from which to start listing results (used for pagination)
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
AGENT-EMAIL
string
If you want to only see the query history of a specific agent, you can provide the agent's email address here. It can be found under Settings > Agents in your dashboard.
OWN-USER-ID
string
If you want to only see the query history of a specific user, you can provide the user's ID here. It can be found in the Conversations menu in your dashboard.
Request Example
Response Example
View User Information
GET https://backend.alli.ai/webapi/users
Check the OWN-USER-ID, CUSTOMER GROUP, and email of a user
Query Parameters
customer_group
string
The name of the CUSTOMER GROUP to filter on when looking up users. You can obtain this value by using the CUSTOMER GROUP Query API call.
offset
string
Determines the position of the first item to be displayed on the page. Defaults to 0.
limit
string
Determines how many items to display on the page. The default is 10 and the maximum is 1000.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Example
Response Example
View Individual User Information
GET https://backend.alli.ai/webapi/user/{OWN-USER-ID}
Check the OWN-USER-ID, CUSTOMER GROUP, and email of a user
Query Parameters
OWN-USER-ID*
string
The user's ID. You can obtain the ID of all users by using the API to retrieve user information.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Example
Be sure to replace {OWN-USER-ID} with your user's ID. You can obtain the ID of all users using the API to retrieve user information
Response Example
Update User Information
POST https://backend.alli.aiwebapi/user/{OWN-USER-ID}/customer_variables/{variableName}
Update the OWN-USER-ID and CUSTOMER GROUP of individual users
Query Parameters
OWN-USER-ID*
string
The user's ID. You can obtain the ID of all users by using the API to retrieve user information.
variableName*
string
This is what you want to update. Only 'CUSTOMER_GROUP' or 'CUSTOMER_ID' can be entered.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
id*
string
ID of 'CUSTOMER_GROUP' or 'CUSTOMER_ID' to change.
Request Example
Be sure to replace {variableName} and {id} with your corresponding values. Enter the item you want to update ("CUSTOMER_GROUP" or "CUSTOMER_ID”) in {variableName}, and enter the id value you want to change in {id}. You can check the ID you need through the API for retrieving user information.
Response Example
CUSTOMER GROUP Query
GET https://backend.alli.ai/webapi/customer_variable/{variableName}/customer_group/category_elements
Check the registered CUSTOMER GROUP
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Example
Response Example
Create CUSTOMER GROUP
POST https://backend.alli.ai/webapi/customer_variable/{variableName}/customer_group/category_element
Create CUSTOMER GROUP
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
value*
string
The name of the CUSTOMER GROUP to add
Request example{variableName}
Response example
Update CUSTOMER GROUP
POST https://backend.alli.aiwebapi/customer_variable/{variableName}/category_element/{categoryElementId}
Update CUSTOMER GROUP
Path Parameters
categoryElementId*
string
The ID of the CUSTOMER GROUP you want to update. You can obtain it by using the CUSTOMER GROUP query API.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
value*
string
The name of the CUSTOMER GROUP to change
Request Example
Be sure to replace {categoryElementId} with the ID of your CUSTOMER GROUP. You can obtain it by using the CUSTOMER GROUP query API.
Response Example
Delete CUSTOMER GROUP
DELETE https://backend.alli.aiwebapi/customer_variable/{variableName}/category_element/{categoryElementId}
Delete CUSTOMER GROUP
Path Parameters
categoryElementId*
string
The ID of the CUSTOMER GROUP you want to delete. You can obtain it by using the CUSTOMER GROUP query API.
Headers
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Example
Be sure to replace {categoryElementId} with the ID of your CUSTOMER GROUP. You can obtain it by using the CUSTOMER GROUP query API.
Response Example
Integrated API
Find Match
POST
https://backend.alli.ai/webapi/find_match
This API is for integrated search for fuzzy match, small talk, q&a.
Headers
Name
Type
Description
API-KEY*
string
Your cognitive search API key can be found in your dashboard Settings menu, under the General tab.
Request Body
Name
Type
Description
process_order
array
can be list of "exact_match", "small_talk", "faq", "mrc", default: ["exact_match", "small_talk", "faq"]
exact_match_list
array
exact match list when using "exact_match"
exact_match_threshold
number
default: 0.85
small_talk_threshold
number
default: 0.85
faq_threshold
number
default:0. 90
faq_direct_answer_mdethod
string
can be "adaptive", "simple". default: "adaptive"
faq_direct_answer_adaptive_thrdshold
number
default: 0.4
faq_direct_answer_direct_threshold
string
default: 0.9
faq_hashtags
array
faq filtering hashtags
faq_hashtags_operator
string
can be "and", "or", default: "or"
faq_count
number
default: 5
faq_format
string
can be "draftjs", "html", "text". default: "text"
mrc_threshold
number
default: 0.80
mrc_hashtags
array
mrc filtering hashtags
mrc_hashtags_operator
string
can be "and", "or", default: "or"
mrc_count
string
default: "5"
mrc_format
string
can be "text", "html". default: "text"
mrc_return_po
boolean
default: False
faq_excluding_hashtags
array
faq filter-out hashtags
faq_excluding_hashtags_operator
string
can be "and", "or", default: "or"
Bulk Preview Documents with Highlight
POST
https://backend.alli.ai/webapi/previews
Headers
Name
Type
Description
API-KEY*
string
Your API key can be found in your dashboard Settings menu, under the General tab.
Request Body
Name
Type
Description
inputs*
array
List of objects containing:
documentId
pageNo
paragraphIndex (optional, for highlighting)
Request Example
paragraphIndex from webapi/mrc
Response Example
200 OK: The result will be returned in the following JSON format:
pdfUrl: The download URL for a PDF preview of the document.
pdfs: Equivalent to pdfPreviewRawData in the response from the webapi/mrc API.
previewUrl: Equivalent to pdfPreview in the response from the webapi/mrc API.
API Classifications
View the API classifications and mapping for billing purposes.
Download the Excel file here
Last updated
