JIRA REST API documentation

This document describes the REST API and resources provided by JIRA.
The REST APIs are for developers who want to integrate JIRA into their application
and for administrators who want to script interactions with the JIRA server.

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. Currently, the only supported reponse format is JSON.
Your methods will be the standard HTTP methods like GET, PUT, POST and DELETE
(see API descriptions below for which methods are available for each resource).

Because the REST API is based on open standards, you can use any web development language to access the API.

Currently, the are two api-names available 'api' and 'auth'. REST endpoints in the 'api' path allow you to access most of the information contained within an issue. The current api-version is 2.
REST endpoints in the 'auth' path allow you to access information related to authentication. The current api-version is 1.

How to use
expansion in the REST APIs

In order to minimise network traffic from the client perspective, our API uses a technique called expansion.

You can use the 'expand' query parameter to specify a comma-separated list of entities that you want
expanded, identifying each entity by a given identifier. For example, the value "comments,worklogs"
requests the expansion of entities for which the expand identifier is "comments" and worklogs".

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

Note: The 'expand' attribute should not be confused with the 'expand' query parameter which specifies
which entities you want expanded.

You can use the dot notation to specify expansion of entities within another entity.
For example "children.children" would expand the children and the children's children (because its
expand identifier is children) and the child entities within the plugin.

The response contains an Atlassian-wide "session" portion containing the session ID that can
used for further authenticated-requests.
It also contains a JIRA-specific "loginInfo" section containing information about the current user's
login details.

Returned if the login is denied due to a CAPTCHA requirement, throtting, or any other reason. It's possible
that the supplied credentials are valid, in this case.

GET

Get information about the current user. If the current user is anonymous they will get a permission denied error
trying to access this resource.
The response contains information about the current user. It will contain their username, login information,
and a link to the User Resource for the user.

Example

{"self":"http://www.example.com/jira/rest/api/2/project/MKY/role/10360","name":"Developers","id":10360,"description":"A project role that represents developers in a project","actors":[{"id":10240,"displayName":"jira-developers","type":"atlassian-group-role-actor","name":"jira-developers"}]}

Returned if the project and role exists and the user has permission to view it. Contains the role name,
description, and project actors.

Example

Example

{"self":"http://www.example.com/jira/rest/api/2/project/MKY/role/10360","name":"Developers","id":10360,"description":"A project role that represents developers in a project","actors":[{"id":10240,"displayName":"jira-developers","type":"atlassian-group-role-actor","name":"jira-developers"}]}

Returned if the project and role exists and the user has permission to view it. Contains the role name,
description, and project actors.

Example

Example

{"self":"http://www.example.com/jira/rest/api/2/project/MKY/role/10360","name":"Developers","id":10360,"description":"A project role that represents developers in a project","actors":[{"id":10240,"displayName":"jira-developers","type":"atlassian-group-role-actor","name":"jira-developers"}]}

Returned if the project and role exists and the user has permission to view it. Contains the role name,
description, and project actors.

DELETE

Returned if the project or role is not found, the calling user does not have permission to view it, or does
not have permission to modify the actors in the project role.

/api/2/issueLink

The Link Issue Resource provides functionality to manage issue links.

Methods

POST

Creates an issue link between two issues.
The user requires the link issue permission for the issue which will be linked to another issue.
The specified link type in the request is used to create the link and will create a link from the first issue
to the second issue using the outward description. It also create a link from the second issue to the first issue using the
inward description of the issue link type.
It will add the supplied comment to the first issue. The comment can have a restriction who can view it.
If group is specified, only users of this group can view this comment, if roleLevel is specified only users who have the specified role can view this comment.
The user who creates the issue link needs to belong to the specified group or have the specified role.

/api/2/issue/{issueIdOrKey}?fields

resource-wide template parameters

Methods

GET

Returns a full representation of the issue for the given issue key.
An issue JSON consists of the issue key, a collection of fields,
a link to the workflow transition sub-resource, and (optionally) the HTML rendered values of any fields that support it
(e.g. if wiki syntax is enabled for the description or comments).

Returns a full representation of the transitions possible for the specified issue and the fields required to perform the transition.

POST

Perform a transition on an issue.
The POST must contain a single JSON Object. It must have a "transition" string and a "fields" object.
A "comment" is optional. The comment can be either a simple string or an object with a "body" and "role" or "group".

request query parameters

a String of true or false indicating that any subtasks should also be deleted. If the
issue has no subtasks this parameter is ignored. If the issue has subtasks and this parameter is missing or false,
then the issue will not be deleted and an error will be returned.

Methods

GET

Returns the meta data for creating issues. This includes the available projects, issue types and fields,
including field types and whether or not those fields are required.
Projects will not be returned if the user does not have permission to create issues in that project.

Fields will only be returned if expand=projects.issuetypes.fields.

The results can be filtered by project and/or issue type, given by the query params.

request query parameters

combined with the projectKeys param, lists the projects with which to filter the results. If absent, all projects are returned.
This parameter can be specified multiple times, and/or be a comma-separated list.
Specifiying a project that does not exist (or that you cannot create issues in) is not an error, but it will not be in the results.

combined with the projectIds param, lists the projects with which to filter the results. If null, all projects are returned.
This parameter can be specified multiple times, and/or be a comma-separated list.
Specifiying a project that does not exist (or that you cannot create issues in) is not an error, but it will not be in the results.

combinded with issuetypeNames, lists the issue types with which to filter the results. If null, all issue types are returned.
This parameter can be specified multiple times, and/or be a comma-separated list.
Specifiying an issue type that does not exist is not an error.

combinded with issuetypeIds, lists the issue types with which to filter the results. If null, all issue types are returned.
This parameter can be specified multiple times, but is NOT interpreted as a comma-separated list.
Specifiying an issue type that does not exist is not an error.

POST

Creates or updates a remote issue link from a JSON representation. If a globalId is provided and a remote link
exists with that globalId, the remote link is updated. Otherwise, the remote link is created.

Example

{"self":"http://www.example.com/jira/rest/api/2/resolution/1","description":"A fix for this issue is checked into the tree and tested.","iconUrl":"http://www.example.com/jira/images/icons/status_resolved.gif","name":"Fixed"}

Returned if the resolution exists and the user has permission to view it. Contains a full representation of
the resolution in JSON format.

/api/2/issue/{issueIdOrKey}/attachments

Issue attachments

resource-wide template parameters

Methods

POST

Add one or more attachments to an issue.

This resource expects a multipart post. The media-type multipart/form-data is defined in RFC 1867. Most client
libraries have classes that make dealing with multipart posts simple. For instance, in Java the Apache HTTP Components
library provides a
MultiPartEntity
that makes it simple to submit a multipart POST.

In order to protect against XSRF attacks, because this method accepts multipart/form-data, it has XSRF protection
on it. This means you must submit a header of X-Atlassian-Token: nocheck with the request, otherwise it will be
blocked.

Returned if attachments is disabled or if you don't have permission to add attachments to this issue.

REST endpoint for searching groups in a group picker

/api/2/groups/picker?query

Methods

GET

Returns groups with substrings matching a given query. This is mainly for use with
the group picker, so the returned groups contain html to be used as picker suggestions.
The groups are also wrapped in a single response object that also contains a header for
use in the picker, specifically Showing X of Y matching groups.
The number of groups returned is limited by the system property "jira.ajax.autocomplete.limit"
The groups will be unique and sorted.

request query parameters

the maximum number of issues to return (defaults to 50). The maximum allowable value is
dictated by the JIRA property 'jira.search.views.default.max'. If you specify a value that is higher than this
number, your search results will be truncated.

Example

{"self":"http://www.example.com/jira/rest/api/2.0/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"comment":"I did some work here.","visibility":{"type":"GROUP","value":"jira-developers"},"started":"2011-08-30T23:14:17.339-0500","minutesSpent":180}

Returned if the work log with the given id exists and the currently authenticated user has permission to
view it. The returned response contains a full representation of the work log in JSON format.

PUT

Modify a component via PUT. Any fields present in the PUT will override existing values. As a convenience, if a field
is not present, it is silently ignored.
If leadUserName is an empty string ("") the component lead will be removed.

Example

{"self":"http://localhost:8090/jira/rest/api/2.0/status/10000","description":"The issue is currently being worked on.","iconUrl":"http://localhost:8090/jira/images/icons/progress.gif","name":"In Progress","id":"10000"}