The LEAPWORK REST API

1. Introduction

The LEAPWORK Automation Platform comes with a REST API allowing any third party system to run automation flows on the platform and to retrieve the results. The REST API makes it easy to incorporate automated flows as part of any CI/CD pipeline.

The REST API is hosted on the LEAPWORK Controller as outlined in the figure below. The REST API exposes its endpoint on port 9001 per default, but the port can be configured if needed.

The REST API also includes an API explorer, which can be accessed in a browser on the following URL:

http://{controllerMachine}:{controllerPort}/help/index#

This will allow you to easily try out the endpoints in the API and explore results before setting up the actual integration.

2. Accessing the API

The API can be accessed on the LEAPWORK Controller on the following base URL:

http://{controllerMachine}:{controllerPort}/api/v3

Example:

http://myLeapworkController.dom:9001/api/v3

The API is versioned as part of the URL. The current version is version 3, indicated by the “v3” in the base URL.

2.1 Access Keys

An access key is required to access any of the end points to restrict unauthorized access to the API. The access keys should be confidential and shared with caution.

Access keys are created and maintained as described below and are to be used in any requests to the API.

2.1.1 Managing Access Keys

Only the “Administrator” role has the privileges to manage the API Access Keys.

To create a new API Access Key, do the following:

  1. In LEAPWORK Studio, click ‘Settings’ in the main menu.
  2. Select the ‘API Access Keys’ and click ‘Add Key’
  3. In the ‘Add Access Key’ dialog, click ‘Generate key’, to generate a new access key. The access key is a 16-character text string, e.g. ‘Mo87Nc4qDAtzJNDb’
  4. Add a comment to make administration easier, e.g. “Integration from CI/CD pipeline”
  5. Press the ‘Add’ button.

The new access key can now be found in the list of Access Keys.

To distribute an access key, select the access key in the list and press 'Copy'. This will copy the access key to the clipboard for easy insertion in e-mails, chats etc.

Best practice is to generate an individual access key per system that uses the API.

Firstly, this will allow better debugging, as all actions triggered through the API will include the access key used by the system accessing the API, which will show up in the audit log in LEAPWORK.

Secondly, it allows administrators to block/delete a specific access key, to prevent access from a particular source, without affecting other systems using the API.

2.1.2 Using Access Keys

A valid access key needs to be part of all requests to the API.

The access key should be added as a HEADER field named ‘AccessKey’ with the value containing a valid access key.

Example:

'AccessKey: Mo87Nc4qDAtzJNDb'

If the access key is omitted or not valid, the endpoint will return 401 – Unauthorized.

2.1.3 Creating a request to the API

All standard HTTP request types (GET, PUT and POST etc.) are supported by the API. The Accept/Content-type header needs to be set to ‘application/json’ as all input parameters and return values are JSON formatted. Furthermore, the requests need to include a valid API Access Key in the ‘AccessKey’ HEADER field.

Below are some examples of how to access the API from various types of sources.

2.1.3.1 CURL

In this example, the list of available schedules in the LEAPWORK system is requested using curl.

curl -X GET --header 'Accept: application/json' --header 'AccessKey: Mo87Nc4qDAtzJNDb' 'http://{controllerMachine}:{controllerPort}/api/v3/schedules'

2.1.3.2 PowerShell

This Powershell example will retrieve all available schedules in the LEAPWORK system.

$headers = @{}

$headers.Add("AccessKey"," Mo87Nc4qDAtzJNDb")

Invoke-WebRequest -Uri "http://localhost:9001/api/v3/schedules" -ContentType "application/json" -Headers $headers -Method GET

3 Integration Endpoints

Endpoint URL Description
Get All Schedules GET /api/v3/schedules Returns a list of all schedules currently configured on the controller. The returned list of schedules will give access to names and IDs of the schedules which is needed to call other endpoints in the API.
Get Schedule By ID GET /api/v3/schedules/{scheduleId} Returns complete information about a schedule selected by the {scheduleId}. On success the returned response consists of information like ‘Schedule Title’, ‘Id’, ‘DateModify’, ‘DateCreation’, ‘IsEnabled’ etc. This information can be used to get the status of a specific schedule and call other endpoints in the API.
Run Schedule Now PUT /api/v3/schedules/{scheduleId}/runNow Triggers a schedule identified by the {scheduleId}.

This endpoint is used a lot for integration with Continuous integration (CI) system to trigger collections of automation cases as part of a greater release plan.

In the configuration of a schedule using LEAPWORK Studio, it is possible to define variables and assign values to the variables. It is also possible to set the values of the variables using this endpoint, by adding the nae of the variable and the value as GET parameters in the calling URL.
Get Schedule Run Status GET /api/v3/schedules/{scheduleId}/status Returns the execution status of a schedule identified by the {scheduleId}. This endpoint is used to check the current execution state of schedule. E.g. to check if the schedule can be started on a different environment.
Stop Schedule By Schedule ID PUT /api/v3/schedules/{scheduleId}/stop Stops an already running schedule identified by the {scheduleId}. On the successful stop of a schedule, the endpoint will return ‘true’ in the response body.
Stop Schedule By Run ID PUT /api/v3/run/{runId}/stop Stop an already running schedule identified by its {runId}. The {runId} is a unique Id for the individual instance run of a schedule. On successful stop of a run, the end-point will return ‘true’ in the response body.
Get Run Status By Run ID GET /api/v3/run/{runId}/status Returns the run status of a specific scheduled run identified by the {runId}.
Get Run By ID GET /api/v3/run/{runId} Returns all information about a scheduled run identified by the {runId}.
Get Run Items ID by Run ID GET /api/v3/run/{runId}/runItemIds Returns a list of the IDs of the RunItems generated by a scheduled run identified by the {runId}.
Get Run Item By ID GET /api/v3/runItems/{runItemId} Returns detailed information about a run of a flow in a schedule. The run of the flow (RunItem) is identified by the Id of the RunItem.
Get Run Item Keyframes GET /api/v3/runItems/{runItemId}/keyframes/{offset} The complete logging of running a flow consists of a number of keyframes. Each keyframe contains information about a specific point in time in the execution of the flow, i.e. starting an application, clicking a button etc.

This endpoint returns a list of keyframes of a run of a flow identified by the RunItemId, with the option of specifying a number of keyframes to offset to the list with.
Get Run Ids by Schedule Id GET /api/v3/schedules/{scheduleId}/runIds Returns a list of the IDs of the run instances generated by a schedule identified by the {scheduleId}.

 

4 Accessing Global Variables

Endpoint URL Description
Get All Variables GET /api/v3/variables Returns list of all permanent variables. These variables are static across the LEAPWORK Controller and should not be confused with the variables used to trigger a Schedule.
Edit Variable By Name PUT /api/v3/variables Updates the value of a permanent variable identified by the {requestBody}.
Get Variable By Name GET /api/v3/variables/{name} Returns details of a specific permanent variable identified by the variable {name}.