API: Milestones

Use the following API methods to request details about milestones and to create or modify milestones.

get_milestone

Returns an existing milestone.

GET index.php?/api/v2/get_milestone/:milestone_id

:milestone_id The ID of the milestone

Response content

Please see below for a typical example response:

{
	"completed_on": 1389968184,
	"description": "...",
	"due_on": 1391968184,
	"id": 1,
	"is_completed": true,
	"name": "Release 1.5",
	"project_id": 1,
	"url": "http://<server>/testrail/index.php?/milestones/view/1"
}

The following fields are included in the response:

Name Type Description
completed_on timestamp The date/time when the milestone was marked as completed (as UNIX timestamp)
description string The description of the milestone
due_on timestamp The due date/time of the milestone (as UNIX timestamp)
id int The unique ID of the milestone
is_completed bool True if the milestone is marked as completed and false otherwise
is_started bool True if the milestone is marked as started and false otherwise (available since TestRail 5.3)
milestones array The sub milestones that belong to the milestone (if any); only available with get_milestone (available since TestRail 5.3)
name string The name of the milestone
parent_id int The ID of the parent milestone the milestone belongs to (if any) (available since TestRail 5.3)
project_id int The ID of the project the milestone belongs to
start_on timestamp The scheduled start date/time of the milestone (as UNIX timestamp) (available since TestRail 5.3)
started_on timestamp The date/time when the milestone was started (as UNIX timestamp) (available since TestRail 5.3)
url string The address/URL of the milestone in the user interface

Response codes

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

get_milestones

Returns the list of milestones for a project.

GET index.php?/api/v2/get_milestones/:project_id

:project_id The ID of the project

Request filters

The following filters can be applied:

Name Type Description
:is_completed bool 1 to return completed milestones only. 0 to return open (active/upcoming) milestones only (available since TestRail 4.0).
:is_started bool 1 to return started milestones only. 0 to return upcoming milestones only (available since TestRail 5.3).

# All active milestones for project with ID 1 
GET index.php?/api/v2/get_milestones/1&is_completed=0

Response content

The response includes an array of milestones. Each milestone in this list follows the same format as get_milestone.

[
	{ "id": 1, "name": "Release 1.5", .. },
	{ "id": 2, "name": "Release 1.6", .. },
	..
]

Response codes

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

add_milestone

Creates a new milestone.

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

:project_id The ID of the project the milestone should be added to

Request fields

The following POST fields are supported:

Name Type Description
name string The name of the milestone (required)
description string The description of the milestone
due_on timestamp The due date of the milestone (as UNIX timestamp)
parent_id int The ID of the parent milestone, if any (for sub-milestones) (available since TestRail 5.3)
start_on timestamp The scheduled start date of the milestone (as UNIX timestamp) (available since TestRail 5.3)

Request example

Also see below for an example on how to create a new, empty milestone with a due date:

{
	"name": "Release 2.0",
	"due_on": 1394596385
}

Response content

If successful, this method returns the new milestone using the same response format as get_milestone.

Response codes

200 Success, the milestone was created and is returned as part of the response
400 Invalid or unknown project
403 No permissions to add milestones or no access to the project

update_milestone

Updates an existing milestone (partial updates are supported, i.e. you can submit and update specific fields only).

POST index.php?/api/v2/update_milestone/:milestone_id

:milestone_id The ID of the milestone

Request fields

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

Name Type Description
is_completed bool True if a milestone is considered completed and false otherwise
is_started bool True if a milestone is considered started and false otherwise
parent_id int The ID of the parent milestone, if any (for sub-milestones) (available since TestRail 5.3)
start_on timestamp The scheduled start date of the milestone (as UNIX timestamp) (available since TestRail 5.3)

Request example

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

{
	"is_completed": true
}

Response content

If successful, this method returns the updated milestone using the same response format as get_milestone.

Response codes

200 Success, the milestone was updated and is returned as part of the response
400 Invalid or unknown milestone
403 No permissions to modify milestones or no access to the project

delete_milestone

Deletes an existing milestone.

POST index.php?/api/v2/delete_milestone/:milestone_id

:milestone_id The ID of the milestone

Please note: Deleting a milestone cannot be undone.

Response codes

200 Success, the milestone was deleted
400 Invalid or unknown milestone
403 No permissions to delete milestones or no access to the project