API: Sections

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

:section_id 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 int The level in the section hierarchy of the test suite
description string The description of the section (added with TestRail 4.0)
display_order int The order in the test suite
id int The unique ID of the section
parent_id int The ID of the parent section in the test suite
name string The name of the section
suite_id int 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

200 Success, the section is returned as part of the response
400 Invalid or unknown section
403 No access to the project

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

:project_id The ID of the project
:suite_id The ID of the test suite (optional if the project is operating in single suite mode)

Response content

Please see below for a typical example:

[
	{
		"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

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

add_section

Creates a new section.

POST index.php?/api/v2/add_section/:project_id

:project_id The ID of the project

Request fields

The following POST fields are supported:

Name Type Description
description string The description of the section (added with TestRail 4.0)
suite_id int The ID of the test suite (ignored if the project is operating in single suite mode, required otherwise)
parent_id int The ID of the parent section (to build section hierarchies)
name string The name of the section (required)

Request example

Also see the following example which shows how to create a new, empty section (using a previously created section as 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

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

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

:section_id The ID of the section

Request fields

The following POST fields are supported:

Name Type Description
description string The description of the section (added with TestRail 4.0)
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

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

delete_section

Deletes an existing section.

POST index.php?/api/v2/delete_section/:section_id

:section_id The ID of the section

Please note: 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.

Response codes

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