Use the following API methods to request details about sections and to create or modify sections. Sections are used to group and organize test cases in test suites.
get_section
Returns an existing section.
GET index.php?/api/v2/get_section/{section_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
section_id | integer | true | The ID of the section |
Response content
Please see below for a typical response:
{
"depth": 0,
"description": null,
"display_order": 1,
"id": 1,
"name": "Prerequisites",
"parent_id": null,
"suite_id": 1
}
The following fields are included in the response:
Name | Type | Description |
---|---|---|
depth | integer | The level in the section hierarchy of the test suite |
description | string | The description of the section |
display_order | integer | The order in the test suite |
id | integer | The unique ID of the section |
parent_id | integer | The ID of the parent section in the test suite |
name | string | The name of the section |
suite_id | integer | The ID of the test suite this section belongs to |
The depth
, display_order
and parent
fields determine the hierarchy of the sections in a test suite. The depth
field is 0 for all sections on the root level and greater than 0 for all child sections. The depth
field, therefore, resembles the level in the section hierarchy. Also, see get_sections for an example.
Response codes
Status Code | Description |
---|---|
200 | Success (the section is returned as part of the response) |
400 | Invalid or unknown section |
403 | No access to the project |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
get_sections
Returns a list of sections for a project and test suite.
GET index.php?/api/v2/get_sections/{project_id}&suite_id={suite_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
project_id | integer | true | The ID of the project |
suite_id | integer | See Description | The ID of the test suite (optional if the project is operating in single suite mode) |
Request filters
The following filters can be applied using query parameters in the request URL:
Name | Type | Description |
---|---|---|
limit | integer | The number of sections the response should return (The response size is 250 by default) – requires TestRail 6.7 or later |
offset | integer | Where to start counting the sections from (the offset) – requires TestRail 6.7 or later |
Response Content
Please see below for a typical example:
{
"offset": 0,
"limit": 250,
"size": 23,
"_links": {
"next": null,
"prev": null
},
"sections": [
{
"depth": 0,
"display_order": 1,
"id": 1,
"name": "Prerequisites",
"parent_id": null,
"suite_id": 1
},
{
"depth": 0,
"display_order": 2,
"id": 2,
"name": "Documentation & Help",
"parent_id": null,
"suite_id": 1
},
{
"depth": 1, // A child section
"display_order": 3,
"id": 3,
"name": "Licensing & Terms",
"parent_id": 2, // Points to the parent section
"suite_id": 1
}
]
}
Also, see get_section for details on the included fields.
Response codes
Status Code | Description |
---|---|
200 | Success (the sections are returned as part of the response) |
400 | Invalid or unknown project or test suite |
403 | No access to the project |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
add_section
Creates a new section.
POST index.php?/api/v2/add_section/{project_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
project_id | integer | true | The ID of the project |
Request body
The following fields are supported in the POST request body:
Name | Type | Required | Description |
---|---|---|---|
description | string | false | The description of the section |
suite_id | integer | See Description | The ID of the test suite (ignored if the project is operating in single suite mode, required otherwise) |
parent_id | integer | false | The ID of the parent section (to build section hierarchies) |
name | string | true | The name of the section |
Request example
Also see the following example which shows how to create a new, empty section (using a previously created section as the parent):
{
"suite_id": 5,
"name": "This is a new section",
"parent_id": 10
}
Once you’ve added a section, you can start adding test cases.
Response content
If successful, this method returns the new section using the same response format as get_section.
Response codes
Status Code | Description |
---|---|
200 | Success (the section was created and is returned as part of the response) |
400 | Invalid or unknown project or test suite |
403 | No permissions to add sections or no access to the project |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
move_section
This endpoint requires TestRail 6.5.2 or later.
Moves a section to another suite or section.
POST index.php?/api/v2/move_section/{section_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
section_id | integer | true | The ID of the section |
Request body
The following fields are supported in the POST request body:
Name | Type | Description |
---|---|---|
parent_id | integer | The ID of the parent section (it can be null if it should be moved to the root). Must be in the same project and suite. May not be a direct child of the section being moved. |
after_id | integer | The section ID after which the section should be put (can be null) |
Response codes
Status Code | Description |
---|---|
200 | Success (the section was moved and is returned as part of the response) |
400 | Invalid or unknown section_id, parent_id, or after_id |
403 | No permissions to add sections or no access to the project |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
update_section
Updates an existing section (partial updates are supported, i.e. you can submit and update specific fields only).
POST index.php?/api/v2/update_section/{section_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
section_id | integer | true | The ID of the section |
Request body
The following fields are supported in the POST request body:
Name | Type | Description |
---|---|---|
description | string | The description of the section |
name | string | The name of the section |
Request example
Also, see the following example which shows how to update the name of an existing section:
{
"name": "A better section name"
}
Response content
If successful, this method returns the updated section using the same response format as get_section.
Response codes
Status Code | Description |
---|---|
200 | Success (the section was updated and is returned as part of the response) |
400 | Invalid or unknown section |
403 |
No permissions to modify sections or no access to the project |
429 | TestRail Cloud only—Too many requests (see API rate limit) |
delete_section
Deleting a section cannot be undone and also deletes all related test cases as well as active tests & results, i.e. tests & results that weren’t closed (archived) yet.
Deletes an existing section.
POST index.php?/api/v2/delete_section/{section_id}
Parameters
Name | Type | Required | Description |
---|---|---|---|
section_id | integer | true | The ID of the section |
Soft Parameter
Omitting the soft parameter, or submitting soft=0 will delete the section and its test cases
If soft=1, this will return data on the number of affected tests, cases, etc.
Including soft=1 will not actually delete the entity in TestRail UI and the output will only show in the API response.
Response codes
Status Code | Description |
---|---|
200 | Success (the section was deleted) |
400 | Invalid or unknown section |
403 | No permissions to delete sections or test cases or no access to the project |
429 | TestRail Cloud only—Too many requests (see API rate limit) |