JIRA Agile REST API Reference

JIRA Agile 6.7.6

This is the reference document for the REST API and resources provided by JIRA. The REST APIs are developers who want to integrate JIRA with other standalone or web applications, and administrators who want to script interactions with the JIRA server.

If you are after an introductory, high-level view of the JIRA REST API, rather than an exhaustive reference document, then the best place to start is the JIRA REST API home.

Getting started

Because the REST API is based on open standards, you can use any web development language to access the API. If you are using Java, however, the easiest way to get started using the JIRA REST API is to download with the JIRA REST Java Client (JRJC) and use it as a library within your own application. For other languages, refer to the JIRA REST API home for code examples.

Structure of the REST URIs

JIRA'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 REST API uses JSON as its communication format, and the standard HTTP methods like GET, PUT, POST and DELETE (see API descriptions below for which methods are available for each resource). URIs for JIRA's REST API resource have the following structure: 

http://host:port/context/rest/api-name/api-version/resource-name

Currently there are two API names available, which will be discussed further below:

  • auth - for authentication-related operations, and
  • api - for everything else.

The current API version is 2. However, there is also a symbolic version, called latest, which resolves to the latest version supported by the given JIRA instance. As an example, if you wanted to retrieve the JSON representation of issue JRA-9 from Atlassian's public issue tracker, you would access: 

https://jira.atlassian.com/rest/api/latest/issue/JRA-9

There is a WADL document that contains the documentation for each resource in the JIRA REST API. It is available here.

Expansion in the REST APIs

In order to minimise network traffic and server CPU usage, the JIRA REST API sometimes uses a technique called expansion. When a REST resource uses expansion then parts of that resource will not be included in the JSON response unless explicitly requested. The way to request those fragments to be included is by using the expand query parameter.

You can use the expand query parameter to specify a comma-separated list of entities that you want expanded, identifying each of them by name. For example, appending ?expand=names,renderedFields to an issue's URI requests the inclusion of the translated field names and the HTML-rendered field values in the response. Continuing with our example above, we would use the following URL to get that information for JRA-9: 

https://jira.atlassian.com/rest/api/latest/issue/JRA-9?expand=names,renderedFields

To discover the identifiers for each entity, look at the expand property in the parent object. In the JSON example below, the resource declares widgets as being expandable. 

{"expand":"widgets", "self":"http://www.example.com/jira/rest/api/resource/KEY-1", "widgets":{"widgets":[],"size":5}}

You can use the dot notation to specify expansion of entities within another entity. For example ?expand=widgets.fringels would expand the widgets collection and also the fringel property on each widget.

Authentication

Any authentication that works against JIRA will work against the REST API. The prefered authentication methods are OAuth and HTTP Basic (when using SSL), which are both documented in the JIRA REST API Tutorials. Other supported methods include: HTTP Cookies, and Trusted Applications.

The log-in page uses cookie-based authentication, so if you are using JIRA in a browser you can call REST from Javascript on the page and rely on the authentication that the browser has established. Callers wanting to reproduce the behaviour of the JIRA log-in page (for example, to display authentication error messages to users) or who are calling both the REST and SOAP API can POST to the /auth/1/session resource as per the documentation below.

You can find OAuth code samples in several programming languages at bitbucket.org/atlassian_tutorial/atlassian-oauth-examples.

Paged API

JIRA uses pagination to conserve server resources and limit response size for resources that return potentially large collection of items. A request to a pages API will result in a values array wrapped in a JSON object with some paging metada, like this: 

{
    "startAt" : 0,
    "maxResults" : 10,
    "total": 200,
    "values": [
        { /* result 0 */ },
        { /* result 1 */ },
        { /* result 2 */ }
    ]
}

Clients can use the startAt and maxResults parameters to retrieve the desired numbers of results.

The maxResults parameter indicates how many results to return per page. Each API may have a different limit for number of items returned.

The startAt parameter indicates which item should be used as the first item in the page of results.

Important: The response contains a total field. This indicates, how many items to which calling user has permissions are in the system. This number may change while client requests next pages. A client should always assume that the requested page can be empty. REST API consumers should also consider the field to be optional. In cases, when calculating this value is too expensive we may not include this in response.

Experimental methods

Methods marked as experimental may change without an earlier notice. We are looking for your feedback for these methods.

Special Request and Response headers

  • X-AUSERNAME - Response header which contains either username of the authenticated user or 'anonymous'.
  • X-Atlassian-Token - methods which accept multipart/form-data will only process requests with 'X-Atlassian-Token: nocheck' header.

Resources

greenhopper/experimental-api/1.0//sprint

Get a sprint given its id. The sprint is only returned if the user can see board where the sprint was created or can see at least one of the issues assigned to the sprint.

Responses
  • Status 200 - application/json

    Example
    {"id":37,"self":"http://www.example.com/jira/rest/greenhopper/experimental-api/1.0/sprint/23","state":"closed","name":"sprint 1","startDate":"2015-04-11T15:22:00.000+10:00","endDate":"2015-04-20T01:22:00.000+10:00","completeDate":"2015-04-20T11:04:00.000+10:00"}

    Returns the requested sprint.
  • Status 403
    Returned if user does not have valid license.
  • Status 404
    Returned if sprint does not exist or the user cannot view it.

Performs a full update of a sprint.

This is a full update, meaning that the result will be exactly the same as request body. Any field not present in the sent json will be set to null.

Sprint state cannot be updated.

Request

Example
{"state":"closed","name":"sprint 1","startDate":"2015-04-11T15:36:00.000+10:00","endDate":"2015-04-16T14:01:00.000+10:00","completeDate":"2015-04-20T11:11:28.008+10:00"}

Responses
  • Status 200 - application/json

    Example
    {"id":37,"self":"http://www.example.com/jira/rest/greenhopper/experimental-api/1.0/sprint/23","state":"closed","name":"sprint 1","startDate":"2015-04-11T15:22:00.000+10:00","endDate":"2015-04-20T01:22:00.000+10:00","completeDate":"2015-04-20T11:04:00.000+10:00"}

    Updated sprint
  • Status 403
    Returned if user does not have valid license.
  • Status 404
    Returned if the sprint does not exist.

Performs a partial update of a sprint.

This is a partial update, meaning that fields omitted in the request json will not be updated.

Sprint state cannot be updated.

Request

Example
{"name":"new name"}

Responses
  • Status 200 - application/json

    Example
    {"id":37,"self":"http://www.example.com/jira/rest/greenhopper/experimental-api/1.0/sprint/23","state":"closed","name":"sprint 1","startDate":"2015-04-11T15:22:00.000+10:00","endDate":"2015-04-20T01:22:00.000+10:00","completeDate":"2015-04-20T11:04:00.000+10:00"}

    Updated sprint
  • Status 403
    Returned if user does not have valid license.
  • Status 404
    Returned if the sprint does not exist.

Deletes a sprint.

Only future sprint can be deleted. All sprint issues are moved to the backlog.

Responses
  • Status 204 - application/json
    Returned if the sprint was deleted successfully
  • Status 400
    Returned if the sprint is active or completed.
  • Status 403
    Returned if user does not have valid license or does not have permission to delete sprints.
  • Status 404
    Returned if the sprint does not exist.

greenhopper/experimental-api/1.0/board

Get all boards visible for the user.

Request
query parameters
parametertypedescription
startAtlong

the index of the first board to return (0 based).

maxResultsint

the maximum number of boards to return (default 50).

typestring

restricts boards to certain type. Possible type: scrum, kanban.

namestring

a required part of a board name.

Responses
  • Status 200 - application/json

    Example
    {"maxResults":2,"startAt":1,"total":5,"isLast":false,"values":[{"id":84,"self":"http://www.example.com/jira/rest/greenhopper/experimental-api/1.0/board/84","name":"scrum board","type":"scrum"},{"id":92,"self":"http://www.example.com/jira/rest/greenhopper/experimental-api/1.0/board/92","name":"kanban board","type":"kanban"}]}

    Returns the list of the board available for the user.
  • Status 403
    Returned if user does not have valid license.

Get a board given its id. The board is only returned if the user have permission to see it.

Responses
  • Status 200 - application/json

    Example
    {"id":84,"self":"http://www.example.com/jira/rest/greenhopper/experimental-api/1.0/board/84","name":"scrum board","type":"scrum"}

    Returns the requested board.
  • Status 403
    Returned if user does not have valid license.
  • Status 404
    Returned if board does not exist or the user cannot view it.

Get all epics visible for the user on board which given id. Epics are only returned if the user have permission to see the board and epics.

Request
query parameters
parametertypedescription
startAtlong

the index of the first epic to return (0 based).

maxResultsint

the maximum number of epics to return (default 50).

donestring

restricts epics to those that are done or not. Possible done param values: true, false.

Responses
  • Status 200 - application/json

    Example
    {"maxResults":2,"startAt":1,"total":5,"isLast":false,"values":[{"id":37,"self":"http://www.example.com/jira/rest/greenhopper/experimental-api/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true},{"id":37,"self":"http://www.example.com/jira/rest/greenhopper/experimental-api/1.0/epic/13","name":"epic 2","summary":"epic 2 summary","color":{"key":"color_2"},"done":false}]}

    Returns the list of epics visible on specified board.
  • Status 403
    Returned Returned if user does not have valid license.
  • Status 404
    Returned if board does not exist or the user cannot view it.

Get all sprints visible for the user on board which given id. Sprints are only returned if the user have permission to see the board.

Request
query parameters
parametertypedescription
startAtlong

the index of the first sprint to return (0 based).

maxResultsint

the maximum number of sprints to return (default 50).

statestring

restricts sprints to certain states. Possible sprint's states: future, active, closed. It is possible to define many states e.g. state=active&state=closed

Responses
  • Status 200 - application/json

    Example
    {"maxResults":2,"startAt":1,"total":5,"isLast":false,"values":[{"id":37,"self":"http://www.example.com/jira/rest/greenhopper/experimental-api/1.0/sprint/23","state":"closed","name":"sprint 1","startDate":"2015-04-11T15:22:00.000+10:00","endDate":"2015-04-20T01:22:00.000+10:00","completeDate":"2015-04-20T11:04:00.000+10:00"},{"id":72,"self":"http://www.example.com/jira/rest/greenhopper/experimental-api/1.0/sprint/73","state":"future","name":"sprint 2"}]}

    Returns the list of sprint visible on specified board.
  • Status 403
    Returned Returned if user does not have valid license.
  • Status 404
    Returned if board does not exist or the user cannot view it.

Creates a sprint. Sprint name and state are required.

State can be one of three:

active
Active sprint, start and end date must be provided
closed
Closed sprint, start, end and completion date must be provided
future
Future sprint, no dates are expected

Name is trimmed.

Request

Example
{"state":"closed","name":"sprint 1","startDate":"2015-04-11T15:36:00.000+10:00","endDate":"2015-04-16T14:01:00.000+10:00","completeDate":"2015-04-20T11:11:28.008+10:00"}

Responses
  • Status 201 - application/json

    Example
    {"id":37,"self":"http://www.example.com/jira/rest/greenhopper/experimental-api/1.0/sprint/23","state":"closed","name":"sprint 1","startDate":"2015-04-11T15:22:00.000+10:00","endDate":"2015-04-20T01:22:00.000+10:00","completeDate":"2015-04-20T11:04:00.000+10:00"}

    Created sprint
  • Status 403
    Returned if user does not have valid license.
  • Status 404
    Returned if board does not exist or the user cannot view it.

Get all versions visible for the user on board which given id. Versions are only returned if the user have permission to see the board.

Request
query parameters
parametertypedescription
startAtlong

the index of the first version to return (0 based).

maxResultsint

the maximum number of versions to return (default 50).

releasedstring

restricts versions to released or unreleased. Possible released param values: true, false.

Responses
  • Status 200 - application/json

    Example
    {"maxResults":2,"startAt":1,"total":5,"isLast":false,"values":[{"id":10000,"projectId":10000,"name":"Version 1","description":"A first version","archived":false,"released":true,"releaseDate":"2015-04-20T01:02:00.000+10:00"},{"id":10010,"projectId":10000,"name":"Next Version","description":"Minor Bugfix version","archived":false,"released":false}]}

    Returns the list of version visible on specified board.
  • Status 403
    Returned Returned if user does not have valid license.
  • Status 404
    Returned if board does not exist or the user cannot view it.

greenhopper/experimental-api/1.0/epic

Get a epic given its id. The epic is only returned if the user can has permission to see it.

Responses
  • Status 200 - application/json

    Example
    {"id":37,"self":"http://www.example.com/jira/rest/greenhopper/experimental-api/1.0/epic/23","name":"epic 1","summary":"epic 1 summary","color":{"key":"color_4"},"done":true}

    Returns the requested epic.
  • Status 403
    Returned if user does not have valid license.
  • Status 404
    Returned if epic does not exist or the user cannot view it.