Projects

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_projects

Request 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=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/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)
Was this article helpful?
0 out of 1 found this helpful