API Task real-time endpoint

Instantly invoke API Tasks with a real-time endpoint. You can generate an API Task execution URL along with a token to start an API Task execution through an API endpoint.

Key benefits

  • Programmatic deployment: Invoke API Task from anywhere real-time using your preferred API client.
  • Response time: Designed for low latency with near real-time response rates, aiming to provide responses almost instantly (typically within milliseconds).
  • Processing:
    • Automations are loaded into cloud and ready to accept requests at all times. This allows for quick processing and response.
    • Premium license helps to scale your automation and provide access to a larger pool of cloud resources that can execute multiple instances of your API Task, boosting concurrency and enabling you to handle more API Task requests simultaneously.
  • Use cases:
    • Ideal for interactive situations like chatbots
    • real-time fraud detection
    • Online case creations
    • or any use case where instant response is crucial

Prerequisites

The following sample code snippets provide you with a procedure to deploy an API Task real-time to a cloud device. You can also pass variables to API Tasks when they are deployed.

Step 1: Authenticate
Authenticate access to your Control Room instance.
Step 2: Create an API Task allocation (admin)
An admin can create an API Task allocation.
Step 3: (Optional) List API Task allocation (admin)
An admin can list all the API Task allocations.
Step 4: Generate Task Execution URL/Token
Generate the URL and Token to deploy your API Task.
Step 5: Execute API Task
Execute your API Task with the unique URL generated along with the token..

Authenticate

Authenticate to get access to your environment. This commonly involves access tokens or API keys. 

POST https://{{ControlRoomURL}}v1/authentication
Header: X-Authorization: <<authentication token>> or Authorization: Bearer <<b
earer token>>

There are two distinct authentication flows for interacting with the API Task real-time endpoint:

1. Bot Developer Authentication (API Task Execution):

This flow allows bot developers to generate a URL and token (Generate Task Execution URL/Token) for executing an API Task (Execute API Task).

All API calls must contain either an authentication token from Authentication API (generates JSON Web token) or a bearer token from OAuth services. You cannot use both together in an API.

2. Admin Authentication (API Task Allocation):

This authentication is required for administrators to allocate (Create an API Task allocation (admin)) the API Task in the cloud, so that a bot developer will be able to execute the API Task.

Create an API Task allocation (admin)

Note: You need admin rights to create an API Task allocation.

After an API Task is checked-in, you can add the API Task to cloud. This API endpoint adds the API Task to cloud and creates a resource allocation for your API Taskto run. The corresponding section that details the API Task allocation within the Control Room is Add API Task to Cloud. The API Task allocation is done after an API Task is created. For more information creating an API Task, see Create an API Task (API Task in form). 

PUT https://{{ControlRoomURL}}orchestrator/v1/hotbot/config/create
Request body:
{
  "fileId": "5",
  "runAsUserOrNone": 3,
  "concurrencyLimit": 2
}
Response:
{
  "fileId": "5",
  "runAsUserOrNone": 3,
  "concurrencyLimit": 2
}
Request/Response parameters
Parameter Type Required Description
fileId Integer Yes

ID of the automation to be deployed.
runAsUserOrNone Integer No The apitaskrunner to establish the RunAsUser context for API Tasks. For more information on apitaskrunner, see Run as user for API Task (apitaskrunner).
Note: This RunAsUser does not require a Bot Runner license.
concurrencyLimit Integer No Maximum number of concurrency to run for a given real-time (hotbot) request.

(Optional) List API Task allocation (admin)

Note: You need admin rights to list the API Tasks allocation.

This API endpoint lists all the API Tasks allocations within your Control Room. You can confirm if a particular API Task is added to the API Task allocation list before proceeding to generate API Task Execution URL with token. 

POST https://orchestrator/v1/hotbot/config
Request body:
{
  "page": {
    "offset": 0,
    "length": 100
  }
}
Request parameters
Parameter Type Required Description
page object No object (PageRequest)

Pagination rules, allows you to filter based on desired page
offset Integer No Page starting index.
length Integer No Page length.
Response:
{
    "list": [
        {
            "fileId": "149",
            "filePath": "Automation Anywhere\\Bots\\Zip Code API Task",
            "fileName": "Zip Code API Task",
            "runAsUserOrNone": "12",
            "concurrencyLimit": 1
        },
        {
            "fileId": "180",
            "filePath": "Automation Anywhere\\Bots\\API_task_String 01 1708025672.bot",
            "fileName": "API_task_String 01 1708025672.bot",
            "runAsUserOrNone": "12",
            "concurrencyLimit": 3
        },
        {
            "fileId": "184",
            "filePath": "Automation Anywhere\\Bots\\API_task_Rest 01 1708026445.bot",
            "fileName": "API_task_Rest 01 1708026445.bot",
            "runAsUserOrNone": "12",
            "concurrencyLimit": 5
        }
    ],
    "page": {
        "offset": 0,
        "total": 3,
        "totalFilter": 3
    }
}
Response parameters
Parameter Type Description
fileId Integer

ID of the automations.
filePath String The file path of the automations
fileName String The file name of the automations.
runAsUserOrNone Integer The apitaskrunner to establish the RunAsUser context for API Tasks. For more information on apitaskrunner, see Add API Task to Cloud.
concurrencyLimit Integer Maximum number of concurrency to run for a given real-time (hotbot) request.

Generate Task Execution URL/Token

This API endpoint generates task execution URL and Token with which you will be able to deploy an API Task. 

POST https://orchestrator/v1/hotbot/config/accessdetails
Request body:
{
  "botRepositoryPath": [
    "Automation Anywhere\\Bots\\My-API-Task"
  ]
}
Request parameters
Parameter Type Required Description
botRepositoryPath String Yes Repository path of the API Task.
Response:
{
  "accessDetails": {
    "Automation Anywhere\\Bots\\My-API-Task": {
      "url": "https://hotbot-2689-knative-0a665343-88e9-17be-8189-936dad5d0144.prod-ause1-ee.my.automationanywhere.digital/execute",
      "headers": {
        "X-Authorization": "eyJhbGciOiJSUzUxMiJ9.eyJzdWIiOiIzODAiLCJ0ZW5hbnRVdWlkIjoiMGE2NjUzNDMtODhlOS0xN2JlLTgxODktOTM2ZGFkNWQwMTQ0IiwiY2xpZW50VHlwZSI6IldFQiIsIm11bHRpcGxlTG9naW4iOnRydWUsImJvdElkIjoyNjg5LCJpYXQiOjE3MDgzNTIxOTgsImV4cCI6MTcwODM5NTM5OCwiaXNzIjoiQXV0b21hdGlvbkFueXdoZXJlIiwibmFub1RpbWUiOjI5OTg3MDkyNzIxNjc5MH0.p8xsnlec7-ZbPJBfDDk1Wq0k8RqAzzsL6bK7BOtLp_jY1NgQvdAO5Yra647-94JV2cY8Vbe5H7zObia3S9oQ9dFXrnmSSSYs3_x7e_-vkaNcwx1Ev3J7lymqnH8Xc73s-TTGyebRlXiI714Ii62DJ_vKBEUvNM47V0H1FQk6xIfpzJAMMDRFZWO3MUvowgD4L-O6xre0RLapCYOSVtH_0CbM0VBfNkuwDAnF1kQeCtpWIvv_nETy7A-UdSox9GqtDp9h2Elkl-v3KJ8kEru7qT4fWZlsuzFPL7XzqkALCP39N7fxOpzlCfHYGPooLRHcFLGIPxpqi1bkfsn-Xk2BfQ"
      }
    }
  },
  "errors": {
  }
}
Response parameters
Parameter Type Description
url String

URL - This is the container endpoint for your next request to deploy your API Task.
X-Authorization String Contains the token that you need to provide in the headers as X-Authorization.
Note:

Once you generate the API Task execution URL as well as the necessary headers to execute the API Task, you can send a deploy requests via the generated URL. If you specify inputs, make sure that for the automation to successfully receive these mapped-in values, the variable for that automation must be marked as input. Additionally, the name of the variable in the automation has to match the value that is being mapped in the request body.

Execute API Task

Execute your API Task with the unique URL generated along with the token. 

POST https://hotbot-2689-knative-0a665343-88e9-17be-8189-936dad5d0144.prod-ause1-ee.my.automationanywhere.digital/execute
Header: X-Authorization: eyJhbGciOiJSUzUxMiJ9.eyJzdWIiOiIzODAiLCJ0ZW5hbnRVdWlkIjoiMGE2NjUzNDMtODhlOS0xN2JlLTgxODktOTM2ZGFkNWQwMTQ0IiwiY2xpZW50VHlwZSI6IldFQiIsIm11bHRpcGxlTG9naW4iOnRydWUsImJvdElkIjoyNjg5LCJpYXQiOjE3MDgzNTIxOTgsImV4cCI6MTcwODM5NTM5OCwiaXNzIjoiQXV0b21hdGlvbkFueXdoZXJlIiwibmFub1RpbWUiOjI5OTg3MDkyNzIxNjc5MH0.p8xsnlec7-ZbPJBfDDk1Wq0k8RqAzzsL6bK7BOtLp_jY1NgQvdAO5Yra647-94JV2cY8Vbe5H7zObia3S9oQ9dFXrnmSSSYs3_x7e_-vkaNcwx1Ev3J7lymqnH8Xc73s-TTGyebRlXiI714Ii62DJ_vKBEUvNM47V0H1FQk6xIfpzJAMMDRFZWO3MUvowgD4L-O6xre0RLapCYOSVtH_0CbM0VBfNkuwDAnF1kQeCtpWIvv_nETy7A-UdSox9GqtDp9h2Elkl-v3KJ8kEru7qT4fWZlsuzFPL7XzqkALCP39N7fxOpzlCfHYGPooLRHcFLGIPxpqi1bkfsn-Xk2BfQ
Request body:
{
   "botInput":{
      "iStrZipCode":{
         "type":"STRING",
         "string":"76131"
      }
   }
}
Request parameters
Parameter Type Required Description
botInput Object
type Any No By default it is STRING. Possible values for type includes: STRING, NUMBER, BOOLEAN, FILE, ITERATOR, LIST, DICTIONARY, TABLE, VARIABLE, CONDITIONAL, WINDOW, TASKBOT, DATETIME, UIOBJECT, RECORD, EXCEPTION, CREDENTIAL, COORDINATE, IMAGE, REGION, PROPERTIES, TRIGGER, CONDITIONALGROUP, FORM, FORMELEMENT, HOTKEY, and WORKITEM.
Response:
{
   "hotBotResult":{
      "botOutput":{
         "State":{
            "type":"STRING",
            "string":"California"
         },
         "Place":{
            "type":"STRING",
            "string":"San Jose"
         }
      }
   }
}
Response parameters
Parameter Type Description
hotBotResult Object

Object containing the API Task output.