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.

Structure of the REST URIs

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

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.

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 document the current REST API provided by JIRA.

Resources

/auth/1/session

Implement a REST resource for acquiring a session cookie.

Methods

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.

available response representations:

  • 200 [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2.0/user/fred","name":"fred","loginInfo":{"failedLoginCount":10,"loginCount":127,"lastFailedLoginTime":"2011-02-08T12:29:58.092+1100","previousLoginTime":"2011-02-08T12:29:58.092+1100"}}

    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.

POST

Login a user to JIRA.

acceptable request representations:

  • application/json [expand]

    Example
    {"username":"fred","password":"freds_password"}

available response representations:

  • 200 [expand]

    Example
    {"session":{"name":"JSESSIONID","value":"12345678901234567890"},"loginInfo":{"failedLoginCount":10,"loginCount":127,"lastFailedLoginTime":"2011-02-08T12:29:58.092+1100","previousLoginTime":"2011-02-08T12:29:58.092+1100"}}

    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.

DELETE

Log the current user out of JIRA.

available response representations:

  • 204 [expand]

    Returned if the user was successfully logged out.

  • 401 [expand]

    Returned if the user is not authenticated.

/api/2.0.alpha1/attachment/{id}

resource-wide template parameters
parametervaluedescription

id

string

the attachment id

Methods

GET

Returns the meta-data for an attachment, including the URI of the actual attached file.

available response representations:

  • 404 [expand]

    Returned if the attachment with the given id does not exist, or is not accessible by the calling user.

  • 200 - application/json (attachment) [expand]

    Example
    {"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.0/user?username=fred","name":"fred","displayName":"Fred F. User"},"created":"2011-02-08T12:29:58.499+1100","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.

/api/2.0.alpha1/priority/{id}

resource-wide template parameters
parametervaluedescription

id

string

a String containing the priority id

Methods

GET

Returns an issue priority.

available response representations:

  • 404 [expand]

    Returned if the issue priority does not exist or is not visible to the calling user.

  • 200 - application/json (issuePriority) [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2.0/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.

/api/2.0.alpha1/issueType/{id}

resource-wide template parameters
parametervaluedescription

id

string

a String containing an issue type id

Methods

GET

Returns a full representation of the issue type that has the given id.

available response representations:

  • 404 [expand]

    Returned if the issue type does not exist, or is not visible to the calling user.

  • 200 - application/json (issueType) [expand]

    Returned if the issue type exists and is visible by the calling user.

/api/2.0.alpha1/version/{id}

resource-wide template parameters
parametervaluedescription

id

string

a String containing the version id

Methods

GET

Returns a project version.

available response representations:

  • 404 [expand]

    Returned if the version does not exist or the currently authenticated user does not have permission to view it.

  • 200 - application/json (project) [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2.0/version/10000","description":"An excellent version","name":"New Version 1","archived":false,"released":true,"releaseDate":"2010-07-06T13:04:42.288+1000"}

    Returned if the version exists and the currently authenticated user has permission to view it. Contains a full representation of the version.

/api/2.0.alpha1/issue/{issueKey}/transitions

resource-wide template parameters
parametervaluedescription

issueKey

string

the issue you want to transition

Methods

GET

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:

  • 404 [expand]

    Returned if the requested issue is not found or the user does not have permission to view it.

  • 200 - application/json [expand]

    Example
    {"Close Issue":[{"id":"resolution","required":true,"type":"com.atlassian.jira.issue.resolution.Resolution"}],"Send To QA":[{"id":"priority","required":false,"type":"com.atlassian.jira.issue.priority.Priority"},{"id":"assignee","required":true,"type":"com.opensymphony.user.User"}]}

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

POST

Peform a transition on an issue.

acceptable request representations:

  • application/json [expand]

    Example
    {
       "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:

  • 204 [expand]

    Nothing is returned on success.

  • 404 [expand]

    The issue does not exist or the user does not have permission to view it

  • 400 [expand]

    The request body failed to validate.

/api/2.0.alpha1/issue/{issueKey}/votes

resource-wide template parameters
parametervaluedescription

issueKey

string

the issue to view voting information for

Methods

DELETE

Remove your vote from an issue. (i.e. "unvote")

available response representations:

  • 204 [expand]

    Nothing is returned on success.

  • 404 [expand]

    Returned if the user cannot remove a vote for any reason. (The user did not vote on the issue, the user is the reporter, voting is disabled, the issue does not exist, etc.)

POST

Cast your vote in favour of an issue.

available response representations:

  • 204 [expand]

    Nothing is returned on success.

  • 404 [expand]

    Returned if the user cannot vote for any reason. (The user is the reporter, the user does not have permission to vote, voting is disabled in the instance, the issue does not exist, etc.)

GET

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:

  • 404 [expand]

    Returned if the user cannot view the issue in question or voting is disabled.

  • 200 - application/json [expand]

    Example
    {"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.0/user?username=fred","name":"fred","displayName":"Fred F. User"}]}

    Information about voting on the current issue.

/api/2.0.alpha1/issue/{issueKey}

resource-wide template parameters
parametervaluedescription

issueKey

string

the issue key to request (i.e. JRA-1330)

Methods

GET

Returns a full representation of the issue for the given issue key.

available response representations:

  • 404 [expand]

    Returned if the requested issue is not found, or the user does not have permission to view it.

  • 200 - application/json (issue) [expand]

    Example
    {"expand":"html","self":"http://example.com:8080/jira/rest/api/2.0/issue/EX-1","key":"EX-1","fields":{"sub-tasks":{"name":"sub-tasks","type":"issuelinks","value":[{"issueKey":"EX-2","issue":"http://example.com:8080/jira/rest/api/2.0/issue/EX-2","type":{"name":"Sub-task","direction":"OUTBOUND"}}]},"timetracking":{"name":"timetracking","type":"timetracking","value":{"timeoriginalestimate":10,"timeestimate":3,"timespent":6}},"project":{"name":"project","type":"com.atlassian.jira.project.Project","value":{"self":"http://example.com:8080/jira/rest/api/2.0/project/PRJ","key":"PRJ"}},"updated":{"name":"updated","type":"java.util.Date","value":1},"description":{"name":"description","type":"java.lang.String","value":"example bug report"},"links":{"name":"links","type":"issuelinks","value":[{"issueKey":"PRJ-2","issue":"http://example.com:8080/jira/rest/api/2.0/issue/PRJ-2","type":{"name":"Dependent","direction":"OUTBOUND","description":"depends on"}},{"issueKey":"PRJ-3","issue":"http://example.com:8080/jira/rest/api/2.0/issue/PRJ-3","type":{"name":"Dependent","direction":"INBOUND","description":"is depended by"}}]},"attachment":{"name":"attachment","type":"attachment","value":[{"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.0/user?username=fred","name":"fred","displayName":"Fred F. User"},"created":"2011-02-08T12:29:58.499+1100","size":23123,"mimeType":"image/jpeg","content":"http://www.example.com/jira/attachments/10000","thumbnail":"http://www.example.com/jira/secure/thumbnail/10000"}]},"watcher":{"name":"watcher","type":"watcher","value":{"self":"http://www.example.com/jira/rest/api/2.0/issue/EX-1/watchers","isWatching":false,"watchCount":1,"watchers":[{"self":"http://www.example.com/jira/rest/api/2.0/user?username=fred","name":"fred","displayName":"Fred F. User"}]}},"comment":{"name":"comment","type":"java.lang.String","value":[{"self":"http://example.com:8080/jira/rest/api/2.0/comment/10000","author":{"self":"http://www.example.com/jira/rest/api/2.0/user?username=fred","name":"fred","displayName":"Fred F. User"},"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.","groupLevel":"jira-user","updateAuthor":{"self":"http://www.example.com/jira/rest/api/2.0/user?username=fred","name":"fred","displayName":"Fred F. User"},"created":"2011-02-08T12:29:58.442+1100","updated":"2011-02-08T12:29:58.442+1100","roleLevel":"jira-users"}]},"worklog":{"name":"worklog","type":"worklog","value":[{"self":"http://www.example.com/jira/rest/api/2.0/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2.0/user?username=fred","name":"fred","displayName":"Fred F. User"},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2.0/user?username=fred","name":"fred","displayName":"Fred F. User"},"comment":"I did some work here.","groupLevel":"jira-developers","started":"2011-02-08T12:29:58.499+1100","minutesSpent":180}]}},"html":{}}

    Returns a full representation of a JIRA issue in JSON format. An issue JSON consists of several members, each of which has its own format.

/api/2.0.alpha1/issue/{issueKey}/watchers

resource-wide template parameters
parametervaluedescription

issueKey

string

a String containing an issue key

Methods

GET

Returns the list of watchers for the issue with the given key.

available response representations:

  • 404 [expand]

    Returned if the requested issue is not found, or the user does not have permission to view it.

  • 200 - application/json (watchers) [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2.0/issue/EX-1/watchers","isWatching":false,"watchCount":1,"watchers":[{"self":"http://www.example.com/jira/rest/api/2.0/user?username=fred","name":"fred","displayName":"Fred F. User"}]}

    Returns the list of watchers for an issue.

POST

Adds a user to an issue's watcher list.

acceptable request representations:

  • application/json [expand]

    Example
    "fred"

available response representations:

  • 204 [expand]

    Returned if the watcher was added successfully.

  • 404 [expand]

    Returned if either the issue or the user does not exist.

  • 401 [expand]

    Returned if the calling user does not have permission to add the watcher to the issue's list of watchers.

  • 400 [expand]

    Returned if there is a problem with the received user representation.

/api/2.0.alpha1/issue/{issueKey}/watchers/{userName}

resource-wide template parameters
parametervaluedescription

userName

string

a String containing the name of the user to remove from the watcher list

issueKey

string

a String containing an issue key

Methods

DELETE

Removes a user from an issue's watcher list.

available response representations:

  • 204 [expand]

    Returned if the watcher was removed successfully.

  • 404 [expand]

    Returned if either the issue or the user does not exist.

  • 401 [expand]

    Returned if the calling user does not have permission to remove the watcher from the issue's list of watchers.

/api/2.0.alpha1/component/{id}

resource-wide template parameters
parametervaluedescription

id

string

a String containing the component key

Methods

GET

Returns a project component.

available response representations:

  • 404 [expand]

    Returned if there is no component with the given key, or if the calling user does not have permission to view the component.

  • 200 - application/json (component) [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2.0/component/COM-1","name":"Component 1","description":"This is a JIRA component"}

    Returns a full JSON representation of a project component.

/api/2.0.alpha1/project/{key}

resource-wide template parameters
parametervaluedescription

key

string

the project key

Methods

GET

Contains a full representation of a project in JSON format.

available response representations:

  • 404 [expand]

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

  • 200 - application/json (project) [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2.0/project/1","key":"EX","description":"Sample project","lead":{"self":"http://www.example.com/jira/rest/api/2.0/user?username=fred","name":"fred","displayName":"Fred F. User"},"components":[{"self":"http://www.example.com/jira/rest/api/2.0/component/COM-1","name":"Component 1","description":"This is a JIRA component"}],"url":"http://www.example.com/jira/browse/EX","versions":[]}

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

/api/2.0.alpha1/serverInfo

Methods

GET

Returns general information about the current JIRA server.

available response representations:

  • 200 - application/json (serverInfo) [expand]

    Returns a full representation of the server info in JSON format

/api/2.0.alpha1/status/{id}

resource-wide template parameters
parametervaluedescription

id

string

a numeric Status id

Methods

GET

Returns a full representation of the Status having the given id.

available response representations:

  • 404 [expand]

    Returned if the requested issue status is not found, or the user does not have permission to view it.

  • 200 - application/json (status) [expand]

    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"}

    Returns a full representation of a JIRA issue status in JSON format.

/api/2.0.alpha1/comment/{id}?render

resource-wide template parameters
parametervaluedescription

id

string

the ID of the issue to request

Methods

GET

Returns a single issue comment.

request query parameters
parametervaluedescription

render

boolean

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:

  • 404 [expand]

    Returned if the requested comment is not found, or the user does not have permission to view it.

  • 200 - application/json (comment) [expand]

    Example
    {"self":"http://example.com:8080/jira/rest/api/2.0/comment/10000","author":{"self":"http://www.example.com/jira/rest/api/2.0/user?username=fred","name":"fred","displayName":"Fred F. User"},"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.","groupLevel":"jira-user","updateAuthor":{"self":"http://www.example.com/jira/rest/api/2.0/user?username=fred","name":"fred","displayName":"Fred F. User"},"created":"2011-02-08T12:29:58.442+1100","updated":"2011-02-08T12:29:58.442+1100","roleLevel":"jira-users"}

    Returns a full representation of a JIRA comment in JSON format.

/api/2.0.alpha1/worklog/{id}

resource-wide template parameters
parametervaluedescription

id

string

a String containing the work log id

Methods

GET

Returns a work log.

available response representations:

  • 404 [expand]

    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.

  • 200 - application/json (worklog) [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2.0/worklog/10000","author":{"self":"http://www.example.com/jira/rest/api/2.0/user?username=fred","name":"fred","displayName":"Fred F. User"},"updateAuthor":{"self":"http://www.example.com/jira/rest/api/2.0/user?username=fred","name":"fred","displayName":"Fred F. User"},"comment":"I did some work here.","groupLevel":"jira-developers","started":"2011-02-08T12:29:58.499+1100","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.

/api/2.0.alpha1/resolution/{id}

resource-wide template parameters
parametervaluedescription

id

string

a String containing the resolution id

Methods

GET

Returns a resolution.

available response representations:

  • 404 [expand]

    Returned if the resolution does not exist or the user does not have permission to view it.

  • 200 - application/json (resolution) [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2.0/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.0.alpha1/user?username

Methods

GET

Returns a user. This resource cannot be accessed anonymously.

request query parameters
parametervaluedescription

username

string

the username

available response representations:

  • 404 [expand]

    Returned if the requested user is not found.

  • 200 - application/json (user) [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2.0/user?username=fred","name":"fred","emailAddress":"fred@example.com","avatarUrl":"http://example.com:8080/jira/secure/useravatar?size=large&ownerId=fred","displayName":"Fred F. User","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.

  • 401 [expand]

    Returned if the current user is not authenticated.