REST API Endpoints

The app provides several API endpoints to retrieve and manage milestones from outside Jira. You can find detailed information on the available REST API endpoints, including methods, required parameters, body content, and endpoint URLs on this API documentation page.

Please note: Each instance has unique endpoints, which can be retrieved on the Project Milestones settings page in the Jira administration by system administrators.

Authentication

When accessing any of the REST API endpoints mentioned below, users must authenticate themselves using the email associated with their Atlassian account and an app API token obtainable from the app's administration.

To generate your token, navigate to Apps → Manage your Apps → Project Milestones Settings (left sidebar) → API token tab.

You have access to a comprehensive list of all your generated tokens, along with details on their creation and last usage. To generate a new API token, simply click on the designated button located at the top of the page.

Please remember that your generated token is only visible during the creation process in the modal dialog. It is crucial to copy it to your clipboard and securely store it. Once generated, the token cannot be displayed again. In case you misplace your token and fail to save it, you will need to delete the current token and generate a new one.

REST API Endpoints

1. Get Milestones

Retrieve all milestones for a project.

Method: GET
Parameters:
- project key: The project key of the project you want to get milestones for.
Body: None
Endpoint URL: Unique endpoint for your cloud instance. As system administrator, get it from Apps → Manage apps → Project Milestones Settings → REST API Endpoints tab

Responses:

Status code	Status text	Body	Reason
200	`OK`	JSON array with milestones
405	`Method not allowed`	JSON `{ error: true, message: "Method not allowed. Please use GET method." }`	Another method than GET has been used to call the endpoint.
401	`Unauthorized`	JSON `{ error: true, message: "Unauthorized - something is wrong with the provided credentials. Please authenticate with email address and api token." }`	Either email address or api token used for authentication isn’t correct. The user couldn’t be authenticated on the instance with the provided credentials.
404	`Not found`	JSON `{ error: true, message: "No project could be found with this key." }`	No project could be found with the provided key.
403	`No access`	JSON `{ error: true, message: "Access denied - you do not have permission to view this data." }`	The user calling the api has either no access to the project at all, or no permission to view milestones in that project.

2. Create Milestone

Create a new milestone in a project.

Method: POST
Parameters:
- project key: The project key of the project you want to create a milestone in.

Body:

JSON

{
    "title": "<title>",
    "description": "<description>",
    "start": "<date_format_YYYY-MM-DD>",
    "end": "<date_format_YYYY-MM-DD>"
}

Example:

JSON

{
    "title": "Feature freeze",
    "start": "2024-08-01",
    "end": "2024-08-31",
    "description": "No more features after that period."
}

Endpoint URL: Unique endpoint for your cloud instance. As system administrator, get it from Apps → Manage apps → Project Milestones Settings → REST API Endpoints tab

Responses:

Status code	Status text	Body	Reason
201	`Created`	JSON object of new milestone including new id. JSON `{ id: <new_milestone_id>, title: <new_milestone_title>, start: <new_milestone_start>, end: <new_milestone_end>, description: <new_milestone_description> }`
500	`Internal Server Error`	JSON `{ error: true, message: "Saving new milestone not possible at the moment. Please try again." }`	An error occurred when the new milestone is saved.
405	`Method not allowed`	JSON `{ error: true, message: "Method not allowed. Please use POST method." }`	Another method than POST has been used to call the endpoint.
400	`Bad request`	JSON `{ error: true, message: "<Reason for error in request body>" }`	The error can be returned for multiple reasons: the format of the request body isn’t correct provided start date is later than end date of the milestone required fields missing in request body the provided dates aren’t in format `YYYY-MM-DD`
401	`Unauthorized`	JSON `{ error: true, message: "Unauthorized - something is wrong with the provided credentials. Please authenticate with email address and api token." }`	Either email address or api token used for authentication isn’t correct. The user couldn’t be authenticated on the instance with the provided credentials.
404	`Not found`	JSON `{ error: true, message: "No project could be found with this key." }`	No project could be found with the provided key.
403	`No access`	JSON `{ error: true, message: "Access denied - you do not have permission to create milestones." }`	The user calling the api has either no access to the project at all, or no permission to create milestones in that project.

3. Edit Milestone

Edit an existing milestone in a project.

Method: PUT
Parameters:
- project key: The project key of the project you want to edit a milestone in.

Body:

JSON

{
    "id": "<milestone_id>",
    "description": "<description>",
    "start": "<date_format_YYYY-MM-DD>",
    "end": "<date_format_YYYY-MM-DD>"
}

Only milestone id is required. The milestone attributes included in the body will be updated.

Endpoint URL: Unique endpoint for your cloud instance. As system administrator, get it from Apps → Manage apps → Project Milestones Settings → REST API Endpoints tab

Responses:

Status code	Status text	Body	Reason
201	`Created`	JSON object of edited milestone. JSON `{ id: <milestone_id>, title: <new_milestone_title>, start: <new_milestone_start>, end: <new_milestone_end>, description: <new_milestone_description> }`
500	`Internal Server Error`	JSON `{ error: true, message: "Saving milestone not possible at the moment. Please try again." }`	An error occurred when the edited milestone is saved.
405	`Method not allowed`	JSON `{ error: true, message: "Method not allowed. Please use PUT method." }`	Another method than PUT has been used to call the endpoint.
400	`Bad request`	JSON `{ error: true, message: "<Reason for error in request body>" }`	The error can be returned for multiple reasons: the format of the request body isn’t correct start date would be later than end date of the milestone after editing id of milestone to be edited is missing in the request body provided dates aren’t in format `YYYY-MM-DD`
401	`Unauthorized`	JSON `{ error: true, message: "Unauthorized - something is wrong with the provided credentials. Please authenticate with email address and api token." }`	Either email address or api token used for authentication isn’t correct. The user couldn’t be authenticated on the instance with the provided credentials.
404	`Not found`	JSON `{ error: true, message: "Invalid milestone ID. The milestone with the provided ID doesn't exist." }`	No milestone to edit could be found for the provided id.
404	`Not found`	JSON `{ error: true, message: "No project could be found with this key." }`	No project could be found with the provided key.
403	`No access`	JSON `{ error: true, message: "Access denied - you do not have permission to edit milestones." }`	The user calling the api has either no access to the project at all, or no permission to edit milestones in that project.

4. Delete Milestone

Delete an existing milestone in a project.

Method: DELETE
Parameters:
- project key: The project key of the project you want to delete a milestone from.
- id: id of the milestone to be deleted
Body: None

Endpoint URL: Unique endpoint for your cloud instance. As system administrator, get it from Apps → Manage apps → Project Milestones Settings → REST API Endpoints tab

Responses:

Status code	Status text	Body	Reason
200	`OK`	Id of the milestone that has been deleted JSON `{ id: <milestone_id> }`
500	`Internal Server Error`	JSON `{ error: true, message: "Deleting milestone not possible at the moment. Please try again." }`	An error occurred when deleting the milestone.
405	`Method not allowed`	JSON `{ error: true, message: "Method not allowed. Please use DELETE method." }`	Another method than DELETE has been used to call the endpoint.
400	`Bad request`	JSON `{ error: true, message: "Missing required parameters. Milestone ID is missing." }`	No id for an milestone to be deleted has been provided as parameter.
401	`Unauthorized`	JSON `{ error: true, message: "Unauthorized - something is wrong with the provided credentials. Please authenticate with email address and Atlassian api token." }`	Either email address or api token used for authentication isn’t correct. The user couldn’t be authenticated on the instance with the provided credentials.
404	`Not found`	JSON `{ error: true, message: "Invalid milestone ID. The milestone with the provided ID doesn't exist." }`	No milestone to delete could be found for the provided id.
404	`Not found`	JSON `{ error: true, message: "No project could be found with this key." }`	No project could be found with the provided key.
403	`No access`	JSON `{ error: true, message: "Access denied - you do not have permission to delete milestones." }`	The user calling the api has either no access to the project at all, or no permission to delete milestones in that project.