API: Suites - TestRail

API: Suites

Use the following API methods to request details about test suites and to create or modify test suites.

On this page:

    get_suite

    Returns an existing test suite.

    GET index.php?/api/v2/get_suite/{suite_id}

    Parameters

    Name Type Required Description
    suite_id
    integer true The ID of the test suite

     

    Response content

    Please see below for a typical example response:

    {
    	"description": "..",
    	"id": 1,
    	"name": "Setup & Installation",
    	"project_id": 1,
    	"url": "http:///testrail/index.php?/suites/view/1"
    }
    

    The following fields are included in the response:

    Name Type Description
    completed_on
    timestamp The date/time when the test suite was closed (as UNIX timestamp) (added with TestRail 4.0)
    description
    string The description of the test suite
    id
    integer The unique ID of the test suite
    is_baseline
    boolean True if the test suite is a baseline test suite and false otherwise (added with TestRail 4.0)
    is_completed
    boolean True if the test suite is marked as completed/archived and false otherwise (added with TestRail 4.0)
    is_master
    boolean True if the test suite is a master test suite and false otherwise (added with TestRail 4.0)
    name
    string The name of the test suite
    project_id
    integer The ID of the project this test suite belongs to
    url
    string The address/URL of the test suite in the user interface

    Response codes

    Status Code Description
    200 Success (the test suite is returned as part of the response)
    400 Invalid or unknown test suite
    403 No access to the project
    429 TestRail Cloud only—Too many requests (see API rate limit)

     

    get_suites

    Returns a list of test suites for a project.

    GET index.php?/api/v2/get_suites/{project_id}

    Parameters

    Name Type Required Description
    project_id
    integer true The ID of the project

     

    Response content

    The response includes an array of test suite. Each test suite in this list follows the same format as get_suite.

    [
    	{ "id": 1, "name": "Setup & Installation", .. },
    	{ "id": 2, "name": "Document Editing", .. },
    	..
    ]
    

    Response codes

    Status Code Description
    200 Success (the test suites are returned as part of the response)
    400 Invalid or unknown project
    403 No access to the project
    429 TestRail Cloud only—Too many requests (see API rate limit)

     

    add_suite

    Creates a new test suite.

    POST index.php?/api/v2/add_suite/{project_id}

    Parameters

    Name Type Required Description
    project_id
    integer true The ID of the project the test suite should be added to

     

    Request body

    The following fields are supported in the POST request body:

    Name Type Required Description
    name
    string true The name of the test suite 
    description
    string false The description of the test suite

    Request example

    Also see the following example which shows how to create a new, empty test suite:

    {
    	"name": "This is a new test suite",
    	"description": "Use the description to add additional context details"
    }
    

    Once you’ve added a test suite, you can start adding sections and test cases.

    Response content

    If successful, this method returns the new test suite using the same response format as get_suite.

    Response codes

    Status Code Description
    200 Success (the test suite was created and is returned as part of the response)
    400 Invalid or unknown project
    403 No permissions to add test suites or no access to the project
    429 TestRail Cloud only—Too many requests (see API rate limit)

     

    update_suite

    Updates an existing test suite (partial updates are supported, i.e. you can submit and update specific fields only).

    POST index.php?/api/v2/update_suite/{suite_id}

    Parameters

    Name Type Required Description
    suite_id
    integer true The ID of the test suite

     

    This methods supports the same POST fields as add_suite.

    Response content

    If successful, this method returns the updated test suite using the same response format as get_suite.

    Response codes

    Status Code Description
    200 Success (the test suite was updated and is returned as part of the response)
    400 Invalid or unknown test suite
    403 No permissions to modify test suites or no access to the project
    429 TestRail Cloud only—Too many requests (see API rate limit)

     

    delete_suite

    Deletes an existing test suite.

    POST index.php?/api/v2/delete_suite/{suite_id}

    Parameters

    Name Type Required Description
    suite_id
    integer true The ID of the test suite

     

    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 test suite and its test cases

    info Please Note: Deleting a test suite cannot be undone and also deletes all active test runs & results, i.e. test runs & results that weren’t closed (archived) yet.

    Response codes

    Status Code Description
    200 Success (the test suite and all active test runs & results were deleted)
    400 Invalid or unknown test suite
    403 No permissions to delete test suites or no access to the project
    429 TestRail Cloud only—Too many requests (see API rate limit)