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:

    API Rate Limit

    Please note that the API is rate-limited on TestRail Cloud to ensure optimal performance for all users and may throttle requests. TestRail might also return a 429 Too Many Requests response, which you are expected to handle. Such a response also includes a Retry-After header indicating how many seconds to wait before you are allowed to submit the next request.

    To avoid rate limits on TestRail Cloud, try using bulk API endpoints (e.g. using as add_results_for_cases instead of add_results_for case), build a time delay into your API calls, or upgrade to TestRail Enterprise Cloud.

    Rate limits for TestRail Cloud are as follows:

    • 180 Requests per instance, per minute for TestRail Cloud Professional subscriptions.
    • 300 Requests per instance, per minute for TestRail Cloud Enterprise subscriptions.

    No API rate limits are built into TestRail Server installations.

    get_suite

    Returns an existing test suite.

    GET index.php?/api/v2/get_suite/:suite_id
    :suite_id 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 int The unique ID of the test suite
    is_baseline bool True if the test suite is a baseline test suite and false otherwise (added with TestRail 4.0)
    is_completed bool True if the test suite is marked as completed/archived and false otherwise (added with TestRail 4.0)
    is_master bool 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 int 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

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

    get_suites

    Returns a list of test suites for a project.

    GET index.php?/api/v2/get_suites/:project_id
    :project_id 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

    200 Success, the test suites are returned as part of the response
    400 Invalid or unknown project
    403 No access to the project

    add_suite

    Creates a new test suite.

    POST index.php?/api/v2/add_suite/:project_id
    :project_id The ID of the project the test suite should be added to

    Request fields

    The following POST fields are supported:

    Name Type Description
    name string The name of the test suite (required)
    description string 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

    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

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

    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

    delete_suite

    Deletes an existing test suite.

    POST index.php?/api/v2/delete_suite/:suite_id
    :suite_id 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

    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