Book demo
Start trial
Book demo
Start trial

 

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 later in this document. The REST API exposes its endpoint on the default port 9001, but the port can be manually configured as needed.

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

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

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

2. Accessing the API

The API can be accessed on the LEAPWORK Controller at 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 v3 in the base URL.

2.1 Access Keys

An access key is required to access any of the endpoints, to restrict unauthorized access to APIs. The access keys should be considered confidential, share with caution.

Access keys are created and maintained and are to be used in any requests to the APIs, as described in the following steps.

2.1.1 Managing Access Keys

Only the Administrator role has privileges to manage API access keys.

To create a new API access key, perform the following steps:

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

The new access key can now be found in the Access Key column list.

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 into e-mails, chats, etc.

For best practice, generate an individual access key per system to use an API. 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 LEAPWORK audit log.

This also allows administrators to block/delete a specific access key, preventing 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 a 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 a 401 – Unauthorized message.

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

The following 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, such as 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 commonly used for integration with a Continuous Integration (CI) system to trigger the collections of automation cases, as part of a greater release plan.

When configuring a schedule in 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 name 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. For example, to check if the schedule can be started in a different environment.
Stop Schedule By Schedule ID PUT /api/v3/schedules/{scheduleId}/stop Stops a currently 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 a currently 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 an ID list of the RunItems generated by a scheduled run, as identified by the {runId}.
Get Run Item By ID GET /api/v3/runItems/{runItemId} Returns detailed information about the 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, for example, starting an application, clicking a button, etc.

This endpoint returns a list of keyframes for the run of a flow, as identified by the RunItemId, with the option of specifying a number of keyframes to offset against the list.
Get Run Ids by Schedule Id GET /api/v3/schedules/{scheduleId}/runIds Returns a list of IDs from the run instances generated by a schedule, as identified by the {scheduleId}.
Re-Run by Run ID PUT /api/v3/run/{scheduleId}/runNow Re-triggers a schedule identified by the runId. The response is a new runId, which is a unique value for the specific run. 
Get Run Item Video GET /api/v3/runItems/{runitemId}/video  Get Run Item Video endpoint returns a video file, identified by the RunItemId.
Get Run Item Screenshot By ScreenshotId

GET /api/v3/runItems/{runitemId}/

screenshot/{screenshotId}

Get Run Item Screenshot By ScreenshotId endpoint returns an image captured as a screenshot (log screenshot) in a flow identified by the RunItemId.

 

4 Accessing Global Variables

Endpoint URL Description
Get All Variables GET /api/v3/variables Returns a 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}.

 

5 Import/Export

Endpoint URL Description
Get Hierarchy GET /api/v3/hierarchy/{itemId} Returns a hierarchical list of the Asset Menu. The returned hierarchy contains detailed information about the following types of items: Folder, Flow, DataFile, etc.
Export GET /api/v3/export/{timeoutMinutes}/{targetItemId)} Get Export endpoint returns a zip file containing all assets (Folder, Flow, DataFile, SubFlow, etc.) on the basis of an itemId.
Import GET /api/v3/import/{timeoutMinutes}/{targetItemId)} Import endpoint is used to import previously exported zip files to the Controller. This endpoint can be used to move flows from one Controller to another.