API: Sections - TestRail

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.

On this page:

    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 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

    Moves a section to another suite or section. 

    Requires TestRail 6.5.2 or later

    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

    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

    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.

    Note: Omitting the soft parameter, or submitting soft=0 will delete the section and its test cases

    info 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

    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)