Create Plan Environment (Appium2)

12 min

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
    }
  ]'