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
    :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:///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) 
    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:

    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) 

     

    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

    The following POST fields are supported:

    Name Type Description
    name string The name of the project
    announcement string The description of the project
    show_annoucement bool True if the annoucnement should be displayed on the project’s overview page and false otherwise
    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

     

    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

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