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}

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 depthdisplay_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)
Was this article helpful?
2 out of 10 found this helpful