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, andapi
- 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 sprintGET /rest/greenhopper/experimental-api/1.0//sprint/{sprintId}
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/jsonReturns the requested sprint.
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"}
- Status
403Returned if user does not have valid license.
- Status
404Returned if sprint does not exist or the user cannot view it.
Update sprintPUT /rest/greenhopper/experimental-api/1.0//sprint/{sprintId}
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/jsonUpdated sprint
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"}
- Status
403Returned if user does not have valid license.
- Status
404Returned if the sprint does not exist.
Partially update sprintPOST /rest/greenhopper/experimental-api/1.0//sprint/{sprintId}
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/jsonUpdated sprint
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"}
- Status
403Returned if user does not have valid license.
- Status
404Returned if the sprint does not exist.
Delete sprintDELETE /rest/greenhopper/experimental-api/1.0//sprint/{sprintId}
Deletes a sprint.
Only future sprint can be deleted. All sprint issues are moved to the backlog.
Responses
- Status
204 - application/jsonReturned if the sprint was deleted successfully
- Status
400Returned if the sprint is active or completed.
- Status
403Returned if user does not have valid license or does not have permission to delete sprints.
- Status
404Returned if the sprint does not exist.
greenhopper/experimental-api/1.0/board
Get all boardsGET /rest/greenhopper/experimental-api/1.0/board
Get all boards visible for the user.
Request
query parameters
parameter | type | description |
---|---|---|
startAt | long | the index of the first board to return (0 based). |
maxResults | int | the maximum number of boards to return (default 50). |
type | string | restricts boards to certain type. Possible type: scrum, kanban. |
name | string | a required part of a board name. |
Responses
- Status
200 - application/jsonReturns the list of the board available for the user.
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"}]}
- Status
403Returned if user does not have valid license.
Get boardGET /rest/greenhopper/experimental-api/1.0/board/{boardId}
Get a board given its id. The board is only returned if the user have permission to see it.
Responses
- Status
200 - application/jsonReturns the requested board.
Example
{"id":84,"self":"http://www.example.com/jira/rest/greenhopper/experimental-api/1.0/board/84","name":"scrum board","type":"scrum"}
- Status
403Returned if user does not have valid license.
- Status
404Returned if board does not exist or the user cannot view it.
Get epicsGET /rest/greenhopper/experimental-api/1.0/board/{boardId}/epic
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
parameter | type | description |
---|---|---|
startAt | long | the index of the first epic to return (0 based). |
maxResults | int | the maximum number of epics to return (default 50). |
done | string | restricts epics to those that are done or not. Possible done param values: true, false. |
Responses
- Status
200 - application/jsonReturns the list of epics visible on specified board.
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}]}
- Status
403Returned Returned if user does not have valid license.
- Status
404Returned if board does not exist or the user cannot view it.
Get all sprintsGET /rest/greenhopper/experimental-api/1.0/board/{boardId}/sprint
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
parameter | type | description |
---|---|---|
startAt | long | the index of the first sprint to return (0 based). |
maxResults | int | the maximum number of sprints to return (default 50). |
state | string | 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/jsonReturns the list of sprint visible on specified board.
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"}]}
- Status
403Returned Returned if user does not have valid license.
- Status
404Returned if board does not exist or the user cannot view it.
Create sprintPOST /rest/greenhopper/experimental-api/1.0/board/{boardId}/sprint
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/jsonCreated sprint
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"}
- Status
403Returned if user does not have valid license.
- Status
404Returned if board does not exist or the user cannot view it.
Get all versionsGET /rest/greenhopper/experimental-api/1.0/board/{boardId}/version
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
parameter | type | description |
---|---|---|
startAt | long | the index of the first version to return (0 based). |
maxResults | int | the maximum number of versions to return (default 50). |
released | string | restricts versions to released or unreleased. Possible released param values: true, false. |
Responses
- Status
200 - application/jsonReturns the list of version visible on specified board.
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}]}
- Status
403Returned Returned if user does not have valid license.
- Status
404Returned if board does not exist or the user cannot view it.
greenhopper/experimental-api/1.0/epic
Get epicGET /rest/greenhopper/experimental-api/1.0/epic/{epicIdOrKey}
Get a epic given its id. The epic is only returned if the user can has permission to see it.
Responses
- Status
200 - application/jsonReturns the requested epic.
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}
- Status
403Returned if user does not have valid license.
- Status
404Returned if epic does not exist or the user cannot view it.