REST API

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:

Operation	Description
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.
License	Retrieve license information for all devices or by type (desktop or simulator devices).
Repository	Upload, download, list, and delete items. Change the repository item locator. Get and edit item information.
Reservation	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.

Protocols

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.

Copy

https://<your-cloud>.app.perfectomobile.com/repository/api/v1/artifacts?artifactType=IOS

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:

Open Postman.
At the top, select the + sign to open a new tab.
For the request URL, enter the following. This sample request retrieves a list of images stored in the Perfecto repository.
Copy
```
https://ps.app.perfectomobile.com/repository/api/v1/artifacts?artifactType=IMAGE
```
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.
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:

Response	Cause	Resolution
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.