API: Projects - TestRail

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:

    {
	"announcement": "..",
	"completed_on": null,
	"id": 1,
	"is_completed": false,
	"name": "Datahub",
	"show_announcement": true,
	"url": "http:///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
    		 integer The date/time when the project was marked as completed (as UNIX timestamp) 
    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

     

    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

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

    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)