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. 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/project/JRA
Example without context: http://myhost.com:8080/rest/api/2/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.
Implement a REST resource for acquiring a session cookie.
Login a user to JIRA.
acceptable request representations:
{"username":"fred","password":"freds_password"}available response representations:
{"session":{"name":"JSESSIONID","value":"12345678901234567890"},"loginInfo":{"failedLoginCount":10,"loginCount":127,"lastFailedLoginTime":"2011-08-30T23:14:16.739-0500","previousLoginTime":"2011-08-30T23:14:16.739-0500"}}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 fails due to an invalid credentials.
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 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:
{"self":"http://www.example.com/jira/rest/api/2.0/user/fred","name":"fred","loginInfo":{"failedLoginCount":10,"loginCount":127,"lastFailedLoginTime":"2011-08-30T23:14:16.739-0500","previousLoginTime":"2011-08-30T23:14:16.739-0500"}}Returns a user. This resource cannot be accessed anonymously.
| parameter | value | description |
|---|---|---|
username | the username |
available response representations:
Returned if the requested user is not found.
{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","id":"fred","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"16x16":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","groups":{"size":3,"items":[{"name":"jira-user"},{"name":"jira-admin"},{"name":"important"}]},"expand":"groups"}Returns a full representation of a JIRA user in JSON format.
Returned if the current user is not authenticated.
| parameter | value | description |
|---|---|---|
username | username |
Returns all avatars which are visible for the currently logged in user.
available response representations:
Returned if the requested user is not found.
{"id":1000,"owner":"fred","isSystemAvatar":true,"isSelected":true,"selected":true}Returns a map containing a list of avatars for both custom an system avatars
Returned if the current user is not authenticated.
Returned if an error occurs while retrieving the list of avatars.
| parameter | value | description |
|---|---|---|
username |
Converts temporary avatar into a real avatar
acceptable request representations:
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"needsCropping":false}available response representations:
Returned if the currently authenticated user does not have EDIT PROJECT permission.
{"id":1000,"owner":"fred","isSystemAvatar":true,"isSelected":true,"selected":true}Returns created avatar
Returned if the cropping coordinates are invalid
Returned if the currently authenticated user does not have permission to pick avatar
Returned if an error occurs while converting temporary avatar to real avatar
| parameter | value | description |
|---|---|---|
username |
Creates temporary avatar
| parameter | value | description |
|---|---|---|
filename | name of file being uploaded | |
size | size of file |
available response representations:
Returned if the currently authenticated user does not have EDIT PROJECT permission.
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}temporary avatar cropping instructions
Returned if the request does not conain a valid XSRF token
Returned if an error occurs while converting temporary avatar to real avatar
| parameter | value | description |
|---|---|---|
id | database id for avatar | |
username | username |
Deletes avatar
available response representations:
Returned if the avatar is successfully deleted.
Returned if the avatar does not exist or the currently authenticated user does not have permission to delete it.
Returned if the currently authenticated user does not have permission to delete the avatar.
Returns a list of users that match the search string. This resource cannot be accessed anonymously.
| parameter | value | description |
|---|---|---|
username | the username |
available response representations:
Returned if the requested user is not found.
{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","id":"fred","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"16x16":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","groups":{"size":3,"items":[{"name":"jira-user"},{"name":"jira-admin"},{"name":"important"}]},"expand":"groups"}Returns a full representation of a JIRA user in JSON format.
Returned if the current user is not authenticated.
Returns a list of users that match the search string. This resource cannot be accessed anonymously.
| parameter | value | description |
|---|---|---|
username | the username | |
project | the key of the project we are finding assignable users for |
available response representations:
Returned if the requested user is not found.
{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","id":"fred","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"16x16":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","groups":{"size":3,"items":[{"name":"jira-user"},{"name":"jira-admin"},{"name":"important"}]},"expand":"groups"}Returns a full representation of a JIRA user in JSON format.
Returned if the current user is not authenticated.
| parameter | value | description |
|---|---|---|
projectKey | the project key |
Contains a list of roles in this project with links to full details.
available response representations:
Returned if the project is not found, or the calling user does not have permission to view it.
{"Users":"http://www.example.com/jira/rest/api/2/project/MKY/role/10001","Administrators":"http://www.example.com/jira/rest/api/2/project/MKY/role/10002","Developers":"http://www.example.com/jira/rest/api/2/project/MKY/role/10000"}Returned if the project exists and the user has permission to view it. A maps of roles to URIs containing full details for that role.
| 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:
Returned if the project or role is not found, or the calling user does not have permission to view it.
{"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.
Updates a project role to contain the sent actors.
acceptable request representations:
{ "user" : ["admin"] }
{ "group" : ["jira-developers"] }available response representations:
Returned if the actor could not be added to the project role
{"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.
Add an actor to a project role.
acceptable request representations:
{ "user" : ["admin"] }
{ "group" : ["jira-developers"] }available response representations:
Returned if the actor could not be added to the project role
{"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.
Remove actors from a project role.
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:
{"linkType":"Duplicate","fromIssueKey":"HSP-1","toIssueKey":"MKY-1","comment":{"body":"Linked related issue!","visibility":{"type":"GROUP","value":"jira-users"}}}available response representations:
If issue linking is disabled or it failed to find one of the issues (issue might exist, but it is not visible for this user) or it failed to find the specified issue link type.
if the issue link was created successfully.
if the user does not have the link issue permission for the issue, which will be linked to another issue.
if it can't create the supplied comment. The response will contain an error message indicating why it failed to create the comment. No issue link will be created if it failed to create the comment.
if an error occurred when creating the issue link or the comment.
Creates an issue from a JSON representation.
acceptable request representations:
{"fields":{"project":{"id":"10000"},"summary":"something's wrong","issuetype":{"id":"10000"},"assignee":{"id":"homer"},"reporter":{"id":"smithers"},"priority":{"id":"20000"},"labels":["bugfix","blitz_test"],"timeTracking":{"originalEstimate":"10","remainingEstimate":"5"},"worklog":{"timeSpent":"1h","started":"05/Jul/11 11:05 AM"},"securityLevel":{"id":"10000"},"versions":[{"id":"10000"}],"environment":"environment","description":"description","dueDate":"2011-03-11","fixVersions":[{"id":"10001"}],"components":[{"id":"10000"}],"customfield_60000":["jira-developers"],"customfield_20000":["06/Jul/11 3:25 PM"],"customfield_40000":["this is a text field"],"customfield_30000":["10000","10002"],"customfield_70000":["jira-administrators","jira-users"],"customfield_50000":["this is a text area. big text."],"customfield_10000":["09/Jun/81"]}}available response representations:
{"id":"10000","key":"TST-24","self":"http://www.example.com/jira/rest/api/2/issue/10000"}Returns a link to the created issue.
{"errorMessages":["Field 'priority' is required"],"errors":{}}Returned if the input is invalid (e.g. missing required fields, invalid field values, and so forth).
Edits an issue from a JSON representation. The issue can either be updated by setting explicit the field value(s) or by using an operation to change the field value.
acceptable request representations:
{"id":"10000","update":{"summary":[{"set":"Bug in business logic"}],"labels":[{"add":"triaged"},{"remove":"blocker"}],"components":[{"clear":""}]}}available response representations:
| parameter | value | description |
|---|---|---|
issueIdOrKey | the issue id or 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).
| parameter | value | description |
|---|---|---|
fields | the list of fields to return for the issue. If null, all fields are returned. |
available response representations:
Returned if the requested issue is not found, or the user does not have permission to view it.
{"expand":"html,names,schema","id":"10002","self":"http://www.example.com/jira/rest/api/2/issue/EX-1","key":"EX-1","fields":{"sub-tasks":[{"issueId":"10003","issueKey":"EX-2","issue":"http://www.example.com/jira/rest/api/2/issue/EX-2","type":{"name":"Sub-task","direction":"OUTBOUND"}}],"timetracking":{"timeoriginalestimate":10,"timeestimate":3,"timespent":6},"project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":10000,"key":"EX","name":"Example","avatarUrls":{"16x16":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000"}},"updated":1,"description":"example bug report","links":[{"issueId":"10004","issueKey":"PRJ-2","issue":"http://www.example.com/jira/rest/api/2/issue/PRJ-2","type":{"name":"Dependent","direction":"OUTBOUND","description":"depends on"}},{"issueId":"10004","issueKey":"PRJ-3","issue":"http://www.example.com/jira/rest/api/2/issue/PRJ-3","type":{"name":"Dependent","direction":"INBOUND","description":"is depended by"}}],"attachment":[{"self":"http://www.example.com/jira/rest/api/2.0/attachments/10000","filename":"picture.jpg","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2011-08-30T23:14:17.327-0500","size":23123,"mimeType":"image/jpeg","content":"http://www.example.com/jira/attachments/10000","thumbnail":"http://www.example.com/jira/secure/thumbnail/10000"}],"watcher":{"self":"http://www.example.com/jira/rest/api/2/issue/EX-1/watchers","isWatching":false,"watchCount":1,"watchers":[{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false}]},"comment":[{"self":"http://example.com:8080/jira/rest/api/2.0/comment/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.","updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2011-08-30T23:14:17.337-0500","updated":"2011-08-30T23:14:17.337-0500","visibility":{"type":"ROLE","value":"Administrators"}}],"worklog":[{"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}]},"names":{"sub-tasks":"sub-tasks","timetracking":"timetracking","project":"project","updated":"updated","description":"description","links":"links","attachment":"attachment","watcher":"watcher","comment":"comment","worklog":"worklog"},"schema":{"properties":{"sub-tasks":{"type":"issuelinks"},"timetracking":{"type":"timetracking"},"project":{"type":"com.atlassian.jira.project.Project"},"updated":{"type":"java.util.Date"},"description":{"type":"java.lang.String"},"links":{"type":"issuelinks"},"attachment":{"type":"attachment"},"watcher":{"type":"watcher"},"comment":{"type":"java.lang.String"},"worklog":{"type":"worklog"}}},"editmeta":"TODO","changelog":"TODO"}Returns a full representation of a JIRA issue in JSON format.
| parameter | value | description |
|---|---|---|
issueIdOrKey | 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:
Returned if the requested issue is not found or the user does not have permission to view it.
{"731":{"id":2,"name":"Close Issue","fields":{"summary":{"required":false,"visible":true,"editable":true,"type":{"type":"STRING"},"operations":["SET","ADD"],"allowedValues":["red","blue"]}},"transitionDestination":"6"}}Returns a full representation of the transitions possible for the specified issue and the fields required to perform the transition.
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:
{
"transition" : 2,
"fields" : { "resolution" : "Duplicate" },
"comment" : "We've already fixed this one."
}
{
"transition" : 3,
"fields" : { "assignee" : "fred", "priority" : "Critical" },
"comment" : { "body" : "This isn't fixed yet.", "group" : "jira-developers" }
}available response representations:
| parameter | value | description |
|---|---|---|
issueIdOrKey | 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:
A REST sub-resource representing the voters on the issue. This sub-resource is also used for voting and unvoting (via POST and DELETE).
available response representations:
Returned if the user cannot view the issue in question or voting is disabled.
{"self":"http://www.example.com/jira/rest/api/issue/MKY-1/votes","votes":24,"hasVoted":true,"voters":[{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false}]}Information about voting on the current issue.
| parameter | value | description |
|---|---|---|
issueIdOrKey | a String containing an issue key |
Returns the list of watchers for the issue with the given key.
available response representations:
Returned if the requested issue is not found, or the user does not have permission to view it.
{"self":"http://www.example.com/jira/rest/api/2/issue/EX-1/watchers","isWatching":false,"watchCount":1,"watchers":[{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false}]}Returns the list of watchers for an issue.
Adds a user to an issue's watcher list.
acceptable request representations:
"fred"available response representations:
Returned if the watcher was added successfully.
Returned if either the issue or the user does not exist.
Returned if the calling user does not have permission to add the watcher to the issue's list of watchers.
Returned if there is a problem with the received user representation.
Removes a user from an issue's watcher list.
| parameter | value | description |
|---|---|---|
username | a String containing the name of the user to remove from the watcher list |
available response representations:
| parameter | value | description |
|---|---|---|
issueIdOrKey | a String containing an issue id or key |
Delete an issue. If the issue has subtasks you must set the parameter deleteSubtasks=true to delete the issue. You cannot delete an issue without its subtasks also being deleted.
| parameter | value | description |
|---|---|---|
deleteSubtasks | 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. |
available response representations:
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.
| parameter | value | description |
|---|---|---|
projectIds | 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. | |
projectKeys | 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. | |
issuetypeIds | 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. | |
issuetypeNames | 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. |
available response representations:
{"expand":"projects","projects":[{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":10000,"key":"EX","name":"Example Project","avatarUrls":{"16x16":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000&avatarId=10011","48x48":"http://www.example.com/jira/secure/projectavatar?pid=10000&avatarId=10011"},"issuetypes":[{"self":"http://www.example.com/jira/rest/api/2/issueType/1","id":1,"name":"Bug","iconUrl":"http://www.example.com/jira/images/icons/bug.gif","fields":{"issueType":{"required":true,"visible":true,"editable":false,"operations":["SET"]}}}]}]}Returns the meta data for creating issues.
Returned if the user does not have permission to view any of the requested projects.
| parameter | value | description |
|---|---|---|
issueIdOrKey | the issue whose edit meta data you want to view |
Returns the meta data for editing an issue.
available response representations:
Returned if the requested issue is not found or the user does not have permission to view it.
{"fields":{"summary":{"required":false,"visible":true,"editable":true,"type":{"type":"STRING"},"operations":["SET","ADD"],"allowedValues":["red","blue"]}}}Returns a response containing a Map of FieldBeans for fields edited by the current user.
| parameter | value | description |
|---|---|---|
issueIdOrKey | the issue to create the remote link for |
A REST sub-resource representing the remote links on the issue. This sub-resource is also used for creating, updating and deleting links (via POST, PUT and DELETE).
| parameter | value | description |
|---|---|---|
globalId | if not null, return only the remote link with this globalId |
available response representations:
Returned if the user cannot view the issue in question.
[{"id":101,"self":"http://www.example.com/jira/rest/api/issue/MKY-1/remotelink/101","globalId":"{\"appId\"=456456,\"issueId\"=456456}","application":{"type":"com.anothercompany.mytestingsystem","name":"Another Company's Testing System"},"relationship":"is tested by","object":{"url":"http://www.anotherapplication.com/testcase/6789","title":"Test Case #6789","summary":"Description of the test case goes here","icon":{"url16x16":"http://www.anotherapplication.com/images/testcase.gif","title":"Test Case"},"status":{"resolved":false,"icon":{"url16x16":"http://www.anotherapplication.com/images/person/fred.gif","title":"Tested by Fred Jones","link":"http://www.anotherapplication.com/person/fred"}}}},null]Information on the remote links for the current issue.
Returned if issue linking is disabled.
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.
acceptable request representations:
available response representations:
| parameter | value | description |
|---|---|---|
issueIdOrKey | the issue to create the remote link for | |
linkId | the id of the remote issue link |
Get the remote link with the given id on the issue.
available response representations:
Returned if the user cannot view the issue in question, or if a remote link with the given linkId is not found.
{"id":101,"self":"http://www.example.com/jira/rest/api/issue/MKY-1/remotelink/101","globalId":"{\"appId\"=456456,\"issueId\"=456456}","application":{"type":"com.anothercompany.mytestingsystem","name":"Another Company's Testing System"},"relationship":"is tested by","object":{"url":"http://www.anotherapplication.com/testcase/6789","title":"Test Case #6789","summary":"Description of the test case goes here","icon":{"url16x16":"http://www.anotherapplication.com/images/testcase.gif","title":"Test Case"},"status":{"resolved":false,"icon":{"url16x16":"http://www.anotherapplication.com/images/person/fred.gif","title":"Tested by Fred Jones","link":"http://www.anotherapplication.com/person/fred"}}}}Information on the remote link with the given id.
Returned if the linkId is not a valid number.
Returned if issue linking is disabled.
Updates a remote issue link from a JSON representation.
acceptable request representations:
available response representations:
Delete the remote link with the given id on the issue.
available response representations:
Returned if the remote link was removed successfully.
Returned if the issue or remote link do not exist.
Returned if the calling user is not authenticated.
Returned if the calling user does not have permission to delete the remote link, or if issue linking is disabled.
Create a version via POST.
acceptable request representations:
{"description":"An excellent version","name":"New Version 1","userReleaseDate":"5/Jul/2010","project":"PXA","archived":false,"released":true,"releaseDate":"2010-07-05"}available response representations:
Returned if the version does not exist or the currently authenticated user does not have permission to view it.
{"description":"An excellent version","name":"New Version 1","userReleaseDate":"5/Jul/2010","project":"PXA","archived":false,"released":true,"releaseDate":"2010-07-05"}Returned if the version is created successfully.
Returned if the currently authenticated user does not have permission to edit the version.
| 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:
Returned if the version does not exist or the currently authenticated user does not have permission to view it.
{"self":"http://www.example.com/jira/rest/api/2/version/10000","id":10000,"description":"An excellent version","name":"New Version 1","overdue":true,"userReleaseDate":"5/Jul/2010","archived":false,"released":true,"releaseDate":"2010-07-05"}Returned if the version exists and the currently authenticated user has permission to view it. Contains a full representation of the version.
Modify a version 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.
acceptable request representations:
{"self":"http://www.example.com/jira/rest/api/2/version/10000","id":10000,"description":"An excellent version","name":"New Version 1","overdue":true,"userReleaseDate":"5/Jul/2010","archived":false,"released":true,"releaseDate":"2010-07-05"}available response representations:
Returned if the version does not exist or the currently authenticated user does not have permission to view it.
Returned if the version exists and the currently authenticated user has permission to edit it.
Returned if the currently authenticated user does not have permission to edit the version.
| parameter | value | description |
|---|---|---|
id | a String containing the version id |
Returns a bean containing the number of fixed in and affected issues for the given version.
available response representations:
Returned if the version does not exist or the currently authenticated user does not have permission to view it.
{"self":"http://www.example.com/jira/rest/api/2/version/10000","issuesFixedCount":23,"issuesAffectedCount":101}Returned if the version exists and the currently authenticated user has permission to view it. Contains counts of issues fixed in and affecting this version.
| parameter | value | description |
|---|---|---|
id | a String containing the version id |
Returns the number of unresolved issues for the given version
available response representations:
Returned if the version does not exist or the currently authenticated user does not have permission to view it.
{"self":"http://www.example.com/jira/rest/api/2/version/10000","issuesUnresolvedCount":23}Returned if the version exists and the currently authenticated user has permission to view it. Contains counts of issues unresolved in this version.
| 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:
{"after":"http://www.example.com/jira/rest/api/2/version/10000"}available response representations:
Returned if the version, or target of the version to move after does not exist or the currently authenticated user does not have permission to view it.
{"self":"http://www.example.com/jira/rest/api/2/version/10000","id":10000,"description":"An excellent version","name":"New Version 1","overdue":true,"userReleaseDate":"5/Jul/2010","archived":false,"released":true,"releaseDate":"2010-07-05"}Returned if the version exists and the currently authenticated user has permission to view it. Contains a full representation of the version moved.
| parameter | value | description |
|---|---|---|
id | a String containing the priority id |
Returns an issue priority.
available response representations:
Returned if the issue priority does not exist or is not visible to the calling user.
{"self":"http://www.example.com/jira/rest/api/2/priority/3","statusColor":"#009900","description":"Major loss of function.","iconUrl":"http://www.example.com/jira/images/icons/priority_major.gif","name":"Major"}Returned if the issue priority exists and is visible by the calling user. Contains a full representation of the issue priority in JSON.
| 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:
Returned if the requested comment is not found, or the user does not have permission to view it.
{"self":"http://example.com:8080/jira/rest/api/2.0/comment/10000","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"body":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.","updateAuthor":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2011-08-30T23:14:17.337-0500","updated":"2011-08-30T23:14:17.337-0500","visibility":{"type":"ROLE","value":"Administrators"}}Returns a full representation of a JIRA comment in JSON format.
Rest resource to retrieve a list of issue link types.
Returns a list of available issue link types, if issue linking is enabled. Each issue link type has an id, a name and a label for the outward and inward link relationship.
available response representations:
Returned if issue linking is disabled.
{"issueLinkTypes":[{"id":1000,"name":"Duplicate","inward":"Duplicated by","outward":"Duplicates","self":"http://www.example.com/jira/rest/api/2//issueLinkType/1000"},{"id":1010,"name":"Blocks","inward":"Blocked by","outward":"Blocks","self":"http://www.example.com/jira/rest/api/2//issueLinkType/1010"}]}Returns a list of all available issue link types.
| parameter | value | description |
|---|---|---|
issueLinkTypeId |
Returns for a given issue link type id all information about this issue link type.
available response representations:
Returned if issue linking is disabled or no issue link type with the given id exists.
{"id":1000,"name":"Duplicate","inward":"Duplicated by","outward":"Duplicates","self":"http://www.example.com/jira/rest/api/2//issueLinkType/1000"}Returns the issue link type with the given id.
| parameter | value | description |
|---|---|---|
id | a String containing the resolution id |
Returns a resolution.
available response representations:
Returned if the resolution does not exist or the user does not have permission to view it.
{"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.
Issue attachments
| parameter | value | description |
|---|---|---|
issueIdOrKey | 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:
Returned if successful.
Returned if the requested issue is not found, the user does not have permission to view it, or if the attachments exceeds the maximum configured attachment size.
Returned if attachments is disabled or if you don't have permission to add attachments to this issue.
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:
Returned even if no groups match the given substring
| parameter | value | description |
|---|---|---|
id |
Resource for searches.
Searches for issues using JQL.
Sorting
the jql parameter is a full JQL
expression, and includes an ORDER BY clause.
GET vs POST: 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. | |
fields | the list of fields to return for each issue. If null, all fields are returned. | |
expand | the parameters to expand |
available response representations:
{"expand":"names,schema","startAt":0,"maxResults":50,"total":1,"issues":[{"expand":"","id":"10001","self":"http://www.example.com/jira/rest/api/2/issue/HSP-1","key":"HSP-1","editmeta":"TODO","changelog":"TODO"}]}Returns a JSON representation of the search results.
Returned if there is a problem with the JQL query.
Performs a search using JQL.
acceptable request representations:
{"jql":"project = HSP","startAt":0,"maxResults":15,"fields":["summary","status","assignee"]}available response representations:
{"expand":"names,schema","startAt":0,"maxResults":50,"total":1,"issues":[{"expand":"","id":"10001","self":"http://www.example.com/jira/rest/api/2/issue/HSP-1","key":"HSP-1","editmeta":"TODO","changelog":"TODO"}]}Returns a JSON representation of the search results.
Returned if there is a problem with the JQL query.
| parameter | value | description |
|---|---|---|
id | a String containing the work log id |
Returns a work log.
available response representations:
Returned if the work log with the given id does not exist or if the currently authenticated user does not have permission to view it.
{"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.
Returns general information about the current JIRA server.
available response representations:
{"baseUrl":"http://localhost:8080/jira","version":"4.2-SNAPSHOT","buildNumber":582,"buildDate":"2011-08-30T23:14:17.155-0500","serverTime":"2011-08-30T23:14:17.155-0500","scmInfo":"482389","buildPartnerName":"Example Partner Co.","serverTitle":"My Shiny New JIRA Server"}Returns a full representation of the server info in JSON format
| parameter | value | description |
|---|---|---|
id | a String containing an custom Field Option id |
Returns a full representation of the custom Field Option that has the given id.
available response representations:
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:
{"name":"Component 1","description":"This is a JIRA component","leadUserName":"fred","assigneeType":"PROJECT_LEAD","isAssigneeTypeValid":false,"project":"PXA"}available response representations:
Returned if the component does not exist or the currently authenticated user does not have permission to view it.
{"self":"http://www.example.com/jira/rest/api/2/component/10000","id":10000,"name":"Component 1","description":"This is a JIRA component","lead":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"isAssigneeTypeValid":false}Returned if the component is created successfully.
Returned if the currently authenticated user does not have permission to edit the component.
| 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:
Returned if there is no component with the given key, or if the calling user does not have permission to view the component.
{"self":"http://www.example.com/jira/rest/api/2/component/10000","id":10000,"name":"Component 1","description":"This is a JIRA component","lead":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"isAssigneeTypeValid":false}Returns a full JSON representation of a project component.
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:
{"name":"Component 1","description":"This is a JIRA component","leadUserName":"fred","assigneeType":"PROJECT_LEAD","isAssigneeTypeValid":false}available response representations:
Returned if the component does not exist or the currently authenticated user does not have permission to view it.
Returned if the component exists and the currently authenticated user has permission to edit it.
Returned if the currently authenticated user does not have permission to edit the component.
| parameter | value | description |
|---|---|---|
id | a String containing the component id |
Returns a project component.
available response representations:
Returned if the component does not exist or the currently authenticated user does not have permission to view it.
{"self":"http://www.example.com/jira/rest/api/2/component/10000","issueCount":23}Returned if the component exists and the currently authenticated user has permission to view it. Contains counts of issues fixed in and affecting this component.
| parameter | value | description |
|---|---|---|
id | a String containing an issue type id |
Returns a full representation of the issue type that has the given id.
available response representations:
Returns all projects which are visible for the currently logged in user. If no user is logged in, it returns the list of projects that are visible when using anonymous access.
available response representations:
[{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":10000,"key":"EX","name":"Example","avatarUrls":{"16x16":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000"}},{"self":"http://www.example.com/jira/rest/api/2/project/ABC","id":10001,"key":"ABC","name":"Alphabetical","avatarUrls":{"16x16":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10001","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10001"}}]Returns a list of projects for which the user has the BROWSE, ADMINISTER or PROJECT_ADMIN project permission.
Returned if an error occurs while retrieving the list of projects.
| parameter | value | description |
|---|---|---|
key | the project key |
Contains a full representation of a project in JSON format.
available response representations:
Returned if the project is not found, or the calling user does not have permission to view it.
{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":10000,"key":"EX","description":"This project was created as an example for REST.","lead":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"components":[{"self":"http://www.example.com/jira/rest/api/2/component/10000","id":10000,"name":"Component 1","description":"This is a JIRA component","lead":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"isAssigneeTypeValid":false}],"url":"http://www.example.com/jira/browse/EX","assigneeType":"PROJECT_LEAD","versions":[],"name":"Example","roles":{"Developers":"http://www.example.com/jira/rest/api/2/project/EX/role/10000"},"avatarUrls":{"16x16":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000"}}Returned if the project exists and the user has permission to view it. Contains a full representation of a project in JSON format.
| parameter | value | description |
|---|---|---|
key | the project key |
Contains a full representation of a the specified project's versions.
| parameter | value | description |
|---|---|---|
expand |
available response representations:
Returned if the project is not found, or the calling user does not have permission to view it.
{"self":"http://www.example.com/jira/rest/api/2/version/10000","id":10000,"description":"An excellent version","name":"New Version 1","overdue":true,"userReleaseDate":"5/Jul/2010","archived":false,"released":true,"releaseDate":"2010-07-05"}Returned if the project exists and the user has permission to view its versions. Contains a full representation of the project's versions in JSON format.
| parameter | value | description |
|---|---|---|
key | the project key |
Contains a full representation of a the specified project's components.
available response representations:
Returned if the project is not found, or the calling user does not have permission to view it.
{"self":"http://www.example.com/jira/rest/api/2/component/10000","id":10000,"name":"Component 1","description":"This is a JIRA component","lead":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"isAssigneeTypeValid":false}Returned if the project exists and the user has permission to view its components. Contains a full representation of the project's components in JSON format.
| parameter | value | description |
|---|---|---|
key | project key |
Returns all avatars which are visible for the currently logged in user.
available response representations:
Returned if the currently authenticated user does not have VIEW PROJECT permission.
{"id":1000,"owner":"fred","isSystemAvatar":true,"isSelected":true,"selected":true}Returns a map containing a list of avatars for both custom an system avatars, which the user has the BROWSE project permission.
Returned if an error occurs while retrieving the list of avatars.
| parameter | value | description |
|---|---|---|
key |
Converts temporary avatar into a real avatar
acceptable request representations:
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"needsCropping":false}available response representations:
Returned if the currently authenticated user does not have EDIT PROJECT permission.
{"id":1000,"owner":"fred","isSystemAvatar":true,"isSelected":true,"selected":true}Returns created avatar
Returned if the cropping coordinates are invalid
Returned if the currently authenticated user does not have permission to pick avatar
Returned if an error occurs while converting temporary avatar to real avatar
| parameter | value | description |
|---|---|---|
key |
Creates temporary avatar
| parameter | value | description |
|---|---|---|
filename | name of file being uploaded | |
size | size of file |
available response representations:
Returned if the currently authenticated user does not have EDIT PROJECT permission.
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}temporary avatar cropping instructions
Returned if the request does not conain a valid XSRF token
Returned if an error occurs while converting temporary avatar to real avatar
| parameter | value | description |
|---|---|---|
id | database id for avatar | |
key | Project key |
Deletes avatar
available response representations:
Returned if the avatar is successfully deleted.
Returned if the avatar does not exist or the currently authenticated user does not have permission to delete it.
Returned if the currently authenticated user does not have permission to delete the component.
| parameter | value | description |
|---|---|---|
id | the attachment id |
Returns the meta-data for an attachment, including the URI of the actual attached file.
available response representations:
Returned if the attachment with the given id does not exist, or is not accessible by the calling user.
{"self":"http://www.example.com/jira/rest/api/2.0/attachments/10000","filename":"picture.jpg","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"created":"2011-08-30T23:14:17.327-0500","size":23123,"mimeType":"image/jpeg","content":"http://www.example.com/jira/attachments/10000","thumbnail":"http://www.example.com/jira/secure/thumbnail/10000"}Returns a JSON representation of the attachment meta-data. The representation does not contain the attachment itself, but contains a URI that can be used to download the actual attached file.
| parameter | value | description |
|---|---|---|
id | a numeric Status id |
Returns a full representation of the Status having the given id.
available response representations:
Returned if the requested issue status is not found, or the user does not have permission to view it.
{"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"}Returns a full representation of a JIRA issue status in JSON format.