JIRA 5.0 and later. REST is the recommended and supported remote API in JIRA 5.0 and later. This is where Atlassian will focus its attention from this point onwards, adding functionality and fixing bugs.
JIRA's REST APIs are for developers who want to build functionality on top of JIRA.
On this page:
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.
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:
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.
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 an OnDemand 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:
- Our tutorial about creating an issue via REST.
- Information about updating an issue via REST is equally applicable to creating an issue.
The Shape of an Issue in REST
What does an issue look like in JIRA REST? See the JSON for a JIRA Issue in REST.
Issue Fields in REST
How are issue fields handled in REST in JIRA? Here's a guide to the basics.
How to Edit and Update Issues
A guide to how to update an issue via REST.
See our JIRA REST API tutorials.
Full REST API Documentation
See the details of each REST request and response in our reference documentation.