API: Suites

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

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://<server>/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

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