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}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 suites. 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 method 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
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.
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
Omitting the soft parameter, or submitting soft=0 will delete the test suite and its test cases
If soft=1, this will return data on the number of affected tests, cases, etc.
Including soft=1 will not actually delete the entity.
Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the test suite and all active test runs and 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) |