Getting started with the REST API 2.0

About

The Jira Align REST API exposes key objects in Jira Align's people, work, and time hierarchies via a standardized programmatic interface. Using the API, you can perform most actions available through the user interface, as well as simplify user management, mass update work objects, and develop integrations between Jira Align and other applications.

This page provides an overview of the API and documents the REST resources available in Jira Align. For complete documentation on the resources, along with HTTP responses and sample requests, please view the documentation available in your environment at:

https://<site-url>/rest/align/api/docs/index.html

Versions and URI

This documentation is for version 2 of the Jira Align REST API, which is the latest version.

The URIs for resources have the following structure:

https://<site-url>/rest/align/api/2/<resource-name>

For example, https://your-domain.agilecraft.com/rest/align/api/2/epic/1001

Version 1 of Jira Align REST API is still supported, but no additional resources will be added; all development is on version 2 of the API.

Authentication

You can authenticate to the API using Atlassian API tokens or Jira Align API tokens. If you log into Jira Align using the Atlassian Guard authentication method, we recommend using Atlassian API tokens. This lets you take advantage of new security features for the Atlassian API such as revoking and blocking token access, and new features rolled out in the future.

Atlassian API tokens

Obtain Atlassian API tokens if you authenticate to Jira Align using Atlassian Guard. Review the manage API tokens for your Atlassian account article for instructions on obtaining a new token.

Note: To access Jira Align's swagger API documentation with an Atlassian API token, you will need to use the basic authentication type. The username and api token need to be Base64 encoded as a single string, with a colon between the two values.

{
"method": "GET",
"url": "https://alignsupport.jiraalign.com/rest/align/api/2/{end point}",
"headers": {
"Authorization": "Basic {username:api_token}"
}

Jira Align API tokens

Bearer authentication using API tokens (tokens can be generated on the User Profile page of Jira Align) is supported. These tokens do not expire until the user generates a new token or is deactivated.

The user token needs to include "bearer" in front of the user's API Token (API Key). 

Example JSON Request format:

{
"method": "GET",
"url": "https://alignsupport.jiraalign.com/rest/align/api/2/{end point}",
"headers": {
"Authorization": "bearer {api key}"
}

Authorization is based on the authenticated user when Jira Align REST APIs are called. User privileges, such as data and page access, via the REST APIs are identical to privileges in the interface. For example, if a user's system role provides read-only access to epics in a single portfolio, the user will not be able to create or update epics with the API, and will only be able to read epics from the single portfolio.

Rate Limiting

To ensure our platform remains stable, all Jira Align APIs are rate-limited. Currently, if calls from same IP address exceed 600 requests per 60 seconds, calls are blocked for 60 seconds. When this threshold is met and calls are blocked, you'll receive a '429 too many requests' error response. We ask developers to use industry-standard techniques for limiting calls, caching results, and re-trying requests responsibly.

Objects

Jira Aligns's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The Jira Align REST API uses JSON as its communication format, and the standard HTTP methods like GET, PUT, POST, and PATCH (see API descriptions below for which methods are available for each resource).

The objects listed below use the default Jira Align terminology: