Sub test plan API endpoints

API reference for managing sub test plans in BrowserStack Test Management, including creating, updating, retrieving, and deleting sub test plans under a test plan.

Use these endpoints to manage sub test plans within a test plan. You can create, update, retrieve, and delete sub test plans for a project, enabling granular test management and reporting.

List all sub test plans

GET /api/v2/projects/{project_id}/test-plans/{test_plan_id}/sub-test-plans

This endpoint retrieves all sub test plans for a given test plan in a project. Use it to get an overview of all sub test plans and their details.

This list is paginated; for more information about request and response pagination in the Test Management API, see pagination in the Test Management API.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/{project_id}/test-plans/{test_plan_id}/sub-test-plans

project_id^* string

Unique identifier for the project.
test_plan_id^* string

Unique identifier for the test plan.

Response attributes `200` `application/json`

Response

{
  "success": true,
  "sub_test_plans": [
    {
      "active_state": "active",
      "description": "Sample Description",
      "identifier": "STP-194",
      "test_runs_count": { "active": 0, "closed": 0 },
      "tags": [],
      "name": "Sub Test Plan - 26/12/2025",
      "issues": [],
      "project_id": "PR-90177",
      "parent_plan_id": "TP-2553",
      "start_date": null,
      "end_date": null,
      "created_at": "2025-12-26T07:28:18.000Z",
      "owner": "owner@example.com",
      "custom_fields": []
    }
  ],
  "info": {
    "page": 1,
    "page_size": 30,
    "count": 2,
    "prev": null,
    "next": null
  }
}

success Boolean

Indicates if the request was successful.
sub_test_plans Array

List of sub test plans.

▶ SHOW VALUES
- active_state String
  
  State of the sub test plan (e.g., active).
- description String
  
  Description of the sub test plan.
- identifier String
  
  Unique identifier of the sub test plan.
- test_runs_count Object
  
  Count of active and closed test runs in the sub test plan.
  
  ▶ SHOW VALUES
  - active Integer
    
    Number of active test runs.
  - closed Integer
    
    Number of closed test runs.
- tags Array
  
  List of tags associated with the sub test plan.
- name String
  
  Name of the sub test plan.
- issues Array
  
  List of issue identifiers linked to the sub test plan.
- project_id String
  
  Unique identifier of the project.
- parent_plan_id String
  
  Unique identifier of the parent test plan.
- start_date String
  
  Start date of the sub test plan (ISO 8601 format or null).
- end_date String
  
  End date of the sub test plan (ISO 8601 format or null).
- created_at String
  
  Timestamp when the sub test plan was created.
- owner String
  
  Email of the sub test plan owner. null when the owner is not a user in your group.
- custom_fields Array
  
  Custom field values set on the sub test plan. Empty when no value is set.
  
  ▶ SHOW VALUES
  - id Integer
    
    Unique identifier of the custom field.
  - field_type String
    
    Data type of the custom field, prefixed with field_, such as field_dropdown or field_string.
  - field_name String
    
    System name of the custom field.
  - field_user_name String
    
    Name of the custom field as shown in Test Management. Use this name as the key when you set the value.
  - optional Boolean
    
    true when the field is not required.
  - value String
    
    Stored value of the field. For dropdown fields, the identifier of the selected option.
  - option Object
    
    The selected option of a dropdown field, with its id and option_value. null for other field types.
  - options Array
    
    The selected options of a multi_dropdown field. Empty for other field types.
info Object

Pagination information.

▶ SHOW VALUES
- page Integer
  
  Current page number.
- page_size Integer
  
  Number of items per page.
- count Integer
  
  Total number of items.
- prev Integer
  
  Previous page number, or null on the first page.
- next Integer
  
  Next page number, or null on the last page.

Get a sub test plan

GET /api/v2/projects/{project_id}/test-plans/{test_plan_id}/sub-test-plans/{sub_test_plan_id}

This endpoint retrieves details of a specific sub test plan by its ID.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/{project_id}/test-plans/{test_plan_id}/sub-test-plans/{sub_test_plan_id}

project_id^* string

Unique identifier of the project.
test_plan_id^* string

Unique identifier of the test plan.
sub_test_plan_id^* string

Unique identifier for the sub test plan.

Response attributes `200` `application/json`

Response

{
  "success": true,
  "sub_test_plan": {
    "active_state": "active",
    "description": "Sample Description",
    "identifier": "STP-194",
    "test_runs_count": { "active": 0, "closed": 0 },
    "tags": [],
    "test_runs": [],
    "links": {
      "self": "/api/v1/projects/2784593/test-plans/94276",
      "test_runs": "/api/v2/projects/PR-90177/test-plans/STP-194/test-runs"
    },
    "name": "Sub Test Plan - 26/12/2025",
    "issues": null,
    "project_id": "PR-90177",
    "parent_plan_id": "TP-2553",
    "start_date": null,
    "end_date": null,
    "created_at": "2025-12-26T07:28:18.000Z",
    "owner": "owner@example.com",
    "custom_fields": []
  }
}

success Boolean

Indicates if the request was successful.
sub_test_plan Object

Sub test plan details.

▶ SHOW VALUES
- active_state String
  
  State of the sub test plan (e.g., active).
- description String
  
  Description of the sub test plan.
- identifier String
  
  Unique identifier of the sub test plan.
- test_runs_count Object
  
  Count of active and closed test runs in the sub test plan.
  
  ▶ SHOW VALUES
  - active Integer
    
    Number of active test runs.
  - closed Integer
    
    Number of closed test runs.
- tags Array
  
  List of tags associated with the sub test plan.
- test_runs Array
  
  List of test runs in the sub test plan (only in details API).
- links Object
  
  Related API links for the sub test plan (only in details API).
  
  ▶ SHOW VALUES
  - self String
    
    API endpoint URL for the sub test plan itself.
  - test_runs String
    
    API endpoint URL for the test runs in the sub test plan.
- name String
  
  Name of the sub test plan.
- issues Array
  
  List of issue identifiers linked to the sub test plan.
- project_id String
  
  Unique identifier of the project.
- parent_plan_id String
  
  Unique identifier of the parent test plan.
- start_date String
  
  Start date of the sub test plan (ISO 8601 format or null).
- end_date String
  
  End date of the sub test plan (ISO 8601 format or null).
- created_at String
  
  Timestamp when the sub test plan was created.
- owner String
  
  Email of the sub test plan owner. null when the owner is not a user in your group.
- custom_fields Array
  
  Custom field values set on the sub test plan. Empty when no value is set.
  
  ▶ SHOW VALUES
  - id Integer
    
    Unique identifier of the custom field.
  - field_type String
    
    Data type of the custom field, prefixed with field_, such as field_dropdown or field_string.
  - field_name String
    
    System name of the custom field.
  - field_user_name String
    
    Name of the custom field as shown in Test Management. Use this name as the key when you set the value.
  - optional Boolean
    
    true when the field is not required.
  - value String
    
    Stored value of the field. For dropdown fields, the identifier of the selected option.
  - option Object
    
    The selected option of a dropdown field, with its id and option_value. null for other field types.
  - options Array
    
    The selected options of a multi_dropdown field. Empty for other field types.

Create a sub test plan

POST /api/v2/projects/{project_id}/test-plans/{test_plan_id}/sub-test-plans

This endpoint creates a new sub test plan under a test plan.

To assign an owner, pass the email of a user in your group in owner. Without owner, the sub test plan is owned by the user whose credentials made the request. An unknown owner email returns 400 Bad Request.

To set custom field values, pass a custom_fields object keyed by the custom field name. Sub test plans use the test plan custom fields of the project. For dropdown fields, pass the option label. For multi_dropdown fields, pass an array of option labels. An undefined custom field name returns 400 Bad Request.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/{project_id}/test-plans/{test_plan_id}/sub-test-plans

project_id^* string

Unique identifier of the project.
test_plan_id^* string

Unique identifier of the test plan.

Request body

Request Body

{
  "sub_test_plan": {
    "name": "Sprint 1 Testing",
    "description": "Smoke and regression testing for sprint 1 features",
    "start_date": "2024-02-01",
    "end_date": "2024-02-15",
    "tags": [
      "sprint",
      "regression"
    ],
    "owner": "owner@example.com",
    "custom_fields": {
      "Severity": "High"
    }
  }
}

name^* String

Name of the sub test plan.
description String

Description of the sub test plan.
start_date String

Start date of the sub test plan (YYYY-MM-DD).
end_date String

End date of the sub test plan (YYYY-MM-DD).
tags Array

List of tags for the sub test plan.
owner String

Email of the user who owns the sub test plan. Must be a user in your group. Without it, the user who made the request owns the sub test plan.
custom_fields Object

Custom field values keyed by test plan custom field name, for example {"Severity": "High"}. Pass option labels for dropdown fields and an array of option labels for multi_dropdown fields. A name that is not defined for test plans in the project returns 400.

Response attributes `200` `application/json`

Response

{
  "success": true,
  "sub_test_plan": {
    "active_state": "active",
    "description": "Smoke and regression testing for sprint 1 features",
    "identifier": "STP-195",
    "test_runs_count": {
      "active": 0,
      "closed": 0
    },
    "tags": [
      "regression",
      "sprint"
    ],
    "name": "Sprint 1 Testing",
    "issues": [
      "xyz-001",
      "abc-002"
    ],
    "project_id": "PR-90177",
    "parent_plan_id": "TP-2553",
    "sub_plans_count": 0,
    "start_date": "2024-02-01T00:00:00.000Z",
    "end_date": "2024-02-15T00:00:00.000Z",
    "created_at": "2025-12-26T07:47:24.000Z",
    "owner": "owner@example.com",
    "custom_fields": [
      {
        "id": 5678,
        "field_type": "field_dropdown",
        "field_name": "severity",
        "field_user_name": "Severity",
        "optional": true,
        "value": 900,
        "option": {
          "id": 900,
          "option_value": "High"
        },
        "options": []
      }
    ]
  }
}

success Boolean

Indicates if the request was successful.
sub_test_plan Object

Sub test plan details

▶ SHOW VALUES
- active_state String
  
  State of the sub test plan (e.g., active).
- description String
  
  Description of the sub test plan.
- identifier String
  
  Unique identifier of the sub test plan.
- test_runs_count Object
  
  Count of active and closed test runs in the sub test plan.
  
  ▶ SHOW VALUES
  - active Integer
    
    Number of active test runs.
  - closed Integer
    
    Number of closed test runs.
- tags Array
  
  List of tags associated with the sub test plan.
- name String
  
  Name of the sub test plan.
- issues Array
  
  List of issue identifiers linked to the sub test plan.
- project_id String
  
  Unique identifier of the project.
- parent_plan_id String
  
  Unique identifier of the parent test plan.
- sub_plans_count Integer
  
  Number of sub plans (only in create/update response).
- start_date String
  
  Start date of the sub test plan (ISO 8601 format or null).
- end_date String
  
  End date of the sub test plan (ISO 8601 format or null).
- created_at String
  
  Timestamp when the sub test plan was created.
- owner String
  
  Email of the sub test plan owner. null when the owner is not a user in your group.
- custom_fields Array
  
  Custom field values set on the sub test plan. Empty when no value is set.
  
  ▶ SHOW VALUES
  - id Integer
    
    Unique identifier of the custom field.
  - field_type String
    
    Data type of the custom field, prefixed with field_, such as field_dropdown or field_string.
  - field_name String
    
    System name of the custom field.
  - field_user_name String
    
    Name of the custom field as shown in Test Management. Use this name as the key when you set the value.
  - optional Boolean
    
    true when the field is not required.
  - value String
    
    Stored value of the field. For dropdown fields, the identifier of the selected option.
  - option Object
    
    The selected option of a dropdown field, with its id and option_value. null for other field types.
  - options Array
    
    The selected options of a multi_dropdown field. Empty for other field types.

Update a sub test plan

PATCH /api/v2/projects/{project_id}/test-plans/{test_plan_id}/sub-test-plans/{sub_test_plan_id}

This endpoint updates an existing sub test plan.

To change the owner or custom field values, pass owner or custom_fields in the same shape as the create request. When you leave them out, the existing values stay unchanged.

Request parameters

Request

curl  -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PATCH https://test-management.browserstack.com/api/v2/projects/{project_id}/test-plans/{test_plan_id}/sub-test-plans/{sub_test_plan_id} \

project_id^* string

Unique identifier for the project.
test_plan_id^* string

Unique identifier for the test plan.
sub_test_plan_id^* string

Unique identifier for the sub test plan.

Request body

Request Body

{
  "sub_test_plan": {
    "name": "Sprint 1 - Extended Testing",
    "description": "Regression + UAT scope",
    "start_date": "2024-02-01",
    "end_date": "2024-02-20",
    "plan_status": "active",
    "owner": "owner@example.com",
    "custom_fields": {
      "Severity": "Medium"
    }
  }
}

name^* String

Name of the sub test plan.
description String

Description of the sub test plan.
start_date String

Start date of the sub test plan (YYYY-MM-DD).
end_date String

End date of the sub test plan (YYYY-MM-DD).
plan_status String

Status of the sub test plan (e.g., active).
owner String

Email of the user who owns the sub test plan. Must be a user in your group. Without it, the owner stays unchanged.
custom_fields Object

Custom field values keyed by test plan custom field name, for example {"Severity": "High"}. Pass option labels for dropdown fields and an array of option labels for multi_dropdown fields. Without it, the existing values stay unchanged. A name that is not defined for test plans in the project returns 400.

Response attributes `200` `application/json`

Response

{
  "success": true,
  "sub_test_plan": {
    "active_state": "active",
    "description": "Smoke and regression testing for sprint 1 features",
    "identifier": "STP-195",
    "test_runs_count": {
      "active": 0,
      "closed": 0
    },
    "tags": [
      "regression",
      "sprint"
    ],
    "name": "Sprint 1 Testing",
    "issues": [
      "xyz-001",
      "abc-002"
    ],
    "project_id": "PR-90177",
    "parent_plan_id": "TP-2553",
    "sub_plans_count": 0,
    "start_date": "2024-02-01T00:00:00.000Z",
    "end_date": "2024-02-15T00:00:00.000Z",
    "created_at": "2025-12-26T07:47:24.000Z",
    "owner": "owner@example.com",
    "custom_fields": [
      {
        "id": 5678,
        "field_type": "field_dropdown",
        "field_name": "severity",
        "field_user_name": "Severity",
        "optional": true,
        "value": 901,
        "option": {
          "id": 901,
          "option_value": "Medium"
        },
        "options": []
      }
    ]
  }
}

success Boolean

Indicates if the request was successful.
sub_test_plan Object

Updated sub test plan details.

▶ SHOW VALUES
- active_state String
  
  State of the sub test plan (e.g., active).
- description String
  
  Description of the sub test plan.
- identifier String
  
  Unique identifier of the sub test plan.
- test_runs_count Object
  
  Count of active and closed test runs in the sub test plan.
  
  ▶ SHOW VALUES
  - active Integer
    
    Number of active test runs.
  - closed Integer
    
    Number of closed test runs.
- tags Array
  
  List of tags associated with the sub test plan.
- name String
  
  Name of the sub test plan.
- issues Array
  
  List of issue identifiers linked to the sub test plan.
- project_id String
  
  Unique identifier of the project.
- parent_plan_id String
  
  Unique identifier of the parent test plan.
- sub_plans_count Integer
  
  Number of sub plans (only in create/update response).
- start_date String
  
  Start date of the sub test plan (ISO 8601 format or null).
- end_date String
  
  End date of the sub test plan (ISO 8601 format or null).
- created_at String
  
  Timestamp when the sub test plan was created.
- owner String
  
  Email of the sub test plan owner. null when the owner is not a user in your group.
- custom_fields Array
  
  Custom field values set on the sub test plan. Empty when no value is set.
  
  ▶ SHOW VALUES
  - id Integer
    
    Unique identifier of the custom field.
  - field_type String
    
    Data type of the custom field, prefixed with field_, such as field_dropdown or field_string.
  - field_name String
    
    System name of the custom field.
  - field_user_name String
    
    Name of the custom field as shown in Test Management. Use this name as the key when you set the value.
  - optional Boolean
    
    true when the field is not required.
  - value String
    
    Stored value of the field. For dropdown fields, the identifier of the selected option.
  - option Object
    
    The selected option of a dropdown field, with its id and option_value. null for other field types.
  - options Array
    
    The selected options of a multi_dropdown field. Empty for other field types.

Delete a sub test plan

DELETE /api/v2/projects/{project_id}/test-plans/{test_plan_id}/sub-test-plans/{sub_test_plan_id}

This endpoint deletes a sub test plan by its ID.

Request parameters

Request

curl -X DELETE \
  'https://test-management.browserstack.com/api/v2/projects/{project_id}/test-plans/{test_plan_id}/sub-test-plans/{sub_test_plan_id}' \ 
  -u "YOUR_USERNAME:YOUR_ACCESS_KEY"

project_id^* string

Unique identifier of the project.
test_plan_id^* string

Unique identifier of the test plan.
sub_test_plan_id^* string

Unique identifier for the sub test plan.

Response attributes `200` `application/json`

Response

{
  "success": true,
  "message": "Sub Test Plan STP-201 deleted successfully."
}

success Boolean

Indicates if the request was successful.
message String

Deletion status message.

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Sub test plan API endpoints

List all sub test plans

Request parameters

project_id* string

test_plan_id* string

Response attributes 200 application/json

success Boolean

sub_test_plans Array

active_state String

description String

identifier String

test_runs_count Object

active Integer

closed Integer

tags Array

name String

issues Array

project_id String

parent_plan_id String

start_date String

end_date String

created_at String

owner String

custom_fields Array

id Integer

field_type String

field_name String

field_user_name String

optional Boolean

value String

option Object

options Array

info Object

page Integer

page_size Integer

count Integer

prev Integer

next Integer

Get a sub test plan

Request parameters

project_id* string

test_plan_id* string

sub_test_plan_id* string

Response attributes 200 application/json

success Boolean

sub_test_plan Object

active_state String

description String

identifier String

test_runs_count Object

active Integer

closed Integer

tags Array

test_runs Array

links Object

self String

test_runs String

name String

issues Array

project_id String

parent_plan_id String

start_date String

end_date String

created_at String

owner String

custom_fields Array

id Integer

field_type String

field_name String

field_user_name String

optional Boolean

value String

option Object

options Array

Create a sub test plan

Request parameters

project_id* string

test_plan_id* string

Request body

name* String

project_id^* string

test_plan_id^* string

Response attributes `200` `application/json`

project_id^* string

test_plan_id^* string

sub_test_plan_id^* string

Response attributes `200` `application/json`

project_id^* string

test_plan_id^* string

name^* String

Response attributes `200` `application/json`

project_id^* string

test_plan_id^* string

sub_test_plan_id^* string

name^* String

Response attributes `200` `application/json`