Building API Requests

All Orchestrator API calls are made using HTTP methods to the Orchestrator URL. The Orchestrator URL has the following syntax: https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_ . It is recommended to encrypt the data you send via API calls, by using the HTTPS protocol.

Important:

For accessing resources in a folder, each request must contain either the FolderId, FolderPath, or FolderKey in an HTTP header. This header may be encoded (using Base64 UTF-16LE encoding) or plain text.

For example:

• X-UIPATH-OrganizationUnitId "FolderId",
• X-UIPATH-FolderPath-Encoded "{Encoded FolderPath value}",
• X-UIPATH-FolderPath "PlainText FolderPath value", or
• X-UIPATH-FolderKey "FolderKey".

The FolderId can be obtained by performing a GET request to the /odata/Folders endpoint and copying the "Id" value, or from the Orchestrator URL - https://your-domain-server.com/? fid=2032 &tid=8. FolderId is of type Int 64.

The FolderKey can be obtained by performing a GET request to the /odata/Folders endpoint and copying the "Key" value. FolderKey is of type Unique Id/String.

If you change the licensing plan for your Orchestrator account (for example, from Enterprise Trial to Enterprise), the FolderId value also changes, whereas the FolderKey value remains the same.

If you upgraded and had Organization Units enabled in your previous Orchestrator instance, each OU is migrated as a new Classic folder.

Relative folder paths are supported in an X-UIPATH-FolderPath-Encoded header, as follows:

• Path starting with / - starts from the root folder of the tree the ambient folder is part of.
• Path starting with . - starts from the ambient folder.
• Path starting with .. - starts one level up in the hierarchy of the ambient folder for each .. in the path (e.g. ../ for one level up, ../../ for two levels up in the hierarchy).

Note that trailing slashes are not accepted.

Important: When using the Orchestrator API in conjunction with MSXML, the 204 No Content response may result in a 1223 Status Code and cause errors.

GET Requests

GET requests are usually the simplest ones to make. They help you retrieve data and use generic OData clauses:

• $top
• $filter
• $expand
• $select
• $orderby
• $skip

$top

This clause helps you limit the amount of data you retrieve. It has an upper cap that is determined by the endpoint you are making calls to and the number of such resources that exist on you Orchestrator instances.

For example, this request https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$top=10 returns the first 10 environments available in the Community Edition of Orchestrator. However, if only 5 environments exist, only those are retrieved.

$filter

This OData clause is used to filter a specific resource according to its properties.

For example, one can filter according to:

• numeric properties:
  • https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$filter=Id%20eq%2015 - requests a specific environment based on its Id
• text properties:
  • https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Environments?$filter=contains(Name,'N')&$top=10 - returns the first 10 environments whose name contains the letter "N"
• boolean properties:
  • https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Processes?$filter=Title%20eq%20'test'%20%26%20IsLatestVersion%20eq%20true - returns all processes that contain the word "test" and represent the latest version
• enumerable properties:
  • https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/QueueItems?$filter=Priority%20eq%20'High' - returns all queue items that have a High priority
• the propery of a property:
  • https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Jobs?$top=10$filter=Robot/MachineName%20eq%20'Documentation' - returns the first 10 jobs that were executed by any Robot that exists on the "Documentation" machine

Filter parameters can be combined using logical operators "and", "or" and/or "not" and can be grouped with parentheses "( )", such as the following request:

• https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Jobs?$top=10&$filter=Robot/MachineName eq 'LAVINIA-PC' and (not(Source eq 'Manual') or StartTime gt 2017-10-28T12:13:00.07Z) - displays the top 10 jobs that are being executred manually or after "2017-10-28T12:13:00.07Z", by a Robot deployed on the "LAVINIA-PC" machine.

Known issue

OData $filter queries containing an expression that compares a nested complex object to null do not work. For example, using the Release ne null expression returns an error, because Release is a complex object which includes its own nested properties.

In such cases, we recommend replacing the complex object with a simple object.

Examples:

• You can replace Release ne null with ReleaseName ne null, as ReleaseName is an existing simple object.
  Note: You cannot replace Machine ne null with MachineName ne null, as MachineName does not exist.
• You can use a nested property on the complex object for comparison. For instance, Release/Name ne null can replace Release ne null, and Machine/Name ne null can replace Machine ne null.

$expand

This clause is used to fully load navigation properties of the requested resource.

$select

This OData clause enables you to specify a subset of resource properties that you want to be returned. If you want to extract multiple resources, you can separate them by using a comma.

$orderby

The $orderby clause enables you to sort retrieved resources. As with the $select clause, the resources you want to order by are separated by commas, and they can be sorted in an ascending (asc) or descending (desc) order. If neither of these operators are specified, resources are automatically sorted in an ascending manner.

$skip

This clause enables you to skip the first n number of items, in an indicated filter.

POST Requests

The POST HTTP verb helps you create new items, subordinate to other resources. When creating a new resource, POST to the parent, and Orchestrator takes care of associating the new resource with the parent, assigning an ID, and other required information. The data is added through the body of the request, and the response is the entire created object.

You can add new items to a queue, create new assets, environments or processes, assign a reviewer to one or multiple failed transactions, and the list goes on.

Note: Special characters cannot be escaped in the body of POST requests. To use special characters you need to first declare the parameter you use them in as string, using the following format "[e-mail]": "#String". For a better understanding, please see how the Specific Content parameter was populated in the example below.

PUT Requests

PUT is usually required when you want to update the contents of a resource. In general, requests are made to a specific entity by adding its Id in the URL. Note that a PUT call replaces the existing entity with the contents of the request or, if none exists at the designated location, attempts to create it.

It is possible to update queues, environments, organization units, comments on transactions, processes and other resources' details.

PATCH Requests

PATCH is used to update the contents of an existing entity, with the desired entity specified by adding its Id in the URL. The body of the request contains only those contents that you want to change. This is distinguished from a PUT call which replaces the current entity with the contents of the subsequent request.

It is possible to use a PATCH request to update Machines, Processes, Robots, Tenants, Users (except the Organization Unit and Roles), and Webhooks entities.

DELETE Requests

Using this HTTP verb enables you to mark a specified item as deleted in the database. The resource is usually indicated with the help of its Id in the URL you make the call to. A 204 response should let you know that your request was successful.

It is possible to delete assets, environments, queue item comments, processes, roles, tenants, users and many others.