Orchestrator API guide

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.

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

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.

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

For example, one can filter according to:

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

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:

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

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.

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.

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

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.

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 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.

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.