Create Plan Environment (Appium2)
This endpoint creates or updates the environment list of an Appium2 test plan.
The request body contains the DevicePark environment definitions that should be assigned to the plan. Existing active environments that are not included in the request are deactivated, and new environments are created when they do not already exist for the plan.
Endpoint Information
- URL: {gateway-url}/plan-environment/plan/{planId}
- Method: POST
- Authentication: Required (Bearer Token)
Request Headers
Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer token used for authentication. Example: Bearer <your_access_token> |
Content-Type | Yes | Must be application/json. |
X-Company-Id | Yes | The company ID used by the gateway to authorize and route the request. |
Path Variables
Parameter | Type | Required | Description |
|---|---|---|---|
planId | Long | Yes | The ID of the Appium2 test plan. |
Request Body
[
{
"platform": "iOS",
"manufacturer": "Apple",
"model": "iPhone13,2",
"platformVersion": "18.6.2",
"marketName": "iPhone 12",
"privateDevice": false
}
]Request Body Parameters
Field | Type | Required | Description |
|---|---|---|---|
platform | String | Yes | Operating system of the device. Example: iOS, Android. |
manufacturer | String | Yes | Device manufacturer. Example: Apple, Samsung. |
model | String | Yes | Device model identifier. Example: iPhone13,2, SM-A305F. |
platformVersion | String | Yes | Operating system version of the device. |
marketName | String | No | Commercial or user-friendly device name. Example: iPhone 12. |
privateDevice | Boolean | No | Indicates whether the device belongs to a private device pool. Default is false. |
Response Body
{
"data": [
{
"id": 753,
"platform": "iOS",
"platformName": null,
"platformVersion": "18.6.2",
"model": "iPhone13,2",
"modelName": null,
"manufacturer": "Apple",
"marketName": "iPhone 12",
"testFrameworkType": null,
"udid": null,
"licenceId": null,
"enabled": true,
"privateDevice": false
}
]
}Response Fields
Field | Type | Description |
|---|---|---|
data | Array of objects | List of environments assigned to the plan. |
data[].id | Long | Unique identifier of the plan environment record. |
data[].platform | String | Operating system of the device. |
data[].platformName | String | Display name of the platform, if available. |
data[].platformVersion | String | Operating system version. |
data[].model | String | Device model identifier. |
data[].modelName | String | Display name of the model, if available. |
data[].manufacturer | String | Device manufacturer. |
data[].marketName | String | Commercial device name. |
data[].testFrameworkType | String | Framework type, if available. |
data[].udid | String | Device UDID, if available. |
data[].licenceId | Long | Related licence ID, if available. |
data[].enabled | Boolean | Indicates whether the environment is active for the plan. |
data[].privateDevice | Boolean | Indicates whether the environment belongs to a private device pool. |
Important Notes
- This endpoint is only supported for Appium2 and Selenium4 style device environments.
- For Appium2 plans, device OS version is validated against the selected mobile app minimum supported version.
- The environment uniqueness key is based on platform, manufacturer, model, platformVersion, and privateDevice.
- Sending an empty array deactivates all currently assigned environments for the plan.
- The response does not include result.code or result.message.
Error Response Format
{
"instance": "/plan-environment/plan/999999",
"status": 404,
"title": "Not Found",
"type": "https://errors.testinium.com/exception",
"timestamp": "2026-08-18T12:08:41.165927056Z",
"errorType": "EXCEPTION",
"errors": {
"code": 10003,
"message": "Plan with id 999999 not found!"
}
}HTTP Error Codes
HTTP Code | Error Message | Description |
|---|---|---|
400 | Bad Request | Request body is invalid, malformed, contains missing required fields, or selected device OS version is not compatible with the app. |
401 | Unauthorized | Authentication is missing or invalid. |
403 | Forbidden | User does not have permission for this operation or company. |
404 | Not Found | Plan was not found, deleted, disabled, or not accessible within the current company scope. |
405 | Method Not Allowed | The endpoint was called with an unsupported HTTP method. |
500 | Internal Server Error | An unexpected error occurred on the server side. |
503 | Service Unavailable | Environment service, project service, or another downstream service is unavailable. |
Application Error Codes
Code | HTTP Status | Source | Description |
|---|---|---|---|
90016 | 400 | Environment | Selected environment version is not compatible with the mobile app minimum supported OS version. |
10003 | 404 | Project | Test plan not found. |
10001 | 401 | Gateway | Authentication is required. |
10002 | 401 | Gateway | Token is invalid or cannot be verified. |
10003 | 403 | Gateway | Authorization failed for the requested resource. |
10004 | 400 | Gateway | A required header, such as X-Company-Id, is missing or invalid. |
10008 | 503 | Gateway | Routed service is unavailable. |
10007 | 503 | Common | Downstream service is unavailable. |
20005 | 400 | Common Validation | Request body or path variable validation failed. |
20008 | 400 | Common Validation | Path variable type is invalid. |
20009 | 405 | Common Validation | HTTP method is not supported. |
Example Request
curl --location '{gateway-url}/plan-environment/plan/{planId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'X-Company-Id: <company_id>' \
--data '[
{
"platform": "iOS",
"manufacturer": "Apple",
"model": "iPhone13,2",
"platformVersion": "18.6.2",
"marketName": "iPhone 12",
"privateDevice": false
}
]'