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

    Request filters

    The following filters can be applied:

    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:

    [
    		"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
    	},
    	..
    ] 
    

    info Please Note: As of February 26, 2021 the data structure returned by bulk GET API endpoints will change. These bulk endpoints will no longer return an array of all entities, but will instead return an object with additional pagination fields and an array of up to 250 entities.To see the new response structure and test any necessary code changes, include the following header and value in your API requests: x-api-ident: beta.

    New 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

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

    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
    :section_id The ID of the section.

     

    Request fields

    The following POST fields are supported:

    Name Type Description
    parent_id int 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 direct child of the section being moved.
    after_id int The section ID after which the section should be put (can be null)

     

    Response codes

    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

     

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

    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.

    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

    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