Create Plan Scenarios (Appium2)

12 min

This endpoint assigns scenarios to a test plan.

The operation replaces the current scenario list of the plan with the scenario IDs provided in the request body. The order of the scenarios in the plan follows the order of the IDs in the request.

Endpoint Information

URL: {gateway-url}/plan-scenarios/plan/{planId}/scenario

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 test plan. Must be a positive number.

Request Body

{
  "scenarioIds": [101, 204, 305]
}

Request Body Parameters

Field	Type	Required	Description
scenarioIds	Array	Yes	List of scenario IDs to assign to the plan. The list should not be empty.
scenarioIds[]	Long	Yes	Each item must be a valid scenario ID accessible within the current company scope.

Response Body

{
  "data": [
    {
      "id": 3224,
      "scenarioName": "Deneme",
      "description": "",
      "projectId": 913,
      "parentId": null,
      "sourceFile": "Android/android.spec",
      "javaTestMethods": "@Deneme",
      "userId": 13,
      "orderNo": 1,
      "testRailCaseId": null,
      "xrayIssueKey": null,
      "subScenarios": []
    }
  ]
}

Response Fields

Field	Type	Description
data	Array	List of scenarios assigned to the plan.
data[].id	Long	Unique identifier of the scenario.
data[].scenarioName	String	Name of the scenario.
data[].description	String	Description of the scenario.
data[].projectId	Long	ID of the project that owns the scenario.
data[].parentId	Long	Parent scenario ID, if the scenario is a child scenario.
data[].sourceFile	String	Source file where the scenario is defined.
data[].javaTestMethods	String	Java test method or selector associated with the scenario.
data[].userId	Long	ID of the user associated with the scenario.
data[].orderNo	Integer	Scenario order inside the plan.
data[].testRailCaseId	Integer	TestRail case ID, if configured.
data[].xrayIssueKey	String	Xray issue key, if configured.
data[].subScenarios	Array	Child scenarios, if any.

Important Notes

This endpoint replaces the existing scenario list of the plan.

Scenario order is determined by the order of scenarioIds.

If a scenario ID is not found, deleted, disabled, or not accessible in the current company scope, the request fails.

The response does not include result.code or result.message.

Error Response Format

{
  "instance": "/plan-scenarios/plan/999999/scenario",
  "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 malformed or path variable validation failed.
401	Unauthorized	Authentication is missing or invalid.
403	Forbidden	User does not have permission for this operation or company.
404	Not Found	Plan or scenario 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	Project service is unavailable or cannot be reached through the gateway.

Application Error Codes

Code	HTTP Status	Source	Description
10003	404	Project	Test plan not found.
10004	404	Project	Scenario 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-scenarios/plan/{planId}/scenario' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'X-Company-Id: <company_id>' \
  --data '{
    "scenarioIds": [101, 204, 305]
  }'