Botminds REST API reference
20 June 2021REST APIs are service endpoints that support sets of HTTP operations (methods), which provide create, retrieve, update, or delete access to the platform. This article walks you through:
- The basic components of a REST API request/response pair.
- Overviews of creating and sending a REST request, and handling the response.
Components of a REST API request/response
An API request/response pair can be separated into five components:
- The request URI, which consists of:
{URI-scheme} :// {URI-host} / {resource-path}
. Although the request URI is included in the request message header, we call it out separately here because most languages or frameworks require you to pass it separately from the request message.- URI scheme: Indicates the protocol used to transmit the request. For example,
http
orhttps
. - URI host: Specifies the domain name or IP address of the server where the REST service endpoint is hosted, such as
portal.botminds.ai
. - Resource path: Specifies the path of the api. For example:
api/seedpage/{project-id}/getjobsforseedpage
be used to query the list a sources crawled owners within the project.
- URI scheme: Indicates the protocol used to transmit the request. For example,
- HTTP request message header fields:
- A required HTTP method (also known as an operation or verb), which tells the service what type of operation you are requesting. Botminds APIs support GET and POST methods.
- Optional additional header fields, as required by the specified URI and HTTP method. For example, an Authorization header that provides a bearer token containing client authorization information for the request.
- Optional HTTP request message body fields, to support the URI and HTTP operation. For example, POST operations contain MIME-encoded objects that are passed as complex parameters. For POST operations, the MIME-encoding type for the body should be specified in the
Content-type
request header as well. Some services require you to use a specific MIME type, such asapplication/json
. - HTTP response message header fields:
- An HTTP status code, ranging from 2xx success codes to 4xx or 5xx error codes.
- Optional additional header fields, as required to support the request's response, such as a
Content-type
response header.
- Optional HTTP response message body fields:
MIME-encoded response objects are returned in the HTTP response body, such as a response from a GET method that is returning data. Typically, these objects are returned in a structured format as JSON, as indicated by theContent-type
response header. For example, when you request anaccess token
, it is returned in the response body as the access_token element, one of several name/value paired objects in a data collection. In this example, a response header ofContent-Type: application/json
is also included.
Create the Request
This section covers the first three of the five components that we discussed earlier. You first need to acquire the access token from Azure AD, which you use to assemble your request message header. To acquire the access token we first need to encrypt the password.
-
Encrypt the password
This endpoint /api/account/encryptText
is used to obtain an encrypted text in response to text.
URL | https://portal.botminds.ai/a/webapi/api/account/encryptText |
Type | POST |
Request Headers |
|
Request Payload |
|
Response |
|
-
Acquire an access token
This grant is used by both web and native clients, requiring credentials from a signed-in user in order to delegate resource access to the client application. It uses the /api/account/login
endpoint to obtain an access token in response to user sign-in/consent.
URL | https://portal.botminds.ai/a/webapi/api/account/login |
Type | POST |
Request Headers |
|
Request Payload |
|
Response |
|
Sample JS Code
var xhr = new XMLHttpRequest();
var params = {grant_type: "password", UserName: "{{user-name}}", Password: "{{password}}"};
xhr.open("POST", "https://portal.botminds.ai/a/webapi/api/account/login", false);
xhr.setRequestHeader('Content-type', 'application/json');
xhr.send(JSON.stringify(params));
-
Assemble the request message
Most programming languages or frameworks and scripting environments make it easy to assemble and send the request message. They typically provide a web/HTTP class or API that abstracts the creation or formatting of the request, making it easier to write the client code (the HttpWebRequest class in the .NET Framework, for example). For brevity, and because most of the task is handled for you, this section covers only the important elements of the request.
-
Request URI
Because sensitive information is being transmitted and received, all REST requests require the HTTPS protocol for the URI scheme, giving the request and response a secure channel. The information (that is access/bearer token and sensitive request/response data) is encrypted by a lower transport layer, ensuring the privacy of the messages.
The remainder of your service's request URI (the host and resource path) are determined by its related REST API specification.
-
Request header
The request URI is bundled in the request message header, along with any additional fields required by your service's REST API specification and the HTTP specification. Your request might require the following common header fields:
Authorization Contains the bearer token to secure the request.
Content-Type Typically set to "application/json" (name/value pairs in JSON format), and specifies the MIME type of the request body.
-
Request body
As mentioned earlier, the request message body is optional, depending on the specific operation you're requesting and its parameter requirements. If it's required, the API specification for the service you are requesting also specifies the encoding and format.
The request body is separated from the header by an empty line, formatted in accordance with the Content-Type
header field. An example of an "application/json" formatted body would appear as follows:
{
"{{name}}": "{{value}}"
}
-
Send the request
Now that you have the service's request URI and have created the related request message header and body, you are ready to send the request to the REST service endpoint.
API List
1. Create Source
This endpoint will create a source config for processing files.
Path - a/webapi/api/seedpage/create
Params:
SubscriptionId - Unique subscription identifier
FinonId - Unique project identifier
Name - Source name (optional)
Kind - Botminds supports 11 different types of source types for processing various types of documents. Use 11 for processing files using file upload
Priority - Botminds supports 3 different priority file process. Use 0 for high priority file process.
MaxContentPageToFetch - Maximum number of documents allowed in a project
URL | https://portal.botminds.ai/a/webapi/api/seedpage/create |
Type | POST |
Request Headers |
|
Request Payload |
|
Response |
|
2.(A) Process File
This endpoint process the files using the source config created above. Use AccessKey
from the previous response.
Path - a/webapi/api/uploadfile
.
Params:
file - File path
AccessKey - Access key of the source config
URL | https://portal.botminds.ai/a/webapi/uploadfile |
Type | POST |
Request Headers |
|
Payload |
|
Response |
|
2.(B) Process Links
This endpoint process the Links using the source config created above. Use AccessKey
from the previous response.
Path - a/webapi/processlink
.
Params:
file - File path
AccessKey - Access key of the source config
URL | https://portal.botminds.ai/a/webapi/processlink |
Type | POST |
Request Payload |
|
Response |
|
3. Check Status
Files uploaded in above step goes through multiple process. So we provide an api to check the status of the file uploaded.
Path - a/webapi/checkjobstatus
.
Params:
JobId - Each file will have unique jobids. Use Job Id from above response
AccessKey - Access key of the source config
URL | https://portal.botminds.ai/a/webapi/checkjobstatus |
Type | POST |
Request Headers |
|
Payload |
|
Response |
|
4. Get the list of processed documents
Get the list of processed documents meta information. This rest api supports pagination. Processed document list can be filtered by dates, users and stages of workflow pipelines.
Path - a/webapi/api/document/documentsearch
Params:
FinonId - Unique project identifier
Count - Number of documents to be fetched
PageNumber - Number for pagination support
StartDate (optional) - Date range filter support
EndDate (optional) - Date range filter support
AssignedWorkflowStageId (optional) - Array of workflow stage ids to be filtered
AssignedUserEmail (optinal) - Array of user emails to be filtered
URL | https://portal.botminds.ai/a/webapi/api/document/documentsearch |
Type | POST |
Request Headers |
|
Payload |
|
Response |
|
5. Get the output JSON for processed document
Get the detailed summary view of the datapoints collected from the document that is processed successfully in json format.
Path - a/webapi/getoutputjson
Params:
DocId - Each document will have unique Document Id. Use ProcessedDocumentIds from above response
AccessKey - Access key of the source config
URL | https://portal.botminds.ai/a/webapi/getoutputjson |
Type | POST |
Request Headers |
|
Payload |
|
Response |
|
6. To view the processed document from Botminds Drive
Get the detailed summary view of the datapoints collected from the document that is processed successfully in Botminds Drive.
Path - a/webapi/api/filedrive/getFiles
Params:
SubscriptionId - Unique subscription identifier
FinonId - Unique project identifier
FolderPath - Folder Path from Botminds Drive
FileName - Access key of the source config
BlobName - Unique file identifier from Botminds Drive
TakeCount - Number of files
URL | a/webapi/api/filedrive/getFiles |
Type | POST |
Request Headers |
|
Payload |
|
Response |
|
7. To download the processed output files from Botminds Drive
Download the detailed summary of the datapoints collected from the document that is processed successfully in Botminds Drive.
Path - a/webapi/api/filedrive/downloadFile/filedrive/{{blobname}}/false
Params:
SubscriptionId - Unique subscription identifier
FinonId - Unique project identifier
BlobName - Unique file identifier taken from GetFiles response
URL | a/webapi/api/filedrive/downloadFile/filedrive/{{blobname}}/false |
Type | GET |
Request Headers |
|
Response |
|
8. To Retrieve Answers to Questions in Chat
Retrieve answers to specific chat questions for a given subscription, project, and prompt.
Path - a/chatllm/qa/
Params:
SubscriptionId - Unique subscription identifier
FinonId - Unique project identifier
PromptId - Unique id of the prompt
Question - Question
ChatHistory - Previous chathistory for the conversational questions. Array of objects with Question and Answer.
URL | a/chatllm/qa |
Type | POST |
Request Headers |
|
Payload |
|
Response |
|