JIRA REST APIs

This page provides an overview of the JIRA REST APIs. JIRA's REST APIs are the recommended and supported remote APIs (from JIRA 5.0 and later). This is where Atlassian will focus its attention from this point onwards, adding functionality and fixing bugs.

  • Looking for the full REST API documentation for JIRA? See the JIRA APIs page or use the search (top right of page) if you know the name of the resource.

On this page:

Overview

The Atlassian REST APIs provide a standard interface for interacting with JIRA and our other applications. 

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. Your methods will be the standard HTTP methods like GET, PUT, POST and DELETE. REST APIs operate over HTTP(s) making it easy to use with any programming language or framework. The input and output format for the JIRA REST APIs is JSON.

JIRA uses the Atlassian REST plugin to implement the JIRA APIs. The REST plugin is bundled with JIRA. You can add your own REST APIs to JIRA by creating a JIRA plugin that includes the REST plugin module. See the basic principles we employ in our REST API design

If you haven't used the JIRA REST APIs before, make sure you read the Atlassian REST API policy.

Browsing and Testing your REST APIs from the Application UI

Since the specifics of the REST API vary between Atlassian applications, the best way to learn about the REST API Browser for your product is to use the REST API Browser built into your JIRA instance. 

The REST API Browser lets you browse, inspect and try the REST API Browser for your application. It's a tool for discovering the REST APIs and other remote APIs available in Atlassian applications.

The browser is built into several types of Atlassian applications, including Stash and recent versions of Confluence and JIRA. It's also a part of the Developer Toolbox plugin (included by default in developer instances of Atlassian applications) or available separately.

For details on getting and using the RAB, see Using the REST API Browser

A Simple Example: Creating an Issue in JIRA

Want to create an issue in JIRA via REST? Here's how easy it is.

The examples below use curl. Ideally, you should use the REST API Browser to investigate how the API works, but this example is meant to give you a glimpse.  We'll create an issue in a local JIRA instance.

A few points to note about our example:

  • The input file is denoted by the '--data @filename' syntax. The data is shown separately, and uses the JSON format.
  • Make sure the content type in the request is set to 'application/json', as shown in the example.
  • POST the JSON to your JIRA server. In the example, the server is http://localhost:2990/jira/rest/api/2/issue/.
  • The example uses basic authentication, with a username of admin and password of admin.
  • You'll need to add a project to the instance before running, and get the project ID of the project to which you want to add the issue beforehand.

To try a simple REST command with curl, follow these steps:

  1. Start by creating the data file that contains the POST data. In our command, we'll assume the file is named data.txt. Add the following content:

    Our project ID is 10000. You should use a suitable ID of a project in your instance. Also, the issue type in our case is 3, which represents a task.

    Alternatively, find the api/2/issue resource in the REST API Browser, and paste the text above into the Request Body field to try it out.

  2. From the command line enter the following command:

    As before, adjust details for your environment, such as the hostname or port of the JIRA instance. Note that a cloud instance or most public instances would require the use of HTTPS and of course valid credentials for the instance.

The response provides the issue ID, issue key, and the URL to the issue (which can then be used to GET additional data, PUT updates, etc).

Instead of using numeric identifiers for the project and issue type, you could have used the key and name of the type instead. For example:

To learn more about creating an issue via REST, see:

Authentication

The REST APIs support basic authentication, OAuth and session authentication. See the examples of basic authentication and OAuth.

How to Edit and Update Issues

A guide to how to update an issue via REST.

Tutorials

Get hands-on with the JIRA REST API with our JIRA REST API tutorials.

Powered by Confluence and Scroll Viewport