Devices Rest API

Continuous Testing allows device management using the Rest API.

info

The role of the user performing the Rest Operation is specified by the Authorization header.
For more information see How To Execute Rest API.

Get All Devices

This gets the information of all the devices the user has access to.

GET /api/v1/devices

Response

Response Status: 200 OK
{
    "status": "SUCCESS",
    "data": [
        {
            "id": "83",
            "udid": "1115fbd4746c2f05",
            "iosUdid": "",
            "deviceName": "Samsung S6 Edge",
            "notes": "",
            "deviceOs": "Android",
            "osVersion": "7.0",
            "model": "SM-G928C",
            "manufacturer": "samsung",
            "currentUser": "None",
            "deviceCategory": "PHONE",
            "uptime": "",
            "isEmulator": false,
            "profiles": "no profiles",
            "agentName": "",
            "agentIp": "",
            "agentLocation": "",
      		"region": "Europe - Master",
            "currentStatus": "offline",
            "statusTooltip": "",
            "lastUsedDateTime": "2017-04-21T13:03:44.403+03:00",
            "previousStatus": "offline",
            "statusAgeInMinutes": "868542",
            "statusModifiedAt": "1502176646041",
            "statusModifiedAtDateTime": "2017-08-08T10:17:26.041+03:00",
            "displayStatus": "Offline",
            "whitelistCleanup": true,
            "defaultDeviceLanguage": null,
            "defaultDeviceRegion": null,
            "iosConfigurationProfiles": ["Foobar"],
            "screenWidth": 720,
            "screenHeight": 1280
            "tags": [
                "stable",
                "new_device_2019"
                "expensive"
            ],
			"phoneNumber1: "123456",
			"phoneNumber2: null,
			"bluetooth": {
				"adapterName": "name123456",
				"state": "OFFLINE"
			}
        }
    ],
    "code": "OK"
}

Get Devices by Query

This gets the devices' information based on device query. The results are limited to the devices the user has access to.

For more information on how to write device queries, see Device Queries.

GET /api/v1/devices?query=@os='android' and starts-with(@model,'SM-')

The query can be specified as parameter as well.

GET /api/v1/devices

Parameter

Name	Type	Mandatory	Description
query	String	No	Returns all devices if not provided or empty string.

Response

Response Status: 200 OK
{
    "status": "SUCCESS",
    "data": [
        {
            "id": "83",
            "udid": "1115fbd4746c2f05",
            "iosUdid": "",
            "deviceName": "Samsung S6 Edge",
            "notes": "",
            "deviceOs": "Android",
            "osVersion": "7.0",
            "model": "SM-G928C",
            "manufacturer": "samsung",
            "currentUser": "None",
            "deviceCategory": "PHONE",
            "uptime": "",
            "isEmulator": false,
            "profiles": "no profiles",
            "agentName": "",
            "agentIp": "",
            "agentLocation": "",
      		"region": "Europe - Master",
            "currentStatus": "offline",
            "statusTooltip": "",
            "lastUsedDateTime": "2017-04-21T13:03:44.403+03:00",
            "previousStatus": "offline",
            "statusAgeInMinutes": "868542",
            "statusModifiedAt": "1502176646041",
            "statusModifiedAtDateTime": "2017-08-08T10:17:26.041+03:00",
            "displayStatus": "Offline",
            "whitelistCleanup": true,
            "defaultDeviceLanguage": null,
            "defaultDeviceRegion": null,
            "iosConfigurationProfiles": ["Foobar"],
            "screenWidth": 720,
            "screenHeight": 1280
            "tags": [
                "stable",
                "new_device_2019"
                "expensive"
            ],
			"phoneNumber1: "123456",
			"phoneNumber2: null,
			"bluetooth": {
				"adapterName": "name123456",
				"state": "OFFLINE"
			}
        }
    ],
    "code": "OK"
}

Get Device

This gets the device information of the given ID.

This API call is available only to a cloud administrator.

GET /api/v1/devices/<id>

id - Device ID. The Device ID can be retrieved from the 'id' attribute of /api/v1/devices.

Response

Response Status: 200 OK
{
    "status": "SUCCESS",
    "data": {
        "id": "12345",
        "udid": "11111",
        "iosUdid": "",
        "deviceName": "Google Pixel",
        "notes": "",
        "deviceOs": "Android",
        "osVersion": "9",
        "model": "Pixel XL",
        "manufacturer": "Google",
        "currentUser": "None",
        "deviceCategory": "PHONE",
        "uptime": "0d 00:03",
        "isEmulator": false,
        "profiles": "no profiles",
        "agentName": "windowsagent",
        "agentIp": "192.168.0.0",
        "agentLocation": "2",
		"region": "Europe - Master",
        "currentStatus": "online",
        "statusTooltip": "",
        "lastUsedDateTime": "2019-04-04T10:31:29.776+03:00",
        "previousStatus": "offline",
        "statusAgeInMinutes": "3",
        "statusModifiedAt": "1554364275730",
        "statusModifiedAtDateTime": "2019-04-04T10:51:15.730+03:00",
        "displayStatus": "Available",
        "whitelistCleanup": true,
        "screenWidth": 720,
        "screenHeight": 1280,
        "project": "11111,Project2",
        "tags": [
           "stable",
           "new_device_2019",
           "expensive"
        ],
        "iosConfigurationProfiles": ["Foobar"],
        "deviceGroups": {
            "1": "Default",
            "987654": "devgroup",
        },
		"lastActivity": 1603371650000,
		"phoneNumber1: "123456",
		"phoneNumber2: null,
		"bluetooth": {
			"adapterName": "name123456",
			"state": "OFFLINE"
		}
    },
    "code": "OK"
}

Edit Device

This edits a device's name, notes or category.

This API call is available only to a cloud administrator.

POST /api/v1/devices/<id>

id - Device ID. The Device ID can be retrieved from the 'id' attribute of /api/v1/devices.

Parameters

Name	Type	Mandatory	Description
name	String	No	New name of the device
notes	String	No	New notes of the device
category	String	No	New category of the device (allowed categories: WATCH / TABLET / PHONE / UNKNOWN)

Response

Response Status: 200 OK
{
    "status": "SUCCESS",
    "code": "OK"
}

Get Device Reservations

This the device reservations of the specified device.

This API is available only for a cloud administrator.

GET /api/v1/devices/<id>/reservations

id - Device ID. The Device ID can be retrieved from the 'id' attribute of /api/v1/devices.

Parameters

Name	Type	Mandatory	Description
start	String	Yes	YYYY-MM-DD-hh-mm-ss as (2019-04-04-13-30-00)
end	String	Yes	YYYY-MM-DD-hh-mm-ss
current_timestamp	String	Yes	YYYY-MM-DD-hh-mm-ss

Response

Response Status: 200 OK
{
    "status": "SUCCESS",
    "data": [
        {
            "start": "2019-04-04T18:51:44.940+03:00",
            "end": "2019-04-04T19:36:44.940+03:00",
            "id": 2264433,
            "title": "keerthana@NO_HOST"
        }
    ],
    "code": "OK"
}

Reserve Device

This reserves a device. If a User ID is provided, the device is reserved for that user. Otherwise, the device is reserved for the current user.

If the user has more than one project, the project ID must be provided. Otherwise, the sole project is used.

This API is available only for a cloud administrator.

POST /api/v1/devices/<id>/reservations/new

id - Device ID. The Device ID can be retrieved from the 'id' attribute of /api/v1/devices.

Parameters

Name	Type	Mandatory	Description
start	String	Yes	YYYY-MM-DD-hh-mm-ss
end	String	Yes	YYYY-MM-DD-hh-mm-ss
clientCurrentTimestamp	String	Yes	YYYY-MM-DD-hh-mm-ss
userId	String	No	User ID
projectId	String	No	Project ID
notes	String	No	Free text notes. This is typically used to specify the reason for the reservation.

Response

Response Status: 200 OK
{
    "status": "SUCCESS",
    "data": {
        "reservationId": 14833,
        "reservations": "Reservation added successfully"
    },
    "code": "OK"
}

Reserve Multiple Devices

This reserves multiple devices.

If a User ID is provided, the devices are reserved for that user. Otherwise, the devices are reserved for the current user.

If the user has more than one project, the project ID must be provided. Otherwise, the sole project is used.

This API is available only for a cloud administrator.

POST /api/v1/devices/reservations/new

Parameters

Name	Type	Mandatory	Description
devicesList	String	Yes	list of id of the device (as "8,235,54")
start	String	Yes	YYYY-MM-DD-hh-mm-ss
end	String	Yes	YYYY-MM-DD-hh-mm-ss
clientCurrentTimestamp	String	Yes	YYYY-MM-DD-hh-mm-ss
userId	String	No	id of a user
projectId	String	No	id of a project
notes	String	No	a reason for this reservation

Response

Response Status: 200 OK
{
    "status": "SUCCESS",
    "data": {
        "reservations for id: 11664": "{\"status\":\"SUCCESS\",\"data\":{\"reservationId\":14835,\"reservations\":\"Reservation added successfully\"},\"code\":\"OK\"}"
    },
    "code": "OK"
}

Release Device

This releases the device from its current user.

POST /api/v1/devices/<id>/release

id - Device ID

Response

Response Status: 200 OK
{
    "status": "SUCCESS",
    "code": "OK"
}

Reboot Device

This reboots the device.

This API is available only for a cloud administrator.

POST /api/v1/devices/<id>/reboot

id - Device ID

Response

Response Status: 200 OK
{
    "status": "SUCCESS",
    "code": "OK"
}

Reset USB Connection

This resets the USB Connection.

This API is available only for a cloud administrator.

POST /api/v1/devices/<id>/resetusb

id - Device ID

Response

Response Status: 200 OK
{
    "status": "SUCCESS",
    "code": "OK"
}

Download App Container

(Only for iOS) - This downloads an application container as a zip file. The file name format is: <bundle-id>.zip

The device must be reserved by a user.
The application must be built for debugging.

This API is available only for a cloud administrator.

GET /api/v1/devices/<id>/app-container/<bundle-id>

id - Device ID
bundle-id - Bundle ID

Start Web Control on a Specific Device

This start web access control of the device.

When choosing the Debug option, Grid must run from the same user who ran the API call.

This API call is available only for a cloud administrator.

PUT /api/v1/devices/<id>/web-control

id - Device ID

Parameters

Name	Type	Mandatory	Description
type	String	Yes	0-Manual, 1 - View, 2 - Automation, 3 - Debug
emulatorInstanceName	String	No	Name for the emulator

Response

Response Status: 200 OK
{
    "deviceId": 12345,
    "regularLink": "https://my.cloud.experitest.com:443/agent-25/#/ZqZPSfMvLHRtlXWF?1",
    "externalLink": null
}

Open Mobile Studio for Device Identified by Device Query

This API is available for all user roles.

POST /api/v1/devices/web-control

JSON Body Parameters

Name	Type	Mandatory	Description
deviceQuery	String	Yes	Specifies which devices are to be used.

Request Example

{
  "deviceQuery": "@os = 'Android'"
}

Response Example

{
  "status": "SUCCESS",
  "data": {
    "link": "https://cloud.example.com/mobile-studio/YHVryoOSU98xPc9L"
  },
  "code": "OK"
}

Create a Report Template for Manual Tests

This creates a report template for manual tests. For more information about report templates, see Manual Reports.

This API is available for all user roles.

POST /api/v1/devices/web-control

JSON Body Parameters

Name	Type	Mandatory	Description
deviceQuery	String	Yes	Specifies which devices can be used
testName	String	Yes	Name of the manual test
testSteps	Array	Yes	Array of objects describing the manual test steps
name	String	Yes	Name of the manual test step (max 255 characters)
description	String	No	Step description
expectedResult	String	No	Expected result of the step
attachment	String	No	Link with the additional related information

JSON Response Properties

Name	Type	Mandatory	Description
data.link	String	Yes	Link for opening the reserved device in the browser.
data.report_api_id	String	Yes	Identifier for this manual test. This can be used for retrieving the details from Reporter.

Request Example

{
  "deviceQuery": "@os = 'Android'",
  "testName": "Application can be launched",
  "testSteps": [
     {
       "name": "Find the application icon on the device and click it",
       "expectedResult": "Application opens and stays visible in foreground"
     }
  ]
}

Response Example

{
  "status": "SUCCESS",
  "data": {
    "link": "https://cloud.example.com/mobile-studio/YHVryoOSU98xPc9L",
    "report_api_id": "97bdf5bb-0948-4901-95e9-17a4669d57b6"
  },
  "code": "OK"
}

Get Device Tags

This gets tags that were added to device.

This API call is available for all users.

GET /api/v1/devices/<id>/tags

id - Device ID

Response

Response Status: 200 OK
{
    "status": "SUCCESS",
    "data": [
        "stable",
        "new_device_2019",
        "expensive"
    ],
    "code": "OK"
}

Add Device Tag

This adds tags to device.

Tags can contain only letters, digits, and underscore character.

Up to 10 tags are allowed for each device.

Tags are not case sensitive.

This API is available for Cloud Administrators and Project Administrators.

PUT /api/v1/devices/<id>/tags/<tag_value>

id - Device ID

tag_value - Tag text

Success Response

Response

Response Status: 200 OK
{"status":"SUCCESS","code":"OK"}

Invalid Character Response

Response

Response Status: 400 BAD REQUEST
{"status":"ERROR","message":"Device tag can contain only digits, letters and underscores","code":"BAD_REQUEST"}

Already Has 10 Tags Response

Response

Response Status: 400 BAD REQUEST
{"status":"ERROR","message":"Cannot add tag to device. Device has: 10 tags. Maximum allowed number of tags is: 10","code":"BAD_REQUEST"}

Remove Device Tag

This removes a device tag.

This API call is available for Cloud Administrators and Project Administrators.

DELETE /api/v1/devices/<id>/tags/<tag_value>

id - Device ID

tag_value - Tag to be deleted

Response

Response Status: 200 OK
{"status":"SUCCESS","code":"OK"}

Remove All Device Tags

This removes all tags from a device.

This API is available for Cloud Administrators and Project Administrators.

DELETE /api/v1/devices/<id>/tags

id - Device ID

Response

Response Status: 200 OK
{"status":"SUCCESS","code":"OK"}

Get Installed Certificates from Device

This is applicable to Android devices only.

This API is available for Cloud Administrators.

Pre-existing accounts on the device (such as Google, Samsung, and Xiaomi) must be removed from the device before using this API for the first time. This is required to set the profile owner. Once the profile owner is set, accounts may be added again. There is no need to remove and add accounts for subsequent uses.

GET /api/v1/devices/<id>/cacerts

id - Device ID

Response

{
    "status": "SUCCESS",
    "data": [
        "CN=OISTE WISeKey Global Root GC CA,OU=OISTE Foundation Endorsed,O=WISeKey,C=CH",
        "CN=CFCA EV ROOT,O=China Financial Certification Authority,C=CN",
        "CN=Cybertrust Global Root,O=Cybertrust\\, Inc",
        "CN=QuoVadis Root CA 1 G3,O=QuoVadis Limited,C=BM",
        "CN=Staat der Nederlanden Root CA - G3,O=Staat der Nederlanden,C=NL",
        "CN=Certum Trusted Network CA,OU=Certum Certification Authority,O=Unizeto Technologies S.A.,C=PL",
        "CN=thawte Primary Root CA,OU=(c) 2006 thawte\\, Inc. - For authorized use only,OU=Certification Services Division,O=thawte\\, Inc.,C=US",
        "C=ES,O=ACCV,OU=PKIACCV,CN=ACCVRAIZ1",
        "CN=GTS Root R4,O=Google Trust Services LLC,C=US",
        "CN=GeoTrust Primary Certification Authority - G2,OU=(c) 2007 GeoTrust Inc. - For authorized use only,O=GeoTrust Inc.,C=US",
        "CN=T-TeleSec GlobalRoot Class 2,OU=T-Systems Trust Center,O=T-Systems Enterprise Services GmbH,C=DE",
        "CN=Certum Trusted Network CA 2,OU=Certum Certification Authority,O=Unizeto Technologies S.A.,C=PL",
        "CN=GlobalSign Root CA,OU=Root CA,O=GlobalSign nv-sa,C=BE",
        "CN=SecureTrust CA,O=SecureTrust Corporation,C=US",
        "CN=GTS Root R3,O=Google Trust Services LLC,C=US",
        "CN=Secure Global CA,O=SecureTrust Corporation,C=US",
        "CN=Entrust Root Certification Authority,OU=(c) 2006 Entrust\\, Inc.,OU=www.entrust.net/CPS is incorporated by reference,O=Entrust\\, Inc.,C=US",
        "CN=Go Daddy Secure Certificate Authority - G2,OU=http://certs.godaddy.com/repository/,O=GoDaddy.com\\, Inc.,L=Scottsdale,ST=Arizona,C=US",
        "O=mitmproxy,CN=mitmproxy"
    ],
    "code": "OK"
}

Install CA Certificates on Device

This is applicable to Android devices only.

This API is available for Cloud Administrators.

POST /api/v1/devices/{id}/install-certs

id - Device ID

Parameters

Name	Type	Mandatory	Description
file	File	Yes	Certificate file 1
file	File	No	Certificate file 2
⋮	⋮	⋮	⋮

Each certificate file must be in its own line in the response body.

The files must confirm to X.509 standard. They can have various extensions, for example: .pem, .crt, .cer

Response

Response Status: 200 OK
{
    "status": "SUCCESS",
    "code": "OK"
}

List Installed Applications

This returns a is a list of package identifiers for Android devices and a list of Bundle ID for iOS devices of the installed applications.

GET /api/v1/devices/<id>/applications

id -Device ID

Request Parameters

Name	Type	Mandatory	Default Value	Description
includeSystemApps	Boolean	No	False	If response should include system applications

List Installed Configuration Profiles

This returns a list of identifiers of the configuration profiles installed on the device.

This is applicable to iOS devices only.

This API is available for Cloud Administrators.

GET /api/v1/devices/<id>/profiles

<id> -Device ID

Get IP and Wi-Fi Address

This API is available only for Available or In-Use devices.

This returns the SSID (not be seen in iOS), IPv4 address, and IPv6 address (if available).

GET /api/v1/devices/<id>/WifiIPAddress

id -Device ID

Change Passcode for Devices

POST /api/v1/devices/passcode

JSON Body Parameters

Name	Type	Mandatory	Description
passcode	String	Yes	New passcode to be set for the device
devicesList	String	Yes	list of id of devices (i.e. 1,2,3)

Response Example

Response Status: 207 (Multi-Status)
{
  "status": "PARTIAL",
  "success": [
    {
            "message": "Passcode edited successfully"
            "deviceId": 1,
            "deviceUid: "23423sdf234o2i34",
    },
  ],
  "failure": [
        {
            "message": "Passcode cannot be edited, device is 'In-Use'"
            "DeviceID": 2,
            "deviceUid: "ierw9823werwe30230",
        }
  ]
}

Get All Devices​

Get Devices by Query​

Parameter​

Get Device​

Edit Device​

Parameters​

Get Device Reservations​

Parameters​

Reserve Device​

Parameters​

Reserve Multiple Devices ​

Parameters​

Release Device​

Reboot Device​

Reset USB Connection​

Download App Container​

Start Web Control on a Specific Device​

Parameters​

Open Mobile Studio for Device Identified by Device Query​

JSON Body Parameters​

Create a Report Template for Manual Tests​

JSON Body Parameters​

JSON Response Properties​

Get Device Tags​

Success Response​

Invalid Character Response​

Already Has 10 Tags Response​

Remove Device Tag​

Remove All Device Tags​

Get Installed Certificates from Device​

Install CA Certificates on Device​

Parameters​

List Installed Applications​

Request Parameters​

List Installed Configuration Profiles​

Get IP and Wi-Fi Address​

Change Passcode for Devices​

JSON Body Parameters​

Get All Devices

Get Devices by Query

Parameter

Get Device

Edit Device

Parameters

Get Device Reservations

Parameters

Reserve Device

Parameters

Reserve Multiple Devices

Parameters

Release Device

Reboot Device

Reset USB Connection

Download App Container

Start Web Control on a Specific Device

Parameters

Open Mobile Studio for Device Identified by Device Query

JSON Body Parameters

Create a Report Template for Manual Tests

JSON Body Parameters

JSON Response Properties

Get Device Tags

Success Response

Invalid Character Response

Already Has 10 Tags Response

Remove Device Tag

Remove All Device Tags

Get Installed Certificates from Device

Install CA Certificates on Device

Parameters

List Installed Applications

Request Parameters

List Installed Configuration Profiles

Get IP and Wi-Fi Address

Change Passcode for Devices

JSON Body Parameters