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:

    {
    "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)