Botminds REST API reference

20 June 2021

REST 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:

  1. 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 or https.
    • 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.
  2. 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.
  3. 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 as application/json.
  4. 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.
  5. 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 the Content-type response header. For example, when you request an access 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 of Content-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.

  • 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/token endpoint to obtain a access token in response to user sign-in/consent.

URL https://portal.botminds.ai/a/webapi/api/account/token
Type POST
Request Headers
{
    "Content-Type": "application/json"
}

Request Payload
{
    Password: "{{password}}",
    UserName: "{{user-email}}",
    grant_type: "password"
}

Response
{
    UserName: "{{user-email}}",
    AccessToken: "{{bearer-token}}",
    ...........
}

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/token", 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
{
    "SubscriptionId": "{{subscription-id}}",
    "FinonId": "{{project-id}}",
    "Authorization": "Bearer {{bearer-token}}",
    "Content-Type": "application/json"
}

Request Payload
{
    "FinonId": "{{project-id}}",
    "Kind": 11,
    "MaxContentPageToFetch": 100,
    "Name": "{{source-name}}(optional)",
    "Priority": 0,
    "SubscriptionId": "{{subscription-id}}"
}

Response
{
    "AccessKey": "{{access-key}}",
    "FinSeedId": "{{project-id}}-{{created-source-id}}"
    "Name": "{{source-name}}",
    ...........
}

2. 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
{
    "SubscriptionId": "{{subscription-id}}",
    "FinonId": "{{project-id}}",
    "Authorization": "Bearer {{bearer-token}}",
    "Content-Type": "multi-part form"
}

Payload
{
    "file": "{{file-path}}",
    "AccessKey": "{{access-key}}"
}

Response
{
    "Success": true | false,
    "JobId": "{{job-id}}",
    "Message": "success | failure message"
    ...........
}

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
{
    "SubscriptionId": "{{subscription-id}}",
    "FinonId": "{{project-id}}",
    "Authorization": "Bearer {{bearer-token}}",
    "Content-Type": "application/json"
}

Payload
{
    "JobId": "{{job-id}}",
    "AccessKey": "{{access-key}}"
}

Response
{
    "Status": InProgress | Completed | .... | Failed,
    "ProcessedDocumentIds": ["{Document1-Id}','{Document2-Id}',...],
    "Message": "success | failure message"
    ...........
}

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
{
    "SubscriptionId": "{{subscription-id}}",
    "FinonId": "{{project-id}}",
    "Authorization": "Bearer {{bearer-token}}",
    "Content-Type": "application/json"
}

Payload
{
    "FinonId": "{{project-id}}",
    "Count": "{{documents-count}}",
    "PageNumber": "{{page-number}}",
    "StartDate": "{{date-range-start-date}}",
    "EndDate": "{{date-range-end-date}}",
    "AssignedWorkflowStageId": {{list-of-work-flow-stage-id}}
    "AssignedUserEmail": {{list-of-project-users}}
}

Response
{
    "Documents": {{list-of-document-meta-information}},
    "OverallCount": {{documents-count-matching-the-filters}}
    ...........
}

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
{
    "SubscriptionId": "{{subscription-id}}",
    "FinonId": "{{project-id}}",
    "Authorization": "Bearer {{bearer-token}}",
    "Content-Type": "application/json"
}

Payload
{
    "AccessKey": "{{access-key}}",
    "DocId": "{{doc-id}}"
}

Response
{
    "Success": true | false,
    "Summary": {
    	"Title: "{{document-title}}",
        "Url": "{{document-url}}",
        "Summary": {{taxonomy-wise-summary}}
    },
    "Message": "success | failure message"
    ...........
}

Request a Demo

See Botminds Unified platform in action

Please fill all form fields, to successfully submit the form