API: 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

:project_id The ID of the project

Response content

Please see the following example for a typical response:

{
	"announcement": "..",
	"completed_on": null,
	"id": 1,
	"is_completed": false,
	"name": "Datahub",
	"show_announcement": true,
	"url": "http://<server>/testrail/index.php?/projects/overview/1"
}

The following fields are included in the response:

Name Type Description
announcement string The description/announcement of the project
completed_on int The date/time when the project was marked as completed (as UNIX timestamp)
id int The unique ID of the project
is_completed bool True if the project is marked as completed and false otherwise
name string The name of the project
show_announcement bool 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) (added with TestRail 4.0)
url string The address/URL of the project in the user interface

Response codes

200 Success, the project is returned as part of the response
400 Invalid or unknown project
403 No access to the project

get_projects

Returns the list of available projects.

GET index.php?/api/v2/get_projects

Request filters

The following filters can be applied: (available since TestRail 4.0)

Name Type Description
:is_completed bool 1 to return completed projects only. 0 to return active projects only.

# 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.

[
	{ "id": 1, "name": "DataHub", .. },
	{ "id": 2, "name": "Writer", .. },
	..
]

Response codes

200 Success, the projects are returned as part of the response. Note: only returns those projects with at least read-access.

add_project

Creates a new project (admin status required).

POST index.php?/api/v2/add_project

Request fields

The following POST fields are supported:

Name Type Description
name string The name of the project (required)
announcement string The description of the project
show_announcement bool True if the announcement should be displayed on the project's overview page 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) (added with TestRail 4.0)

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

200 Success, the project was created and is returned as part of the response
403 No permissions to add projects (requires admin rights)

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

:project_id The ID of the project

Request fields

In addition to the POST fields supported by add_project, this method also supports:

Name Type Description
is_completed bool Specifies whether a project is considered completed or not

Request example

Also see below for an example on how to mark a project as completed:

{
	"is_completed": true
}

Response content

If successful, this method returns the updated project using the same response format as get_project.

Response codes

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)

delete_project

Deletes an existing project (admin status required).

POST index.php?/api/v2/delete_project/:project_id

:project_id The ID of the project

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

200 Success, the project was deleted
400 Invalid or unknown project
403 No permissions to delete projects (requires admin rights)