Use the following API methods to request details about projects and to create or modify projects.
get_project
Returns an existing project.
GET index.php?/api/v2/get_project/{project_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| project_id | integer | true | The ID of the project |
Response content
Please see the following example for a typical response:
{
"id": 1,
"announcement": "Welcome to project X",
"completed_on": 1389968184,
"default_role_id": 3,
"default_role": "Tester",
"is_completed": false,
"name": "Project X",
"show_announcement": true,
"suite_mode": 1,
"url": "https://instance.testrail.io/index.php?/projects/overview/1",
"users": [
{
"id": 3,
"global_role_id": null,
"global_role": null,
"project_role_id": null,
"project_role": null
}
],
"groups": []
}The following fields are included in the response:
| Name | Type | Description |
|---|---|---|
| announcement | string | The description/announcement of the project |
| completed_on | integer | The date/time when the project was marked as completed (as UNIX timestamp) |
| default_role | string | The name of the default role configured for project access- requires TestRail 7.3 or later |
| default_role_id | integer | The ID of the default role configured for project access- requires TestRail 7.3 or later |
| groups | array | An array of group objects. See the Groups table below- requires TestRail 7.3 or later |
| id | integer | The unique ID of the project |
| is_completed | boolean | True if the project is marked as completed and false otherwise |
| name | string | The name of the project |
| show_announcement | boolean | True to show the announcement/description and false otherwise |
| suite_mode | integer | The suite mode of the project (1 for single suite mode, 2 for single suite + baselines, 3 for multiple suites) |
| url | string | The address/URL of the project in the user interface |
| users | array | An array of user objects. See the Users table below - requires TestRail Enterprise 7.3 or later |
The following GROUPS fields are included in the response:
| Name | Type | Description |
|---|---|---|
| id | integer | The ID of the user group |
| role | string | The name of the role assigned to the group within the project |
| role_id | integer | The ID of the role assigned to the group within the project |
The following USERS fields are included in the response:
| Name | Type | Description |
|---|---|---|
| id | integer | The ID of the user |
| global_role_id | integer | The ID of the role assigned to the user’s global profile |
| global_role | string | The name of the role assigned to the user’s global profile |
| project_role_id | integer | The ID of the role assigned to the user within the project, if any |
| project_role | string | The name of the role assigned to the user within the project, if any |
Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the project is 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) |
get_projects
Returns the list of available projects.
GET index.php?/api/v2/get_projectsRequest body
The following filters can be applied as query parameters on the request URL:
| Name | Type | Description |
|---|---|---|
| is_completed | boolean | 1 to return completed projects only. 0 to return active projects only |
| limit | integer | The number of projects the response should return (The response size is 250 by default) — requires TestRail 6.7 or later |
| offset | integer | Where to start counting the projects from (the offset)— requires TestRail 6.7 or later |
# All active projects
GET index.php?/api/v2/get_projects&is_completed=0Response Content
The response includes an array of projects. Each project in this list follows the same format as get_project.
{
"offset": 0,
"limit": 250,
"size": 2,
"_links": {
"next": null,
"prev": null,
},
"projects": [
{ "id": 1, "name": "DataHub", .. },
{ "id": 2, "name": "Writer", .. }
]
}Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the projects are returned as part of the response. Note: only returns those projects with at least read-access.) |
| 429 | TestRail Cloud only—Too many requests (see API rate limit) |
add_project
Creates a new project (admin status required).
POST index.php?/api/v2/add_projectRequest body
The following filters can be applied in the POST request body message:
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | true | The name of the project |
| announcement | string | false | The description/announcement of the project |
| show_announcement | boolean | false | True if the announcement should be displayed on the project’s overview page and false otherwise |
| suite_mode | integer | false | The suite mode of the project (1 for single suite mode, 2 for single suite + baselines, 3 for multiple suites) |
Request example
Also see below for an example on how to create a new, empty project:
{
"name": "Project X",
"announcement": "Welcome to project X",
"show_announcement": true
}Response content
If successful, this method returns the new project using the same response format as get_project.
Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the project was created and is returned as part of the response) |
| 403 | No permissions to add projects (requires admin rights) |
| 429 | TestRail Cloud only—Too many requests (see API rate limit) |
update_project
Updates an existing project (admin status required; partial updates are supported, i.e. you can submit and update specific fields only).
POST index.php?/api/v2/update_project/{project_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| project_id | integer | true | The ID of the project |
Request body
The following filters can be applied:
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | true | The name of the project |
| announcement | string | false | The description/announcement of the project |
| show_announcement | boolean | false | True if the announcement should be displayed on the project’s overview page and false otherwise |
| suite_mode | integer | false | The suite mode of the project (1 for single suite mode, 2 for single suite + baselines, 3 for multiple suites) |
Request example
Also, see below for an example of how to mark a project as completed:
{
"announcement": "Happy Holidays Everyone!"
}Response content
{
"name": "Project X",
"announcement": "Welcome to project X",
"show_announcement": true,
"default_role_id": 3,
"is_completed": false,
"users": [
{
"user_id": 4,
"role_id": null
}
]
"groups": []
}The following fields are included in the response:
| Name | Type | Description |
|---|---|---|
| default_role_id | integer | The ID of the default role configured for project access— requires TestRail 7.3 or later |
| groups | array | An array of group objects. See the Groups table below — requires TestRail 7.3 or later |
| users | array | An array of user objects. See the Users table below.— requires TestRail 7.3 or later |
The following GROUPS fields are included in the response:
| Name | Type | Description |
|---|---|---|
| id | integer | The ID of the user group |
| role_id | integer | The ID of the role assigned to the group within the project. Submit 0 to change the assignment to ‘Global Role’. Submit null to clear the project-specific role. |
The following USERS fields are included in the response:
| Name | Type | Description |
|---|---|---|
| id | integer | The ID of the user |
| role_id | integer | The ID of the role assigned to the user within the project. Submit 0 to change the assignment to ‘Global Role’. Submit null to clear the project-specific role assignment |
Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the project was updated and is returned as part of the response) |
| 400 | Invalid or unknown project |
| 403 | No permissions to modify projects (requires admin rights) |
| 429 | TestRail Cloud only—Too many requests (see API rate limit) |
delete_project
Deleting a project cannot be undone and also permanently deletes all test suites & cases, test runs & results, and everything else that is part of the project.
Deletes an existing project (admin status required).
POST index.php?/api/v2/delete_project/{project_id}Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| project_id | integer | true | The ID of the project |
Response codes
| Status Code | Description |
|---|---|
| 200 | Success (the project was deleted) |
| 400 | Invalid or unknown project |
| 403 |
No permissions to delete projects (requires admin rights) |
| 429 | TestRail Cloud only—Too many requests (see API rate limit) |