Get started with the Perfecto REST API, a RESTful web service that provides an interface for accessing Perfecto Lab functionality and data from a remote client over the web.

Restriction: If you are a Free Trial user, only the Repository Operations API endpoints are relevant for you.

API Operations

The following API endpoints are available:



Desktop Web

Query the Perfecto Lab for information related to desktop web devices and executions.

Device & Cradle

Legacy but still relevant. Get info on one or all devices, device hosts, or cradles.

Device Group

Manage device groups. This includes adding and editing device groups, deleting device groups, and getting one or more device groups. Device groups are an easy way to manage user access to mobile devices.

Group Create and update groups, get group information, delete groups, and find groups.


Retrieve license information for all devices or by type (desktop or simulator devices).


Upload, download, list, and delete items. Change the repository item locator. Get and edit item information.


Legacy but still relevant. Reserve devices.

Role Add a user to a device group. Remove a user from a device group. Add roles to a user. Remove roles from a user.
User Create, update, delete, and find users.

Authentication and authorization

All API endpoints use the header Perfecto-Authorization, where the value is the Perfecto security token.

Some operations require specific user permissions. For example, user management operations require a user with administrator role or someone who is part of Perfecto Support.


Most API requests can be transmitted to the API server using either the GET or the POST HTTP method, but some requests require the PATCH or DELETE method. To use the GET method, simply specify the request as a URL. Parameter values must be encoded to prevent conflicts with HTTP special characters. The following example shows the URL for getting a list of all iOS artifacts stored in the repository of your cloud.


Operations that upload files to the Perfecto repository must use the POST method.

Test access to API endpoints

The easiest way to test your access to the endpoints of our REST API is using Postman.

To test endpoint access:

  1. Open Postman.
  2. At the top, select the + sign to open a new tab.
  3. For the request URL, enter the following. This sample request retrieves a list of images stored in the Perfecto repository.

  4. Below the URL, on the Headers tab, do the following:

    1. In the KEY field, enter Perfecto-Authorization.

    2. In the VALUE field, enter your security token. For information on retrieving your token, see Perfecto security token.

  5. Click Send.

    The request response should appear in the lower pane.

Error handling

Error messages returned in the response of an API operation are self-explanatory and should be sufficient to resolve issues.

The following table provides guidance for resolving some of the common HTTP codes that you may encounter:




400 Bad Request

One or more of the specified parameters is not valid.

Fix incorrect parameters in the URL.

401 Unauthorized

Authentication is required and has failed.

Fix incorrect authorization parameters in the URL.

500 Internal server error

Internal server error.

Contact your system administrator.