Devices Rest API

Continuous Testing allows device management using Rest API. The following are the supported Rest APIs for managing devices.

The role of the user performing the Rest Operation is specified by the 'Authorization' header.

For more information please visit How To Execute Rest API.

Get all Devices

Get 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
        }
    ],
    "code": "OK"
}

Get Devices by Query

Gets the devices' information based on device query.

This API returns devices which the user has access to.

Device query syntax reference: Device Queries

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

Device query can be specified as parameter too.

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
        }
    ],
    "code": "OK"
}

Get Device

Gets the device information of the given id.

This API is available only for cloud admin.

GET /api/v1/devices/{id}

{id} - id of the device. DeviceId can be retrieved from the 'id' attribute of the /api/v1/devices API

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
    },
    "code": "OK"
}

Edit Device

Edit the device's name, notes or category.

This API is available only for cloud admin.

POST /api/v1/devices/{id}

{id} - id of the device. DeviceId can be retrieved from the 'id' attribute of the /api/v1/devices API
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)

Get Device Reservations

Get the device reservations of the specified device.

This API is available only for the cloud admin.

GET /api/v1/devices/{id}/reservations

{id} - id of the device

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

Reserve Device

Reserves a device for the current user or the user with the userId if given.

If the reservation user has one project, the reservation project will be the user's project. Otherwise, the project id must be specified.

This API is available only for the cloud admin.

POST /api/v1/devices/{id}/reservations/new

{id} - id of the device

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	id of a user
projectId	String	No	id of a project
notes	String	No	a reason for this reservation

Reserve Multiple Devices

Reserves multiple devices for the current user or the user with the userId if given.

If the reservation user has one project, the reservation project will be the user's project. Otherwise, the project id must be specified.

This API is available only for the cloud admin.

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

Release Device

Releases the device from its current user.

POST /api/v1/devices/{id}/release

{id} - id of the device

Reboot Device

Reboot the device.

This API is available only for cloud admin.

POST /api/v1/devices/{id}/reboot

{id} - id of the device

Reset USB Connection

Resets the USB Connection.

This API is available only for cloud admin

POST /api/v1/devices/{id}/resetusb

{id} - id of the device

Download App Container

(Only for iOS) - Download app container as a zip file, file name: '{bundle-id}.zip'

The device must be reserved by User
The app must be built for debugging

This API is available only for cloud admin.

GET /api/v1/devices/{id}/app-container/{bundle-id}

{id} - id of the device

{bundle-id} - bundle id of the application

Start web control on a specific device

Start web access control of the device

When choosing 'Debug' option - Grid must run (from the same user who ran the API)

This API is available only for cloud admin.

PUT /api/v1/devices/{id}/web-control

{id} - id of the device

Parameters

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

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	Specify which devices can 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

read more about the report template for manual testing here.

This API is available for all user roles.

POST /api/v1/devices/web-control

JSON Body Parameters

Name	Type	Mandatory	Description
deviceQuery	String	Yes	Specify which devices can be used
testName	String	Yes	Name of the manual test
testSteps	Array	Yes	An array of objects describing the manual test steps
name	String	Yes	Name of the manual test step (max 255 characters)
description	String	No	The 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	The assigned Identifier for this manual test, 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

Get tags that were added to device.

This API is available for all user roles.

GET /api/v1/devices/{id}/tags

{id} - id of the device

Response

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

Add device tag

Add tags to device.

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

Maximum number of tags allowed for each device: 10

Tags are not case sensitive

This API is available for Cloud Administrators and Project Administrators.

PUT /api/v1/devices/{id}/tags/{tag_value}

{id} - id of the device

{tag_value} - tag value - can contain only letters, digits, and underscore character.

Response

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

When a tag contains invalid characters:

Response

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

When a device already contains 10 tags:

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 API is available for Cloud Administrators and Project Administrators.

DELETE /api/v1/devices/{id}/tags/{tag_value}

{id} - id of the device

{tag_value} - tag that should be deleted

Response

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

Remove all device tags

This API is available for Cloud Administrators and Project Administrators.

DELETE /api/v1/devices/{id}/tags

{id} - id of the device

Response

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

Get Installed Certificates from device

Only for Android devices.

This API is available for Cloud Administrators.

User must remove the pre-existing account from the device (such as Google account, Samsung account, Xiaomi account, etc...) when using this API for the first time. This is required to set the profile owner. Once profile owner is set, account can be added again and there is no need to remove/add accounts for subsequent use.

GET /api/v1/devices/{id}/cacerts

{id} - id for device

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

Only for Android devices.

This API is available for Cloud Administrators.

User must remove the pre-existing account from the device (such as Google account, Samsung account, Xiaomi account, etc...) when using this API for the first time. This is required to set the profile owner. Once profile owner is set, account can be added again and there is no need to remove/add accounts for subsequent use.

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

{id} - id of the device

The certificate files to install should be added in the request body.

Page tree

Devices Rest API

Get all Devices

Get Devices by Query

Get Device

Edit Device

Get Device Reservations

Reserve Device

Reserve Multiple Devices

Release Device

Reboot Device

Reset USB Connection

Download App Container

Start web control on a specific device

Open Mobile Studio for device identified by device query

Create a report template for manual tests

Get device tags

Add device tag

Remove device tag

Remove all device tags

Get Installed Certificates from device

Install CA Certificates on device