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 the new milestones tab for Themes, Epics, Capabilities, and Features.

Environment

Jira Align

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:

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

[
    {
        "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:

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

This will lead to the following result:

Related Content:

Release notes for Jira Align 11.0.X

Release notes for Jira Align 10.133.X