Getting started with the REST API 2.0

Standard
Enterprise

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 GETPUTPOST, and PATCH (see API descriptions below for which methods are available for each resource).

The objects listed below use the default Jira Align terminology:

Object Create (Post) Read (Get) Update (Put or Patch)
Theme  Yes  Yes  Yes
Epic  Yes  Yes  Yes
Capability  Yes  Yes  Yes
Feature  Yes  Yes  Yes
Story  Yes  Yes  Yes
Task  Yes  Yes  Yes
Defect  Yes  Yes  Yes
Risk  Yes  Yes  Yes
Goals  Yes  Yes  Yes
Objectives  Yes  Yes  Yes
Key Results  Yes  Yes  Yes
Portfolio  Yes  Yes  No
Program  Yes  Yes  Yes
Team  Yes  Yes  Yes
User  Yes  Yes  Yes
Release (Program Increment)  Yes  Yes  Yes
Release Vehicles  Yes  Yes  Yes
Iteration (Sprint)  Yes  Yes  Yes
Product  Yes  Yes  Yes
Snapshots  Yes  Yes  Yes
Value Streams (Process Flows)  Yes  Yes  No
Customer  Yes  Yes  No
Region  Yes  Yes  Yes
City  Yes  Yes  Yes
Ideation (Ideas)  Yes  Yes  No

 

Was this article helpful?
1 out of 2 found this helpful
Print Friendly Version of this pagePrint Get a PDF version of this webpagePDF

Join the Atlassian Community!

The Atlassian Community is a unique, highly collaborative space where customers and Atlassians come together. Ask questions and get answers, start discussions, and collaborate with thousands of other Jira Align customers. Visit the Jira Align Community Collection today.

Need to contact Jira Align Support? Please open a support request.