API: Projects
Use the following API methods to request details about projects and to create or modify projects
On this page:
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": integer,
"announcement": text,
"completed_on": UNIX timestamp,
"default_role_id": integer,
"default_role": string,
"is_completed": boolean,
"name": string,
"show_announcement": boolean,
"suite_mode": integer,
"url": string,
"groups": [
{
"id": integer,
"role": string,
"role_id": integer or null
},
{...}
],
"users": [
{
"id": integer,
"global_role_id": integer,
"global_role": string,
"project_role_id": integer or null,
"project_role": string or null
}
]
}
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 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 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 |
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_projects
Request filters
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=0
Response 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_project
Request 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 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": "This is a new project",
"announcement": "This is the description for the project",
"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 | false | The name of the project |
announcement |
string | false | The description 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 mark a project as completed:
{
"announcement": "Happy Holidays Everyone!"
}
Response content
{
"name": string,
"announcement": string,
"show_announcement": boolean,
"default_role_id": integer or null,
"is_completed": boolean,
"users": [
{
"user_id": integer,
"role_id": integer or null
},
{...}
]
"groups": [
{
"group_id": integer,
"role_id": integer or null,
},
{...}
]
}
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 Groups table below. (Requires TestRail 7.3 or later) |
users |
array | An array of user objects. See 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
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 |
info Please Note: 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.
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) |