How to use the Jira Align REST API milestones endpoints available for work items (Theme, Feature, Capability, Epic).
Platform Notice: Cloud and Data Center - This article applies equally to both cloud and data center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
This article describes how to use the REST API 2.0 milestones endpoint for work items introduced with Jira Align version 11.0.0. The endpoint provides API access to milestones available in thenew milestones tab for Themes, Epics, Capabilities, and Features.
Solution
The endpoint can directly be used on the Jira Align Swagger page available with the URL: https://<site-name>.jiraalign.com/rest/align/api/docs/index.html.
In the example below we will use the Epic work item type. A similar approach can be used for the other work item types (Theme, Feature, and Capability)
Retrieving
You can retrieve all the Milestones for a given work item using a GET call and a path parameter with its id (i.e EpicId): https://{{site-name}}/rest/align/api/2/epics/:{epicId}/milestones
You can retrieve a particular Milestone using a GET call and path parameters for the Epic and the Milestone Ids: https://{{site-url}}/rest/align/api/2/epics/:{epicId}/milestones/:{milestoneId}
Creating
You can create a Milestone for a given work item using a POST call, a path parameter with its id (i.e EpicId) https://{{site-name}}/rest/align/api/2/epics/:{epicId}/milestones and a body request such as:
1
2
3
4
5
6
7
8
{
"title": "Milestone created by API with custom category 523",
"description": "Description for Epic Miclestone with custom category id 523",
"category": 523,
"state": 2,
"startOn": "2024-06-12T00:00:00.000Z",
"targetOn": "2024-06-30T00:00:00.000Z"
}(where 523 is the Id of the custom Milestone category created in the Jira Align Administration > SETTINGs > Platform Settings > Dropdowns> Milestone Categories)
Updating
To partially update an existing Milestone, use a PATCH call, a path parameter with the specific Epic and Milestone Ids: https://{{site-url}}/rest/align/api/2/epics/:{epicId}/milestones/:{milestoneId} and a body request such as the one below (to modify the 'targetOn' date).
1
2
3
4
5
6
7
[
{
"op": "replace",
"path": "/targetOn",
"value": "2024-06-30T00:00:00.000Z"
}
]To fully update an existing milestone, use a PATCH call, a path parameter with the specific Epic and Milestone Ids: https://{{site-url}}/rest/align/api/2/epics/:{epicId}/milestones/:{milestoneId} and the body request with the complete object fields:
1
2
3
4
5
6
7
8
9
{
"title": "Test Milestone to update",
"description": "To be updated by API milestone with new state and category",
"category": 523,
"state": 2,
"startOn": "2024-06-20T00:00:00.000Z",
"targetOn": "2024-06-30T00:00:00.000Z",
"completeDate": null
}Related Content:
Was this helpful?