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,
"refs": "RF-1, RF-2",
"url": "http:///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 started 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 |
| refs | string | A comma-separated list of references/requirements (available since TestRail 6.4) |
| 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. |
| :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) |
| refs | string | A comma-separated list of references/requirements (available since TestRail 6.4) |
| 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 |
info 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 |