# Answer Bot API ## 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 | Name | Type | Description | | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 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." %} ``` {"result": [ { "confidence": CONFIDENCE_VALUE, "effectiveConfidence": EFFECTIVE_CONFIDENCE_VALUE, "question": "QUESTION_1", "answer": "ANSWER_1", "id": "ID_1", "hashtags": [], "lastUpdatedDate": "DATE", "agentFeedback": { "positiveCount": 1, "negativeCount": 0 }, "userFeedback": { "positiveCount": 1, "negativeCount": 0 } }, ... ], "count": 3, "hashId": "HASH_ID" } ``` {% endtab %} {% endtabs %} ## 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 | 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 | | ------ | ------ | ------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 Includes fields: question: The question associated with the Q\&A. answer : The answer to the question. id: The id of this Q\&A. userFeedback: The feedback from users (through conversation) about this Q\&A. agentFeedback: The feedback from agents (through dashboard and REST calls) about this Q\&A. lastUpdatedDate, createdDate: The date when the Q\&A was updated / first created. hashtags: All hashtags associated with this question." %} ``` { "result": { "question": "Who is there?", "answer": "Elmo", "id": "RkFROjYwMmY2ZTQ0YWZmMWQ5YmQ0NmM5Y2VkNw==", "userFeedback": { "positiveCount": 0, "negativeCount": 0 }, "agentFeedback": { "positiveCount": 0, "negativeCount": 1 }, "lastUpdatedDate": "2021-02-19", "createdDate": "2021-02-19", "hashtags": [] } } ``` {% endtab %} {% endtabs %} ## Get Single Document `GET` `https://backend.alli.ai/webapi/single_document` This is the method to get all details of a single document. #### 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 | | ---- | ------ | ----------------------- | | id | string | The id of the document. | {% tabs %} {% tab title="200 You will get the result as the following JSON format. id: The Document's ID. documentName: The document's file name. createdDate: The date when the document was uploaded. hashtags: Hashtags registered for the document. agentFeedback : Counts of positive and negative ratings by employees. userFeedback: The feedback from users about this document{"result": {" %} ``` "id": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U=", "documentName": "Policy document 1.docx", "createdDate": "2020-11-12", "agentFeedback": { "positiveCount": 1, "negativeCount": 0 }, "userFeedback": { "positiveCount": 0, "negativeCount": 0 }, "hashtags" : ["hashtag1", "hashtag2"] } } ``` {% endtab %} {% endtabs %} ## 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 | Name | Type | Description | | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ------ | ------- | --------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 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, faqId and postive. faqId: 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": [ { "faqId": "FAQ_ID_1_1", "positive": true or false }, ... ] }, ... ], "count": COUNT_1 } ``` {% endtab %} {% endtabs %} ## 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 | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ---------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 You will get the result as the following JSON format. id: The ID for the Q\&A 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." %} ``` { "result": { "faqTrainSearchResult": { "faq": { "id": "ID" }, "agentFeedback": { "positiveCount": NUMBER, "negativeCount": NUMBER } } }, "errors": null } ``` {% endtab %} {% endtabs %} ## 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 | Name | Type | Description | | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- | | 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). | {% tabs %} {% tab title="200 Returns the current user feedback for this FAQ, both the positiveCount and negativeCount. " %} ``` { "result": { "userFeedback": { "positiveCount": 1, "negativeCount": 0 } } } ``` {% endtab %} {% endtabs %} ## 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 | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ---- | ------ | --------------------------------------------------------------------------- | | file | string | Your local Q\&A file location. xlsx, tsv, csv, and zip files are supported. | {% tabs %} {% tab title="200 result: success if the file upload is successful. notUploaded: If any of the questions are not uploaded or updates existing Q\&A, the details will be listed here. question: The question part of not-uploaded or updated Q\&A. state: dup if the Q\&A is not uploaded due to duplication in 'similar questions' content. up if the Q\&A updated an existing one due to the same question content." %} ``` { "result": "success", "notUploaded": [ { "question": "QUESTION_1", "state": "dup" }, { "question": "QUESTION_2", "state": "up" } ] } ``` {% endtab %} {% endtabs %} ## 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 | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 status: The status of the registered Q\&A. 'created' means the Q\&A is newly created. 'updated' means an existing Q\&A is updated with a new answer. id: The registered Q\&A's ID." %} ``` { "result": { "status": "created", "id": "Q&A_ID" }, "errors": null } ``` {% endtab %} {% endtabs %} ## Delete Q\&A `POST` `https://backend.alli.ai/webapi/delete_faq` You can delete a Q\&A using this API. #### 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 | | ---- | ------ | -------------------------------------- | | id | string | The ID of the Q\&A you want to delete. | {% tabs %} {% tab title="200 status: 'deleted' if the Q\&A is successfully deleted." %} ``` { "result": { "status": "deleted" }, "errors": null } ``` {% endtab %} {% tab title="404 When there's no Q\&A with the ID, this error will be returned." %} ``` { "errors": "The record doesn't exist." } ``` {% endtab %} {% endtabs %} ## List Q\&As `GET` `https://backend.alli.ai/webapi/faqs` You can list Q\&As in the Knowledge Base using this API. #### 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 | | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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. | {% tabs %} {% tab title="200 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." %} ``` { "offset": 0, "count": 10, "totalCount": 12, "results": [ { "id": "Q&A_ID_1", "question": "QUESTION_1", "answer": "ANSWER_1", "hashtags": [ "HASHTAG_1", "HASHTAG_2" ], "userFeedback": { "positiveCount": 0, "negativeCount": 0 }, "agentFeedback": { "positiveCount": 0, "negativeCount": 0 }, "lastUpdatedDate": "2021-05-04", "createdDate": "2021-02-23" }, { "id": "Q&A_ID_2", "question": "QUESTION_2", "answer": "ANSWER_2", "hashtags": [ "HASHTAG_1", "HASHTAG_3" ], "userFeedback": { "positiveCount": 0, "negativeCount": 0 }, "agentFeedback": { "positiveCount": 0, "negativeCount": 0 }, "lastUpdatedDate": "2021-05-04", "createdDate": "2021-02-23" }, ... ] } ``` {% endtab %} {% endtabs %} ## 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 | 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 | | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 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." %} ``` { "result": { "faqCandidates": [ { "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" } }] }, ], "count": 1 }, "errors": null } ``` {% endtab %} {% endtabs %} ## Q\&A Candidates `POST` `https://backend.alli.ai/webapi/add_faq_candidates` Registers a new Q\&A Candidate with the system. #### Headers | Name | Type | Description | | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ------- | ------ | -------------------------------------------------- | | queries | string | The list of all queries you would like to register | {% tabs %} {% tab title="200 You will get the result as the following JSON format. id: The id of the candidate registered." %} ``` { "result": { "candidates": [ { "id": "CANDIDATE_ID_1" }, { "id": "CANDIDATE_ID_2" } ] }, "errors": null } ``` {% endtab %} {% endtabs %} ## 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 | Name | Type | Description | | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ------ | ------- | --------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 You will get the result as the following JSON format. query: The search query for the extracted answer. documentId: The ID of the document where the answer was extracted from. answer: The answer part extracted from the document for the query. answerHash: 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": [ { "documentId": "DOCUMENT_ID_1", "answer": "ANSWER_1", "answerHash": "ANSWER_HASH_1", "positive": true or false }, ... ] } ], "count": NUMBER } ``` {% endtab %} {% endtabs %} ## 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 | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 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." %} ``` { "result": { "mrcFeedbackSearchResult": { "agentFeedback": { "positiveCount": NUMBER, "negativeCount": NUMBER } } }, "errors": null } ``` {% endtab %} {% endtabs %} ## Documents Search User Feedback `POST` `https://backend.alli.ai/webapi/mrc/user_feedback` Provide user feedback to the Documents search result. #### Headers | Name | Type | Description | | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 Returns the positiveCount and negativeCount of the user feedback after the change." %} ``` { "result": { "userFeedback": { "positiveCount": 1, "negativeCount": 0 } } } ``` {% endtab %} {% endtabs %} ## 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 | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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`. | | parentFolderId | string | Target folder ID to upload to. Null to insert at top level. | {% tabs %} {% tab title="200 You will get the result in the following JSON format. id: The ID of the uploaded document. fileName: The filename of the uploaded 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." %} ``` { "result": { "id": "DOCUMENT_ID", "fileName": "YOUR_FILE_NAME", "hashtags": [ "HASHTAG_1", "HASHTAG_2" ], "footer": "FOOTER_IN_HTML" } } ``` {% endtab %} {% endtabs %} ## 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 | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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.

| {% tabs %} {% tab title="200 You will get the result in the following JSON format: 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." %} ``` { "result": { "id": "DOCUMENT_ID", "fileName": "YOUR_FILE_NAME", "hashtags": [ "HASHTAG_1", "HASHTAG_2" ], "footer": "FOOTER_IN_HTML" } } ``` {% endtab %} {% endtabs %} ## 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 | 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 | | ---- | ------ | ----------------------------------- | | id | string | The document id to check the status | {% tabs %} {% tab title="200 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", "errorName": "ERROR"}} ``` {% endtab %} {% endtabs %} ## Delete Documents `POST` `https://backend.alli.ai/webapi/delete_file` This API lets you delete uploaded files. #### 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 | | ---- | ----- | ------------------------------------------------------------ | | ids | array | The document IDs that you want to delete in the array format | {% tabs %} {% tab title="200 You will get the result in the following JSON format. ok: true if the deletion completes successfully. If the deletion fails, the result will be false and errors will contain an error message." %} ``` { "result": { "ok": BOOLEAN }, "errors": null } ``` {% endtab %} {% endtabs %} ## List Documents `GET` `https://backend.alli.ai/webapi/knowledge_bases` This API lets you list out the uploaded documents. #### Query Parameters | Name | Type | Description | | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------------------- | | API-KEY\* | string | Your API key can be found in your dashboard Settings menu, under the General tab. | {% tabs %} {% tab title="200 You will get the result in the following JSON format. 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." %} ``` { "result": { "items": [ { "id": "DOCUMENT_ID", "fileName": "FILENAME", "hashtags": ["HASHTAG_1", "HASHTAG_2"], "folder": "FOLDER", "agentEditor": ["email_1@allganize.ai", "email_2@allganize.ai", "email_3@allganize.ai"], "agentViewer": ["email_4@allganize.ai"], "userViewer": {"variables": {"CUSTOMER_ID": [{"id": "customer_id_1", "value": "customer_id_1"}]}}, "allowOtherAgentsView": true, "allowOtherUsersView": true } ] }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example You will need to replace YOUR API KEY with your project's API key. ``` curl -X GET -d '{"status": true, "offset": 0, "limit": 10, "order": "FILE_NAME_ASC", "hashtags": ["policy", "insurance"], "hashtagsSearchOperator": "OR"}' \ -H 'API-KEY: YOUR API KEY' \ https://backend.alli.ai/webapi/knowledge_bases ``` The following values ​​can be used for `order` parameter. | FILE\_NAME\_ASC | Sort ascending by file name | | ----------------- | ----------------------------------------- | | FILE\_NAME\_DESC | Sort descending by file name | | TYPE\_ASC | Sort ascending by file type | | TYPE\_DESC | Sort descending by file type | | STATUS\_ASC | Sort ascending by on/off status of files | | STATUS\_DESC | Sort descending by on/off status of files | | CREATED\_AT\_ASC | Sort ascending by upload date and time | | CREATED\_AT\_DESC | Sort descending by upload date and time | ## 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 | 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 | | -------- | ------ | ---------------------------------------- | | filename | string | The new name for the specified document. | | id | string | The document ID that you want to rename. | {% tabs %} {% tab title="200 You will get the result in the following JSON format: id: The Document id for the file who's name was changed. filename: The Document's new name." %} ``` { "result": { "id": "DOCUMENT_ID", "filename": "FILENAME" } } ``` {% endtab %} {% endtabs %} ## 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 | 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 | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | {% tabs %} {% tab title="200 You will get the result in the following JSON format. 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." %} ``` { "result": { "knowledgeBase": { "id": "DOCUMENT_ID", "hashtags": [ "HASHTAG_1", "HASHTAG_2" ], "footer": "FOOTER_IN_HTML" } }, "errors": null } ``` {% endtab %} {% endtabs %} ## 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 | 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 | | ---- | ------- | ------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 You will get the result in the following JSON format: knowledgeBases : a list of ONLY the knowledge bases whose status were toggled id: id of knowledge base status: new status of knowledge base (boolean). true meaning status is now on." %} ``` { "result": { "knowledgeBases": [ { "id": "YOUR_FIRST_DOCUMENT_ID", "status": true or false }, { "id": "YOUR_SECOND_DOCUMENT_ID", "status": true or false } ] }, "errors": null } ``` {% endtab %} {% endtabs %} ## 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 | 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 | | ---- | ----- | ------------------------------------------------------- | | ids | array | The document ids you want to retrieve auto hashtags for | {% tabs %} {% tab title="200 You will get the result in the following JSON format. updated -> id : The id of the Document to which the hashtags correspond. autoHashtags: Array of JSON objects, containing the list of hashtags auto-generated for the Document. state: Status of hashtag, depending on if agent has confirmed this auto-generated hashtag. Will be one of: "SUGGESTED", "APPROVED", "DECLINED". bestConfidence: Numerical confidence of this auto-generated hashtag from 0 to 1. autoHashtags -> id: The id of the hashtag. hashtag: String value of hashtag (displayed in Dashboard)." %} ``` { "result": { "updated": [ { "id": "DOCUMENT_ID", "autoHashtags": [ { "id": "KNOWLEDGE_BASE_AUTO_HASHTAG_ID", "state": "STATE", "bestConfidence": NUMBER, "autoHashtag": { "hashtag": "HASHTAG_VALUE" } } ] } ] }, "errors": null } ``` {% endtab %} {% endtabs %} ## 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 | 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 | | -------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------- | | autoHashtagFeedbacks | array |

List of JSON objects containing hashtag id/state pairs.
'state' can be one of: 'accepted', 'declined', 'suggested'

| {% tabs %} {% tab title="200 You will get the result in the following JSON format: result: Array of JSON objects, each corresponding to a auto-hashtag id: The id of the hashtag state: The hashtag's feedback from agent. Will be one of: "suggested", "approved", "declined"" %} ``` { "result": [ { "id": "KNOWLEDGE_BASE_AUTO_HASHTAG_ID", "state": "STATE" }, { "id": "KNOWLEDGE_BASE_AUTO_HASHTAG_ID_2", "state": "STATE" } ] } ``` {% endtab %} {% endtabs %} ## 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 | 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 | | ------ | ------ | ------------------------------------------------ | | hashId | string | The id of the Q\&A search return result | | id | string | The id of the FAQ that you would like to select. | {% tabs %} {% tab title="200 You will get the result in the following JSON format: In case of success" %} ``` {"result": "Success"} ``` {% endtab %} {% tab title="404 In case you provide an invalid FAQ" %} ``` {"result": [], "error": "Record does not exist."} ``` {% endtab %} {% endtabs %} ## Agent Management `POST` `https://backend.alli.ai/webapi/agent_management` Used to create and delete agents from the project. #### 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 | | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | {% tabs %} {% tab title="200 id: ID of agent that was deleted/created status: What happened (either "deleted" or "created")" %} ``` { "result": { "id" : "QWdlbnQ6NWZkMmFjMzIwODQ4MzY1ZDI4NWFjMGUw", "status": "deleted" }, "errors": null } ``` {% endtab %} {% tab title="400 If the agent you try to create already has an email registered." %} ``` { "result": [], "errors": "Agent with provided email already exists." } ``` {% endtab %} {% tab title="404 If you try to delete an agent that doesn't exist." %} ``` { "result": [], "errors": "The record does not exist." } ``` {% endtab %} {% endtabs %} ## Get All Hashtags `GET` `https://backend.alli.ai/webapi/hashtags` Gets all hashtags from both FAQs and MRCs #### Headers | Name | Type | Description | | ------- | ------ | --------------------------------------------------------------------------------- | | API-KEY | string | Your API key can be found in your dashboard Settings menu, under the General tab. | {% tabs %} {% tab title="200 Returns each hashtag with its count of uses" %} ``` { "result": { "sample_tag1": 2, "sample_tag2": 1, } } ``` {% endtab %} {% endtabs %} ## 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 | Name | Type | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 Each query will have the following attributes: agent: an object which contains the id of the agent who made the query. question: The question actually asked in the query answers: All answers provided by the system to the query. Each answer has the Q\&A that was referred to, and the confidence, effective confidence. There is also a count of how many queries were returned in a count field." %} ``` { "result": { "histories": [ { "agent": { "id": "QWdlbnQ6NjA0NmMyNWJmNTFjMmVlYjc4Mjg3Zjcy" }, "question": "What is life?", "answers": [ { "faq": { "id": "RkFROjYwNDZjMmUxM2MzYmQ5MjVmMzgxMGNkOQ==" }, "effectiveConfidence": 0.9999999999999927, "confidence": 0.9999999999999927 } ] } ], "count": 1 }, "errors": null } ``` {% endtab %} {% endtabs %} ## 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 | Name | Type | Description | | ---------- | ------- | ---------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 Each query history will have the following attributes: agent: The id of the agent who made the request. question: The actual question asked. answers: A list of all possible answers provided. Each answer has the knowledgeBase used to source that answer (both the filename and the id), the actual answer itself, the answerFormat, the hashtags associated with the knowledgeBase that was retrieved, and whether feedbackAvailable for this specific answer." %} ``` { "result": { "histories": [ { "agent": { "id": "QWdlbnQ6NWZiNzc5MGIwZjE3Zjc5ZmNiNzVlYzFh" }, "question": "program memory of c004", "answers": [ { "knowledgeBase": { "id": "S25vd2xlZGdlQmFzZTo2MDUyODM0ODFiYzgxNDcwZTEzNGRjNDQ=", "fileName": "specification_en.pdf" }, "answer": "{\"blocks\": [{\"key\": \"kn13\", \"type\": \"unstyled\", \"text\": \"Type capacity program memory program memory - C004, B04KR: 80KB\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}, {\"key\": \"2vjf\", \"text\": \" \", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}, {\"key\": \"45cb\", \"text\": \"— From specification_en.pdf\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [{\"offset\": 0, \"length\": 27, \"style\": \"ITALIC\"}], \"entityRanges\": [{\"offset\": 7, \"length\": 20, \"key\": 0}], \"data\": {}}], \"entityMap\": {\"0\": {\"type\": \"LINK\", \"mutability\": \"MUTABLE\", \"data\": {\"url\": \"https://staging-download.alli.ai/download_document/UHJvamVjdDo1ZmI3NzkwYjBmMTdmNzlmY2I3NWVjMWM=/S25vd2xlZGdlQmFzZTo2MDUyODM0ODFiYzgxNDcwZTEzNGRjNDQ=\"}}}}", "answerHash": "6648c76e9be27864557f84ab7822cde8", "answerFormat": "DRAFTJS", "hashtags": [], "feedbackAvailable": true, "columnFilterValues": [] }, ... { "knowledgeBase": { "id": "S25vd2xlZGdlQmFzZTo2MDUyODM0ODFiYzgxNDcwZTEzNGRjNDQ=", "fileName": "specification_en.pdf" }, "answer": "{\"blocks\": [{\"key\": \"87us\", \"type\": \"unstyled\", \"text\": \"Type capacity reload memory reload memory - C004, B04KR: 2048KB\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}, {\"key\": \"p0wr\", \"text\": \" \", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}, {\"key\": \"qpau\", \"text\": \"— From specification_en.pdf\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [{\"offset\": 0, \"length\": 27, \"style\": \"ITALIC\"}], \"entityRanges\": [{\"offset\": 7, \"length\": 20, \"key\": 0}], \"data\": {}}], \"entityMap\": {\"0\": {\"type\": \"LINK\", \"mutability\": \"MUTABLE\", \"data\": {\"url\": \"https://staging-download.alli.ai/download_document/UHJvamVjdDo1ZmI3NzkwYjBmMTdmNzlmY2I3NWVjMWM=/S25vd2xlZGdlQmFzZTo2MDUyODM0ODFiYzgxNDcwZTEzNGRjNDQ=\"}}}}", "answerHash": "9537b6560701930d079f39ced8be1b3e", "answerFormat": "DRAFTJS", "hashtags": [], "feedbackAvailable": true, "columnFilterValues": [] } ] } ], "count": 1 }, "errors": null } ``` {% endtab %} {% endtabs %} ## Uploading Q\&A and Documents Please [sign up](https://app.alli.ai/signup?project_type=COGNITIVE_SEARCH) and [sign in](https://app.alli.ai/) to the Alli dashboard first. **You must select 'Cognitive Search' for the Project Type when you sign up.** Go to the [Q\&A tab](https://app.alli.ai/faq) 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](https://app.alli.ai/faq/documents) 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](https://app.alli.ai/faq/source). Uploading the document via API is in the [Upload Document section](https://docs.allganize.ai/api_documentation/#upload-documents) 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](https://app.alli.ai/settings), 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](https://app.alli.ai/settings/agents). Below is an example. ``` -H 'AGENT-EMAIL: agent_1@email.com' ``` 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. ``` -H 'OWN-USER-ID: 5f1234567a409876c082487z' \ -H 'USER-EMAIL: user_1@email.com' ``` **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](https://app.alli.ai/customers). ![](https://2494697713-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MCUOyJmcDC1YdUwbM6Y%2F-MaFvoCZnO18pi3fa2xL%2F-MaG-U_I2rk1wTzlvavs%2FScreen_Shot_2021-05-21_at_3_16_21_PM.png?alt=media\&token=3c574f58-e25f-469a-b70c-b41feaa004a8) ## 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”} ``` ## 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 | Name | Type | Description | | ----------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 " %} 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. ``` {"result": [ { "confidence": CONFIDENCE_VALUE, "effectiveConfidence": EFFECTIVE_CONFIDENCE_VALUE, "question": "QUESTION_1", "answer": "ANSWER_1", "id": "ID_1", "hashtags": [], "lastUpdatedDate": "DATE", "agentFeedback": { "positiveCount": 1, "negativeCount": 0 }, "userFeedback": { "positiveCount": 1, "negativeCount": 0 } }, ... ], "count": 3, "hashId": "HASH_ID" } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. Please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl -d '{ "query": "How much is it?", "maxResults": 3, "hashtags": ["wiki", "knowledge"], "hashtagsOperator": "OR", "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, "effectiveConfidence": 0.9698303406362148, "question": "How is the product priced?", "answer": "We have a pricing table that includes a free plan.", "id": "ClMVIjCoNDAiZDLyNWZhM1O3YTUIIKZjPPRcER==", "hashtags": [], "lastUpdatedDate": "2020-11-19", "agentFeedback": { "positiveCount": 1, "negativeCount": 0 }, "userFeedback": { "positiveCount": 1, "negativeCount": 0 } }, { "confidence": 0.6119840535714456, "effectiveConfidence": 0.7738889000171243, "question": "Do you have a pricing table?", "answer": "Yes we do. Please check out our website", "id": "RkFROjVmNDAwZDMyNWZhM2Y4YTA1ZDZjNWUwMQ==", "hashtags": [], "lastUpdatedDate": "2020-11-20", "agentFeedback": { "positiveCount": 1, "negativeCount": 0 }, "userFeedback": { "positiveCount": 1, "negativeCount": 0 } ], "count": 2, "hashId": "d4ca12d4e64766er0c2b45f4aa5463a4" } ``` ## 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 | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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 | Name | Type | Description | | --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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.

| | | | | {% tabs %} {% tab title="200 " %} 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. ``` { "result": [ { "answer": "ANSWER_1", "answerHash": "ANSWER_HASH_1", "confidence": CONFIDENCE_1, "effectiveConfidence": EFFECTIVE_CONFIDENCE_1, "documentId": "DOCUMENT_ID_1", "documentName": "DOCUMENT_NAME_1", "hashtags": [], "pageNo": PAGE_NUMBER, "paragraphIndex": 0, "createdDate": "DATE", "agentFeedback": { "positiveCount": 0, "negativeCount": 0 }, "userFeedback": { "positiveCount": 0, "negativeCount": 0 }, "body": "PREVIEW_HTML_BODY", "css": "PREVIEW_CSS", "pdfPreview": "PDF_PREVIEW_URL", "folder": "folder 1", "editor": ["email_1@allganize.ai", "email_2@allganize.ai"], "viewer": ["email_3@allganize.ai"] } ] } ``` {% endtab %} {% endtabs %} ### Request Example (hashtags) Please replace YOUR\_API\_KEY with your one in the example below. Please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl -X POST -d '{ "query": "can I disclose the composite ratings?", "maxResults": 3, "hashtags": ["wiki", "knowledge"], "hashtagsOperator": "OR", "format": "text", "returnPdfPreview": true, "returnPdfPreviewRawData": true \ -H 'API-KEY: YOUR API KEY' \ -H 'Content-Type: application/json' \ https://backend.alli.ai/webapi/mrc ``` ### Request Example (combinedHashtags) Please replace YOUR\_API\_KEY with your one in the example below. Please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl -X POST -d '{ "query": "can I cancel my policy within 30 days?", "maxResults": 3, "hashtags": [], "hashtagsOperator": "OR", "combinedHashtags": [["wiki","knowledge"],["elibrary","compliance"]] "combinedHashtagsOperator": "AND", "format": "text", "returnPdfPreview": true, "returnPdfPreviewRawData": true }' \ -H 'API-KEY: YOUR API KEY' \ -H 'Content-Type: application/json' \ https://backend.alli.ai/webapi/mrc ``` ### Response Example ``` { "result": [ { "answer": "Cancellation is possible within 30 days without any disadvantage..", "answerHash": "8430cf3b9af628abc1bb063802db39be", "confidence": 0.9998937845230103, "effectiveConfidence": 1, "documentId": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U=", "documentName": "Insurance Standard Terms and Conditions.docx", "hashtags": [], "pageNo": 5, "createdDate": "2020-11-18", "agentFeedback": { "positiveCount": 2, "negativeCount": 0 }, "userFeedback": { "positiveCount": 1, "negativeCount": 0 }, "pdfPreview": "PDF_PREVIEW_URL", "folder": "folder 1", "agentEditor": ["email_1@allganize.ai", "email_2@allganize.ai", "email_3@allganize.ai"], "agentViewer": ["email_4@allganize.ai"], "userViewer": {"variables": {"CUSTOMER_ID": [{"id": "customer_id_1", "value": "customer_id_1"}]}}, "allowOtherAgentsView": true, "allowOtherUsersView": true, "properties": {} ​ }, { "answer": "No refunds will be given if cancellation is made after 30 days.", "answerHash": "d849a49662a4f21df51de24d06196547", "confidence": 0.9998629689216614, "effectiveConfidence": 1, "documentId": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U=", "documentName": "Actual insurance terms and conditions 2020.pdf", "hashtags": ["policy", "2020"], "pageNo": 234, "createdDate": "2020-11-18", "agentFeedback": { "positiveCount": 4, "negativeCount": 1 }, "userFeedback": { "positiveCount": 1, "negativeCount": 0 }, "pdfPreview": "PDF_PREVIEW_URL", "folder": "folder 1", "agentEditor": ["email_1@allganize.ai", "email_2@allganize.ai", "email_3@allganize.ai"], "agentViewer": ["email_4@allganize.ai"], "userViewer": {"variables": {"CUSTOMER_ID": [{"id": "customer_id_1", "value": "customer_id_1"}]}}, "allowOtherAgentsView": true, "allowOtherUsersView": true, "properties": {} } ] } ``` ## 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 | 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 | | ------------------------------------ | ------ | ------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 Includes fields: question: The question associated with the Q\&A. answer : The answer to the question. id: The id of this Q\&A. userFeedback: The feedback from users (through conversation) about this Q\&A. agentFeedback: The feedback from agents (through dashboard and REST calls) about this Q\&A. lastUpdatedDate, createdDate: The date when the Q\&A was updated / first created. hashtags: All hashtags associated with this question." %} ``` { "result": { "question": "Who is there?", "answer": "Elmo", "id": "RkFROjYwMmY2ZTQ0YWZmMWQ5YmQ0NmM5Y2VkNw==", "userFeedback": { "positiveCount": 0, "negativeCount": 0 }, "agentFeedback": { "positiveCount": 0, "negativeCount": 1 }, "lastUpdatedDate": "2021-02-19", "createdDate": "2021-02-19", "hashtags": [] } } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. Please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section to get the api key. ``` curl -X GET \ -d '{"id": "iuHjHBhjHGbhjm==", "format": "text"}' \ -H "API-KEY: YOUR API KEY" \ https://backend.alli.ai/webapi/single_faq ``` ### Response Example ``` { "result": { "question": "Who is there?", "similarQuestion": ["Who's present?", "Who is it?"], "answer": "Elmo", "id": "RkFROjYwMmY2ZTQ0YWZmMWQ5YmQ0NmM5Y2VkNw==", "userFeedback": { "positiveCount": 0, "negativeCount": 0 }, "agentFeedback": { "positiveCount": 0, "negativeCount": 1 }, "lastUpdatedDate": "2021-02-19", "createdDate": "2021-02-19", "hashtags": [] } } ``` ## Get Single Document `GET` `https://backend.alli.ai/webapi/single_document` This is the method to get all details of a single document. #### 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 | | ------------------------------------ | ------ | ----------------------- | | id\* | string | The id of the document. | {% tabs %} {% tab title="200 You will get the result as the following JSON format. id: The Document's ID. documentName: The document's file name. createdDate: The date when the document was uploaded. hashtags: Hashtags registered for the document. agentFeedback : Counts of positive and negative ratings by employees. userFeedback: The feedback from users about this document{"result": {" %} ``` "id": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U=", "documentName": "Policy document 1.docx", "createdDate": "2020-11-12", "agentFeedback": { "positiveCount": 1, "negativeCount": 0 }, "userFeedback": { "positiveCount": 0, "negativeCount": 0 }, "hashtags" : ["hashtag1", "hashtag2"] } } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. Please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section to get the api key. ``` curl -X GET \ -d '{"id": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U="}' \ -H "API-KEY: YOUR API KEY" \ https://backend.alli.ai/webapi/single_document ``` ### Response Example ``` {"result": { "id": "S25vd2xlZGdlQmFzZTo1ZjMzODFkZmNhYWJjYWUyMjkzYjFhY2U=", "documentName": "Policy document 1.docx", "createdDate": "2020-11-12", "agentFeedback": { "positiveCount": 1, "negativeCount": 0 }, "userFeedback": { "positiveCount": 0, "negativeCount": 0 }, "hashtags" : ["hashtag1", "hashtag2"] } } ``` ## 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 | Name | Type | Description | | ----------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ------ | ------- | --------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 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, faqId and postive. faqId: 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": [ { "faqId": "FAQ_ID_1_1", "positive": true or false }, ... ] }, ... ], "count": COUNT_1 } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. Please see [getting-api-key](https://docs.allganize.ai/#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. ``` 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": [ { "faqId": "RkFROjVmNDA1MWVkMTFmOWJjMTJjOGUwMTg5YQ==", "positive": true }, { "faqId": "RkFROjVmNDA1MWVkMTFmOWJjMTJjOGUwMThhNA==", "positive": false }, { "faqId": "RkFROjVmNDA1MWVjMTFmOWJjMTJjOGUwMTgyYw==", "positive": true } ] }, { "query": "Are you funded?", "feedbacks": [ { "faqId": "RkFROjVmNDA1MWVjMTFmOWJjMTJjOGUwMTgyNw==", "positive": true } ] } ], "count": 4 } ``` ## 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 | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | -------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 You will get the result as the following JSON format. id: The ID for the Q\&A 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." %} ``` { "result": { "faqTrainSearchResult": { "faq": { "id": "ID" }, "agentFeedback": { "positiveCount": NUMBER, "negativeCount": NUMBER } } }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. Please see [getting-api-key](https://docs.allganize.ai/#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](https://docs.allganize.ai/#search-from-q-and-a) or [Q\&A Feedbacks](https://docs.allganize.ai/#q-and-a-feedback) section. It's id in [Response Example of Search from Q\&A](https://docs.allganize.ai/#response-example) section, or faq\_id in [Response Example of Q\&A Feedbacks](https://docs.allganize.ai/#response-example-2). ``` curl https://backend.alli.ai/webapi/faq_feedback \ -d '{"query": "What do I do if I didn't get a receipt?", "id": "Q&A_ID", "isPositive": true}' \ -H "API-KEY: YOUR API KEY" \ -H "Content-Type: application/json" ``` ### Response Example ``` { "result": { "faqTrainSearchResult": { "faq": { "id": "RkFROjVlOTc5MWExMjM5NjFiNzYzOTcxMWI1Mg==" }, "agentFeedback": { "positiveCount": 1, "negativeCount": 0 } } }, "errors": null } ``` ## 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 | Name | Type | Description | | ----------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------- | | 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 | {% tabs %} {% tab title="200 Returns the current user feedback for this FAQ, both the positiveCount and negativeCount. " %} ``` { "result": { "userFeedback": { "positiveCount": 1, "negativeCount": 0 } } } ``` {% endtab %} {% endtabs %} ### Request Example ``` curl https://backend.alli.ai/webapi/faq/user_feedback \ -H 'API-KEY: YOUR_API_KEY' \ -H "Content-Type: application/json" \ -d '{ "query": "QUERY", "prev": PREVIOUSLY_ASSIGNED_FEEDBACK, "id": "FAQ_ID", "positive": true }' ``` ### Response Example ``` { "result": { "userFeedback": { "positiveCount": 1, "negativeCount": 0 } } } ``` ## 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 | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | -------------------------------------- | ------ | --------------------------------------------------------------------------- | | file\* | string | Your local Q\&A file location. xlsx, tsv, csv, and zip files are supported. | {% tabs %} {% tab title="200 result: success if the file upload is successful. notUploaded: If any of the questions are not uploaded or updates existing Q\&A, the details will be listed here. question: The question part of not-uploaded or updated Q\&A. state: dup if the Q\&A is not uploaded due to duplication in 'similar questions' content. up if the Q\&A updated an existing one due to the same question content." %} ``` { "result": "success", "notUploaded": [ { "question": "QUESTION_1", "state": "dup" }, { "question": "QUESTION_2", "state": "up" } ] } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl -F 'file=@/location/to/your_file' \ -H 'API-KEY: YOUR_API_KEY' https://backend.alli.ai/webapi/upload_faq_file ``` ### Response Example ``` { "result": "success", "notUploaded": [ { "question": "How to teach AI", "state": "dup" }, { "question": "I'd like to schedule a meeting or a demo.", "state": "up" } ] } ``` ## 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 | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | {% tabs %} {% tab title="200 status: The status of the registered Q\&A. 'created' means the Q\&A is newly created. 'updated' means an existing Q\&A is updated with a new answer. id: The registered Q\&A's ID." %} ``` { "result": { "status": "created", "id": "Q&A_ID" }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl 'https://backend.alli.ai/webapi/register_faq' \ -H 'API-KEY: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "status": "ON", "question": "Where is the office?", "similarQuestions": ["Office location?", "Office address?"], "answer": "We have offices in Oakland(US), Seoul(Korea), and Tokyo(Japan)", "hashtags": ["office", "location"], "memo": "Added from API", "folder": "folder 1", "agentEditor": ["your@email.com"], "agentViewer": ["your@email_2.com"], "userViewer": { "variables": { "CUSTOMER_ID": ["id_1", "id_2"], "CUSTOMER_GROUP": ["{categoryElementId}", "{categoryElementId}"] } }, "followFolderPermission": false, "allowOtherAgentsView": true, "allowOtherUsersView": true }' ``` ### Response Example ``` { "result": { "status": "created", "id": "RkFROkYwYRQxYzIzMDcxYWM5M3JlOWR5Y2EeOQ==" }, "errors": null } ``` ## Delete Q\&A `POST` `https://backend.alli.ai/webapi/delete_faq` You can delete a Q\&A using this API. #### 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 | | ------------------------------------ | ------ | -------------------------------------- | | id\* | string | The ID of the Q\&A you want to delete. | {% tabs %} {% tab title="200 status: 'deleted' if the Q\&A is successfully deleted." %} ``` { "result": { "status": "deleted" }, "errors": null } ``` {% endtab %} {% tab title="404 When there's no Q\&A with the ID, this error will be returned." %} ``` { "errors": "The record doesn't exist." } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl 'https://backend.alli.ai/webapi/delete_faq' \ -H 'API-KEY: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d { "id": "RkFROkYwYRQxYzIzMDcxYWM5M3JlOWR5Y2EeOQ==" } ``` ### Response Example ``` { "result": { "status": "deleted" }, "errors": null } ``` ## List Q\&As `GET` `https://backend.alli.ai/webapi/faqs` You can list Q\&As in the Knowledge Base using this API. #### 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 | | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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. | {% tabs %} {% tab title="200 " %} **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. ``` { "offset": 0, "count": 10, "totalCount": 12, "results": [ { "id": "Q&A_ID_1", "question": "QUESTION_1", "answer": "ANSWER_1", "hashtags": [ "HASHTAG_1", "HASHTAG_2" ], "userFeedback": { "positiveCount": 0, "negativeCount": 0 }, "agentFeedback": { "positiveCount": 0, "negativeCount": 0 }, "lastUpdatedDate": "2021-05-04", "createdDate": "2021-02-23" }, { "id": "Q&A_ID_2", "question": "QUESTION_2", "answer": "ANSWER_2", "hashtags": [ "HASHTAG_1", "HASHTAG_3" ], "userFeedback": { "positiveCount": 0, "negativeCount": 0 }, "agentFeedback": { "positiveCount": 0, "negativeCount": 0 }, "lastUpdatedDate": "2021-05-04", "createdDate": "2021-02-23" }, ... ] } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl -X GET 'https://backend.alli.ai/webapi/faqs' \ -H 'API-KEY: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "searchTerm": "Allganize", "isUsed": true, "hashtags": ["company", "Alli"], "hashtagsOperator": "OR", "createdByAgent": true, "answeredByMrc": true, "autoGenerated": false, "editedByAgent": false, "format": "text", "offset": 0, "limit": 10 }' ``` ### Response Example ``` { "offset": 0, "count": 2, "totalCount": 2, "results": [ { "id": "RkRODjYwUIr2YTUzYTc0MjNmMDgxOTFkZTRlNA==", "question": "How many people work at Allganize?", "answer": "Currently (Nov 2019), we have 16 employees working at three different locations.", "hashtags": [ "company", "actual" ], "userFeedback": { "positiveCount": 0, "negativeCount": 0 }, "agentFeedback": { "positiveCount": 0, "negativeCount": 0 }, "lastUpdatedDate": "2021-05-04", "createdDate": "2021-02-23" }, { "id": "RkFROjYwIdU4YTUzYTc0MjNmUR2wOTFkZTU1OA==", "question": "Do you have any references or case studies?", "answer": "We do! Check out our recent case studies and other articles on our blog: https://blog.allganize.ai/", "hashtags": [ "company", "actual" ], "userFeedback": { "positiveCount": 0, "negativeCount": 0 }, "agentFeedback": { "positiveCount": 0, "negativeCount": 0 }, "lastUpdatedDate": "2021-05-04", "createdDate": "2021-02-23" } ] } ``` ## 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 | 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 | | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 " %} 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. ``` { "result": { "faqCandidates": [ { "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" } }] }, ], "count": 1 }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#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 ``` { "result": { "faqCandidates": [ { "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==" } }] } ], "count": 1 }, "errors": null } ``` ## Q\&A Candidates `POST` `https://backend.alli.ai/webapi/add_faq_candidates` Registers a new Q\&A Candidate with the system. #### Headers | Name | Type | Description | | ----------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ----------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 You will get the result as the following JSON format. id: The id of the candidate registered." %} ``` { "result": { "candidates": [ { "id": "CANDIDATE_ID_1" }, { "id": "CANDIDATE_ID_2" } ] }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl https://backend.alli.ai/webapi/add_faq_candidates \ -d '{"queries": ["what is that processor", "how much does the processor cost"]}' \ -H "Content-Type: application/json" \ -H "API-KEY: YOUR_API_KEY" ``` ### Response Example ``` { "result": { "candidates": [ { "id": "RkFRQ2FuZGlkYXRlOjVmOGE1ZDA0ODgxNzc0OWNjMWUwMzRiNg==" }, { "id": "iGBiuGIGIugBIGBIugBIuBGiHBiJUhbhIBgIbKHJBJCYUBLHKGJfBJbIb==" } ] }, "errors": null } ``` ## 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 | Name | Type | Description | | ----------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ------ | ------- | --------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 You will get the result as the following JSON format. query: The search query for the extracted answer. documentId: The ID of the document where the answer was extracted from. answer: The answer part extracted from the document for the query. answerHash: 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": [ { "documentId": "DOCUMENT_ID_1", "answer": "ANSWER_1", "answerHash": "ANSWER_HASH_1", "positive": true or false }, ... ] } ], "count": NUMBER } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#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. ``` 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": [ { "documentId": "S25vd2xlZGdlQmFzZTo1ZWM1YmJiZTczNmUxNmM0NDRjZDI2ZGM=", "answer": "You can cancel the policy in 30 days.", "answerHash": "44094c4a281484daadf28e67a4745747", "positive": true }, { "documentId": "S25vd2xlZGdlQmFzZTo1ZWM1YmJiZTczNmUxNmM0NDRjZDI2ZGM=", "answer": "This is how you enroll the policy.", "answerHash": "296ffa9691166c583b00365fb6839a06", "positive": false }, { "documentId": "S25vd2xlZGdlQmFzZTo1ZWM1YmJiZTczNmUxNmM0NDRjZDI2ZGM=", "answer": "You cannot get refunded upon cancelation after 30 days.", "answerHash": "48e5273910c913dbf0fc08482f7cd22c", "positive": true } ] } ], "count": 3 } ``` ## 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 | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | -------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 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." %} ``` { "result": { "mrcFeedbackSearchResult": { "agentFeedback": { "positiveCount": NUMBER, "negativeCount": NUMBER } } }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#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](https://docs.allganize.ai/#search-from-documents) or [Documents Feedbacks](https://docs.allganize.ai/#documents-feedbacks) section. ``` curl https://backend.alli.ai/webapi/mrc_feedback \ -d '{"query": "what is that processor", "id": "DOCUMENT_ID", "answerHash": "ANSWER_HASH", "isPositive": false}' \ -H "Content-Type: application/json" \ -H "API-KEY: YOUR_API_KEY" ``` ### Response Example ``` { "result": { "mrcFeedbackSearchResult": { "agentFeedback": { "positiveCount": 0, "negativeCount": 1 } } }, "errors": null } ``` ## Documents Search User Feedback `POST` `https://backend.alli.ai/webapi/mrc/user_feedback` Provide user feedback to the Documents search result. #### Headers | Name | Type | Description | | ----------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | -------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 extracted from the document for the query | | 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 | {% tabs %} {% tab title="200 Returns the positiveCount and negativeCount of the user feedback after the change." %} ``` { "result": { "userFeedback": { "positiveCount": 1, "negativeCount": 0 } } } ``` {% endtab %} {% endtabs %} ### Request Example ``` curl -request POST 'https://backend.alli.ai/webapi/mrc/user_feedback' \ --header 'API-KEY: YOUR_API_KEY' \ -d '{ "query": "QUERY", "answer": "ANSWER", "answerHash": "RESULT_ID", "id": "DOCUMENT_ID", "positive": true }' ``` ### Response Example ``` { "result": { "userFeedback": { "positiveCount": 1, "negativeCount": 0 } } } ``` ## 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 | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 Returns the document uploaded" %} ``` { "result": { "id": "ID", "fileName": "DOCUMENT_NAME", "hashtags": [], "footer": "{FOOTER_INFORMATION}", "folder": "FOLDER_NAME", "agentEditor": ["AGENT_NAME"], "agentViewer": ["VIEWER_NAME"], "allowOtherAgentsView": true, "allowOtherUsersView": true, "properties": {} } }    ``` {% endtab %} {% endtabs %} ### 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](https://docs.allganize.ai/#getting-api-key) section. ``` curl -F 'file=@"/location/to/your_file"' \ -F 'hashtags="[\"api1\", \"api2\"]"' \ -F 'footerUrl="www.allganize.ai"' \ -F 'footerTitle="Allganize website"' \ -F 'folder="folder 1"' \ -F 'followFolderPermission=false' \ -F 'agentViewer="[\"agent@allganize.io\"]"' \ -F 'userViewer="{ \"variables\": { \"CUSTOMER_ID\": [\"customer_1\"], \"CUSTOMER_GROUP\": [\"Q2F0ZWdvcnlFbGVtZW5OAjYzNzkyZDY1NWM5ZDIxMTU5NDMwZDY1OA==\"] } }"' \ -H 'API-KEY: YOUR_API_KEY' https://backend.alli.ai/webapi/upload_file ``` ### Response Example ``` { "result": { "id": "S25vd2xlZGdlQmA23To2MGJjIsjA1YjM1Nz9iRc1YWIzYjA1ODk=", "fileName": "policy.docx", "hashtags": [ "api1", "api2" ], "footer": "{\"blocks\": [{\"key\": \"oio7\", \"text\": \"— From ocr_en.png\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [{\"offset\": 0, \"length\": 17, \"style\": \"ITALIC\"}], \"entityRanges\": [{\"offset\": 7, \"length\": 10, \"key\": 0}], \"data\": {}}], \"entityMap\": {\"0\": {\"type\": \"LINK\", \"mutability\": \"MUTABLE\", \"data\": {\"url\": \"https://download.alli.ai/download_document/UHJvamUiddDo1ZGMxYmI1qwe0ZTk0YWNmMmY5MjRlMzU=/S12vd2xlZGdlQmFzZTo2MGJijef1YjM1Nzc4NTc1YWIzYjA1ODk=\"}}}}", "folder": "folder 1", "agentEditor": ["admin_1@allganize.ai", "admin_2@allganize.ai"], "agentViewer": ["viewer_email@allganize.ai"], "allowOtherAgentsView": true, "allowOtherUsersView": true, "properties": {} } }                                                                                                          ``` ## 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 | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 You will get the result in the following JSON format." %} **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. ``` { "result": { "id": "S25vd2xlZGdlQmA23To2MGJjIsjA1YjM1Nz9iRc1YWIzYjA1ODk=", "fileName": "policy.docx", "hashtags": [ "api1", "api2" ], "footer": "{\"blocks\": [{\"key\": \"oio7\", \"text\": \"— From ocr_en.png\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [{\"offset\": 0, \"length\": 17, \"style\": \"ITALIC\"}], \"entityRanges\": [{\"offset\": 7, \"length\": 10, \"key\": 0}], \"data\": {}}], \"entityMap\": {\"0\": {\"type\": \"LINK\", \"mutability\": \"MUTABLE\", \"data\": {\"url\": \"https://download.alli.ai/download_document/UHJvamUiddDo1ZGMxYmI1qwe0ZTk0YWNmMmY5MjRlMzU=/S12vd2xlZGdlQmFzZTo2MGJijef1YjM1Nzc4NTc1YWIzYjA1ODk=\"}}}}", "folder": null, "agentEditor": [ "agent1@allganize.io" ], "agentViewer": [], "userViewer": { "variables": { "CUSTOMER_ID": [ { "id": "new_user_1", "value": "new_user_1" } ], "CUSTOMER_GROUP": [ { "id": "Q2F0ZWdvcnlFbGVtZW50OjYzNdf2MjU0OWU4OTM4N2IzMTkxN2Y0ZA==", "value": "group_1" }, { "id": "Q2F0ZWdvcnlFbGVtZW50OjYzNziymRU1Nzg4YWFmODVjZTU1YjVkMg==", "value": "group_2" } ] } }, "allowOtherAgentsView": true, "allowOtherUsersView": false, "properties": {} } } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl https://backend.alli.ai/webapi/upload_from_s3 -d '{ "path": "s3://YOUR_S3_FILE_PATH", "secretKey": "YOUR_SECRET_KEY", "accessKey": “YOUR_ACCESS_KEY", "bucket": "YOUR_BUCKET_NAME", "hashtags": ["HASHTAG_1", "HASHTAG_2"], "footerTitle": "Allganize API Documentation", "footerUrl": "docs.allganize.ai"}, "folder": "folder 1", "followFolderPermission": false, "agentViewer": ["viewer_email@allganize.ai"], "userViewer": { "variables": { "CUSTOMER_ID": ["id_1"], "CUSTOMER_GROUP": ["{categoryElementsId}"] } }}' \ -H "Content-Type: application/json" \ -H "API-KEY: YOUR_API_KEY" ``` ### Response Example ``` { "result": { "id": "S25vd2xlZGdlQmA23To2MGJjIsjA1YjM1Nz9iRc1YWIzYjA1ODk=", "fileName": "policy.docx", "hashtags": [ "api1", "api2" ], "footer": "{\"blocks\": [{\"key\": \"oio7\", \"text\": \"— From ocr_en.png\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [{\"offset\": 0, \"length\": 17, \"style\": \"ITALIC\"}], \"entityRanges\": [{\"offset\": 7, \"length\": 10, \"key\": 0}], \"data\": {}}], \"entityMap\": {\"0\": {\"type\": \"LINK\", \"mutability\": \"MUTABLE\", \"data\": {\"url\": \"https://download.alli.ai/download_document/UHJvamUiddDo1ZGMxYmI1qwe0ZTk0YWNmMmY5MjRlMzU=/S12vd2xlZGdlQmFzZTo2MGJijef1YjM1Nzc4NTc1YWIzYjA1ODk=\"}}}}", "folder": null, "agentEditor": [ "agent1@allganize.io" ], "agentViewer": [], "userViewer": { "variables": { "CUSTOMER_ID": [ { "id": "new_user_1", "value": "new_user_1" } ], "CUSTOMER_GROUP": [ { "id": "Q2F0ZWdvcnlFbGVtZW50OjYzNdf2MjU0OWU4OTM4N2IzMTkxN2Y0ZA==", "value": "group_1" }, { "id": "Q2F0ZWdvcnlFbGVtZW50OjYzNziymRU1Nzg4YWFmODVjZTU1YjVkMg==", "value": "group_2" } ] } }, "allowOtherAgentsView": true, "allowOtherUsersView": false, "properties": {} } } ``` ## 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 | 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 | | ------------------------------------ | ------ | ----------------------------------- | | id\* | string | The document id to check the status | {% tabs %} {% tab title="200 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"}} ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY to your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. Please replace DOCUMENT\_ID accordingly as well. About getting document id, please take a look at [Search from Documents](https://docs.allganize.ai/#search-from-documents) or the [Documents Feedbacks](https://docs.allganize.ai/#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 ``` ## Delete Documents `POST` `https://backend.alli.ai/webapi/delete_file` This API lets you delete uploaded files. #### 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 | | ------------------------------------- | ----- | ------------------------------------------------------------ | | ids\* | array | The document IDs that you want to delete in the array format | {% tabs %} {% tab title="200 You will get the result in the following JSON format. ok: true if the deletion completes successfully. If the deletion fails, the result will be false and errors will contain an error message." %} ``` { "result": { "ok": BOOLEAN }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. Please replace DOCUMENT\_ID accordingly as well. About getting document id, please take a look at [Search from Documents](https://docs.allganize.ai/#search-from-documents) or [Documents Feedbacks](https://docs.allganize.ai/#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 ``` { "result": { "ok": true, }, "errors": null } ``` ## Preview Documents `GET` `https://backend.alli.ai/webapi/knowledge_base_preview` This API lets you preview the uploaded documents. #### Query Parameters | Name | Type | Description | | ------ | ------ | ----------------------------------------- | | id | string | The document ID that you want to preview | | pageNo | string | Pages of the document you want to preview | #### Headers | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------------------- | | API-KEY\* | string | Your API key can be found in your dashboard Settings menu, under the General tab. | {% tabs %} {% tab title="200 You will get the result in the following JSON format." %} **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. ``` { "result": { "totalPageCount": 3, "pageNo": 1, "css": null, "body": null, "highlightIndexes": [], "exactAnswer": null, "pdf": "PDF", "draftjs": null, "highlights": { "indexes": null, "pageIndexes": [], "__typename": "KnowledgeBasePreviewHighlights" }, "knowledgeBase": { "id": "DOCUMENT_ID", "title": "DOCUMENT_TITLE", "__typename": "MSDocsKnowledgeBase" }, "__typename": "KnowledgeBasePreview" }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. Please replace DOCUMENT\_ID accordingly as well. About getting document id, please take a look at [Search from Documents](https://docs.allganize.ai/#search-from-documents) or [Documents Feedbacks](https://docs.allganize.ai/#documents-feedbacks) section. ``` curl -d '{"id": "DOCUMENT_ID", "pageNo": 1}' \ -H "API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ https://backend.alli.ai/webapi/knowledge_base_preview ``` ### 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". ``` { "result": { "totalPageCount": 3, "pageNo": 1, "css": null, "body": null, "highlightIndexes": [], "exactAnswer": null, "pdf": "PDF", "draftjs": null, "highlights": { "indexes": null, "pageIndexes": [], "__typename": "KnowledgeBasePreviewHighlights" }, "knowledgeBase": { "id": "DOCUMENT_ID", "title": "DOCUMENT_TITLE", "__typename": "MSDocsKnowledgeBase" }, "__typename": "KnowledgeBasePreview" }, "errors": null } ``` ## List Documents `GET` `https://backend.alli.ai/webapi/knowledge_bases` This API lets you list out the uploaded documents. #### Query Parameters | Name | Type | Description | | ------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------------------- | | API-KEY\* | string | Your API key can be found in your dashboard Settings menu, under the General tab. | {% tabs %} {% tab title="200 You will get the result in the following JSON format." %} **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. ``` { "result": { "items": [ { "id": "DOCUMENT_ID", "fileName": "FILENAME", "hashtag": ["HASHTAG_1", "HASHTAG_2"], "autoHashtag": ["AUTOHASHTAG_1"], "folder": "folder 2", "editor": ["email_1@allganize.ai", "email_2@allganize.ai"], "viewer": ["email_3@allganize.ai"] } ] }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl -X GET -d '{"status": true, "offset": 0, "limit": 10, "order": "FILE_NAME_ASC", "searchTerm": "term1 OR term2" "hashtags": ["policy", "insurance"], "hashtagsSearchOperator": "OR"}' \ -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 | | ----------------- | ----------------------------------------------------------------------------- | | 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 ``` { "result": { "items": [ { "id": "S23wd2xlZGdlQmRzZTo1ZmFmMzYwZ3IyYjliMTI2OTAyMWVmMDQ=", "fileName": "policy1.docx", "hashtags": ["policy"], "score": 1.0, "downloadUrl": "https://download.alli.ai/download_document/UHJvamVjdDo1YzZiYjYyNDQxNmFmYzAwMDgyMTQwNDU=/S23wd2xlZGdlQmRzZTo1ZmFmMzYwZ3IyYjliMTI2OTAyMWVmMDQ=", "footerUrl": "https://download.alli.ai/download_document/UHJvamVjdDo1YzZiYjYyNDQxNmFmYzAwMDgyMTQwNDU=/S23wd2xlZGdlQmRzZTo1ZmFmMzYwZ3IyYjliMTI2OTAyMWVmMDQ=", "folder": "folder 2", "editor": ["email_1@allganize.ai", "email_2@allganize.ai"], "viewer": ["email_3@allganize.ai"] }, { "id": "S75vd2elZGdlQmFzZTo1ZmFlMjdhYmMx22E3MWM1MzA0NDI3ZWQ=", "fileName": "insurance_policy.pdf", "hashtags": ["policy", "insurance"], "score": 0.89, "downloadUrl": "https://download.alli.ai/download_document/UHJvamVjdDo1YzZiYjYyNDQxNmFmYzAwMDgyMTQwNDU=/S75vd2elZGdlQmFzZTo1ZmFlMjdhYmMx22E3MWM1MzA0NDI3ZWQ=", "footerUrl": "www.example.com", "folder": "folder 2", "editor": ["email_1@allganize.ai", "email_2@allganize.ai"], "viewer": ["email_3@allganize.ai"] } ], "count": 2 }, "errors": null } ``` ## List Documents `POST` `https://backend.alli.ai/webapi/knowledge_bases` This API lets you list out the uploaded documents. #### Query Parameters | Name | Type | Description | | ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------------------- | | API-KEY\* | string | Your API key can be found in your dashboard Settings menu, under the General tab. | {% tabs %} {% tab title="200 You will get the result in the following JSON format." %} **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. ``` { "result": { "items": [ { "id": "DOCUMENT_ID", "fileName": "FILENAME", "hashtag": ["HASHTAG_1", "HASHTAG_2"], "autoHashtag": ["AUTOHASHTAG_1"], "folder": "folder 2", "editor": ["email_1@allganize.ai", "email_2@allganize.ai"], "viewer": ["email_3@allganize.ai"] } ] }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl -X GET -d '{"status": true, "offset": 0, "limit": 10, "order": "FILE_NAME_ASC", "searchTerm": "term1 OR term2" "hashtags": ["policy", "insurance"], "hashtagsSearchOperator": "OR"}' \ -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 | | ----------------- | ----------------------------------------------------------------------------- | | 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 ``` { "result": { "items": [ { "id": "S23wd2xlZGdlQmRzZTo1ZmFmMzYwZ3IyYjliMTI2OTAyMWVmMDQ=", "fileName": "policy1.docx", "hashtags": ["policy"], "score": 1.0, "downloadUrl": "https://download.alli.ai/download_document/UHJvamVjdDo1YzZiYjYyNDQxNmFmYzAwMDgyMTQwNDU=/S23wd2xlZGdlQmRzZTo1ZmFmMzYwZ3IyYjliMTI2OTAyMWVmMDQ=", "footerUrl": "https://download.alli.ai/download_document/UHJvamVjdDo1YzZiYjYyNDQxNmFmYzAwMDgyMTQwNDU=/S23wd2xlZGdlQmRzZTo1ZmFmMzYwZ3IyYjliMTI2OTAyMWVmMDQ=", "folder": "folder 2", "editor": ["email_1@allganize.ai", "email_2@allganize.ai"], "viewer": ["email_3@allganize.ai"] }, { "id": "S75vd2elZGdlQmFzZTo1ZmFlMjdhYmMx22E3MWM1MzA0NDI3ZWQ=", "fileName": "insurance_policy.pdf", "hashtags": ["policy", "insurance"], "score": 0.89, "downloadUrl": "https://download.alli.ai/download_document/UHJvamVjdDo1YzZiYjYyNDQxNmFmYzAwMDgyMTQwNDU=/S75vd2elZGdlQmFzZTo1ZmFlMjdhYmMx22E3MWM1MzA0NDI3ZWQ=", "footerUrl": "www.example.com", "folder": "folder 2", "editor": ["email_1@allganize.ai", "email_2@allganize.ai"], "viewer": ["email_3@allganize.ai"] } ], "count": 2 }, "errors": null } ``` ## 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 | Name | Type | Description | | --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------------------- | | API-KEY\* | string | Your API key can be found in your dashboard Settings menu, under the General tab. | {% tabs %} {% tab title="200: OK You will get the result in the following JSON format." %} **`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. ```json { "result": [ { "id": "DOCUMENT_ID", "fileName": "FILE_NAME.docx", "hashtags": ["hashtag1", "hashtag2"], "score": 0.87, "folder": "folder 2", "editor": ["email_1@allganize.ai", "email_2@allganize.ai"], "viewer": ["email_3@allganize.ai"] } ] } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl -X GET 'https://backend.alli.ai/webapi/search_document_by_title' \ -H 'API-KEY: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ --data-urlencode “query=cpu specs” \ --data-urlencode “hashtags=company,alli” ``` ### Response Example ``` { "result": [ { "id": "616a0cd34e0176b2fbed54bc", "fileName": "SPECIFICATIONS.docx", "hashtags": ["specs", "Alli"], "score": 0.87, "folder": "folder 2", "editor": ["email_1@allganize.ai", "email_2@allganize.ai"], "viewer": ["email_3@allganize.ai"] } ] } ``` ## 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 | 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 | | ------------------------------------------ | ------ | ---------------------------------------- | | filename\* | string | The new name for the specified document. | | id\* | string | The document ID that you want to rename. | {% tabs %} {% tab title="200 You will get the result in the following JSON format: id: The Document id for the file who's name was changed. filename: The Document's new name." %} ``` { "result": { "id": "DOCUMENT_ID", "filename": "FILENAME" } } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. Please replace DOCUMENT\_ID accordingly as well. About getting document id, please take a look at [Search from Documents](https://docs.allganize.ai/#search-from-documents) or [Documents Feedbacks](https://docs.allganize.ai/#documents-feedbacks) section. ``` curl -L -X POST 'https://backend.alli.ai/webapi/update_kb_name' \ -H 'Content-Type: application/json' \ -H 'API-KEY: YOUR_API_KEY' \ --data-raw '{"id": "DOCUMENT_ID", "filename": "FILENAME"}' ``` ### Response Example ``` { "result": { "id": "DOCUMENT_ID", "filename": "policy.docx" } } ``` ## 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 | 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 | | ------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 You will get the result in the following JSON format." %} **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. ``` { "result": { "knowledgeBase": { "id": "S25vd1iuRGdlQmFzZTo2MGJhYjQzERHjYTNiNWE0PLD3MDk1YTg=", "hashtags": [ "hashtag1", "hashtag2" ], "footer": "{\"blocks\": [{\"key\": \"qn8p\", \"text\": \"— From Allganize API documentation\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [{\"offset\": 7, \"length\": 27, \"key\": 0}], \"data\": {}}], \"entityMap\": {\"0\": {\"type\": \"LINK\", \"mutability\": \"MUTABLE\", \"data\": {\"url\": \"docs.allganize.ai\"}}}}", "folder": "folder 2", "agentsEditor": ["admin_1@allganize.ai", "admin_2@allganize.ai"], "agentsViewer": ["viewer_email@allganize.ai"], "userViewer": {"variables": {"CUSTOMER_GROUP": [{"id": "Q2F0ZwdvcnlFbGVtZW50OjYzNzcyZDY1NWM5ZDIxMTU5NDMwZDY1OA==", "value": "group_name"}], "CUSTOMER_ID": [{"id": "id_1", "value": "id_1"}]}}, "allowOtherAgentsView": true, "allowOtherUsersView": true } }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. Please replace DOCUMENT\_ID accordingly as well. About getting document id, please take a look at [Search from Documents](https://docs.allganize.ai/#search-from-documents) or [Documents Feedbacks](https://docs.allganize.ai/#documents-feedbacks) section. ``` curl -L -X POST 'https://backend.alli.ai/webapi/update_document' \ -H 'Content-Type: application/json' \ -H 'API-KEY: YOUR_API_KEY' \ -d '{ "hashtags": ["hashtag1", "hashtag2"], "id": "DOCUMENT_ID", "footerTitle": "Allganize API documentation", "footerUrl": "docs.allganize.ai", "folder": "folder 2", "followFolderPermission": false, "agentViewer": ["viewer_email@allganize.ai"], "userViewer": { "variables": { "CUSTOMER_ID": ["id_1"], "CUSTOMER_GROUP": ["{categoryElementsId}"] } }, "allowOtherUsersView": true }' ``` ### Response Example ``` { "result": { "knowledgeBase": { "id": "S25vd1iuRGdlQmFzZTo2MGJhYjQzERHjYTNiNWE0PLD3MDk1YTg=", "hashtags": [ "hashtag1", "hashtag2" ], "footer": "{\"blocks\": [{\"key\": \"qn8p\", \"text\": \"— From Allganize API documentation\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [{\"offset\": 7, \"length\": 27, \"key\": 0}], \"data\": {}}], \"entityMap\": {\"0\": {\"type\": \"LINK\", \"mutability\": \"MUTABLE\", \"data\": {\"url\": \"docs.allganize.ai\"}}}}", "folder": "folder 2", "agentsEditor": ["admin_1@allganize.ai", "admin_2@allganize.ai"], "agentsViewer": ["viewer_email@allganize.ai"], "userViewer": {"variables": {"CUSTOMER_GROUP": [{"id": "Q2F0ZwdvcnlFbGVtZW50OjYzNzcyZDY1NWM5ZDIxMTU5NDMwZDY1OA==", "value": "group_name"}], "CUSTOMER_ID": [{"id": "id_1", "value": "id_1"}]}}, "allowOtherAgentsView": true, "allowOtherUsersView": true } }, "errors": null } ``` ### Create/Read/Update/Delete Custom Properties #### Create Custom Properties If you'd like to create custom properties to a document, please use properties parameter. ``` curl -L -X POST 'https://backend.alli.ai/webapi/update_document' \ -H 'Content-Type: application/json' \ -H 'API-KEY: YOUR_API_KEY' \ -d '{ "id": "DOCUMENT_ID", "properties": {"testVar": "testValue", "testNumVar": 1234} }' ``` Then, you will receive the following response. ``` { "result": { "knowledgeBase": { "id": "YOUR_DOCUMENT_ID", "properties": { "testKey": "testValue", "testNumVar": 1234 }, } }, "errors": null } ``` #### 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. ``` curl -X POST 'https://backend.alli.ai/webapi/update_document' \ -H 'Content-Type: application/json' \ -H 'API-KEY: YOUR_API_KEY' \ -d '{ "id": "DOCUMENT_ID", "properties": {"testVar": "newTestValue"} }' ``` Then, you will receive the following response. 
{
    "result": {
        "knowledgeBase": {
            "id": "YOUR_DOCUMENT_ID",
            "properties": {
                "testKey": "newTestValue"
            },
        }
    },
    "errors": null
}
#### 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. ``` { "result": { "knowledgeBase": { "id": "YOUR_DOCUMENT_ID", "properties": null, } }, "errors": null } ``` Then, you will receive the following response. ``` { "result": { "knowledgeBase": { "id": "YOUR_DOCUMENT_ID", "properties": {}, } }, "errors": null } ``` ## 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 | 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 | | ------------------------------------- | ------- | ------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 You will get the result in the following JSON format: knowledgeBases : a list of ONLY the knowledge bases whose status were toggled id: id of knowledge base status: new status of knowledge base (boolean). true meaning status is now on." %} ``` { "result": { "knowledgeBases": [ { "id": "YOUR_FIRST_DOCUMENT_ID", "status": true or false }, { "id": "YOUR_SECOND_DOCUMENT_ID", "status": true or false } ] }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example ``` curl -X 'POST' -H 'API-KEY: YOUR_API_KEY' -d '{ "ids":[YOUR_FIRST_DOCUMENT_ID, YOUR_SECOND_DOCUMENT_ID, ETC], "use": true }' https://backend.alli.ai/webapi/toggle_documents ``` ### Response Example ``` { "result": { "knowledgeBases": [ { "id": "YOUR_FIRST_DOCUMENT_ID", "status": true }, { "id": "YOUR_SECOND_DOCUMENT_ID", "status": false } ] }, "errors": null } ``` ## 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 | 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 | | ------------------------------------- | ----- | ------------------------------------------------------- | | ids\* | array | The document ids you want to retrieve auto hashtags for | {% tabs %} {% tab title="200 You will get the result in the following JSON format. updated -> id : The id of the Document to which the hashtags correspond. autoHashtags: Array of JSON objects, containing the list of hashtags auto-generated for the Document. state: Status of hashtag, depending on if agent has confirmed this auto-generated hashtag. Will be one of: "SUGGESTED", "APPROVED", "DECLINED". bestConfidence: Numerical confidence of this auto-generated hashtag from 0 to 1. autoHashtags -> id: The id of the hashtag. hashtag: String value of hashtag (displayed in Dashboard)." %} ``` { "result": { "updated": [ { "id": "DOCUMENT_ID", "autoHashtags": [ { "id": "KNOWLEDGE_BASE_AUTO_HASHTAG_ID", "state": "STATE", "bestConfidence": NUMBER, "autoHashtag": { "hashtag": "HASHTAG_VALUE" } } ] } ] }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. Please replace DOCUMENT\_ID accordingly as well. About getting document id, please take a look at [Search from Documents](https://docs.allganize.ai/#search-from-documents) or [Documents Feedbacks](https://docs.allganize.ai/#documents-feedbacks) section. ``` curl -X POST -d '{"ids": ["DOCUMENT_ID"]}' \ -H 'API-KEY: YOUR_API_KEY' \ https://backend.alli.ai/webapi/kb_auto_hashtag ``` ### Response Example ``` { "result": { "updated": [ { "id": "S25vd2xlZGdlQmFzZTo1ZmY3Y2U0YzZiNzk4MjM0YTAwNGRkNGE=", "autoHashtags": [ { "id": "S25vd2xlZGdlQmFzZUF1dG9IYXNodGFnOjVmZmRmMDg5ZmMzYjUwNjJlY2ZlZWIzOA==", "state": "SUGGESTED", "bestConfidence": 0.9866862297058105, "autoHashtag": { "hashtag": "CLASSIFICATION_RESULT" } }, { "id": "S25vd2xlZGdlQmFzZUF1dG9IYXNodGFnOjVmZmUwMWFmZTcwZGYzMGUwYzQ2NTQ3Yg==", "state": "SUGGESTED", "bestConfidence": 0.9445914626121521, "autoHashtag": { "hashtag": "CLASSIFICATION_RESULT" } } ] } ] }, "errors": null } ``` ## 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 | 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 | | ------------------------------------------------------ | ----- | ----------------------------------------------------------------------------------------------------------------------------- | | autoHashtagFeedbacks\* | array |

List of JSON objects containing hashtag id/state pairs.
'state' can be one of: 'accepted', 'declined', 'suggested'

| {% tabs %} {% tab title="200 You will get the result in the following JSON format: result: Array of JSON objects, each corresponding to a auto-hashtag id: The id of the hashtag state: The hashtag's feedback from agent. Will be one of: "suggested", "approved", "declined"" %} ``` { "result": [ { "id": "KNOWLEDGE_BASE_AUTO_HASHTAG_ID", "state": "STATE" }, { "id": "KNOWLEDGE_BASE_AUTO_HASHTAG_ID_2", "state": "STATE" } ] } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#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)](https://docs.allganize.ai/api_documentation/#knowledge-base-auto-hashtag-classification) section. ``` curl -X POST -d '{ "autoHashtagFeedbacks": [ {"id": "HASHTAG_ID_1", "state": "approved"}, {"id": "HASHTAG_ID_2", "state": "declined"} ] }' \ -H 'API-KEY: YOUR_API_KEY' \ https://backend.alli.ai/webapi/kb_auto_hashtag_feedback ``` ### Response Example ``` { "result": [ { "id": "S25vd2xlZGdlQmFzZUF1dG9IYXNodGFnOjVmZjhmZmJlYzJkNmUyNjJkOTVlZTQyYg==", "state": "approved" }, { "id": "S25vd2xlZGdlQmFzZUF1dG9IYXNodGFnOjVmZjhmZTdmYzJkNmUyNjJkOTVlZTI5OQ==", "state": "declined" } ] } ``` ## 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 | 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 | | ---------------------------------------- | ------ | ------------------------------------------------ | | hashId\* | string | The id of the Q\&A search return result | | id\* | string | The id of the FAQ that you would like to select. | {% tabs %} {% tab title="200 You will get the result in the following JSON format: In case of success" %} ``` {"result": "Success"} ``` {% endtab %} {% tab title="404 In case you provide an invalid FAQ" %} ``` {"result": [], "error": "Record does not exist."} ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. Please replace FAQ\_ID accordingly as well. About getting FAQ ids, please take a look at [Search from Q\&A](https://docs.allganize.ai/api_documentation/#search-from-q-and-a) section. ``` curl -X POST -d '{ "id": "FAQ_ID", "hashId": "Hash ID from Q&A search result" }' \ -H 'API-KEY: YOUR_API_KEY' \ https://backend.alli.ai/webapi/faq/select_answer ``` ### Response Example ``` { "result": "Success" } ``` ## Agent Management `POST` `https://backend.alli.ai/webapi/agent_management` Used to create and delete agents from the project. #### 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 | | -------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | {% tabs %} {% tab title="200 id: ID of agent that was deleted/created status: What happened (either "deleted" or "created")" %} ``` { "result": { "id" : "QWdlbnQ6NWZkMmFjMzIwODQ4MzY1ZDI4NWFjMGUw", "status": "deleted" }, "errors": null } ``` {% endtab %} {% tab title="400 If the agent you try to create already has an email registered." %} ``` { "result": [], "errors": "Agent with provided email already exists." } ``` {% endtab %} {% tab title="404 If you try to delete an agent that doesn't exist." %} ``` { "result": [], "errors": "The record does not exist." } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl https://backend.alli.ai/webapi/agent_management \ -d '{"email": "1234@gmail.com", "deleteFlag": true, "password": "Password_4321", "locale": "en"}' \ -H "Content-Type: application/json" \ -H "API-KEY: YOUR_API_KEY" ``` ### Response Example ``` { "result": { "id" : "QWdlbnQ6NWZkMmFjMzIwODQ4MzY1ZDI4NWFjMGUw", "status": "created" }, "errors": null } ``` ## Get All Hashtags `GET` `https://backend.alli.ai/webapi/hashtags` Gets all hashtags from both FAQs and MRCs #### Headers | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------------------- | | API-KEY\* | string | Your API key can be found in your dashboard Settings menu, under the General tab. | {% tabs %} {% tab title="200 Returns each hashtag with its count of uses" %} ``` { "result": { "sample_tag1": 2, "sample_tag2": 1, } } ``` {% endtab %} {% endtabs %} ### Request Example Please replace YOUR\_API\_KEY with your one in the example below. To get the api key, please see [getting-api-key](https://docs.allganize.ai/#getting-api-key) section. ``` curl -X GET \ -H "API-KEY: YOUR API KEY" \ https://backend.alli.ai/webapi/hashtags ``` ### Response Example ``` { "result": { "sample_tag1": 2, "sample_tag2": 1, } } ``` ## 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 | Name | Type | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 Each query will have the following attributes: agent: an object which contains the id of the agent who made the query. question: The question actually asked in the query answers: All answers provided by the system to the query. Each answer has the Q\&A that was referred to, and the confidence, effective confidence. There is also a count of how many queries were returned in a count field." %} ``` { "result": { "histories": [ { "agent": { "id": "QWdlbnQ6NjA0NmMyNWJmNTFjMmVlYjc4Mjg3Zjcy" }, "question": "What is life?", "answers": [ { "faq": { "id": "RkFROjYwNDZjMmUxM2MzYmQ5MjVmMzgxMGNkOQ==" }, "effectiveConfidence": 0.9999999999999927, "confidence": 0.9999999999999927 } ] } ], "count": 1 }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example ``` curl -X GET \ -d { "startDate":"2021-02-19","endDate":"2021-02-23", \ "order": "DESC","searchTerm":"life", "limit": 1, "offset": 0 } \ -H 'API-KEY: YOUR_API_KEY' \ https://backend.alli.ai/webapi/faq_histories ``` ### Response Example ``` { "result": { "histories": [ { "agent": { "id": "QWdlbnQ6NjA0NmMyNWJmNTFjMmVlYjc4Mjg3Zjcy" }, "question": "What is life?", "answers": [ { "faq": { "id": "RkFROjYwNDZjMmUxM2MzYmQ5MjVmMzgxMGNkOQ==" }, "effectiveConfidence": 0.9999999999999927, "confidence": 0.9999999999999927 } ] } ], "count": 1 }, "errors": null } ``` ## 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 | Name | Type | Description | | ---------- | ------- | ---------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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. | {% tabs %} {% tab title="200 Each query history will have the following attributes: agent: The id of the agent who made the request. question: The actual question asked. answers: A list of all possible answers provided. Each answer has the knowledgeBase used to source that answer (both the filename and the id), the actual answer itself, the answerFormat, the hashtags associated with the knowledgeBase that was retrieved, and whether feedbackAvailable for this specific answer." %} ``` { "result": { "histories": [ { "agent": { "id": "QWdlbnQ6NWZiNzc5MGIwZjE3Zjc5ZmNiNzVlYzFh" }, "question": "program memory of c004", "answers": [ { "knowledgeBase": { "id": "S25vd2xlZGdlQmFzZTo2MDUyODM0ODFiYzgxNDcwZTEzNGRjNDQ=", "fileName": "specification_en.pdf" }, "answer": "{\"blocks\": [{\"key\": \"kn13\", \"type\": \"unstyled\", \"text\": \"Type capacity program memory program memory - C004, B04KR: 80KB\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}, {\"key\": \"2vjf\", \"text\": \" \", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}, {\"key\": \"45cb\", \"text\": \"— From specification_en.pdf\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [{\"offset\": 0, \"length\": 27, \"style\": \"ITALIC\"}], \"entityRanges\": [{\"offset\": 7, \"length\": 20, \"key\": 0}], \"data\": {}}], \"entityMap\": {\"0\": {\"type\": \"LINK\", \"mutability\": \"MUTABLE\", \"data\": {\"url\": \"https://staging-download.alli.ai/download_document/UHJvamVjdDo1ZmI3NzkwYjBmMTdmNzlmY2I3NWVjMWM=/S25vd2xlZGdlQmFzZTo2MDUyODM0ODFiYzgxNDcwZTEzNGRjNDQ=\"}}}}", "answerHash": "6648c76e9be27864557f84ab7822cde8", "answerFormat": "DRAFTJS", "hashtags": [], "feedbackAvailable": true, "columnFilterValues": [] }, ... { "knowledgeBase": { "id": "S25vd2xlZGdlQmFzZTo2MDUyODM0ODFiYzgxNDcwZTEzNGRjNDQ=", "fileName": "specification_en.pdf" }, "answer": "{\"blocks\": [{\"key\": \"87us\", \"type\": \"unstyled\", \"text\": \"Type capacity reload memory reload memory - C004, B04KR: 2048KB\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}, {\"key\": \"p0wr\", \"text\": \" \", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}, {\"key\": \"qpau\", \"text\": \"— From specification_en.pdf\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [{\"offset\": 0, \"length\": 27, \"style\": \"ITALIC\"}], \"entityRanges\": [{\"offset\": 7, \"length\": 20, \"key\": 0}], \"data\": {}}], \"entityMap\": {\"0\": {\"type\": \"LINK\", \"mutability\": \"MUTABLE\", \"data\": {\"url\": \"https://staging-download.alli.ai/download_document/UHJvamVjdDo1ZmI3NzkwYjBmMTdmNzlmY2I3NWVjMWM=/S25vd2xlZGdlQmFzZTo2MDUyODM0ODFiYzgxNDcwZTEzNGRjNDQ=\"}}}}", "answerHash": "9537b6560701930d079f39ced8be1b3e", "answerFormat": "DRAFTJS", "hashtags": [], "feedbackAvailable": true, "columnFilterValues": [] } ] } ], "count": 1 }, "errors": null } ``` {% endtab %} {% endtabs %} ### Request Example ``` curl -X GET \ -d { "startDate":"2021-02-19","endDate":"2021-02-23", \ "order": "DESC","searchTerm":"life", "limit": 1, "offset": 0 } \ -H 'API-KEY: YOUR_API_KEY' \ https://backend.alli.ai/webapi/mrc_histories ``` ### Response Example ``` { "result": { "histories": [ { "agent": { "id": "QWdlbnQ6NWZiNzc5MGIwZjE3Zjc5ZmNiNzVlYzFh" }, "question": "program memory of c004", "answers": [ { "knowledgeBase": { "id": "S25vd2xlZGdlQmFzZTo2MDUyODM0ODFiYzgxNDcwZTEzNGRjNDQ=", "fileName": "specification_en.pdf" }, "answer": "{\"blocks\": [{\"key\": \"kn13\", \"type\": \"unstyled\", \"text\": \"Type capacity program memory program memory - C004, B04KR: 80KB\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}, {\"key\": \"2vjf\", \"text\": \" \", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}, {\"key\": \"45cb\", \"text\": \"— From specification_en.pdf\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [{\"offset\": 0, \"length\": 27, \"style\": \"ITALIC\"}], \"entityRanges\": [{\"offset\": 7, \"length\": 20, \"key\": 0}], \"data\": {}}], \"entityMap\": {\"0\": {\"type\": \"LINK\", \"mutability\": \"MUTABLE\", \"data\": {\"url\": \"https://download.alli.ai/download_document/UHJvamVjdDo1ZmI3NzkwYjBmMTdmNzlmY2I3NWVjMWM=/S25vd2xlZGdlQmFzZTo2MDUyODM0ODFiYzgxNDcwZTEzNGRjNDQ=\"}}}}", "answerHash": "6648c76e9be27864557f84ab7822cde8", "answerFormat": "DRAFTJS", "hashtags": [], "feedbackAvailable": true, "columnFilterValues": [] }, ... { "knowledgeBase": { "id": "S25vd2xlZGdlQmFzZTo2MDUyODM0ODFiYzgxNDcwZTEzNGRjNDQ=", "fileName": "specification_en.pdf" }, "answer": "{\"blocks\": [{\"key\": \"87us\", \"type\": \"unstyled\", \"text\": \"Type capacity reload memory reload memory - C004, B04KR: 2048KB\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}, {\"key\": \"p0wr\", \"text\": \" \", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [], \"entityRanges\": [], \"data\": {}}, {\"key\": \"qpau\", \"text\": \"— From specification_en.pdf\", \"type\": \"unstyled\", \"depth\": 0, \"inlineStyleRanges\": [{\"offset\": 0, \"length\": 27, \"style\": \"ITALIC\"}], \"entityRanges\": [{\"offset\": 7, \"length\": 20, \"key\": 0}], \"data\": {}}], \"entityMap\": {\"0\": {\"type\": \"LINK\", \"mutability\": \"MUTABLE\", \"data\": {\"url\": \"https://download.alli.ai/download_document/UHJvamVjdDo1ZmI3NzkwYjBmMTdmNzlmY2I3NWVjMWM=/S25vd2xlZGdlQmFzZTo2MDUyODM0ODFiYzgxNDcwZTEzNGRjNDQ=\"}}}}", "answerHash": "9537b6560701930d079f39ced8be1b3e", "answerFormat": "DRAFTJS", "hashtags": [], "feedbackAvailable": true, "columnFilterValues": [] } ] } ], "count": 1 }, "errors": null } ``` ## View User Information `GET` `https://backend.alli.ai/webapi/users` Check the OWN-USER-ID, CUSTOMER GROUP, and email of a user #### Query Parameters | Name | Type | Description | | --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | 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 | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------------------- | | API-KEY\* | string | Your API key can be found in your dashboard Settings menu, under the General tab. | {% tabs %} {% tab title="200 Results are shown in the JSON format as shown below" %} ``` { "result": [ { "id": "1" "email": "example_1@email.com", "customerGroup": { "id": "B3D0ZWdvcnlFbGVtZW50OjYzNzcyZDY1NWM5ZDIxMTU5NDMwZDY1OA==", "value": "IT", } }, { "id": "2" "email": "example_2@email.com", "customerGroup": { "id": "X2F0ZWdvcnlFbGVtZW50OjYzNzcyZDY1NWM5ZDIxMTU5NDMwZDY1OC==", "value": "QA", } } ], "totalCount": 10 "count": 2 } ``` {% endtab %} {% endtabs %} ### Request Example ``` curl -L -X GET 'https://backend.alli.ai/webapi/users' \ -H 'API-KEY: YOUR_API_KEY' ``` ### Response Example ``` { "result": [ { "id": "1" "email": "example_1@email.com", "customerGroup": { "id": "B3D0ZWdvcnlFbGVtZW50OjYzNzcyZDY1NWM5ZDIxMTU5NDMwZDY1OA==", "value": "IT", } }, { "id": "2" "email": "example_2@email.com", "customerGroup": { "id": "X2F0ZWdvcnlFbGVtZW50OjYzNzcyZDY1NWM5ZDIxMTU5NDMwZDY1OC==", "value": "QA", } } ], "totalCount": 10 "count": 2 } ``` ## 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 | Name | Type | Description | | --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | 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 | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------------------- | | API-KEY\* | string | Your API key can be found in your dashboard Settings menu, under the General tab. | {% tabs %} {% tab title="200 Results are shown in the JSON format as shown below" %} ``` { "result": { "id": "123" "email": "abc@email.com", "customerGroup": { "id": "Q2F0ZWdvcnlFbGVtZW50OjYzNzcyZDY1NWM5sXIxMTU5NDMwZDY1OA==", "value": "IT", } } } ``` {% endtab %} {% endtabs %} ### 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 ``` curl -L -X GET 'https://backend.alli.ai/webapi/user/{OWN-USER-ID}' \ -H 'API-KEY: YOUR_API_KEY' ``` ### Response Example ``` { "result": { "id": "123" "email": "abc@email.com", "customerGroup": { "id": "Q2F0ZWdvcnlFbGVtZW50OjYzNzcyZDY1NWM5sXIxMTU5NDMwZDY1OA==", "value": "IT", } } } ``` ## 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 | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | 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 | 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 | | ------------------------------------ | ------ | ---------------------------------------------------- | | id\* | string | ID of 'CUSTOMER\_GROUP' or 'CUSTOMER\_ID' to change. | {% tabs %} {% tab title="200 Results are shown in the JSON format as shown below" %} ``` { "result": { "id": "123" "email": "sdf@sdf.ca", "customerGroup": { "id": "123", "value": "123", } } } ``` {% endtab %} {% endtabs %} ### 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. ``` curl -L -X POST 'https://backend.alli.ai/webapi/user/{OWN-USER-ID}/customer_variable/{variableName}' \ -H 'Content-Type: application/json' \ -H 'API-KEY: YOUR_API_KEY' \ -d '{ "id": "{id}" }' ``` ### Response Example ``` { "result": { "name": "CUSTOMER_ID", "type": "STRING" "id": "60091782", "value": "60091782" } } ``` ## CUSTOMER GROUP Query `GET` `https://backend.alli.ai/webapi/customer_variable/{variableName}/customer_group/category_elements` Check the registered CUSTOMER GROUP #### Headers | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------------------- | | API-KEY\* | string | Your API key can be found in your dashboard Settings menu, under the General tab. | {% tabs %} {% tab title="200 Results are shown in the JSON format as shown below" %} ``` { "result": [ { "id": "RkFROjVkZDQ4ZWFhN2E4ZGM2M2Y4OGNhZmUzOa==", "value": "IT", }, { "id": "RkFROjVkZDQ4ZWFhN2E4ZGM2M2Y4OGNhZmUzOb==", "value": "QA", }, ] } ``` {% endtab %} {% endtabs %} ### Request Example ``` curl -L -X GET 'https://backend.alli.ai/webapi/customer_variable/{variableName}/customer_group/category_elements' \ -H 'API-KEY: YOUR_API_KEY' ``` ### Response Example ``` { "result": [ { "id": "RkFROjVkZDQ4ZWFhN2E4ZGM2M2Y4OGNhZmUzOa==", "value": "IT", }, { "id": "RkFROjVkZDQ4ZWFhN2E4ZGM2M2Y4OGNhZmUzOb==", "value": "QA", }, ] } ``` ## Create CUSTOMER GROUP `POST` `https://backend.alli.ai/webapi/customer_variable/{variableName}/customer_group/category_element` Create CUSTOMER GROUP #### 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 | | --------------------------------------- | ------ | ------------------------------------- | | value\* | string | The name of the CUSTOMER GROUP to add | {% tabs %} {% tab title="200 Results are shown in the JSON format as shown below" %} ``` { "result": { "id": "category_element_id" "value": "sample_category_element" } } ``` {% endtab %} {% endtabs %} ### Request example{variableName} ``` curl -L -X POST 'https://backend.alli.ai/webapi/customer_variable/{variableName}/category_element' \ -H 'Content-Type: application/json' \ -H 'API-KEY: YOUR_API_KEY' \ -d '{ "value": "sample_category_element" }' ``` ### Response example ``` { "result": { "id": "category_element_id" "value": "sample_category_element" } } ``` ## Update CUSTOMER GROUP `POST` `https://backend.alli.aiwebapi/customer_variable/{variableName}/category_element/{categoryElementId}` Update CUSTOMER GROUP #### Path Parameters | Name | Type | Description | | --------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | categoryElementId\* | string | The ID of the CUSTOMER GROUP you want to update. You can obtain it by using the CUSTOMER GROUP query API. | #### 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 | | --------------------------------------- | ------ | ---------------------------------------- | | value\* | string | The name of the CUSTOMER GROUP to change | {% tabs %} {% tab title="200 Results are shown in the JSON format as shown below" %} ``` { "result": { "id": "category_element_id" "value": "sample_category_element" } } ``` {% endtab %} {% endtabs %} ### 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. ``` curl -L -X POST 'https://backend.alli.ai/webapi/customer_variable/{variableName}/customer_group/category_element/{categoryElementId}' \ -H 'Content-Type: application/json' \ -H 'API-KEY: YOUR_API_KEY' \ -d '{ "value": "sample_category_element" }' ``` ### Response Example ``` { "result": { "id": "category_element_id" "value": "sample_category_element" } } ``` ## Delete CUSTOMER GROUP `DELETE` `https://backend.alli.aiwebapi/customer_variable/{variableName}/category_element/{categoryElementId}` Delete CUSTOMER GROUP #### Path Parameters | Name | Type | Description | | --------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | categoryElementId\* | string | The ID of the CUSTOMER GROUP you want to delete. You can obtain it by using the CUSTOMER GROUP query API. | #### Headers | Name | Type | Description | | ----------------------------------------- | ------ | --------------------------------------------------------------------------------- | | API-KEY\* | string | Your API key can be found in your dashboard Settings menu, under the General tab. | {% tabs %} {% tab title="200 Results are shown in the JSON format as shown below" %} ``` {} ``` {% endtab %} {% endtabs %} ### 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. ``` curl -L -X DELETE 'https://backend.alli.ai/webapi/customer_variable/{variableName}/customer_group/category_element/{categoryElementId}' \ -H 'API-KEY: YOUR_API_KEY' ``` ### 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:

| ### Request Example paragraphIndex from `webapi/mrc` ```json { "inputs": [ { "documentId": "DOCUMENT_ID", "pageNo": 130, "paragraphIndex": 1934 }, { "documentId": "DOCUMENT_ID", "pageNo": 33, "paragraphIndex": 367 }, { "documentId": "DOCUMENT_ID", "pageNo": 85, "paragraphIndex": 1239 } ] } ``` ### **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. ```json { "result": [ { "documentId": "DOCUMENT_ID", "title": "DOCUMNET_TITLE", "pageNo": PAGE_NUMBER, "pdfPreview": { "pdfUrl": "PDF_ACTUAL_URL" "pdfs": [ { "pdfUrl": "PDF_ACTUAL_URL", "pageNo": 1, "highlightIndexes": [ 12 ] }, { "pdfUrl": "PDF_ACTUAL_URL", "pageNo": 2, "highlightIndexes": [ 12, 13, 14 ] } ], "totalPageNo": 10, "previewUrl": "PDF_PREVIEW_URL" }, "htmlPreview": { "body": "HTML_BODY", "css": "HTML_CSS" } } ] }// Some code ``` *** ## API Classifications View the API classifications and mapping for billing purposes. Download the Excel file [here](https://docs.google.com/spreadsheets/d/1ZwXQjvJFfnH2V-ynOa3Jc7ixgR0yn7WK0ptvtZp8HOY/export?format=xlsx) {% embed url="" %}