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.
URIs for JIRA's REST API resource have the following structure:
With context: http://host:port/context/rest/api-name/api-version/resource-name
Or without context: http://host:port/rest/api-name/api-version/resource-name
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.0.alpha1. REST endpoints in the 'auth' path allow you to access information related to authentication. The current api-version is 1.
Example with context: http://myhost.com:8080/jira/rest/api/2.0.alpha1/project/JRA
Example without context: http://myhost.com:8080/rest/api/2.0.alpha1/project/JRA
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.
All methods return accept and return JSON exclusively. Example:
{
"expand": "widgets",
"self": "http://www.example.com/jira/rest/api/resource/KEY-1",
"widgets": {
"widgets": [],
"size": 5
}
}This documents the current REST API provided by JIRA.
Returns general information about the current JIRA server.
available response representations:
| parameter | value | description |
|---|---|---|
issueKey | the issue key to request (i.e. JRA-1330) |
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).
The fields is the heart of the issue. Each field has the same basic shape:
"field-id" : { "name" : "field-name", "type" : "field-type", "value" : "field-value" }
For system fields, you'll notice that the field-id and the field-name are the same (e.g. "assignee" and "assignee"), while for custom fields they are different ("customfield_10000" and "Participants").
If a field has no value then the "value" key will not be present. For instance, if there is no assignee it would simply appear as:
"assignee" : { "name" : "assignee", "type" : "com.opensymphony.user.User" }
This indicates there is a field named assignee but it has no value.
available response representations:
| parameter | value | description |
|---|---|---|
issueKey | the issue you want to transition |
Get a list of the transitions possible for this issue by the current user, along with fields that are required and their types.
available response representations:
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".
acceptable request representations:
available response representations:
| parameter | value | description |
|---|---|---|
issueKey | the issue to view voting information for |
Remove your vote from an issue. (i.e. "unvote")
available response representations:
Cast your vote in favour of an issue.
available response representations:
| parameter | value | description |
|---|---|---|
issueKey | a String containing an issue key |
Returns the list of watchers for the issue with the given key.
available response representations:
Adds a user to an issue's watcher list.
acceptable request representations:
available response representations:
Implement a REST resource for acquiring a session cookie.
Login a user to JIRA.
acceptable request representations:
available response representations:
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.
available response representations:
| parameter | value | description |
|---|---|---|
id |
Delete a project version.
| parameter | value | description |
|---|---|---|
moveFixIssuesTo | The version to set fixVersion to on issues where the deleted version is the fix version, If null then the fixVersion is removed. | |
moveAffectedIssuesTo | The version to set affectedVersion to on issues where the deleted version is the affected version, If null then the affectedVersion is removed. |
available response representations:
Returns a project version.
| parameter | value | description |
|---|---|---|
expand |
available response representations:
| parameter | value | description |
|---|---|---|
id | a String containing the version id |
| parameter | value | description |
|---|---|---|
id | a String containing the version id |
| parameter | value | description |
|---|---|---|
id | a String containing the version id |
Modify a version's sequence within a project. The move version bean has 2 alternative field value pairs:
acceptable request representations:
available response representations:
| parameter | value | description |
|---|---|---|
id | the ID of the comment to request |
Returns a single issue comment.
| parameter | value | description |
|---|---|---|
render | Default: true | true if text fields should be rendered according to the renderer associated with them; false to return the raw, unrendered data |
available response representations:
| parameter | value | description |
|---|---|---|
id | a String containing an issue type id |
Create a component via POST. Any fields present in the PUT will override existing values. As a convenience, if a field is not present, it is silently ignored.
acceptable request representations:
available response representations:
| parameter | value | description |
|---|---|---|
id |
Delete a project component.
| parameter | value | description |
|---|---|---|
moveIssuesTo | The new component applied to issues whose 'id' component will be deleted. If this value is null, then the 'id' component is simply deleted. |
available response representations:
Returns a project component.
available response representations:
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.
acceptable request representations:
available response representations:
| parameter | value | description |
|---|---|---|
id | a String containing the component id |
| parameter | value | description |
|---|---|---|
id | a String containing an custom Field Option id |
Issue attachments
| parameter | value | description |
|---|---|---|
issueKey | the issue that you want to add the attachments to |
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.
available response representations:
| parameter | value | description |
|---|---|---|
key | the project key |
| parameter | value | description |
|---|---|---|
key | the project key |
| parameter | value | description |
|---|---|---|
key | the project key |
Resource for searches.
Searches for issues using JQL. If the JQL query is too large to be encoded as a query param you should instead POST to this resource.
| parameter | value | description |
|---|---|---|
jql | a JQL query string | |
startAt | the index of the first issue to return (0-based) | |
maxResults | 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. |
available response representations:
The Link Issue Resource provides functionality to manage issue links.
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.
acceptable request representations:
available response representations:
| parameter | value | description |
|---|---|---|
projectKey | the project key |
| parameter | value | description |
|---|---|---|
projectKey | the project key | |
id | the project role id | |
projectKey | the project key |
Details on a given project role.
available response representations:
Updates a project role to contain the sent actors.
acceptable request representations:
available response representations:
Add an actor to a project role.
acceptable request representations:
available response representations:
Rest resource to retrieve a list of issue link types.
| parameter | value | description |
|---|---|---|
issueLinkTypeId |
| parameter | value | description |
|---|---|---|
id | a String containing the resolution id |
| parameter | value | description |
|---|---|---|
id | a numeric Status id |
| parameter | value | description |
|---|---|---|
id | the attachment id |
| parameter | value | description |
|---|---|---|
id | a String containing the work log id |
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.
| parameter | value | description |
|---|---|---|
query | a String to match groups agains |
available response representations:
| parameter | value | description |
|---|---|---|
id | a String containing the priority id |