JIRA 6.4.13 REST API documentation

This is the reference document for the REST API and resources provided by JIRA. The REST APIs are developers who want to integrate JIRA with other standalone or web applications, and administrators who want to script interactions with the JIRA server.

If you are after an introductory, high-level view of the JIRA REST API, rather than an exhaustive reference document, then the best place to start is the JIRA REST API home.

Getting started

Because the REST API is based on open standards, you can use any web development language to access the API. If you are using Java, however, the easiest way to get started using the JIRA REST API is to download with the JIRA REST Java Client (JRJC) and use it as a library within your own application. For other languages, refer to the JIRA REST API home for code examples.

Structure of the REST URIs

JIRA's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The JIRA REST API uses JSON as its communication format, and the standard HTTP methods like GET, PUT, POST and DELETE (see API descriptions below for which methods are available for each resource). URIs for JIRA's REST API resource have the following structure: 

http://host:port/context/rest/api-name/api-version/resource-name

Currently there are two API names available, which will be discussed further below:

The current API version is 2. However, there is also a symbolic version, called latest, which resolves to the latest version supported by the given JIRA instance. As an example, if you wanted to retrieve the JSON representation of issue JRA-9 from Atlassian's public issue tracker, you would access: 

https://jira.atlassian.com/rest/api/latest/issue/JRA-9

There is a WADL document that contains the documentation for each resource in the JIRA REST API. It is available here.

Expansion in the REST APIs

In order to minimise network traffic and server CPU usage, the JIRA REST API sometimes uses a technique called expansion. When a REST resource uses expansion then parts of that resource will not be included in the JSON response unless explicitly requested. The way to request those fragments to be included is by using the expand query parameter.

You can use the expand query parameter to specify a comma-separated list of entities that you want expanded, identifying each of them by name. For example, appending ?expand=names,renderedFields to an issue's URI requests the inclusion of the translated field names and the HTML-rendered field values in the response. Continuing with our example above, we would use the following URL to get that information for JRA-9: 

https://jira.atlassian.com/rest/api/latest/issue/JRA-9?expand=names,renderedFields

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

{"expand":"widgets", "self":"http://www.example.com/jira/rest/api/resource/KEY-1", "widgets":{"widgets":[],"size":5}}

You can use the dot notation to specify expansion of entities within another entity. For example ?expand=widgets.fringels would expand the widgets collection and also the fringel property on each widget.

Authentication

Any authentication that works against JIRA will work against the REST API. The prefered authentication methods are OAuth and HTTP Basic (when using SSL), which are both documented in the JIRA REST API Tutorials. Other supported methods include: HTTP Cookies, and Trusted Applications.

The log-in page uses cookie-based authentication, so if you are using JIRA in a browser you can call REST from Javascript on the page and rely on the authentication that the browser has established. Callers wanting to reproduce the behaviour of the JIRA log-in page (for example, to display authentication error messages to users) or who are calling both the REST and SOAP API can POST to the /auth/1/session resource as per the documentation below.

You can find OAuth code samples in several programming languages at bitbucket.org/atlassian_tutorial/atlassian-oauth-examples.

Paged API

JIRA uses pagination to limit the response size for resources that return a potentially large collection of items. A request to a paged API will result in a values array wrapped in a JSON object with some paging metadata, for example: 

    {
        "startAt" : 0,
        "maxResults" : 10,
        "total": 200,
        "values": [
            { /* result 0 */ },
            { /* result 1 */ },
            { /* result 2 */ }
        ]
    }

Clients can use the "startAt" and "maxResults" parameters to retrieve the desired numbers of results.

The "maxResults" parameter indicates how many results to return per page. Each API may have a different limit for number of items returned.

The "startAt" parameter indicates which item should be used as the first item in the page of results.

Important: The response contains a "total" field which denotes the total number of entities contained in all pages. This number may change as the client requests the subsequent pages. A client should always assume that the requested page can be empty. REST API consumers should also consider the field to be optional. In cases, when calculating this value is too expensive we may not include this in response.

Experimental methods

Methods marked as experimental may change without an earlier notice. We are looking for your feedback for these methods.

Index

This documents the current REST API provided by JIRA.

Resources

/rest/api/2/application-properties

Methods

GET 

/rest/api/2/application-properties?key&permissionLevel&keyFilter

Returns an application property.

request query parameters
parametervaluedescription

key

string

a String containing the property key

permissionLevel

string

when fetching a list specifies the permission level of all items in the list see {@link com.atlassian.jira.bc.admin.ApplicationPropertiesService.EditPermissionLevel}

keyFilter

string

when fetching a list allows the list to be filtered by the property's start of key e.g. "jira.lf.*" whould fetch only those permissions that are editable and whose keys start with "jira.lf.". This is a regex.

available response representations:

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

    Example
    {"id":"jira.home","key":"jira.home","value":"/var/jira/jira-home","name":"jira.home","desc":"JIRA home directory","type":"string","defaultValue":""}

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

  • 404 [expand]

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

/rest/api/2/application-properties/{id}

resource-wide template parameters
parametervaluedescription

id

string

Methods

PUT 

Modify an application property via PUT. The "value" field present in the PUT will override the existing value.

acceptable request representations:

  • */* [expand]

    Example
    {"id":"jira.home","value":"/var/jira/jira-home"}

available response representations:

  • 200 [expand]

    Returned if the version exists and the currently authenticated user has permission to edit it.

  • 403 [expand]

    Returned if the currently authenticated user does not have permission to edit the version.

  • 404 [expand]

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

/rest/api/2/attachment/{id}

resource-wide template parameters
parametervaluedescription

id

string

id of the attachment to remove

Methods

GET 

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

available response representations:

  • 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/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"created":"2016-03-03T09:32:02.244+0000","size":23123,"mimeType":"image/jpeg","content":"http://www.example.com/jira/attachments/10000","thumbnail":"http://www.example.com/jira/secure/thumbnail/10000"}

    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.

  • 403 [expand]

    The calling user is not permitted to view the requested attachment.

  • 404 [expand]

    Any of:

    • there is no attachment with the requested id
    • attachments feature is disabled

DELETE 

Remove an attachment from an issue.

available response representations:

  • 204 [expand]

    Removal was successful

  • 403 [expand]

    The calling user is not permitted to remove the requested attachment.

  • 404 [expand]

    Any of:

    • there is no attachment with the requested id
    • attachments feature is disabled

/rest/api/2/attachment/meta

Methods

GET 

Returns the meta information for an attachments, specifically if they are enabled and the maximum upload size allowed.

available response representations:

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

    Example
    {"enabled":true,"uploadLimit":1000000}

    JSON representation of the attachment capabilities. Consumers of this resource may also need to check if the logged in user has permission to upload or otherwise manipulate attachments using the {@link com.atlassian.jira.rest.v2.permission.PermissionsResource}.

/rest/api/2/attachment/{id}/expand/raw

resource-wide template parameters
parametervaluedescription

id

string

the id of the attachment to expand.

Methods

GET  (experimental)

Tries to expand an attachment. Output is raw and should be backwards-compatible through the course of time.

available response representations:

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

    Example
    {"entries":[{"entryIndex":0,"name":"Allegro from Duet in C Major.mp3","size":1430174,"mediaType":"audio/mpeg"},{"entryIndex":1,"name":"lrm.rtf","size":331,"mediaType":"text/rtf"}],"totalEntryCount":24}

    JSON representation of the attachment expanded contents. Empty entry list means that attachment cannot be expanded. It's either empty, corrupt or not an archive at all.

  • 403 [expand]

    The calling user is not permitted to view the requested attachment.

  • 404 [expand]

    Any of:

    • there is no attachment with the requested id
    • attachments feature is disabled

  • 409 [expand]

    The archive format is not supported.

/rest/api/2/attachment/{id}/expand/human

resource-wide template parameters
parametervaluedescription

id

string

the id of the attachment to expand.

Methods

GET  (experimental)

Tries to expand an attachment. Output is human-readable and subject to change.

available response representations:

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

    Example
    {"id":7237823,"name":"images.zip","entries":[{"path":"MG00N067.JPG","index":0,"size":"119 kB","mediaType":"image/jpeg","icon":"image.gif","alternativeText":"JPEG file","label":"MG00N067.JPG"},{"path":"Allegro from Duet in C Major.mp3","index":1,"size":"1.36 MB","mediaType":"audio/mpeg","icon":"file.gif","alternativeText":"File","label":"Allegro from Duet in C Major.mp3"},{"path":"long/path/thanks/to/lots/of/subdirectories/inside/making/it/quite/hard/to/reach/the/leaf.txt","index":2,"size":"0.0 k","mediaType":"text/plain","icon":"text.gif","alternativeText":"Text File","label":"long/path/thanks/to/.../reach/the/leaf.txt"}],"totalEntryCount":39,"mediaType":"application/zip"}

    JSON representation of the attachment expanded contents. Empty entry list means that attachment cannot be expanded. It's either empty, corrupt or not an archive at all.

  • 403 [expand]

    The calling user is not permitted to view the requested attachment.

  • 404 [expand]

    Any of:

    • there is no attachment with the requested id
    • attachments feature is disabled

  • 409 [expand]

    The archive format is not supported.

Resource representing the auditing records

/rest/api/2/auditing/record

Methods

POST 

Store a record in Audit Log

acceptable request representations:

  • application/json (record) [expand]

    Example
    {"summary":"User created","created":null,"category":"USER_MANAGEMENT","objectItem":{"id":"usr","name":"user","typeName":"USER","parentId":"1","parentName":"JIRA Internal Directory"},"changedValues":[{"fieldName":"email","changedFrom":"user@atlassian.com","changedTo":"newuser@atlassian.com"}],"associatedItems":[{"id":"jira-users","name":"jira-users","typeName":"GROUP","parentId":"1","parentName":"JIRA Internal Directory"}]}

available response representations:

  • 201 [expand]

    Returned if the record is successfully stored.

  • 400 [expand]

    In case of unhandled error while fetching auditing records

  • 403 [expand]

    Returned if the user does not have admin permission

GET 

/rest/api/2/auditing/record?offset&limit&filter&from&to

Returns auditing records filtered using provided parameters

request query parameters
parametervaluedescription

offset

int

- the number of record from which search starts

limit

int

- maximum number of returned results (if is limit is <= 0 or > 1000, it will be set do default value: 1000)

filter

string

- text query; each record that will be returned must contain the provided text in one of its fields

from

string

- timestamp in past; 'from' must be less or equal 'to', otherwise the result set will be empty only records that where created in the same moment or after the 'from' timestamp will be provided in response

to

string

- timestamp in past; 'from' must be less or equal 'to', otherwise the result set will be empty only records that where created in the same moment or earlier than the 'to' timestamp will be provided in response

available response representations:

  • 200 - application/json [expand]

    Example
    {"id":1,"summary":"User created","remoteAddress":"192.168.1.1","authorKey":"administrator","created":"2014-03-19T18:45:42.967+0000","category":"user management","eventSource":"JIRA Connect Plugin","objectItem":{"id":"usr","name":"user","typeName":"USER","parentId":"1","parentName":"JIRA Internal Directory"},"changedValues":[{"fieldName":"email","changedFrom":"user@atlassian.com","changedTo":"newuser@atlassian.com"}],"associatedItems":[{"id":"jira-users","name":"jira-users","typeName":"GROUP","parentId":"1","parentName":"JIRA Internal Directory"}]}

    Returns a list auditing records filtered with request query parameters

  • 400 [expand]

    In case of unhandled error while fetching auditing records

  • 403 [expand]

    Returned if the user does not have admin permission

/rest/api/2/avatar/{type}/temporaryCrop

resource-wide template parameters
parametervaluedescription

type

string

the avatar type

Methods

POST 

Updates the cropping instructions of the temporary avatar.

acceptable request representations:

  • application/json [expand]

    Example
    {"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"needsCropping":false}

available response representations:

  • 201 - application/json (avatar) [expand]
  • 400 [expand]

    Returned if the cropping coordinates are invalid

  • 500 [expand]

    Returned if an error occurs while cropping the temporary avatar

/rest/api/2/avatar/{type}/temporary

resource-wide template parameters
parametervaluedescription

type

string

the avatar type

Methods

POST 

/rest/api/2/avatar/{type}/temporary?filename&size

Creates temporary avatar

request query parameters
parametervaluedescription

filename

string

name of file being uploaded

size

long

size of file

available response representations:

  • 201 - application/json (avatar) [expand]

    Example
    {"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}

    temporary avatar cropping instructions

  • 400 [expand]

    Valiation failed. For example filesize is beyond max attachment size.

  • 403 [expand]

    Returned if the request does not conain a valid XSRF token

  • 500 [expand]

    Returned if an error occurs while converting temporary avatar to real avatar

/rest/api/2/avatar/{type}/system

resource-wide template parameters
parametervaluedescription

type

string

the avatar type

Methods

GET 

Returns all system avatars of the given type.

available response representations:

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

    Example
    {"system":[{"id":"1000","owner":"fred","isSystemAvatar":true,"isSelected":false,"urls":{"16x16":"http://localhost:8090/jira/secure/useravatar?size=xsmall&avatarId=10040","24x24":"http://localhost:8090/jira/secure/useravatar?size=small&avatarId=10040","32x32":"http://localhost:8090/jira/secure/useravatar?size=medium&avatarId=10040","48x48":"http://localhost:8090/jira/secure/useravatar?avatarId=10040"},"selected":false}]}

    Returns a map containing a list of system avatars. A map is returned to be consistent with the shape of the project/KEY/avatars REST end point.

  • 500 [expand]

    Returned if an error occurs while retrieving the list of avatars.

/rest/api/2/comment/{commentId}/properties

resource-wide template parameters
parametervaluedescription

commentId

string

the comment from which keys will be returned.

Methods

GET  (experimental)

Returns the keys of all properties for the comment identified by the key or by the id.

available response representations:

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

    Example
    {"keys":[{"self":"http://www.example.com/jira/rest/api/2/issue/EX-2/properties/issue.support","key":"issue.support"}]}

    Returned if the comment was found.

  • 400 [expand]

    Returned if the comment key or id is invalid.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to browse the comment.

  • 404 [expand]

    Returned if the comment with given key or id does not exist or if the property with given key is not found.

/rest/api/2/comment/{commentId}/properties/{propertyKey}

resource-wide template parameters
parametervaluedescription

commentId

string

the comment from which keys will be returned.

propertyKey

string

the key of the property to remove.

commentId

string

the comment from which the property will be removed.

Methods

PUT  (experimental)

Sets the value of the specified comment's property.

You can use this resource to store a custom data against the comment identified by the key or by the id. The user who stores the data is required to have permissions to administer the comment.

available response representations:

  • 200 [expand]

    Returned if the comment property is successfully updated.

  • 201 [expand]

    Returned if the comment property is successfully created.

  • 400 [expand]

    Returned if the comment key or id is invalid.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to administer the comment.

  • 404 [expand]

    Returned if the comment with given key or id does not exist.

GET  (experimental)

Returns the value of the property with a given key from the comment identified by the key or by the id. The user who retrieves the property is required to have permissions to read the comment.

available response representations:

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

    Example
    {"key":"issue.support","value":{}}

    Returned if the comment property was found.

  • 400 [expand]

    Returned if the comment key or id is invalid.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to browse the comment.

  • 404 [expand]

    Returned if the comment with given key or id does not exist or if the property with given key is not found.

DELETE  (experimental)

Removes the property from the comment identified by the key or by the id. Ths user removing the property is required to have permissions to administer the comment.

available response representations:

  • 204 [expand]

    Returned if the comment property was removed successfully.

  • 400 [expand]

    Returned if the comment key or id is invalid.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to edit the comment.

  • 404 [expand]

    Returned if the comment with given key or id does not exist or if the property with given key is not found.

/rest/api/2/component

Methods

POST 

Create a component via POST.

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"Component 1","description":"This is a JIRA component","leadUserName":"fred","assigneeType":"PROJECT_LEAD","isAssigneeTypeValid":false,"project":"PROJECTKEY","projectId":10000}

available response representations:

  • 201 - application/json [expand]

    Example
    {"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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"isAssigneeTypeValid":false,"project":"HSP","projectId":10000}

    Returned if the component is created successfully.

  • 401 [expand]

    Returned if the caller is not logged in and does not have permission to create components in the project.

  • 403 [expand]

    Returned if the caller is authenticated and does not have permission to create components in the project.

  • 404 [expand]

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

/rest/api/2/component/{id}

resource-wide template parameters
parametervaluedescription

id

string

Methods

DELETE 

/rest/api/2/component/{id}?moveIssuesTo

Delete a project component.

request query parameters
parametervaluedescription

moveIssuesTo

string

The new component applied to issues whose 'id' component will be deleted. If this value is null, then the 'id' component is simply removed from the related isues.

available response representations:

  • 204 [expand]

    Returned if the component is successfully deleted.

  • 403 [expand]

    Returned if the currently authenticated user does not have permission to delete the component.

  • 404 [expand]

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

GET 

Returns a project component.

available response representations:

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

    Example
    {"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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"isAssigneeTypeValid":false,"project":"HSP","projectId":10000}

    Returns a full JSON representation of a project component.

  • 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.

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.

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"Component 1","description":"This is a JIRA component","leadUserName":"fred","assigneeType":"PROJECT_LEAD","isAssigneeTypeValid":false,"project":"PROJECTKEY","projectId":10000}

available response representations:

  • 200 [expand]

    Returned if the component exists and the currently authenticated user has permission to edit it.

  • 403 [expand]

    Returned if the currently authenticated user does not have permission to edit the component.

  • 404 [expand]

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

/rest/api/2/component/{id}/relatedIssueCounts

resource-wide template parameters
parametervaluedescription

id

string

a String containing the component id

Methods

GET 

Returns counts of issues related to this component.

available response representations:

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

    Example
    {"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 related to this component.

  • 404 [expand]

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

/rest/api/2/configuration

Methods

GET 

Returns the information if the optional features in JIRA are enabled or disabled. If the time tracking is enabled, it also returns the detailed information about time tracking configuration.

available response representations:

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

    Example
    {"votingEnabled":true,"watchingEnabled":true,"unassignedIssuesAllowed":false,"subTasksEnabled":false,"issueLinkingEnabled":true,"timeTrackingEnabled":true,"attachmentsEnabled":true,"timeTrackingConfiguration":{"workingHoursPerDay":8.0,"workingDaysPerWeek":5.0,"timeFormat":"pretty","defaultUnit":"day"}}

    Returned the configuration of optional features in JIRA.

  • 403 [expand]

    Returned if the user is not an admin.

/rest/api/2/customFieldOption/{id}

resource-wide template parameters
parametervaluedescription

id

string

a String containing an Custom Field Option id

Methods

GET 

Returns a full representation of the Custom Field Option that has the given id.

available response representations:

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

    Example
    {"self":"http://localhost:8090/jira/rest/api/2.0/customFieldOption/3","value":"Blue"}

    Returned if the Custom Field Option exists and is visible by the calling user.

  • 404 [expand]

    Returned if the Custom Field Option does not exist, or is not visible to the calling user.

/rest/api/2/dashboard

The /dashboard resource.

Methods

GET 

/rest/api/2/dashboard?filter&startAt&maxResults

Returns a list of all dashboards, optionally filtering them.

request query parameters
parametervaluedescription

filter

string

an optional filter that is applied to the list of dashboards. Valid values include "favourite" for returning only favourite dashboards, and "my" for returning dashboards that are owned by the calling user.

startAt

int

the index of the first dashboard to return (0-based). must be 0 or a multiple of maxResults

maxResults

int

a hint as to the the maximum number of dashboards to return in each call. Note that the JIRA server reserves the right to impose a maxResults limit that is lower than the value that a client provides, dues to lack or resources or any other condition. When this happens, your results will be truncated. Callers should always check the returned maxResults to determine the value that is effectively being used.

available response representations:

  • 200 [expand]

    Example
    {"startAt":10,"maxResults":10,"total":143,"prev":"http://www.example.com/jira/rest/api/2/dashboard?startAt=0","next":"http://www.example.com/jira/rest/api/2/dashboard?startAt=10","dashboards":[{"id":"10000","name":"System Dashboard","self":"http://www.example.com/jira/rest/api/2/dashboard/10000","view":"http://www.example.com/jira/secure/Dashboard.jspa?selectPageId=10000"},{"id":"20000","name":"Build Engineering","self":"http://www.example.com/jira/rest/api/2/dashboard/20000","view":"http://www.example.com/jira/secure/Dashboard.jspa?selectPageId=20000"}]}

    Returns a list of dashboards.

/rest/api/2/dashboard/{id}

resource-wide template parameters
parametervaluedescription

id

string

the dashboard id

Methods

GET 

Returns a single dashboard.

available response representations:

  • 200 [expand]

    Example
    {"id":"10000","name":"System Dashboard","self":"http://www.example.com/jira/rest/api/2/dashboard/10000","view":"http://www.example.com/jira/secure/Dashboard.jspa?selectPageId=10000"}

    Returns a single dashboard.

  • 404 [expand]

    Returned if there is no dashboard with the specified id, or if the user does not have permission to see it.

/rest/api/2/dashboard/{dashboardId}/items/{itemId}/properties

resource-wide template parameters
parametervaluedescription

itemId

string

the dashboard item from which keys will be returned.

dashboardId

string

Methods

GET 

Returns the keys of all properties for the dashboard item identified by the id.

available response representations:

  • 200 - application/json (dashboard-item-properties-keys) [expand]

    Example
    {"keys":[{"self":"http://www.example.com/jira/rest/api/2/issue/EX-2/properties/issue.support","key":"issue.support"}]}

    Returned if the dashboard item was found.

  • 400 [expand]

    Returned if the dashboard item id is invalid.

  • 404 [expand]

    Returned if the dashboard item with given id does not exist or user does not have permissions to view it.

/rest/api/2/dashboard/{dashboardId}/items/{itemId}/properties/{propertyKey}

resource-wide template parameters
parametervaluedescription

itemId

string

the dashboard item from which keys will be returned.

dashboardId

string

propertyKey

string

the key of the property to remove.

itemId

string

the dashboard item from which the property will be removed.

dashboardId

string

Methods

PUT 

Sets the value of the specified dashboard item's property.

You can use this resource to store a custom data against the dashboard item identified by the id. The user who stores the data is required to have permissions to administer the dashboard item.

available response representations:

  • 200 [expand]

    Returned if the dashboard item property is successfully updated.

  • 201 [expand]

    Returned if the dashboard item property is successfully created.

  • 400 [expand]

    Returned if the dashboard item id is invalid.

  • 403 [expand]

    Returned if the calling user does not have permission to administer the dashboard item.

  • 404 [expand]

    Returned if the dashboard item with given id does not exist or user does not have permissions to view it.

GET 

Returns the value of the property with a given key from the dashboard item identified by the id. The user who retrieves the property is required to have permissions to read the dashboard item.

available response representations:

  • 200 - application/json (dashboard item-property) [expand]

    Example
    {"key":"issue.support","value":{}}

    Returned if the dashboard item property was found.

  • 400 [expand]

    Returned if the dashboard item id is invalid.

  • 404 [expand]

    Returned if the dashboard item with given id does not exist or user does not have permissions to view it.

DELETE 

Removes the property from the dashboard item identified by the key or by the id. Ths user removing the property is required to have permissions to administer the dashboard item.

available response representations:

  • 204 [expand]

    Returned if the dashboard item property was removed successfully.

  • 400 [expand]

    Returned if the dashboard item id is invalid.

  • 403 [expand]

    Returned if the calling user does not have permission to edit the dashboard item.

  • 404 [expand]

    Returned if the dashboard item with given id does not exist or user does not have permissions to view it.

/rest/api/2/field

Methods

GET 

Returns a list of all fields, both System and Custom

available response representations:

  • 200 - application/json (List of field) [expand]

    Example
    [{"id":"description","name":"Description","custom":false,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["description"],"schema":{"type":"string","system":"description"}},{"id":"summary","name":"Summary","custom":false,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["summary"],"schema":{"type":"string","system":"summary"}}]

    Contains a full representation of all visible fields in JSON.

POST 

Creates a custom field using a definition (object encapsulating custom field data)

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"New custom field","description":"Custom field for picking groups","type":"com.atlassian.jira.plugin.system.customfieldtypes:grouppicker","searcherKey":"com.atlassian.jira.plugin.system.customfieldtypes:grouppickersearcher"}

available response representations:

  • 201 [expand]

    Returned if custom field was created. {@link FieldBean#DOC_EXAMPLE_CF}

  • 400 [expand]

    Returned if the input is invalid (e.g. invalid values).

  • 500 [expand]

    Returned if exception occured during custom field creation.

/rest/api/2/filter

Resource for searches.

Methods

POST 

/rest/api/2/filter?expand

Creates a new filter, and returns newly created filter. Currently sets permissions just using the users default sharing permissions

request query parameters
parametervaluedescription

expand

string

the parameters to expand

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"All Open Bugs","description":"Lists all open bugs","jql":"type = Bug and resolution is empty","favourite":true}

available response representations:

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

    Example
    {"self":"http://www.example.com/jira/rest/api/2/filter/10000","id":"10000","name":"All Open Bugs","description":"Lists all open bugs","owner":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"jql":"type = Bug and resolution is empty","viewUrl":"http://www.example.com/jira/secure/IssueNavigator.jspa?mode=hide&requestId=10000","searchUrl":"http://www.example.com/jira/rest/api/2/search?jql=type%20%3D%20Bug%20and%20resolutino%20is%20empty","favourite":true,"sharePermissions":[],"subscriptions":{"size":0,"items":[],"max-results":1000,"start-index":0,"end-index":0}}

    Returns a JSON representation of a filter

  • 400 [expand]

    Returned if the input is invalid (e.g. filter name was not provided).

/rest/api/2/filter/{id}

resource-wide template parameters
parametervaluedescription

id

long

The ID of the filter to delete.

Methods

GET 

/rest/api/2/filter/{id}?expand

Returns a filter given an id

request query parameters
parametervaluedescription

expand

string

the parameters to expand

available response representations:

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

    Example
    {"self":"http://www.example.com/jira/rest/api/2/filter/10000","id":"10000","name":"All Open Bugs","description":"Lists all open bugs","owner":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"jql":"type = Bug and resolution is empty","viewUrl":"http://www.example.com/jira/secure/IssueNavigator.jspa?mode=hide&requestId=10000","searchUrl":"http://www.example.com/jira/rest/api/2/search?jql=type%20%3D%20Bug%20and%20resolutino%20is%20empty","favourite":true,"sharePermissions":[],"subscriptions":{"size":0,"items":[],"max-results":1000,"start-index":0,"end-index":0}}

    Returns a JSON representation of a filter

  • 400 [expand]

    Returned if there is a problem looking up the filter given the id

PUT 

/rest/api/2/filter/{id}?expand

Updates an existing filter, and returns its new value.

request query parameters
parametervaluedescription

expand

string

the parameters to expand

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"All Open Bugs","description":"Lists all open bugs","jql":"type = Bug and resolution is empty","favourite":true}

available response representations:

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

    Example
    {"self":"http://www.example.com/jira/rest/api/2/filter/10000","id":"10000","name":"All Open Bugs","description":"Lists all open bugs","owner":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"jql":"type = Bug and resolution is empty","viewUrl":"http://www.example.com/jira/secure/IssueNavigator.jspa?mode=hide&requestId=10000","searchUrl":"http://www.example.com/jira/rest/api/2/search?jql=type%20%3D%20Bug%20and%20resolutino%20is%20empty","favourite":true,"sharePermissions":[],"subscriptions":{"size":0,"items":[],"max-results":1000,"start-index":0,"end-index":0}}

    Returns a JSON representation of a filter

  • 400 [expand]

    Returned if there is a problem updating up the filter of the given id

DELETE 

Delete a filter.

available response representations:

  • 204 [expand]

    Returned if the filter was removed successfully.

  • 400 [expand]

    Returned if an error occurs.

  • 401 [expand]

    Returned if the calling user is not authenticated.

/rest/api/2/filter/{id}/columns

resource-wide template parameters
parametervaluedescription

id

long

id of the filter

Methods

GET 

Returns the default columns for the given filter. Currently logged in user will be used as the user making such request.

available response representations:

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

    Returns a list of columns for configured for the given user

  • 404 [expand]

    Returned if the filter does not have any columns.

  • 500 [expand]

    Returned if an error occurs while retrieving the column configuration.

PUT 

Sets the default columns for the given filter.

acceptable request representations:

  • application/x-www-form-urlencoded [expand]

available response representations:

  • 200 [expand]

    Returned when the columns are saved successfully

  • 500 [expand]

    Returned if an error occurs while retrieving the column configuration.

DELETE 

Resets the columns for the given filter such that the filter no longer has its own column config.

available response representations:

  • 204 [expand]

    Returned when the columns are reset/removed successfully

  • 500 [expand]

    Returned if an error occurs while retrieving the column configuration.

/rest/api/2/filter/defaultShareScope

Methods

GET 

Returns the default share scope of the logged-in user.

available response representations:

  • 200 - application/json [expand]

    Example
    {"scope":"GLOBAL"}

    Returns the default share scope of the logged-in user.

  • 400 [expand]

    Returned if there is a problem looking up preferences for the logged-in user

PUT 

Sets the default share scope of the logged-in user. Available values are GLOBAL and PRIVATE.

acceptable request representations:

  • application/json [expand]

    Example
    {"scope":"GLOBAL"}

available response representations:

  • 200 - application/json [expand]

    Example
    {"scope":"GLOBAL"}

    Returns the new default share scope of the logged-in user.

  • 400 [expand]

    Returned if there is a problem setting the preferences for the logged-in user

/rest/api/2/filter/favourite

Methods

GET 

/rest/api/2/filter/favourite?expand

Returns the favourite filters of the logged-in user.

request query parameters
parametervaluedescription

expand

string

the parameters to expand

available response representations:

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

    Example
    [{"self":"http://www.example.com/jira/rest/api/2/filter/10000","id":"10000","name":"All Open Bugs","description":"Lists all open bugs","owner":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"jql":"type = Bug and resolution is empty","viewUrl":"http://www.example.com/jira/secure/IssueNavigator.jspa?mode=hide&requestId=10000","searchUrl":"http://www.example.com/jira/rest/api/2/search?jql=type%20%3D%20Bug%20and%20resolutino%20is%20empty","favourite":true,"sharePermissions":[],"subscriptions":{"size":0,"items":[],"max-results":1000,"start-index":0,"end-index":0}},{"self":"http://www.example.com/jira/rest/api/2/filter/10010","id":"10010","name":"My issues","description":"Issues assigned to me","owner":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"jql":"assignee = currentUser() and resolution is empty","viewUrl":"http://www.example.com/jira/secure/IssueNavigator.jspa?mode=hide&requestId=10010","searchUrl":"http://www.example.com/jira/rest/api/2/search?jql=assignee+%3D+currentUser%28%29+and+resolution+is+empty","favourite":true,"sharePermissions":[{"id":10000,"type":"global"},{"id":10010,"type":"project","project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}}}],"subscriptions":{"size":0,"items":[],"max-results":1000,"start-index":0,"end-index":0}}]

    Returns a JSON representation of a list of filters

/rest/api/2/group

Methods

POST  (experimental)

Creates a group by given group parameter Returns REST representation for the requested group.

acceptable request representations:

available response representations:

  • 201 - application/json (group) [expand]

    Example
    {"name":"jira-administrators","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-administrators","users":{"size":1,"items":[{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false}],"max-results":50,"start-index":0,"end-index":0},"expand":"users"}

    Returns full representation of a JIRA group in JSON format.

  • 400 [expand]

    Returned if user requested an empty group name or group already exists

  • 401 [expand]

    Returned if the current user is not authenticated.

  • 403 [expand]

    Returned if the current user does not have administrator permissions.

  • 500 [expand]

    Returned if the operation is not permitted or error occurs while creating the group.

GET 

/rest/api/2/group?groupname&expand

Returns REST representation for the requested group. Allows to get list of active users belonging to the specified group and its subgroups if "users" expand option is provided. You can page through users list by using indexes in expand param. For example to get users from index 10 to index 15 use "users[10:15]" expand value. This will return 6 users (if there are at least 16 users in this group). Indexes are 0-based and inclusive.

request query parameters
parametervaluedescription

groupname

string

A name of requested group.

expand

string

List of fields to expand. Currently only available expand is "users".

available response representations:

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

    Example
    {"name":"jira-administrators","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-administrators","users":{"size":1,"items":[{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false}],"max-results":50,"start-index":0,"end-index":0},"expand":"users"}

    Returns full representation of a JIRA group in JSON format.

  • 400 [expand]

    Returned if user requested an empty group name.

  • 401 [expand]

    Returned if the current user is not authenticated.

  • 403 [expand]

    Returned if the current user does not have administrator permissions.

  • 404 [expand]

    Returned if the requested group was not found.

DELETE  (experimental)

/rest/api/2/group?groupname&swapGroup

Deletes a group by given group parameter. Returns no content

request query parameters
parametervaluedescription

groupname

string

a group to delete

swapGroup

string

a group to transfer visibility restrictions of the group that is being deleted

available response representations:

  • 200 - application/json [expand]

    Returned if the group was deleted.

  • 400 [expand]

    Returned if user requested an group that does not exist.

  • 401 [expand]

    Returned if the current user is not authenticated.

  • 403 [expand]

    Returned if the current user does not have administrator permissions.

  • 404 [expand]

    Returned if the requested group was not found.

  • 500 [expand]

    Returned if the operation is not permitted or error occurs while deleting the group.

/rest/api/2/group/user

Methods

POST  (experimental)

/rest/api/2/group/user?groupname

Adds given user to a group. Returns the current state of the group.

request query parameters
parametervaluedescription

groupname

string

A name of requested group.

acceptable request representations:

available response representations:

  • 201 - application/json (group) [expand]

    Returns full representation of a JIRA group in JSON format.

  • 400 [expand]

    Returned if user requested an empty group name or the user already belongs to the group.

  • 401 [expand]

    Returned if the current user is not authenticated.

  • 403 [expand]

    Returned if the current user does not have administrator permissions.

  • 404 [expand]

    Returned if the requested group was not found or requested user was not found.

  • 500 [expand]

    Returned if the operation is not permitted or error occurs while adding user the group.

DELETE  (experimental)

/rest/api/2/group/user?groupname&username

Removes given user from a group. Returns no content

request query parameters
parametervaluedescription

groupname

string

A name of requested group.

username

string

User to remove from a group

available response representations:

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

    If the user was removed from the group.

  • 400 [expand]

    Returned if user requested an empty group name

  • 401 [expand]

    Returned if the current user is not authenticated.

  • 403 [expand]

    Returned if the current user does not have administrator permissions.

  • 404 [expand]

    Returned if the requested group was not found or the requested user wan not found

  • 500 [expand]

    Returned if the operation is not permitted or error occurs while removing user from the group.

REST endpoint for searching groups in a group picker

/rest/api/2/groups/picker

Methods

GET 

/rest/api/2/groups/picker?query&exclude&maxResults

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
parametervaluedescription

query

string

a String to match groups agains

exclude

string

maxResults

int

available response representations:

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

    Example
    {"header":"Showing 20 of 25 matching groups","total":25,"groups":[{"name":"jdog-developers","html":"<b>j</b>dog-developers"},{"name":"juvenal-bot","html":"<b>j</b>uvenal-bot"}]}

    Returned even if no groups match the given substring

/rest/api/2/groupuserpicker

Methods

GET 

/rest/api/2/groupuserpicker?query&maxResults&showAvatar&fieldId&projectId&issueTypeId

Returns a list of users and groups matching query with highlighting. This resource cannot be accessed anonymously.

request query parameters
parametervaluedescription

query

string

A string used to search username, Name or e-mail address

maxResults

int

the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.

showAvatar

boolean

fieldId

string

The custom field id, if this request comes from a custom field, such as a user picker. Optional.

projectId

string

The list of project ids to further restrict the search This parameter can occur multiple times to pass in multiple project ids. Comma separated value is not supported. This parameter is only used when fieldId is present.

issueTypeId

string

The list of issue type ids to further restrict the search. This parameter can occur multiple times to pass in multiple issue type ids. Comma separated value is not supported. Special values such as -1 (all standard issue types), -2 (all subtask issue types) are supported. This parameter is only used when fieldId is present.

available response representations:

/rest/api/2/issue

Methods

POST 

Creates an issue or a sub-task from a JSON representation.

The fields that can be set on create, in either the fields parameter or the update parameter can be determined using the /rest/api/2/issue/createmeta resource. If a field is not configured to appear on the create screen, then it will not be in the createmeta, and a field validation error will occur if it is submitted.

Creating a sub-task is similar to creating a regular issue, with two important differences:

  • the issueType field must correspond to a sub-task issue type (you can use /issue/createmeta to discover sub-task issue types), and
  • you must provide a parent field in the issue create request containing the id or key of the parent issue.

acceptable request representations:

  • application/json [expand]

    Example
    {"update":{"worklog":[{"add":{"started":"2011-07-05T11:05:00.000+0000","timeSpent":"60m"}}]},"fields":{"project":{"id":"10000"},"summary":"something's wrong","issuetype":{"id":"10000"},"assignee":{"name":"homer"},"reporter":{"name":"smithers"},"priority":{"id":"20000"},"labels":["bugfix","blitz_test"],"timetracking":{"originalEstimate":"10","remainingEstimate":"5"},"security":{"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_80000":{"value":"red"},"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:

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

    Example
    {"id":"10000","key":"TST-24","self":"http://www.example.com/jira/rest/api/2/issue/10000"}

    Returns a link to the created issue.

  • 400 [expand]

    Example
    {"errorMessages":["Field 'priority' is required"],"errors":{}}

    Returned if the input is invalid (e.g. missing required fields, invalid field values, and so forth).

/rest/api/2/issue/bulk

Methods

POST 

Creates issues or sub-tasks from a JSON representation.

Creates many issues in one bulk operation.

Creating a sub-task is similar to creating a regular issue. More details can be found in createIssue section: {@link IssueResource#createIssue(IssueUpdateBean)}}

acceptable request representations:

  • application/json [expand]

    Example
    {"issueUpdates":[{"update":{"worklog":[{"add":{"started":"2011-07-05T11:05:00.000+0000","timeSpent":"60m"}}]},"fields":{"project":{"id":"10000"},"summary":"something's wrong","issuetype":{"id":"10000"},"assignee":{"name":"homer"},"reporter":{"name":"smithers"},"priority":{"id":"20000"},"labels":["bugfix","blitz_test"],"timetracking":{"originalEstimate":"10","remainingEstimate":"5"},"security":{"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_80000":{"value":"red"},"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"}},{"update":{},"fields":{"project":{"id":"1000"},"summary":"something's very wrong","issuetype":{"id":"10000"},"assignee":{"name":"jerry"},"reporter":{"name":"kosecki"},"priority":{"id":"20000"},"labels":["new_release"],"timetracking":{"originalEstimate":"15","remainingEstimate":"5"},"security":{"id":"10000"},"versions":[{"id":"10000"}],"environment":"environment","description":"description","duedate":"2011-04-16","fixVersions":[{"id":"10001"}],"components":[{"id":"10000"}],"customfield_60000":"jira-developers","customfield_20000":"06/Jul/11 3:25 PM","customfield_80000":{"value":"red"},"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:

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

    Example
    {"issues":[{"id":"10000","key":"TST-24","self":"http://www.example.com/jira/rest/api/2/issue/10000"},{"id":"10001","key":"TST-25","self":"http://www.example.com/jira/rest/api/2/issue/10001"}],"errors":[]}

    Returns a link to the created issues.

  • 400 [expand]

    Example
    {"status":400,"elementErrors":{"errorMessages":["Field 'priority' is required"],"errors":{}},"failedElementNumber":3}

    Returned if the input is invalid (e.g. missing required fields, invalid field values, and so forth).

/rest/api/2/issue/{issueIdOrKey}

resource-wide template parameters
parametervaluedescription

issueIdOrKey

string

the issue id or key to update (i.e. JRA-1330)

Methods

GET 

/rest/api/2/issue/{issueIdOrKey}?fields&expand

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 param (which can be specified multiple times) gives a comma-separated list of fields to include in the response. This can be used to retrieve a subset of fields. A particular field can be excluded by prefixing it with a minus.

By default, all (*all) fields are returned in this get-issue resource. Note: the default is different when doing a jql search -- the default there is just navigable fields (*navigable).

  • *all - include all fields
  • *navigable - include just navigable fields
  • summary,comment - include just the summary and comments
  • -comment - include everything except comments (the default is *all for get-issue)
  • *all,-comment - include everything except comments

JIRA will attempt to identify the issue by the issueIdOrKey path parameter. This can be an issue id, or an issue key. If the issue cannot be found via an exact match, JIRA will also look for the issue in a case-insensitive way, or by looking to see if the issue was moved. In either of these cases, the request will proceed as normal (a 302 or other redirect will not be returned). The issue key contained in the response will indicate the current value of issue's key.

request query parameters
parametervaluedescription

fields

string

the list of fields to return for the issue. By default, all fields are returned.

expand

string

available response representations:

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

    Example
    {"expand":"renderedFields,names,schema,transitions,operations,editmeta,changelog","id":"10002","self":"http://www.example.com/jira/rest/api/2/issue/10002","key":"EX-1","fields":{"sub-tasks":[{"id":"10000","type":{"id":"10000","name":"","inward":"Parent","outward":"Sub-task"},"outwardIssue":{"id":"10003","key":"EX-2","self":"http://www.example.com/jira/rest/api/2/issue/EX-2","fields":{"status":{"iconUrl":"http://www.example.com/jira//images/icons/statuses/open.png","name":"Open"}}}}],"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400},"project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"updated":1,"description":"example bug report","issuelinks":[{"id":"10001","type":{"id":"10000","name":"Dependent","inward":"depends on","outward":"is depended by"},"outwardIssue":{"id":"10004L","key":"PRJ-2","self":"http://www.example.com/jira/rest/api/2/issue/PRJ-2","fields":{"status":{"iconUrl":"http://www.example.com/jira//images/icons/statuses/open.png","name":"Open"}}}},{"id":"10002","type":{"id":"10000","name":"Dependent","inward":"depends on","outward":"is depended by"},"inwardIssue":{"id":"10004","key":"PRJ-3","self":"http://www.example.com/jira/rest/api/2/issue/PRJ-3","fields":{"status":{"iconUrl":"http://www.example.com/jira//images/icons/statuses/open.png","name":"Open"}}}}],"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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"created":"2016-03-03T09:32:02.244+0000","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://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"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":"2016-03-03T09:32:02.140+0000","updated":"2016-03-03T09:32:02.140+0000","visibility":{"type":"role","value":"Administrators"}}],"worklog":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/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":"2016-03-03T09:32:02.251+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028"}]},"names":{"sub-tasks":"sub-tasks","timetracking":"timetracking","project":"project","updated":"updated","description":"description","issuelinks":"issuelinks","attachment":"attachment","watcher":"watcher","comment":"comment","worklog":"worklog"},"schema":{}}

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

  • 404 [expand]

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

DELETE 

/rest/api/2/issue/{issueIdOrKey}?deleteSubtasks

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.

request query parameters
parametervaluedescription

deleteSubtasks

string

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:

  • 204 [expand]

    Returned if the issue was removed successfully.

  • 400 [expand]

    Returned if an error occurs.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to delete the issue.

  • 404 [expand]

    Returned if the issue does not exist.

PUT 

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.

The fields that can be updated, in either the fields parameter or the update parameter, can be determined using the /rest/api/2/issue/{issueIdOrKey}/editmeta resource.
If a field is not configured to appear on the edit screen, then it will not be in the editmeta, and a field validation error will occur if it is submitted.

Specifying a "field_id": field_value in the "fields" is a shorthand for a "set" operation in the "update" section.
Field should appear either in "fields" or "update", not in both.

acceptable request representations:

  • application/json [expand]

    Example
    {"update":{"summary":[{"set":"Bug in business logic"}],"timetracking":[{"edit":{"originalEstimate":"1w 1d","remainingEstimate":"4d"}}],"labels":[{"add":"triaged"},{"remove":"blocker"}],"components":[{"set":""}]},"fields":{"summary":"This is a shorthand for a set operation on the summary field","customfield_10010":1,"customfield_10000":"This is a shorthand for a set operation on a text custom field"},"historyMetadata":{"type":"myplugin:type","description":"text description","descriptionKey":"plugin.changereason.i18.key","activityDescription":"text description","activityDescriptionKey":"plugin.activity.i18.key","actor":{"id":"tony","displayName":"Tony","type":"mysystem-user","avatarUrl":"http://mysystem/avatar/tony.jpg","url":"http://mysystem/users/tony"},"generator":{"id":"mysystem-1","type":"mysystem-application"},"cause":{"id":"myevent","type":"mysystem-event"},"extraData":{"keyvalue":"extra data","goes":"here"}}}

available response representations:

  • 200 - application/json [expand]

    Returned if it updated the issue succesfully.

  • 400 [expand]

    Returned if the requested issue update failed.

/rest/api/2/issue/{issueIdOrKey}/assignee

resource-wide template parameters
parametervaluedescription

issueIdOrKey

string

a String containing an issue key

Methods

PUT 

Assigns an issue to a user. You can use this resource to assign issues when the user submitting the request has the assign permission but not the edit issue permission. If the name is "-1" automatic assignee is used. A null name will remove the assignee.

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"harry"}

available response representations:

  • 204 [expand]

    Returned if the issue is successfully assigned.

  • 400 [expand]

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

  • 401 [expand]

    Returned if the calling user does not have permission to assign the issue.

  • 404 [expand]

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

/rest/api/2/issue/{issueIdOrKey}/comment

resource-wide template parameters
parametervaluedescription

issueIdOrKey

string

a string containing the issue id or key the comment will be added to

Methods

GET 

/rest/api/2/issue/{issueIdOrKey}/comment?expand

Returns all comments for an issue.

request query parameters
parametervaluedescription

expand

string

optional flags: renderedBody (provides body rendered in HTML)

available response representations:

  • 200 - application/json [expand]

    Example
    {"startAt":0,"maxResults":1,"total":1,"comments":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"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":"2016-03-03T09:32:02.140+0000","updated":"2016-03-03T09:32:02.140+0000","visibility":{"type":"role","value":"Administrators"}}]}

    returns a collection of comments associated with the issue, with count and pagination information.

  • 404 [expand]

    Returned if the issue with the given id/key does not exist or if the currently authenticated user does not have permission to view it.

POST 

/rest/api/2/issue/{issueIdOrKey}/comment?expand

Adds a new comment to an issue.

request query parameters
parametervaluedescription

expand

string

optional flags: renderedBody (provides body rendered in HTML)

acceptable request representations:

  • application/json [expand]

    Example
    {"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.","visibility":{"type":"role","value":"Administrators"}}

available response representations:

  • 201 [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"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":"2016-03-03T09:32:02.140+0000","updated":"2016-03-03T09:32:02.140+0000","visibility":{"type":"role","value":"Administrators"}}

    Returned if add was successful

  • 400 [expand]

    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).

/rest/api/2/issue/{issueIdOrKey}/comment/{id}

resource-wide template parameters
parametervaluedescription

id

string

id of the comment to be deleted

issueIdOrKey

string

a string containing the issue id or key the comment belongs to

Methods

GET 

/rest/api/2/issue/{issueIdOrKey}/comment/{id}?expand

Returns all comments for an issue.

request query parameters
parametervaluedescription

expand

string

optional flags: renderedBody (provides body rendered in HTML)

available response representations:

  • 200 - application/json [expand]

    Example
    {"startAt":0,"maxResults":1,"total":1,"comments":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"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":"2016-03-03T09:32:02.140+0000","updated":"2016-03-03T09:32:02.140+0000","visibility":{"type":"role","value":"Administrators"}}]}

    returns a collection of comments associated with the issue, with count and pagination information.

  • 404 [expand]

    Returned if the issue with the given id/key does not exist or if the currently authenticated user does not have permission to view it.

PUT 

/rest/api/2/issue/{issueIdOrKey}/comment/{id}?expand

Updates an existing comment using its JSON representation.

request query parameters
parametervaluedescription

expand

string

optional flags: renderedBody (provides body rendered in HTML)

acceptable request representations:

  • application/json [expand]

    Example
    {"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.","visibility":{"type":"role","value":"Administrators"}}

available response representations:

  • 200 [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2/issue/10010/comment/10000","id":"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":"2016-03-03T09:32:02.140+0000","updated":"2016-03-03T09:32:02.140+0000","visibility":{"type":"role","value":"Administrators"}}

    Returned if update was successful

  • 400 [expand]

    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).

DELETE 

Deletes an existing comment .

available response representations:

  • 204 [expand]

    Returned if delete was successful

  • 400 [expand]

    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).

/rest/api/2/issue/{issueIdOrKey}/editmeta

resource-wide template parameters
parametervaluedescription

issueIdOrKey

string

the issue whose edit meta data you want to view

Methods

GET 

Returns the meta data for editing an issue.

The fields in the editmeta correspond to the fields in the edit screen for the issue. Fields not in the screen will not be in the editemeta.

available response representations:

  • 200 - application/json [expand]

    Example
    {"fields":{"summary":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My Multi Select","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue"]}}}

    Returns a response containing a Map of FieldBeans for fields editable by the current user.

  • 404 [expand]

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

/rest/api/2/issue/{issueIdOrKey}/notify

resource-wide template parameters
parametervaluedescription

issueIdOrKey

string

a string containing the issue id or key the comment will be added to

Methods

POST 

Sends a notification (email) to the list or recipients defined in the request.

acceptable request representations:

  • application/json [expand]

    Example
    {"subject":"Duis eu justo eget augue iaculis fermentum.","textBody":"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.","htmlBody":"Lorem ipsum <strong>dolor</strong> 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.","to":{"reporter":false,"assignee":false,"watchers":true,"voters":true,"users":[{"name":"fred","active":false}],"groups":[{"name":"notification-group","self":"http://www.example.com/jira/rest/api/2/group?groupname=notification-group"}]},"restrict":{"groups":[{"name":"notification-group","self":"http://www.example.com/jira/rest/api/2/group?groupname=notification-group"}],"permissions":[{"id":"10","key":"BROWSE"}]}}

available response representations:

  • 204 [expand]

    Returned if adding to the mail queue was successful

  • 400 [expand]

    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).

  • 403 [expand]

    Returned is outgoing emails are disabled OR no SMTP server is defined.

/rest/api/2/issue/{issueIdOrKey}/remotelink

resource-wide template parameters
parametervaluedescription

issueIdOrKey

string

the issue to create the remote issue link for

Methods

GET 

/rest/api/2/issue/{issueIdOrKey}/remotelink?globalId

A REST sub-resource representing the remote issue links on the issue.

request query parameters
parametervaluedescription

globalId

string

The id of the remote issue link to be returned. If null (not provided) all remote links for the issue are returned.

For a fullexplanation of Issue Link fields please refer to https://developer.atlassian.com/display/JIRADEV/Fields+in+Remote+Issue+Links

available response representations:

  • 200 - application/json [expand]

    Example
    [{"id":10000,"self":"http://www.example.com/jira/rest/api/issue/MKY-1/remotelink/10000","globalId":"system=http://www.mycompany.com/support&id=1","application":{"type":"com.acme.tracker","name":"My Acme Tracker"},"relationship":"causes","object":{"url":"http://www.mycompany.com/support?id=1","title":"TSTSUP-111","summary":"Crazy customer support issue","icon":{"url16x16":"http://www.mycompany.com/support/ticket.png","title":"Support Ticket"},"status":{"resolved":true,"icon":{"url16x16":"http://www.mycompany.com/support/resolved.png","title":"Case Closed","link":"http://www.mycompany.com/support?id=1&details=closed"}}}},{"id":10001,"self":"http://www.example.com/jira/rest/api/issue/MKY-1/remotelink/10001","globalId":"system=http://www.anothercompany.com/tester&id=1234","application":{"type":"com.acme.tester","name":"My Acme Tester"},"relationship":"is tested by","object":{"url":"http://www.anothercompany.com/tester/testcase/1234","title":"Test Case #1234","summary":"Test that the submit button saves the thing","icon":{"url16x16":"http://www.anothercompany.com/tester/images/testcase.gif","title":"Test Case"},"status":{"resolved":false,"icon":{"url16x16":"http://www.anothercompany.com/tester/images/person/fred.gif","title":"Tested by Fred Jones","link":"http://www.anothercompany.com/tester/person?username=fred"}}}}]

    Information on the remote issue links for the current issue.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to view the remote issue links, or if issue linking is disabled.

  • 404 [expand]

    Returned if the issue or remote issue link do not exist.

POST 

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

acceptable request representations:

  • application/json [expand]

    Example
    {"globalId":"system=http://www.mycompany.com/support&id=1","application":{"type":"com.acme.tracker","name":"My Acme Tracker"},"relationship":"causes","object":{"url":"http://www.mycompany.com/support?id=1","title":"TSTSUP-111","summary":"Crazy customer support issue","icon":{"url16x16":"http://www.mycompany.com/support/ticket.png","title":"Support Ticket"},"status":{"resolved":true,"icon":{"url16x16":"http://www.mycompany.com/support/resolved.png","title":"Case Closed","link":"http://www.mycompany.com/support?id=1&details=closed"}}}}

available response representations:

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

    Example
    {"id":10000,"self":"http://www.example.com/jira/rest/api/issue/MKY-1/remotelink/10000"}

    Returns a link to the created/updated remote issue link.

  • 400 [expand]

    Example
    {"errorMessages":[],"errors":{"title":"'title' is required."}}

    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to create/update the remote issue link, or if issue linking is disabled.

DELETE 

/rest/api/2/issue/{issueIdOrKey}/remotelink?globalId

Delete the remote issue link with the given global id on the issue.

request query parameters
parametervaluedescription

globalId

string

the global id of the remote issue link

available response representations:

  • 204 [expand]

    Returned if the remote issue link was removed successfully.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to delete the remote issue link, or if issue linking is disabled.

  • 404 [expand]

    Returned if the issue or remote issue link do not exist.

/rest/api/2/issue/{issueIdOrKey}/remotelink/{linkId}

resource-wide template parameters
parametervaluedescription

issueIdOrKey

string

the issue to create the remote issue link for

linkId

string

the id of the remote issue link

Methods

GET 

Get the remote issue link with the given id on the issue.

available response representations:

  • 200 - application/json [expand]

    Example
    {"id":10000,"self":"http://www.example.com/jira/rest/api/issue/MKY-1/remotelink/10000","globalId":"system=http://www.mycompany.com/support&id=1","application":{"type":"com.acme.tracker","name":"My Acme Tracker"},"relationship":"causes","object":{"url":"http://www.mycompany.com/support?id=1","title":"TSTSUP-111","summary":"Crazy customer support issue","icon":{"url16x16":"http://www.mycompany.com/support/ticket.png","title":"Support Ticket"},"status":{"resolved":true,"icon":{"url16x16":"http://www.mycompany.com/support/resolved.png","title":"Case Closed","link":"http://www.mycompany.com/support?id=1&details=closed"}}}}

    Information on the remote issue link with the given id.

  • 400 [expand]

    Returned if the linkId is not a valid number, or if the remote issue link with the given id does not belong to the given issue.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to view the remote issue link, or if issue linking is disabled.

  • 404 [expand]

    Returned if the issue or remote issue link do not exist.

PUT 

Updates a remote issue link from a JSON representation. Any fields not provided are set to null.

acceptable request representations:

  • application/json [expand]

    Example
    {"globalId":"system=http://www.mycompany.com/support&id=1","application":{"type":"com.acme.tracker","name":"My Acme Tracker"},"relationship":"causes","object":{"url":"http://www.mycompany.com/support?id=1","title":"TSTSUP-111","summary":"Crazy customer support issue","icon":{"url16x16":"http://www.mycompany.com/support/ticket.png","title":"Support Ticket"},"status":{"resolved":true,"icon":{"url16x16":"http://www.mycompany.com/support/resolved.png","title":"Case Closed","link":"http://www.mycompany.com/support?id=1&details=closed"}}}}

available response representations:

  • 204 [expand]

    Returned if the remote issue link was updated successfully.

  • 400 [expand]

    Example
    {"errorMessages":[],"errors":{"title":"'title' is required."}}

    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to update the remote issue link, or if issue linking is disabled.

DELETE 

Delete the remote issue link with the given id on the issue.

available response representations:

  • 204 [expand]

    Returned if the remote issue link was removed successfully.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to delete the remote issue link, or if issue linking is disabled.

  • 404 [expand]

    Returned if the issue or remote issue link do not exist.

/rest/api/2/issue/{issueIdOrKey}/transitions

resource-wide template parameters
parametervaluedescription

issueIdOrKey

string

the issue you want to transition

Methods

GET 

/rest/api/2/issue/{issueIdOrKey}/transitions?transitionId

Get a list of the transitions possible for this issue by the current user, along with fields that are required and their types.

Fields will only be returned if expand=transitions.fields.

The fields in the metadata correspond to the fields in the transition screen for that transition. Fields not in the screen will not be in the metadata.

request query parameters
parametervaluedescription

transitionId

string

available response representations:

  • 200 - application/json [expand]

    Example
    {"expand":"transitions","transitions":[{"id":"2","name":"Close Issue","to":{"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","statusCategory":{"self":"http://localhost:8090/jira/rest/api/2.0/statuscategory/1","id":1,"key":"in-flight","colorName":"yellow","name":"In Progress"}},"fields":{"summary":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My Multi Select","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue"]}}},{"id":"711","name":"QA Review","to":{"self":"http://localhost:8090/jira/rest/api/2.0/status/5","description":"The issue is closed.","iconUrl":"http://localhost:8090/jira/images/icons/closed.gif","name":"Closed","id":"5","statusCategory":{"self":"http://localhost:8090/jira/rest/api/2.0/statuscategory/9","id":9,"key":"completed","colorName":"green"}},"fields":{"colour":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My Multi Select","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue"]},"summary":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My Multi Select","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue"]}}}]}

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

  • 404 [expand]

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

POST 

Perform a transition on an issue. When performing the transition you can udate or set other issue fields.

The fields that can be set on transtion, in either the fields parameter or the update parameter can be determined using the /rest/api/2/issue/{issueIdOrKey}/transitions?expand=transitions.fields resource. If a field is not configured to appear on the transition screen, then it will not be in the transition metadata, and a field validation error will occur if it is submitted.

acceptable request representations:

  • application/json [expand]

    Example
    {"update":{"comment":[{"add":{"body":"Bug has been fixed."}}]},"fields":{"assignee":{"name":"bob"},"resolution":{"name":"Fixed"}},"transition":{"id":"5"},"historyMetadata":{"type":"myplugin:type","description":"text description","descriptionKey":"plugin.changereason.i18.key","activityDescription":"text description","activityDescriptionKey":"plugin.activity.i18.key","actor":{"id":"tony","displayName":"Tony","type":"mysystem-user","avatarUrl":"http://mysystem/avatar/tony.jpg","url":"http://mysystem/users/tony"},"generator":{"id":"mysystem-1","type":"mysystem-application"},"cause":{"id":"myevent","type":"mysystem-event"},"extraData":{"keyvalue":"extra data","goes":"here"}}}

available response representations:

  • 204 [expand]

    Returned if the transition was successful.

  • 400 [expand]

    If there is no transition specified.

  • 404 [expand]

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

/rest/api/2/issue/{issueIdOrKey}/votes

resource-wide template parameters
parametervaluedescription

issueIdOrKey

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.

available response representations:

  • 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/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false}]}

    Information about voting on the current issue.

  • 404 [expand]

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

/rest/api/2/issue/{issueIdOrKey}/watchers

resource-wide template parameters
parametervaluedescription

issueIdOrKey

string

a String containing an issue key.

Methods

GET 

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

available response representations:

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

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

  • 404 [expand]

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

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.

  • 400 [expand]

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

  • 401 [expand]

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

  • 404 [expand]

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

DELETE 

/rest/api/2/issue/{issueIdOrKey}/watchers?username

Removes a user from an issue's watcher list.

request query parameters
parametervaluedescription

username

string

a String containing the name of the user to remove from the watcher list. Must not be null.

available response representations:

  • 204 [expand]

    Returned if the watcher was removed successfully.

  • 400 [expand]

    Returned if a user name query parameter is not supplied.

  • 401 [expand]

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

  • 404 [expand]

    Returned if either the issue does not exist.

/rest/api/2/issue/{issueIdOrKey}/worklog

resource-wide template parameters
parametervaluedescription

issueIdOrKey

string

a string containing the issue id or key the worklog will be added to

Methods

GET 

Returns all work logs for an issue.

available response representations:

  • 200 - application/json [expand]

    Example
    {"startAt":0,"maxResults":1,"total":1,"worklogs":[{"self":"http://www.example.com/jira/rest/api/2/issue/10010/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":"2016-03-03T09:32:02.251+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028"}]}

    returns a collection of worklogs associated with the issue, with count and pagination information.

  • 404 [expand]

    Returned if the issue with the given id/key does not exist or if the currently authenticated user does not have permission to view it.

POST 

/rest/api/2/issue/{issueIdOrKey}/worklog?adjustEstimate&newEstimate&reduceBy

Adds a new worklog entry to an issue.

request query parameters
parametervaluedescription

adjustEstimate

string

(optional) allows you to provide specific instructions to update the remaining time estimate of the issue. Valid values are

  • "new" - sets the estimate to a specific value
  • "leave"- leaves the estimate as is
  • "manual" - specify a specific amount to increase remaining estimate by
  • "auto"- Default option. Will automatically adjust the value based on the new timeSpent specified on the worklog

newEstimate

string

(required when "new" is selected for adjustEstimate) the new value for the remaining estimate field. e.g. "2d"

reduceBy

string

(required when "manual" is selected for adjustEstimate) the amount to reduce the remaining estimate by e.g. "2d"

acceptable request representations:

  • application/json [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2/issue/10010/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":"2016-03-03T09:32:02.251+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028"}

available response representations:

  • 201 [expand]

    Returned if add was successful

  • 400 [expand]

    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).

  • 403 [expand]

    Returned if the calling user does not have permission to add the worklog

/rest/api/2/issue/{issueIdOrKey}/worklog/{id}

resource-wide template parameters
parametervaluedescription

id

string

id of the worklog to be deleted

issueIdOrKey

string

a string containing the issue id or key the worklog belongs to

Methods

GET 

Returns a specific worklog.

available response representations:

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

    Example
    {"self":"http://www.example.com/jira/rest/api/2/issue/10010/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":"2016-03-03T09:32:02.251+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028"}

    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.

  • 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.

PUT 

/rest/api/2/issue/{issueIdOrKey}/worklog/{id}?adjustEstimate&newEstimate

Updates an existing worklog entry using its JSON representation.

request query parameters
parametervaluedescription

adjustEstimate

string

(optional) allows you to provide specific instructions to update the remaining time estimate of the issue. Valid values are

  • "new" - sets the estimate to a specific value
  • "leave"- leaves the estimate as is
  • "auto"- Default option. Will automatically adjust the value based on the new timeSpent specified on the worklog

newEstimate

string

(required when "new" is selected for adjustEstimate) the new value for the remaining estimate field.

acceptable request representations:

  • application/json [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2/issue/10010/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":"2016-03-03T09:32:02.251+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028"}

available response representations:

  • 200 [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2/issue/10010/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":"2016-03-03T09:32:02.251+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028"}

    Returned if update was successful

  • 400 [expand]

    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).

  • 403 [expand]

    Returned if the calling user does not have permission to update the worklog

DELETE 

/rest/api/2/issue/{issueIdOrKey}/worklog/{id}?adjustEstimate&newEstimate&increaseBy

Deletes an existing worklog entry .

request query parameters
parametervaluedescription

adjustEstimate

string

(optional) allows you to provide specific instructions to update the remaining time estimate of the issue. Valid values are

  • "new" - sets the estimate to a specific value
  • "leave"- leaves the estimate as is
  • "manual" - specify a specific amount to increase remaining estimate by
  • "auto"- Default option. Will automatically adjust the value based on the new timeSpent specified on the worklog

newEstimate

string

(required when "new" is selected for adjustEstimate) the new value for the remaining estimate field. e.g. "2d"

increaseBy

string

(required when "manual" is selected for adjustEstimate) the amount to increase the remaining estimate by e.g. "2d"

available response representations:

  • 204 [expand]

    Returned if delete was successful

  • 400 [expand]

    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).

  • 403 [expand]

    Returned if the calling user does not have permission to delete the worklog

/rest/api/2/issue/createmeta

Methods

GET 

/rest/api/2/issue/createmeta?projectIds&projectKeys&issuetypeIds&issuetypeNames

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.

The fields in the createmeta correspond to the fields in the create screen for the project/issuetype. Fields not in the screen will not be in the createmeta.

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
parametervaluedescription

projectIds

string

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

string

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

string

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

string

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:

  • 200 - application/json [expand]

    Example
    {"expand":"projects","projects":[{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example Project","avatarUrls":{"24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000&avatarId=10011","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000&avatarId=10011","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&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","description":"An error in the code","iconUrl":"http://www.example.com/jira/images/icons/issuetypes/bug.png","name":"Bug","subtask":false,"fields":{"issuetype":{"required":true,"name":"Issue Type","hasDefaultValue":false,"operations":["set"]}}}]}]}

    Returns the meta data for creating issues.

  • 403 [expand]

    Returned if the user does not have permission to view any of the requested projects.

/rest/api/2/issue/picker

Methods

GET 

/rest/api/2/issue/picker?query&currentJQL&currentIssueKey&currentProjectId&showSubTasks&showSubTaskParent

Returns suggested issues which match the auto-completion query for the user which executes this request. This REST method will check the user's history and the user's browsing context and select this issues, which match the query.

request query parameters
parametervaluedescription

query

string

the query.

currentJQL

string

the JQL in context of which the request is executed. Only issues which match this JQL query will be included in results.

currentIssueKey

string

the key of the issue in context of which the request is executed. The issue which is in context will not be included in the auto-completion result, even if it matches the query.

currentProjectId

string

the id of the project in context of which the request is executed. Suggested issues will be only from this project.

showSubTasks

boolean

if set to false, subtasks will not be included in the list.

showSubTaskParent

boolean

if set to false and request is executed in context of a subtask, the parent issue will not be included in the auto-completion result, even if it matches the query.

available response representations:

  • 200 - application/json [expand]

    Returns a list of issues which match the picker parameters.

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

Issue attachments

resource-wide template parameters
parametervaluedescription

issueIdOrKey

string

the issue that you want to add the attachments to

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.

The name of the multipart/form-data parameter that contains attachments must be "file"

A simple example to upload a file called "myfile.txt" to issue REST-123: 

curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt" http://myhost/rest/api/2/issue/TEST-123/attachments

available response representations:

  • 200 - application/json [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/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"created":"2016-03-03T09:32:02.244+0000","size":23123,"mimeType":"image/jpeg","content":"http://www.example.com/jira/attachments/10000","thumbnail":"http://www.example.com/jira/secure/thumbnail/10000"},{"self":"http://www.example.com/jira/rest/api/2.0/attachments/10001","filename":"dbeuglog.txt","author":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"created":"2016-03-03T09:32:02.244+0000","size":2460,"mimeType":"text/plain","content":"http://www.example.com/jira/attachments/10001","thumbnail":"http://www.example.com/jira/secure/thumbnail/10002"}]

  • 403 [expand]

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

  • 404 [expand]

    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.

/rest/api/2/issue/{issueIdOrKey}/properties

resource-wide template parameters
parametervaluedescription

issueIdOrKey

string

the issue from which keys will be returned.

Methods

GET  (experimental)

Returns the keys of all properties for the issue identified by the key or by the id.

available response representations:

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

    Example
    {"keys":[{"self":"http://www.example.com/jira/rest/api/2/issue/EX-2/properties/issue.support","key":"issue.support"}]}

    Returned if the issue was found.

  • 400 [expand]

    Returned if the issue key or id is invalid.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to view the issue.

  • 404 [expand]

    Returned if the issue with given key or id does not exist or if the property with given key is not found.

/rest/api/2/issue/{issueIdOrKey}/properties/{propertyKey}

resource-wide template parameters
parametervaluedescription

issueIdOrKey

string

the issue from which keys will be returned.

issueIdOrKey

string

the issue from which the property will be removed.

propertyKey

string

the key of the property to remove.

Methods

PUT  (experimental)

Sets the value of the specified issue's property.

You can use this resource to store a custom data against the issue identified by the key or by the id. The user who stores the data is required to have permissions to edit the issue.

available response representations:

  • 200 [expand]

    Returned if the issue property is successfully updated.

  • 201 [expand]

    Returned if the issue property is successfully created.

  • 400 [expand]

    Returned if the issue key or id is invalid.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to edit the issue.

  • 404 [expand]

    Returned if the issue with given key or id does not exist.

GET  (experimental)

Returns the value of the property with a given key from the issue identified by the key or by the id. The user who retrieves the property is required to have permissions to read the issue.

available response representations:

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

    Example
    {"key":"issue.support","value":{}}

    Returned if the issue property was found.

  • 400 [expand]

    Returned if the issue key or id is invalid.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to view the issue.

  • 404 [expand]

    Returned if the issue with given key or id does not exist or if the property with given key is not found.

DELETE  (experimental)

Removes the property from the issue identified by the key or by the id. Ths user removing the property is required to have permissions to edit the issue.

available response representations:

  • 204 [expand]

    Returned if the issue property was removed successfully.

  • 400 [expand]

    Returned if the issue key or id is invalid.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to edit the issue.

  • 404 [expand]

    Returned if the issue with given key or id does not exist or if the property with given key is not found.

/rest/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.

acceptable request representations:

  • application/json [expand]

    Example
    {"type":{"name":"Duplicate"},"inwardIssue":{"key":"HSP-1"},"outwardIssue":{"key":"MKY-1"},"comment":{"body":"Linked related issue!","visibility":{"type":"group","value":"jira-users"}}}

available response representations:

  • 200 - application/json [expand]

    if the issue link was created successfully.

  • 400 [expand]

    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.

  • 401 [expand]

    if the user does not have the link issue permission for the issue, which will be linked to another issue.

  • 404 [expand]

    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.

  • 500 [expand]

    if an error occurred when creating the issue link or the comment.

/rest/api/2/issueLink/{linkId}

resource-wide template parameters
parametervaluedescription

linkId

string

the issue link id.

Methods

GET 

Returns an issue link with the specified id.

available response representations:

  • 200 - application/json [expand]

    Example
    {"id":"10001","type":{"id":"1000","name":"Duplicate","inward":"Duplicated by","outward":"Duplicates","self":"http://www.example.com/jira/rest/api/2//issueLinkType/1000"},"inwardIssue":{"id":"10004","key":"PRJ-3","self":"http://www.example.com/jira/rest/api/2/issue/PRJ-3","fields":{"status":{"iconUrl":"http://www.example.com/jira//images/icons/statuses/open.png","name":"Open"}}},"outwardIssue":{"id":"10004L","key":"PRJ-2","self":"http://www.example.com/jira/rest/api/2/issue/PRJ-2","fields":{"status":{"iconUrl":"http://www.example.com/jira//images/icons/statuses/open.png","name":"Open"}}}}

  • 400 [expand]

    If the specified issue link id is invalid.

  • 401 [expand]

    if the user does not have the link issue permission for the issue, which will be linked to another issue.

  • 404 [expand]

    If issue linking is disabled or it failed to find an issue link with the specified id. Either because none exists with this id, or the user doesn't have the permission to see one of the linked issues.

  • 500 [expand]

    if an error occurred when creating the issue link or the comment.

DELETE 

Deletes an issue link with the specified id. To be able to delete an issue link you must be able to view both issues and must have the link issue permission for at least one of the issues.

available response representations:

  • 200 - application/json [expand]
  • 204 [expand]

    If it successfully deleted the issue link.

  • 400 [expand]

    If the specified issue link id is invalid.

  • 401 [expand]

    if the user does not have the link issue permission for the source or destination issue of the issue link.

  • 404 [expand]

    If issue linking is disabled or it failed to find an issue link with the specified id. Either because none exists with this id, or the user doesn't have the permission to see one of the linked issues.

  • 500 [expand]

    if an error occurred when deleting the issue link or the comment.

/rest/api/2/issueLinkType

Rest resource to retrieve a list of issue link types.

Methods

GET 

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:

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

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

  • 404 [expand]

    Returned if issue linking is disabled.

POST 

Create a new issue link type.

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"Duplicate","inward":"Duplicated by","outward":"Duplicates"}

available response representations:

  • 201 - application/json (issueLinkType) [expand]

    Example
    {"id":"1000","name":"Duplicate","inward":"Duplicated by","outward":"Duplicates","self":"http://www.example.com/jira/rest/api/2//issueLinkType/1000"}

    The new issue link type has been created.

  • 404 [expand]

    Issue linking is disabled or you do not have permission to create issue link types.

/rest/api/2/issueLinkType/{issueLinkTypeId}

resource-wide template parameters
parametervaluedescription

issueLinkTypeId

string

Methods

GET 

Returns for a given issue link type id all information about this issue link type.

available response representations:

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

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

  • 404 [expand]

    Returned if issue linking is disabled or no issue link type with the given id exists.

DELETE 

Delete the specified issue link type.

available response representations:

  • 204 (issueLinkType) [expand]
  • 404 [expand]

    Returned if issue linking is disabled or no issue link type with the given id exists.

PUT 

Update the specified issue link type.

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"Duplicate","inward":"Duplicated by","outward":"Duplicates"}

available response representations:

  • 200 [expand]

    Example
    {"id":"1000","name":"Duplicate","inward":"Duplicated by","outward":"Duplicates","self":"http://www.example.com/jira/rest/api/2//issueLinkType/1000"}

  • 400 [expand]

    Returned if the supplied id is not a number.

  • 404 [expand]

    Returned if issue linking is disabled or no issue link type with the given id exists.

/rest/api/2/issuetype

Methods

POST 

Creates an issue type from a JSON representation and adds the issue newly created issue type to the default issue type scheme.

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"name","description":"description","type":"standard"}

available response representations:

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

    Returned if the issue type was successfully created.

  • 400 [expand]

    Returned if the request is invalid. This happens when the name is invalid or issue type is subtask on instance which has subtasks disabled.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to administer JIRA.

  • 409 [expand]

    Returned if there already exists an issue type with the specified name.

GET 

Returns a list of all issue types visible to the user

available response representations:

  • 200 - application/json [expand]

    Example
    [{"self":"http://localhost:8090/jira/rest/api/2.0/issueType/3","id":"3","description":"A task that needs to be done.","iconUrl":"http://localhost:8090/jira/images/icons/issuetypes/task.png","name":"Task","subtask":false,"avatarId":1},{"self":"http://localhost:8090/jira/rest/api/2.0/issueType/1","id":"1","description":"A problem with the software.","iconUrl":"http://localhost:8090/jira/images/icons/issuetypes/bug.png","name":"Bug","subtask":false,"avatarId":10002}]

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

/rest/api/2/issuetype/{id}

resource-wide template parameters
parametervaluedescription

id

string

the id of the issue type to update.

Methods

GET 

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

available response representations:

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

    Example
    {"self":"http://localhost:8090/jira/rest/api/2.0/issueType/3","id":"3","description":"A task that needs to be done.","iconUrl":"http://localhost:8090/jira/images/icons/issuetypes/task.png","name":"Task","subtask":false,"avatarId":1}

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

  • 404 [expand]

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

DELETE 

/rest/api/2/issuetype/{id}?alternativeIssueTypeId

Deletes the specified issue type. If the issue type has any associated issues, these issues will be migrated to the alternative issue type specified in the parameter. You can determine the alternative issue types by calling the /rest/api/2/issuetype/{id}/alternatives resource.

request query parameters
parametervaluedescription

alternativeIssueTypeId

string

the id of an issue type to which issues associated with the removed issue type will be migrated.

available response representations:

  • 204 - application/json [expand]

    Returned if the issue type was successfully removed.

  • 400 [expand]

    Returned if the request is invalid. It happens when there are associated issues with the issue type which is being removed, but it is impossible to migrate these issues to the alternative issue type.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to administer JIRA.

  • 404 [expand]

    Returned if the issue type which is supposed to be removed does not exist or the alternative issue type does not exist.

PUT 

Updates the specified issue type from a JSON representation.

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"name","description":"description","avatarId":1}

available response representations:

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

    Returned if the issue type was successfully updated.

  • 400 [expand]

    Returned if the request is invalid. This happens when the name is invalid or if the avatar with given id does not exist.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to administer JIRA.

  • 404 [expand]

    Returned if the issue type to update does not exist.

  • 409 [expand]

    Returned if there already exists an issue type with the specified name.

/rest/api/2/issuetype/{id}/alternatives

resource-wide template parameters
parametervaluedescription

id

string

Methods

GET 

Returns a list of all alternative issue types for the given issue type id. The list will contain these issues types, to which issues assigned to the given issue type can be migrated. The suitable alternatives are issue types which are assigned to the same workflow, the same field configuration and the same screen scheme.

available response representations:

  • 200 - application/json [expand]

    Example
    [{"self":"http://localhost:8090/jira/rest/api/2.0/issueType/3","id":"3","description":"A task that needs to be done.","iconUrl":"http://localhost:8090/jira/images/icons/issuetypes/task.png","name":"Task","subtask":false,"avatarId":1},{"self":"http://localhost:8090/jira/rest/api/2.0/issueType/1","id":"1","description":"A problem with the software.","iconUrl":"http://localhost:8090/jira/images/icons/issuetypes/bug.png","name":"Bug","subtask":false,"avatarId":10002}]

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

  • 404 [expand]

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

/rest/api/2/issuetype/{id}/avatar

resource-wide template parameters
parametervaluedescription

id

string

the id of the issue type, which avatar is updated.

Methods

POST 

Converts temporary avatar into a real avatar

acceptable request representations:

  • application/json [expand]

    Example
    {"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"needsCropping":false}

available response representations:

  • 201 - application/json (avatar) [expand]

    Example
    {"id":"1000","owner":"fred","isSystemAvatar":true,"isSelected":false,"urls":{"16x16":"http://localhost:8090/jira/secure/useravatar?size=xsmall&avatarId=10040","24x24":"http://localhost:8090/jira/secure/useravatar?size=small&avatarId=10040","32x32":"http://localhost:8090/jira/secure/useravatar?size=medium&avatarId=10040","48x48":"http://localhost:8090/jira/secure/useravatar?avatarId=10040"},"selected":false}

    Returns created avatar

  • 400 [expand]

    Returned if the cropping coordinates are invalid

  • 403 [expand]

    Returned if the currently authenticated user does not have permission to pick avatar

  • 404 [expand]

    Returned if the currently authenticated user does not have EDIT PROJECT permission.

  • 500 [expand]

    Returned if an error occurs while converting temporary avatar to real avatar

/rest/api/2/issuetype/{id}/avatar/temporary

resource-wide template parameters
parametervaluedescription

id

string

the id of the issue type, which avatar is updated.

Methods

POST 

/rest/api/2/issuetype/{id}/avatar/temporary?filename&size

Creates temporary avatar. Creating a temporary avatar is part of a 3-step process in uploading a new avatar for an issue type: upload, crop, confirm.

The following examples shows these three steps using curl. The cookies (session) need to be preserved between requests, hence the use of -b and -c. The id created in step 2 needs to be passed to step 3 (you can simply pass the whole response of step 2 as the request of step 3). 

 curl -c cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \
   -H "Content-Type: image/png" --data-binary @mynewavatar.png \
   'http://localhost:8090/jira/rest/api/2/issuetype/1/avatar/temporary?filename=mynewavatar.png'

 curl -b cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \
   -H "Content-Type: application/json" --data '{"cropperWidth": "65","cropperOffsetX": "10","cropperOffsetY": "16"}' \
   -o tmpid.json \
   http://localhost:8090/jira/rest/api/2/issuetype/1/avatar

 curl -b cookiejar.txt -X PUT -u admin:admin -H "X-Atlassian-Token: no-check" \
   -H "Content-Type: application/json" --data-binary @tmpid.json \
   http://localhost:8090/jira/rest/api/2/issuetype/1/avatar

request query parameters
parametervaluedescription

filename

string

name of file being uploaded

size

long

size of file

available response representations:

  • 201 - application/json (avatar) [expand]

    Example
    {"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}

    temporary avatar cropping instructions

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to administer JIRA.

  • 404 [expand]

    Returned if the issue type to update does not exist or if the request does not contain valid XSRF token.

POST 

Creates temporary avatar using multipart. The response is sent back as JSON stored in a textarea. This is because the client uses remote iframing to submit avatars using multipart. So we must send them a valid HTML page back from which the client parses the JSON from.

Creating a temporary avatar is part of a 3-step process in uploading a new avatar for an issue type: upload, crop, confirm. This endpoint allows you to use a multipart upload instead of sending the image directly as the request body.

You *must* use "avatar" as the name of the upload parameter:

 curl -c cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \
   -F "avatar=@mynewavatar.png;type=image/png" \
   'http://localhost:8090/jira/rest/api/2/issuetype/1/avatar/temporary'

available response representations:

  • 201 - text/html (avatar) [expand]

    Example
    {"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}

    temporary avatar cropping instructions embeded in HTML page. Error messages will also be embeded in the page.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to administer JIRA.

  • 404 [expand]

    Returned if the issue type to update does not exist or if the request does not contain valid XSRF token.

/rest/api/2/jql/autocompletedata

Resource for auto complete data for searches.

Methods

GET 

Returns the auto complete data required for JQL searches.

available response representations:

  • 200 - application/json [expand]

    Example
    "{\"visibleFieldNames\": [{\"value\":\"affectedVersion\",\"displayName\":\"affectedVersion\",\"auto\":\"true\",\"orderable\":\"true\",\"searchable\":\"true\",\"operators\":[\"=\",\"!=\",\"in\",\"not in\",\"is\",\"is not\",\"<\",\"<=\",\">\",\">=\"],\"types\":[\"com.atlassian.jira.project.version.Version\"]},{\"value\":\"assignee\",\"displayName\":\"assignee\",\"auto\":\"true\",\"orderable\":\"true\",\"searchable\":\"true\",\"operators\":[\"!=\",\"was not in\",\"not in\",\"was not\",\"is\",\"was in\",\"was\",\"=\",\"in\",\"changed\",\"is not\"],\"types\":[\"com.atlassian.crowd.embedded.api.User\"]}],\"visibleFunctionNames\": {\"value\":\"currentLogin()\",\"displayName\":\"currentLogin()\",\"types\":[\"java.util.Date\"]},{\"value\":\"currentUser()\",\"displayName\":\"currentUser()\",\"types\":[\"com.atlassian.crowd.embedded.api.User\"]}],\"jqlReservedWords\": \"empty\",\"and\",\"or\",\"in\",\"distinct\"]}"

    The auto complete data required for JQL searches.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 500 [expand]

    Returned if an error occurs while generating the response.

/rest/api/2/jql/autocompletedata/suggestions

Methods

GET 

/rest/api/2/jql/autocompletedata/suggestions?fieldName&fieldValue&predicateName&predicateValue

Returns auto complete suggestions for JQL search.

request query parameters
parametervaluedescription

fieldName

string

the field name for which the suggestions are generated.

fieldValue

string

the portion of the field value that has already been provided by the user.

predicateName

string

the predicate for which the suggestions are generated. Suggestions are generated only for: "by", "from" and "to".

predicateValue

string

the portion of the predicate value that has already been provided by the user.

available response representations:

  • 200 - application/json [expand]

    Example
    {"results":[{"value":"ActiveObjects","displayName":"<b>Ac</b>tiveObjects (AO)"},{"value":"Atlassian Connect","displayName":"Atlassian Connect (<b>AC</b>)"},{"value":"Atlassian Connect in JIRA","displayName":"Atlassian Connect in JIRA (<b>AC</b>JIRA)"}]}

    The autocompletion suggestions for JQL search.

/rest/api/2/licenserole

Provides REST access to JIRA's License Roles.

Methods

GET 

Returns all license roles in the system.

available response representations:

  • 200 - application/json [expand]

    Example
    [{"id":"user","groups":["admins","users"],"name":"User for JIRA","primaryGroup":"users"},{"id":"admin","groups":["admins"],"name":"Admin for JIRA","primaryGroup":"admins"}]

    Returned when the caller has permission to see the license roles.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 403 [expand]

    Returned if the user does not have permission to see license roles.

/rest/api/2/licenserole/{roleId}

resource-wide template parameters
parametervaluedescription

roleId

string

the id of the role to use.

Methods

GET 

Returns the passed license role if it exists.

available response representations:

  • 200 - application/json [expand]

    Example
    {"id":"user","groups":["admins","users"],"name":"User for JIRA","primaryGroup":"users"}

    Returned if the caller has permission to the license role.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 403 [expand]

    Returned if the user does not have permission to see the license role.

  • 404 [expand]

    Returned if the passed license role does not exist.

PUT 

Updates the license role with the passed data. Only the groups of the role may be updated. Requests to change the id or the name of the role will be silently ignored.

acceptable request representations:

  • application/json [expand]

    Example
    {"groups":["admins","user"],"primaryGroup":"user"}

available response representations:

  • 200 - application/json [expand]

    Example
    {"id":"user","groups":["admins","users"],"name":"User for JIRA","primaryGroup":"users"}

    Returned if the caller has permission to update license role.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 403 [expand]

    Returned if the user does not have permission to update the license role.

  • 404 [expand]

    Returned if the passed license role does not exist.

/rest/api/2/licenseValidator

A REST endpoint to provide simple validation services for a JIRA license. Typically used by the setup phase of the JIRA application. This will return an object with a list of errors as key, value pairs.

Methods

POST 

acceptable request representations:

available response representations:

/rest/api/2/mypermissions

Provide permission information for the current user.

Methods

GET 

/rest/api/2/mypermissions?projectKey&projectId&issueKey&issueId

Returns all permissions in the system and whether the currently logged in user has them. You can optionally provide a specific context to get permissions for (projectKey OR projectId OR issueKey OR issueId)

  • When no context supplied the project related permissions will return true if the user has that permission in ANY project
  • If a project context is provided, project related permissions will return true if the user has the permissions in the specified project. For permissions that are determined using issue data (e.g Current Assignee), true will be returned if the user meets the permission criteria in ANY issue in that project
  • If an issue context is provided, it will return whether or not the user has each permission in that specific issue

NB: The above means that for issue-level permissions (EDIT_ISSUE for example), hasPermission may be true when no context is provided, or when a project context is provided, but may be false for any given (or all) issues. This would occur (for example) if Reporters were given the EDIT_ISSUE permission. This is because any user could be a reporter, except in the context of a concrete issue, where the reporter is known.

Global permissions will still be returned for all scopes.

Prior to version 6.4 this service returned project permissions with keys corresponding to com.atlassian.jira.security.Permissions.Permission constants. Since 6.4 those keys are considered deprecated and this service returns system project permission keys corresponding to constants defined in com.atlassian.jira.permission.ProjectPermissions. Permissions with legacy keys are still also returned for backwards compatibility, they are marked with an attribute deprecatedKey=true. The attribute is missing for project permissions with the current keys.

request query parameters
parametervaluedescription

projectKey

string

- key of project to scope returned permissions for.

projectId

string

- id of project to scope returned permissions for.

issueKey

string

- key of the issue to scope returned permissions for.

issueId

string

- id of the issue to scope returned permissions for.

available response representations:

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

    Example
    {"permissions":{"EDIT_ISSUE":{"id":"12","key":"EDIT_ISSUES","name":"Edit Issues","type":"PROJECT","description":"Ability to edit issues.","havePermission":true}}}

    Returns a list of all permissions in JIRA and whether the user has them.

  • 400 [expand]

    Returned if the project or issue id is invalid.

  • 404 [expand]

    Returned if the project or issue id or key is not found.

/rest/api/2/mypreferences

Provide preferences of the currently logged in user.

Methods

GET 

/rest/api/2/mypreferences?key

Returns preference of the currently logged in user. Preference key must be provided as input parameter (key). The value is returned exactly as it is. If key parameter is not provided or wrong - status code 404. If value is found - status code 200.

request query parameters
parametervaluedescription

key

string

- key of the preference to be returned.

available response representations:

PUT 

/rest/api/2/mypreferences?key

Sets preference of the currently logged in user. Preference key must be provided as input parameters (key). Value must be provided as post body. If key or value parameter is not provided - status code 404. If preference is set - status code 204.

request query parameters
parametervaluedescription

key

string

- key of the preference to be set.

acceptable request representations:

available response representations:

DELETE 

/rest/api/2/mypreferences?key

Removes preference of the currently logged in user. Preference key must be provided as input parameters (key). If key parameter is not provided or wrong - status code 404. If preference is unset - status code 204.

request query parameters
parametervaluedescription

key

string

- key of the preference to be removed.

available response representations:

/rest/api/2/myself

Currently logged user resource

Methods

GET 

Returns currently logged user. This resource cannot be accessed anonymously.

available response representations:

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

    Example
    {"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&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","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-user"},{"name":"jira-admin","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-admin"},{"name":"important","self":"http://www.example.com/jira/rest/api/2/group?groupname=important"}]},"expand":"groups"}

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

  • 403 [expand]

    Returned if the current user is not authenticated.

  • 404 [expand]

    Returned if the the user could not be found.

PUT 

Modify currently logged user. The "value" fields present will override the existing value. Fields skipped in request will not be changed. Only email and display name can be change that way.

acceptable request representations:

  • application/json [expand]

    Example
    {"emailAddress":"eddie@atlassian.com","displayName":"Eddie of Atlassian"}

available response representations:

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

    Example
    {"self":"http://www.example.com/jirahttp://www.example.com/jira/rest/api/2/user/charlie","key":"charlie","name":"eddie","emailAddress":"eddie@atlassian.com","displayName":"Eddie of Atlassian"}

    Returned if the user exists and the caller has permission to edit it.

  • 400 [expand]

    Returned if the request is invalid.

  • 403 [expand]

    Returned if the current user is not authenticated.

  • 404 [expand]

    Returned if the the user could not be found.

/rest/api/2/myself/password

Methods

PUT 

Modify caller password.

acceptable request representations:

available response representations:

  • 204 [expand]

    Returned if the user exists and the caller has permission to edit it.

  • 403 [expand]

    Returned if the caller does not have permission to change the user password.

  • 404 [expand]

    Returned if the caller does have permission to change user password but the user does not exist.

REST resource for operations related to passwords and the password policy.

/rest/api/2/password/policy

Methods

GET 

/rest/api/2/password/policy?hasOldPassword

Returns user-friendly statements governing the system's password policy.

request query parameters
parametervaluedescription

hasOldPassword

boolean

Default: false

whether or not the user will be required to enter their current password. Use {@code false} (the default) if this is a new user or if an administrator is forcibly changing another user's password.

available response representations:

  • 200 - application/json [expand]

    Returns an array of message strings.

/rest/api/2/password/policy/createUser

Methods

POST 

Returns user-friendly explanations of why the password policy would disallow a proposed user from being created.

This is a "dry run" of the password policy validation that would be performed by the various user creation methods in {@link com.atlassian.jira.bc.user.UserService}. The intended use is for a user interface to verify the password on the fly as the user enters it (or upon moving to another input field or delaying for some time period, and so on). At the very least, the username and password must be non-empty to run these validations. Note that this validation is only for the password policy itself; other validations, such as whether or not a user with the same name already exists, are not checked by this request.

acceptable request representations:

  • application/json [expand]

    Example
    {"username":"fred","displayName":"Fred Normal","emailAddress":"fred@example.com","password":"secret"}

available response representations:

  • 200 - application/json [expand]

    Returns an array of message strings.

  • 400 [expand]

    Returned if the request is invalid, such as if the username or password is left unspecified.

/rest/api/2/password/policy/updateUser

Methods

POST 

Returns user-friendly explanations of why the password policy would disallow an existing user's password from being updated.

This is a "dry run" of the password policy validation that would be performed by the various ways to update a user's password, such as the {@link com.atlassian.jira.web.action.user.ChangePassword ChangePassword} and {@link com.atlassian.jira.web.action.user.ResetPassword ResetPassword} web actions. The intended use is for a user interface to verify the password on the fly as the user enters it (or upon moving to another input field or delaying for some time period, and so on). At the very least, the username and new password must be non-empty to run these validations, and the user must actually exist. Note that this validation is only for the password policy itself; other validations that would be performed upon submitting the request are not checked by this request. In particular, the old password (if specified) is deliberately not verified by this request, as doing so could cause security problems.

acceptable request representations:

  • application/json [expand]

    Example
    {"username":"fred","oldPassword":"secret","newPassword":"correcthorsebatterystaple"}

available response representations:

  • 200 - application/json [expand]

    Returns an array of message strings.

  • 400 [expand]

    Returned if the request is invalid, such as if the username or new password is left unspecified.

  • 404 [expand]

    Returned if the username does not correspond to any existing user.

/rest/api/2/priority

Methods

GET 

Returns a list of all issue priorities.

available response representations:

  • 200 - application/json (list of priorities) [expand]

    Example
    [{"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/priorities/major.png","name":"Major"},{"self":"http://www.example.com/jira/rest/api/2/priority/5","statusColor":"#cfcfcf","description":"Very little impact.","iconUrl":"http://www.example.com/jira/images/icons/priorities/trivial.png","name":"Trivial"}]

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

/rest/api/2/priority/{id}

resource-wide template parameters
parametervaluedescription

id

string

a String containing the priority id

Methods

GET 

Returns an issue priority.

available response representations:

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

    Example
    {"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/priorities/major.png","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.

  • 404 [expand]

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

/rest/api/2/project

Methods

GET 

/rest/api/2/project?expand

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.

request query parameters
parametervaluedescription

expand

string

the parameters to expand

available response representations:

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

    Example
    [{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},{"self":"http://www.example.com/jira/rest/api/2/project/ABC","id":"10001","key":"ABC","name":"Alphabetical","avatarUrls":{"24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10001","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10001","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10001","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10001"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}}]

    Returns a list of projects for which the user has the BROWSE, ADMINISTER or PROJECT_ADMIN project permission.

  • 500 [expand]

    Returned if an error occurs while retrieving the list of projects.

/rest/api/2/project/{projectIdOrKey}

resource-wide template parameters
parametervaluedescription

projectIdOrKey

string

the project id or project key

Methods

GET 

/rest/api/2/project/{projectIdOrKey}?expand

Contains a full representation of a project in JSON format.

All project keys associated with the project will only be returned if expand=projectKeys.

request query parameters
parametervaluedescription

expand

string

the parameters to expand

available response representations:

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

    Example
    {"expand":"description,lead,url,projectKeys","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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"isAssigneeTypeValid":false,"project":"HSP","projectId":10000}],"issueTypes":[{"self":"http://localhost:8090/jira/rest/api/2.0/issueType/3","id":"3","description":"A task that needs to be done.","iconUrl":"http://localhost:8090/jira/images/icons/issuetypes/task.png","name":"Task","subtask":false,"avatarId":1},{"self":"http://localhost:8090/jira/rest/api/2.0/issueType/1","id":"1","description":"A problem with the software.","iconUrl":"http://localhost:8090/jira/images/icons/issuetypes/bug.png","name":"Bug","subtask":false,"avatarId":10002}],"url":"http://www.example.com/jira/browse/EX","email":"from-jira@example.com","assigneeType":"PROJECT_LEAD","versions":[],"name":"Example","roles":{"Developers":"http://www.example.com/jira/rest/api/2/project/EX/role/10000"},"avatarUrls":{"24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10000","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10000","48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}}

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

  • 404 [expand]

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

/rest/api/2/project/{projectIdOrKey}/avatar

resource-wide template parameters
parametervaluedescription

projectIdOrKey

string

Methods

POST 

Converts temporary avatar into a real avatar

acceptable request representations:

  • application/json [expand]

    Example
    {"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"needsCropping":false}

available response representations:

  • 201 - application/json (avatar) [expand]

    Example
    {"id":"1000","owner":"fred","isSystemAvatar":true,"isSelected":false,"urls":{"16x16":"http://localhost:8090/jira/secure/useravatar?size=xsmall&avatarId=10040","24x24":"http://localhost:8090/jira/secure/useravatar?size=small&avatarId=10040","32x32":"http://localhost:8090/jira/secure/useravatar?size=medium&avatarId=10040","48x48":"http://localhost:8090/jira/secure/useravatar?avatarId=10040"},"selected":false}

    Returns created avatar

  • 400 [expand]

    Returned if the cropping coordinates are invalid

  • 403 [expand]

    Returned if the currently authenticated user does not have permission to pick avatar

  • 404 [expand]

    Returned if the currently authenticated user does not have EDIT PROJECT permission.

  • 500 [expand]

    Returned if an error occurs while converting temporary avatar to real avatar

PUT 

acceptable request representations:

available response representations:

/rest/api/2/project/{projectIdOrKey}/avatar/{id}

resource-wide template parameters
parametervaluedescription

id

long

database id for avatar

projectIdOrKey

string

Project id or project key

Methods

DELETE 

Deletes avatar

available response representations:

  • 204 - application/json [expand]

    Returned if the avatar is successfully deleted.

  • 403 [expand]

    Returned if the currently authenticated user does not have permission to delete the component.

  • 404 [expand]

    Returned if the avatar does not exist or the currently authenticated user does not have permission to delete it.

/rest/api/2/project/{projectIdOrKey}/avatar/temporary

resource-wide template parameters
parametervaluedescription

projectIdOrKey

string

Project id or project key

Methods

POST 

/rest/api/2/project/{projectIdOrKey}/avatar/temporary?filename&size

Creates temporary avatar

request query parameters
parametervaluedescription

filename

string

name of file being uploaded

size

long

size of file

available response representations:

  • 201 - application/json (avatar) [expand]

    Example
    {"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}

    temporary avatar cropping instructions

  • 400 [expand]

    Validation failed. For example filesize is beyond max attachment size.

  • 403 [expand]

    Returned if the request does not contain a valid XSRF token

  • 404 [expand]

    Returned if the currently authenticated user does not have EDIT PROJECT permission.

  • 500 [expand]

    Returned if an error occurs while converting temporary avatar to real avatar

POST 

Creates temporary avatar using multipart. The response is sent back as JSON stored in a textarea. This is because the client uses remote iframing to submit avatars using multipart. So we must send them a valid HTML page back from which the client parses the JSON.

available response representations:

  • 201 - text/html (avatar) [expand]

    Example
    {"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}

    temporary avatar cropping instructions embeded in HTML page. Error messages will also be embeded in the page.

  • 404 [expand]

    Returned if the currently authenticated user does not have EDIT PROJECT permission.

  • 500 [expand]

    Returned if an error occurs while converting temporary avatar to real avatar

/rest/api/2/project/{projectIdOrKey}/avatars

resource-wide template parameters
parametervaluedescription

projectIdOrKey

string

project id or project key

Methods

GET 

Returns all avatars which are visible for the currently logged in user. The avatars are grouped into system and custom.

available response representations:

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

    Example
    {"system":[{"id":"1000","owner":"fred","isSystemAvatar":true,"isSelected":false,"urls":{"16x16":"http://localhost:8090/jira/secure/useravatar?size=xsmall&avatarId=10040","24x24":"http://localhost:8090/jira/secure/useravatar?size=small&avatarId=10040","32x32":"http://localhost:8090/jira/secure/useravatar?size=medium&avatarId=10040","48x48":"http://localhost:8090/jira/secure/useravatar?avatarId=10040"},"selected":false}],"custom":[{"id":"1010","owner":"andrew","isSystemAvatar":false,"isSelected":false,"urls":{"16x16":"http://localhost:8090/jira/secure/useravatar?size=xsmall&avatarId=10080","24x24":"http://localhost:8090/jira/secure/useravatar?size=small&avatarId=10080","32x32":"http://localhost:8090/jira/secure/useravatar?size=medium&avatarId=10080","48x48":"http://localhost:8090/jira/secure/useravatar?avatarId=10080"},"selected":false}]}

    Returns a map containing a list of avatars for both custom an system avatars, which the user has the BROWSE project permission.

  • 404 [expand]

    Returned if the currently authenticated user does not have VIEW PROJECT permission.

  • 500 [expand]

    Returned if an error occurs while retrieving the list of avatars.

/rest/api/2/project/{projectIdOrKey}/components

resource-wide template parameters
parametervaluedescription

projectIdOrKey

string

the project id or project key

Methods

GET 

Contains a full representation of a the specified project's components.

available response representations:

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

    Example
    [{"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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"isAssigneeTypeValid":false,"project":"HSP","projectId":10000},{"self":"http://www.example.com/jira/rest/api/2/component/10000","id":"10050","name":"PXA","description":"This is a another JIRA component","lead":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=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","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},"isAssigneeTypeValid":false,"project":"PROJECTKEY","projectId":10000}]

    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.

  • 404 [expand]

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

/rest/api/2/project/{projectIdOrKey}/statuses

resource-wide template parameters
parametervaluedescription

projectIdOrKey

string

Project id or project key

Methods

GET 

Get all issue types with valid status values for a project

available response representations:

  • 200 - application/json [expand]

    Example
    [{"self":"http://localhost:8090/jira/rest/api/2.0/issueType/3","id":"3","name":"Task","subtask":false,"statuses":[{"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"},{"self":"http://localhost:8090/jira/rest/api/2.0/status/5","description":"The issue is closed.","iconUrl":"http://localhost:8090/jira/images/icons/closed.gif","name":"Closed","id":"5"}]}]

    Returned if the project exists and the user has permission to view its components. Contains a full representation of issue types with status values which are valid for each issue type.

  • 400 [expand]

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

/rest/api/2/project/{projectIdOrKey}/version

resource-wide template parameters
parametervaluedescription

projectIdOrKey

string

the project id or project key

Methods

GET 

/rest/api/2/project/{projectIdOrKey}/version?startAt&maxResults&orderBy&expand

Returns all versions for the specified project. Results are paginated.

Results can be ordered by the following fields:

  • sequence
  • name
  • startDate
  • releaseDate
Ordering can be ascending or descending. By default it's ascending. To specify the ordering use "-" or "+" sign. Examples:
name
Order by "name" ascending
+name
Order by "name" ascending
-name
Order by "name" descending

request query parameters
parametervaluedescription

startAt

long

the page offset, if not specified then defaults to 0

maxResults

int

how many results on the page should be included. Defaults to 50.

orderBy

string

ordering of the results.

expand

string

the parameters to expand

available response representations:

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

    Example
    {"self":"http://www.example.com/jira/rest/api/2/project/PR/version?startAt=0&maxResults=2","nextPage":"http://www.example.com/jira/rest/api/2/project/PR/version?startAt=2&maxResults=2","maxResults":2,"startAt":0,"total":7,"isLast":false,"values":[{"self":"http://www.example.com/jira/rest/api/2/version/10000","id":"10000","description":"An excellent version","name":"New Version 1","archived":false,"released":true,"releaseDate":"2010-07-06","overdue":true,"userReleaseDate":"6/Jul/2010","projectId":10000},{"self":"http://www.example.com/jira/rest/api/2/version/10010","id":"10010","description":"Minor Bugfix version","name":"Next Version","archived":false,"released":false,"overdue":false,"projectId":10000}]}

    One page of versions for the project.

  • 404 [expand]

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

/rest/api/2/project/{projectIdOrKey}/versions

resource-wide template parameters
parametervaluedescription

projectIdOrKey

string

the project id or project key

Methods

GET 

/rest/api/2/project/{projectIdOrKey}/versions?expand

Contains a full representation of a the specified project's versions.

request query parameters
parametervaluedescription

expand

string

the parameters to expand

available response representations:

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

    Example
    [{"self":"http://www.example.com/jira/rest/api/2/version/10000","id":"10000","description":"An excellent version","name":"New Version 1","archived":false,"released":true,"releaseDate":"2010-07-06","overdue":true,"userReleaseDate":"6/Jul/2010","projectId":10000},{"self":"http://www.example.com/jira/rest/api/2/version/10010","id":"10010","description":"Minor Bugfix version","name":"Next Version","archived":false,"released":false,"overdue":false,"projectId":10000}]

    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.

  • 404 [expand]

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

/rest/api/2/project/{projectIdOrKey}/properties

resource-wide template parameters
parametervaluedescription

projectIdOrKey

string

the project from which keys will be returned.

Methods

GET  (experimental)

Returns the keys of all properties for the project identified by the key or by the id.

available response representations:

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

    Example
    {"keys":[{"self":"http://www.example.com/jira/rest/api/2/issue/EX-2/properties/issue.support","key":"issue.support"}]}

    Returned if the project was found.

  • 400 [expand]

    Returned if the project key or id is invalid.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to browse the project.

  • 404 [expand]

    Returned if the project with given key or id does not exist or if the property with given key is not found.

/rest/api/2/project/{projectIdOrKey}/properties/{propertyKey}

resource-wide template parameters
parametervaluedescription

projectIdOrKey

string

the project from which keys will be returned.

projectIdOrKey

string

the project from which the property will be removed.

propertyKey

string

the key of the property to remove.

Methods

PUT  (experimental)

Sets the value of the specified project's property.

You can use this resource to store a custom data against the project identified by the key or by the id. The user who stores the data is required to have permissions to administer the project.

available response representations:

  • 200 [expand]

    Returned if the project property is successfully updated.

  • 201 [expand]

    Returned if the project property is successfully created.

  • 400 [expand]

    Returned if the project key or id is invalid.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to administer the project.

  • 404 [expand]

    Returned if the project with given key or id does not exist.

GET  (experimental)

Returns the value of the property with a given key from the project identified by the key or by the id. The user who retrieves the property is required to have permissions to read the project.

available response representations:

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

    Example
    {"key":"issue.support","value":{}}

    Returned if the project property was found.

  • 400 [expand]

    Returned if the project key or id is invalid.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to browse the project.

  • 404 [expand]

    Returned if the project with given key or id does not exist or if the property with given key is not found.

DELETE  (experimental)

Removes the property from the project identified by the key or by the id. Ths user removing the property is required to have permissions to administer the project.

available response representations:

  • 204 [expand]

    Returned if the project property was removed successfully.

  • 400 [expand]

    Returned if the project key or id is invalid.

  • 401 [expand]

    Returned if the calling user is not authenticated.

  • 403 [expand]

    Returned if the calling user does not have permission to edit the project.

  • 404 [expand]

    Returned if the project with given key or id does not exist or if the property with given key is not found.

/rest/api/2/project/{projectIdOrKey}/role

resource-wide template parameters
parametervaluedescription

projectIdOrKey

string

the project id or project key

Methods

GET 

Contains a list of roles in this project with links to full details.

available response representations:

  • 200 - application/json [expand]

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

  • 404 [expand]

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

/rest/api/2/project/{projectIdOrKey}/role/{id}

resource-wide template parameters
parametervaluedescription

projectIdOrKey

string

the project id or project key

id

long

the project role id

projectIdOrKey

string

the project id or project key

Methods

GET 

Details on a given project role.

available response representations:

  • 200 - application/json [expand]

    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.

  • 404 [expand]

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

POST 

Add an actor to a project role.

acceptable request representations:

  • application/json [expand]

    Example
    { "user" : ["admin"] }  or
{ "group" : ["jira-developers"] }

available response representations:

  • 200 - application/json [expand]

    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.

  • 404 [expand]

    Returned if the actor could not be added to the project role

DELETE 

Remove actors from a project role.

available response representations:

  • 204 [expand]

    Returned if the actor was successfully removed from the project role.

  • 404 [expand]

    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.

PUT 

Updates a project role to contain the sent actors.

acceptable request representations:

  • application/json [expand]

    Example
    { "user" : ["admin"] } or
{ "group" : ["jira-developers"] }

available response representations:

  • 200 - application/json [expand]

    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.

  • 404 [expand]

    Returned if the actor could not be added to the project role

/rest/api/2/projectCategory

Methods

GET 

Returns all project categories

available response representations:

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

    Example
    [{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"},{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10001","id":"10001","name":"SECOND","description":"Second Project Category"}]

    Returns a list of project categories.

  • 500 [expand]

    Returned if an error occurs while retrieving the list of projects.

POST 

Create a project category via POST.

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"CREATED","description":"Created Project Category"}

available response representations:

  • 201 - application/json [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2/projectCategory/10100","id":"10100","name":"CREATED","description":"Created Project Category"}

    Returned if the project category is created successfully.

  • 401 [expand]

    Returned if the caller is not logged in so does not have permission to create project categories.

  • 403 [expand]

    Returned if the caller is authenticated and does not have permission to create project categories (is not global admin).

/rest/api/2/projectCategory/{id}

resource-wide template parameters
parametervaluedescription

id

long

Methods

GET 

Contains a representation of a project category in JSON format.

available response representations:

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

    Example
    {"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}

    Returned if the project category exists. Contains representation of a project category in JSON format.

  • 404 [expand]

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

DELETE 

Delete a project category.

available response representations:

  • 204 [expand]

    Returned if the project category is successfully deleted.

  • 401 [expand]

    Returned if the caller is not logged in so does not have permission to delete project categories.

  • 403 [expand]

    Returned if the caller is authenticated and does not have permission to delete project categories (is not global admin).

  • 404 [expand]

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

PUT 

Modify a project category 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:

  • application/json [expand]

    Example
    {"name":"UPDATED","description":"Updated Project Category"}

available response representations:

  • 200 [expand]

    Returned if the project category exists and the currently authenticated user has permission to edit it.

  • 201 [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2/projectCategory/10100","id":"10100","name":"UPDATED","description":"Updated Project Category"}

  • 401 [expand]

    Returned if the caller is not logged in so does not have permission to change project categories.

  • 403 [expand]

    Returned if the caller is authenticated and does not have permission to change project categories (is not global admin).

  • 404 [expand]

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

/rest/api/2/projectvalidate/key

Methods

GET 

/rest/api/2/projectvalidate/key?key

Validates a project key.

request query parameters
parametervaluedescription

key

string

the project key

available response representations:

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

    Example
    {"errorMessages":[],"errors":{"projectKey":"A project with that project key already exists."}}

    Returns an ErrorCollection containing any validation errors for the project key.

/rest/api/2/reindex

REST resource for starting/stopping/querying indexing.

Methods

POST 

/rest/api/2/reindex?type&indexComments&indexChangeHistory&indexWorklogs

Kicks off a reindex. Need Admin permissions to perform this reindex.

request query parameters
parametervaluedescription

type

string

Case insensitive String indicating type of reindex. If omitted, then defaults to BACKGROUND_PREFERRED

indexComments

boolean

Default: false

Indicates that comments should also be reindexed. Not relevant for foreground reindex, where comments are always reindexed.

indexChangeHistory

boolean

Default: false

Indicates that changeHistory should also be reindexed. Not relevant for foreground reindex, where changeHistory is always reindexed.

indexWorklogs

boolean

Default: false

Indicates that changeHistory should also be reindexed. Not relevant for foreground reindex, where changeHistory is always reindexed.

available response representations:

  • 202 - application/json [expand]

    Example
    {"progressUrl":"http://localhost:8080/jira","currentProgress":0,"currentSubTask":"Currently reindexing Change History","type":"FOREGROUND","submittedTime":"2016-03-03T09:32:01.580+0000","startTime":"2016-03-03T09:32:01.580+0000","finishTime":"2016-03-03T09:32:01.580+0000","success":true}

    Returns a representation of the progress of the re-index operation.

GET 

/rest/api/2/reindex?taskId

Returns information on the system reindexes. If a reindex is currently taking place then information about this reindex is returned. If there is no active index task, then returns information about the latest reindex task run, otherwise returns a 404 indicating that no reindex has taken place.

request query parameters
parametervaluedescription

taskId

long

the id of an indexing task you wish to obtain details on. If omitted, then defaults to the standard behaviour and returns information on the active reindex task, or the last task to run if no reindex is taking place. . If there is no reindexing task with that id then a 404 is returned.

available response representations:

  • 200 - application/json [expand]

    Example
    {"progressUrl":"http://localhost:8080/jira","currentProgress":0,"currentSubTask":"Currently reindexing Change History","type":"FOREGROUND","submittedTime":"2016-03-03T09:32:01.580+0000","startTime":"2016-03-03T09:32:01.580+0000","finishTime":"2016-03-03T09:32:01.580+0000","success":true}

    Returns a representation of the progress of the re-index operation.

  • 404 [expand]

    Returned if there is no re-indexing task found

/rest/api/2/reindex/issue

Methods

POST 

/rest/api/2/reindex/issue?issueId&indexComments&indexChangeHistory&indexWorklogs

Reindexes one or more individual issues. Indexing is performed synchronously - the call returns when indexing of the issues has completed or a failure occurs.

Use either explicitly specified issue IDs or a JQL query to select issues to reindex.

request query parameters
parametervaluedescription

issueId

string

the IDs or keys of one or more issues to reindex.

indexComments

boolean

Default: false

Indicates that comments should also be reindexed.

indexChangeHistory

boolean

Default: false

Indicates that changeHistory should also be reindexed.

indexWorklogs

boolean

Default: false

Indicates that changeHistory should also be reindexed.

available response representations:

  • 202 - application/json [expand]

    Example
    {"progressUrl":"http://localhost:8080/jira","currentProgress":0,"currentSubTask":"Currently reindexing Change History","type":"FOREGROUND","submittedTime":"2016-03-03T09:32:01.580+0000","startTime":"2016-03-03T09:32:01.580+0000","finishTime":"2016-03-03T09:32:01.580+0000","success":true}

    Returns a representation of the progress of the re-index operation.

/rest/api/2/reindex/progress

Methods

GET 

/rest/api/2/reindex/progress?taskId

Returns information on the system reindexes. If a reindex is currently taking place then information about this reindex is returned. If there is no active index task, then returns information about the latest reindex task run, otherwise returns a 404 indicating that no reindex has taken place.

request query parameters
parametervaluedescription

taskId

long

the id of an indexing task you wish to obtain details on. If omitted, then defaults to the standard behaviour and returns information on the active reindex task, or the last task to run if no reindex is taking place. . If there is no reindexing task with that id then a 404 is returned.

available response representations:

  • 200 - application/json [expand]

    Example
    {"progressUrl":"http://localhost:8080/jira","currentProgress":0,"currentSubTask":"Currently reindexing Change History","type":"FOREGROUND","submittedTime":"2016-03-03T09:32:01.580+0000","startTime":"2016-03-03T09:32:01.580+0000","finishTime":"2016-03-03T09:32:01.580+0000","success":true}

    Returns a representation of the progress of the re-index operation.

  • 404 [expand]

    Returned if there is no re-indexing task found

/rest/api/2/reindex/request

REST resource for querying and executing reindex requests.

Methods

POST 

Executes any pending reindex requests. Returns a JSON array containing the IDs of the reindex requests that are being processed. Execution is asynchronous - progress of the returned tasks can be monitored through other REST calls.

available response representations:

  • 200 - application/json [expand]

    Returns an array containing the reindex request IDs being processed.

/rest/api/2/reindex/request/{requestId}

resource-wide template parameters
parametervaluedescription

requestId

long

the reindex request ID.

Methods

GET 

Retrieves the progress of a single reindex request.

available response representations:

  • 200 - application/json [expand]

    Example
    {"id":10500,"status":"PENDING","type":"IMMEDIATE","requestTime":"2016-03-03T09:32:01.619+0000"}

    Details and status of the reindex request.

  • 404 [expand]

    Returned if no such reindex request exists.

/rest/api/2/reindex/request/bulk

Methods

GET 

/rest/api/2/reindex/request/bulk?requestId

Retrieves the progress of a multiple reindex requests. Only reindex requests that actually exist will be returned in the results.

request query parameters
parametervaluedescription

requestId

string

the reindex request IDs.

available response representations:

  • 200 - application/json [expand]

    Example
    {"id":10500,"status":"PENDING","type":"IMMEDIATE","requestTime":"2016-03-03T09:32:01.619+0000"}

    Details and status of the reindex request.

/rest/api/2/resolution

Methods

GET 

Returns a list of all resolutions.

available response representations:

  • 200 - application/json (list of resolutions) [expand]

    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/statuses/resolved.png","name":"Fixed"},{"self":"http://www.example.com/jira/rest/api/2/resolution/3","description":"This is what it is supposed to do.","name":"Works as designed"}]

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

/rest/api/2/resolution/{id}

resource-wide template parameters
parametervaluedescription

id

string

a String containing the resolution id

Methods

GET 

Returns a resolution.

available response representations:

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

    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/statuses/resolved.png","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.

  • 404 [expand]

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

/rest/api/2/role

Methods

GET 

Get all the ProjectRoles available in JIRA. Currently this list is global.

available response representations:

  • 200 [expand]

    Example
    {"name":"Developers","id":10360,"description":"A project role that represents developers in a project"}

    Returned if the user is authenticated

  • 401 [expand]

    Returned if you do not have permissions or you are not logged in.

/rest/api/2/role/{id}

resource-wide template parameters
parametervaluedescription

id

long

Methods

GET 

Get a specific ProjectRole available in JIRA.

available response representations:

  • 200 [expand]

    Example
    {"name":"Developers","id":10360,"description":"A project role that represents developers in a project"}

    Returned if the user is authenticated

  • 401 [expand]

    Returned if you do not have permissions or you are not logged in.

/rest/api/2/screens/{screenId}/tabs

resource-wide template parameters
parametervaluedescription

screenId

long

id of screen

Methods

POST 

Creates tab for given screen

acceptable request representations:

available response representations:

  • 200 - application/json (Newly created tab) [expand]

    Example
    {"id":10000,"name":"Fields Tab"}

    Newly created tab in JSON.

  • 400 [expand]

    Returned if screen does not exist or tab name is invalid

  • 401 [expand]

    Returned if you do not have permissions

GET 

/rest/api/2/screens/{screenId}/tabs?projectKey

Returns a list of all tabs for the given screen

request query parameters
parametervaluedescription

projectKey

string

the key of the project; this parameter is optional

available response representations:

  • 200 - application/json [expand]

    Contains a full representation of all visible tabs in JSON.

  • 400 [expand]

    Returned if screen does not exist

  • 401 [expand]

    Returned if you do not have permissions

/rest/api/2/screens/{screenId}/tabs/{tabId}/fields/{id}

resource-wide template parameters
parametervaluedescription

id

string

screenId

long

id of screen

tabId

long

id of tab

Methods

DELETE 

Removes field from given tab

available response representations:

  • 201 [expand]

    Successfully removed field from tab

  • 400 [expand]

    Returned if screen or tab does not exist

  • 401 [expand]

    Returned if you do not have permissions

/rest/api/2/screens/{screenId}/tabs/{tabId}/fields

resource-wide template parameters
parametervaluedescription

screenId

long

id of screen

tabId

long

id of tab

Methods

POST 

Adds field to the given tab

acceptable request representations:

available response representations:

  • 200 [expand]

    Example
    {"id":"summary","name":"Summary"}

    Newly added field as json

  • 400 [expand]

    Returned if screen,tab or field does not exist.

  • 401 [expand]

    Returned if you do not have permissions

GET 

/rest/api/2/screens/{screenId}/tabs/{tabId}/fields?projectKey

Gets all fields for a given tab

request query parameters
parametervaluedescription

projectKey

string

the key of the project; this parameter is optional

available response representations:

  • 200 [expand]

    List of fields for given tab

  • 400 [expand]

    Returned if screen or tab does not exist

  • 401 [expand]

    Returned if you do not have permissions

/rest/api/2/screens/{screenId}/tabs/{tabId}

resource-wide template parameters
parametervaluedescription

screenId

long

id of screen

tabId

long

id of tab

Methods

PUT 

Renames tab on given screen

acceptable request representations:

available response representations:

  • 200 - application/json (Modified tab) [expand]

    Example
    {"id":10000,"name":"Fields Tab"}

    Modified tab in JSON.

  • 400 [expand]

    Returned if screen does not exist or tab name is invalid

  • 401 [expand]

    Returned if you do not have permissions

DELETE 

Deletes tab to give screen

available response representations:

  • 201 [expand]

    Successfully deleted tab

  • 400 [expand]

    Returned if screen or tab does not exist

  • 401 [expand]

    Returned if you do not have permissions

/rest/api/2/screens/{screenId}/tabs/{tabId}/move/{pos}

resource-wide template parameters
parametervaluedescription

screenId

long

id of screen

tabId

long

id of tab

pos

int

position of tab

Methods

POST 

Moves tab position

available response representations:

  • 201 [expand]

    Successfully moved tab

  • 400 [expand]

    Returned if screen or tab does not exist

  • 401 [expand]

    Returned if you do not have permissions

/rest/api/2/screens/{screenId}/availableFields

resource-wide template parameters
parametervaluedescription

screenId

long

id of screen

Methods

GET 

Gets available fields for screen. i.e ones that haven't already been added.

available response representations:

  • 200 [expand]

    List of available fields for screen

  • 400 [expand]

    Returned if screen does not exist

  • 401 [expand]

    Returned if you do not have permissions

/rest/api/2/screens/{screenId}/tabs/{tabId}/fields/{id}/move

resource-wide template parameters
parametervaluedescription

id

string

screenId

long

id of screen

tabId

long

id of tab

Methods

POST 

Moves field on the given tab

acceptable request representations:

available response representations:

  • 201 [expand]

    Successfully moved tab

  • 400 [expand]

    Returned if screen or tab does not exist. Or move cooridinates invalid.

  • 401 [expand]

    Returned if you do not have permissions

/rest/api/2/screens/addToDefault/{fieldId}

resource-wide template parameters
parametervaluedescription

fieldId

string

id of field / custom field

Methods

POST 

Adds field or custom field to the default tab

available response representations:

  • 201 [expand]

    Successfully added field to default screen / default tab

  • 400 [expand]

    Returned if screen, tab or field does not exist or field is already present on a selected tab

  • 401 [expand]

    Returned if you do not have administrator permissions

/rest/api/2/search

Resource for searches.

Methods

GET 

/rest/api/2/search?jql&startAt&maxResults&validateQuery&fields&expand

Searches for issues using JQL.

Sorting the jql parameter is a full JQL expression, and includes an ORDER BY clause.

The fields param (which can be specified multiple times) gives a comma-separated list of fields to include in the response. This can be used to retrieve a subset of fields. A particular field can be excluded by prefixing it with a minus.

By default, only navigable (*navigable) fields are returned in this search resource. Note: the default is different in the get-issue resource -- the default there all fields (*all).

  • *all - include all fields
  • *navigable - include just navigable fields
  • summary,comment - include just the summary and comments
  • -description - include navigable fields except the description (the default is *navigable for search)
  • *all,-comment - include everything except comments

GET vs POST: If the JQL query is too large to be encoded as a query param you should instead POST to this resource.

Expanding Issues in the Search Result: It is possible to expand the issues returned by directly specifying the expansion on the expand parameter passed in to this resources.

For instance, to expand the "changelog" for all the issues on the search result, it is neccesary to specify "changelog" as one of the values to expand.

request query parameters
parametervaluedescription

jql

string

a JQL query string

startAt

int

the index of the first issue to return (0-based)

maxResults

int

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.

validateQuery

boolean

Default: true

whether to validate the JQL query

fields

string

the list of fields to return for each issue. By default, all navigable fields are returned.

expand

string

A comma-separated list of the parameters to expand.

available response representations:

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

    Example
    {"expand":"names,schema","startAt":0,"maxResults":50,"total":1,"issues":[{"expand":"","id":"10001","self":"http://www.example.com/jira/rest/api/2/issue/10001","key":"HSP-1"}]}

    Returns a JSON representation of the search results.

  • 400 [expand]

    Returned if there is a problem with the JQL query.

POST 

Performs a search using JQL.

acceptable request representations:

  • application/json (searchRequest) [expand]

    Example
    {"jql":"project = HSP","startAt":0,"maxResults":15,"fields":["summary","status","assignee"]}

available response representations:

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

    Example
    {"expand":"names,schema","startAt":0,"maxResults":50,"total":1,"issues":[{"expand":"","id":"10001","self":"http://www.example.com/jira/rest/api/2/issue/10001","key":"HSP-1"}]}

    Returns a JSON representation of the search results.

  • 400 [expand]

    Returned if there is a problem with the JQL query.

/rest/api/2/securitylevel/{id}

resource-wide template parameters
parametervaluedescription

id

string

a String containing an issue security level id

Methods

GET 

Returns a full representation of the security level that has the given id.

available response representations:

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

    Example
    {"self":"http://localhost:8090/jira/rest/api/2/securitylevel/10021","id":"10000","description":"Only the reporter and internal staff can see this issue.","name":"Reporter Only"}

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

  • 404 [expand]

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

/rest/api/2/serverInfo

Methods

GET 

/rest/api/2/serverInfo?doHealthCheck

Returns general information about the current JIRA server.

request query parameters
parametervaluedescription

doHealthCheck

boolean

available response representations:

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

    Example
    {"baseUrl":"http://localhost:8080/jira","version":"5.0-SNAPSHOT","versionNumbers":[5,0,0],"buildNumber":582,"buildDate":"2016-03-03T09:32:00.932+0000","serverTime":"2016-03-03T09:32:00.932+0000","scmInfo":"1f51473f5c7b75c1a69a0090f4832cdc5053702a","buildPartnerName":"Example Partner Co.","serverTitle":"My Shiny New JIRA Server"}

    Returns a full representation of the server info in JSON format

REST resource for changing the JIRA system settings

/rest/api/2/settings/baseUrl

Methods

PUT 

Sets the base URL that is configured for this JIRA instance.

acceptable request representations:

  • application/json [expand]

    Example
    http://jira.atlassian.com/

/rest/api/2/settings/columns

Methods

GET 

Returns the default system columns for issue navigator. Admin permission will be required.

available response representations:

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

    Returns a list of columns for configured for the given user

  • 403 [expand]

    Returned if the user does not have admin permission

  • 500 [expand]

    Returned if an error occurs while retrieving the column configuration.

PUT 

Sets the default system columns for issue navigator. Admin permission will be required.

acceptable request representations:

  • application/x-www-form-urlencoded [expand]

available response representations:

  • 200 [expand]

    Returned when the columns is saved successfully

  • 500 [expand]

    Returned if an error occurs while retrieving the column configuration.

/rest/api/2/status

Methods

GET 

Returns a list of all statuses

available response representations:

  • 200 - application/json (statuses) [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","id":"10000","statusCategory":{"self":"http://localhost:8090/jira/rest/api/2.0/statuscategory/1","id":1,"key":"in-flight","colorName":"yellow","name":"In Progress"}},{"self":"http://localhost:8090/jira/rest/api/2.0/status/5","description":"The issue is closed.","iconUrl":"http://localhost:8090/jira/images/icons/closed.gif","name":"Closed","id":"5","statusCategory":{"self":"http://localhost:8090/jira/rest/api/2.0/statuscategory/9","id":9,"key":"completed","colorName":"green"}}]

    Returns a list of all JIRA issue statuses in JSON format, that are visible to the user.

  • 404 [expand]

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

/rest/api/2/status/{idOrName}

resource-wide template parameters
parametervaluedescription

idOrName

string

a numeric Status id or a status name

Methods

GET 

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

available response representations:

  • 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","id":"10000","statusCategory":{"self":"http://localhost:8090/jira/rest/api/2.0/statuscategory/1","id":1,"key":"in-flight","colorName":"yellow","name":"In Progress"}}

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

  • 404 [expand]

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

/rest/api/2/statuscategory

Methods

GET 

Returns a list of all status categories

available response representations:

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

    Example
    [{"self":"http://localhost:8090/jira/rest/api/2.0/statuscategory/1","id":1,"key":"in-flight","colorName":"yellow","name":"In Progress"},{"self":"http://localhost:8090/jira/rest/api/2.0/statuscategory/9","id":9,"key":"completed","colorName":"green"}]

    Returns a list of all JIRA issue status categories in JSON format, that are visible to the user.

  • 404 [expand]

    Returned if no status categories are found, or the user does not have permission to view them.

/rest/api/2/statuscategory/{idOrKey}

resource-wide template parameters
parametervaluedescription

idOrKey

string

a numeric StatusCategory id or a status category key

Methods

GET 

Returns a full representation of the StatusCategory having the given id or key

available response representations:

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

    Example
    {"self":"http://localhost:8090/jira/rest/api/2.0/statuscategory/1","id":1,"key":"in-flight","colorName":"yellow","name":"In Progress"}

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

  • 404 [expand]

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

/rest/api/2/universal_avatar/type/{type}/owner/{owningObjectId}/avatar

resource-wide template parameters
parametervaluedescription

owningObjectId

string

type

string

Methods

POST 

acceptable request representations:

available response representations:

/rest/api/2/universal_avatar/type/{type}/owner/{owningObjectId}/temp

resource-wide template parameters
parametervaluedescription

owningObjectId

string

type

string

Methods

POST 

/rest/api/2/universal_avatar/type/{type}/owner/{owningObjectId}/temp?filename&size

Creates temporary avatar

request query parameters
parametervaluedescription

filename

string

name of file being uploaded

size

long

size of file

available response representations:

POST 

available response representations:

/rest/api/2/universal_avatar/type/{type}/owner/{owningObjectId}/avatar/{id}

resource-wide template parameters
parametervaluedescription

id

long

database id for avatar

owningObjectId

string

type

string

Project id or project key

Methods

DELETE 

Deletes avatar

available response representations:

/rest/api/2/universal_avatar/type/{type}/owner/{owningObjectId}

resource-wide template parameters
parametervaluedescription

owningObjectId

string

type

string

Methods

GET 

available response representations:

/rest/api/2/upgrade

REST resource for executing and querying delayed upgrades.

Methods

POST 

Runs any pending delayed upgrade tasks. Need Admin permissions to do this.

available response representations:

GET 

Returns the result of the last upgrade task. Returns {@link javax.ws.rs.core.Response#seeOther(java.net.URI)} if still running.

available response representations:

  • 200 - application/json [expand]

    Example
    {"startTime":"2016-03-03T09:32:03.330+0000","duration":2001,"outcome":"SUCCESS","message":""}

    Returned if the upgrade is complete

  • 303 [expand]

    Returned if the upgrade task is still running.

  • 404 [expand]

    Returned if no prior upgrade task exists.

/rest/api/2/user

Methods

GET 

/rest/api/2/user?username&key

Returns a user. This resource cannot be accessed anonymously.

request query parameters
parametervaluedescription

username

string

the username

key

string

user key

available response representations:

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

    Example
    {"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&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","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-user"},{"name":"jira-admin","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-admin"},{"name":"important","self":"http://www.example.com/jira/rest/api/2/group?groupname=important"}]},"expand":"groups"}

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

  • 401 [expand]

    Returned if the current user is not authenticated.

  • 404 [expand]

    Returned if the requested user is not found.

PUT  (experimental)

/rest/api/2/user?username&key

Modify user. The "value" fields present will override the existing value. Fields skipped in request will not be changed.

request query parameters
parametervaluedescription

username

string

the username

key

string

user key

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"eddie","emailAddress":"eddie@atlassian.com","displayName":"Eddie of Atlassian"}

available response representations:

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

    Example
    {"self":"http://www.example.com/jirahttp://www.example.com/jira/rest/api/2/user/charlie","key":"charlie","name":"charlie","emailAddress":"charlie@atlassian.com","displayName":"Charlie of Atlassian"}

    Returned if the user exists and the caller has permission to edit it.

  • 400 [expand]

    Returned if the request is invalid.

  • 403 [expand]

    Returned if the caller user does not have permission to edit the user.

  • 404 [expand]

    Returned if the caller does have permission to edit the user but the user does not exist.

POST  (experimental)

Create user. By default created user will not be notified with email. If password field is not set then password will be randomly generated.

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"charlie","password":"abracadabra","emailAddress":"charlie@atlassian.com","displayName":"Charlie of Atlassian"}

available response representations:

  • 201 [expand]

    Example
    {"self":"http://www.example.com/jirahttp://www.example.com/jira/rest/api/2/user/charlie","key":"charlie","name":"charlie","emailAddress":"charlie@atlassian.com","displayName":"Charlie of Atlassian"}

    Returned if the user was created.

  • 400 [expand]

    Returned if the request is invalid.

  • 403 [expand]

    Returned if the caller user does not have permission to create the user.

  • 500 [expand]

    Returned if the user was not created because of other error.

DELETE  (experimental)

/rest/api/2/user?username&key

Removes user.

request query parameters
parametervaluedescription

username

string

the username

key

string

user key

available response representations:

  • 204 [expand]

    Returned if the user was deleted successfully.

  • 400 [expand]

    Returned if the request is invalid or some other server error occurred.

  • 403 [expand]

    Returned if the caller does not have permission to remove the user.

  • 404 [expand]

    Returned if the caller does have permission to remove user but the user does not exist.

/rest/api/2/user/assignable/multiProjectSearch

Methods

GET 

/rest/api/2/user/assignable/multiProjectSearch?username&projectKeys&startAt&maxResults

Returns a list of users that match the search string and can be assigned issues for all the given projects. This resource cannot be accessed anonymously.

request query parameters
parametervaluedescription

username

string

the username

projectKeys

string

the keys of the projects we are finding assignable users for, comma-separated

startAt

int

the index of the first user to return (0-based)

maxResults

int

the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.

available response representations:

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

    Example
    [{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},{"self":"http://www.example.com/jira/rest/api/2/user?username=andrew","name":"andrew","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=andrew","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=andrew","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=andrew","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=andrew"},"displayName":"Andrew Anderson","active":false}]

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

  • 401 [expand]

    Returned if the current user is not authenticated.

  • 404 [expand]

    Returned if the requested user is not found.

/rest/api/2/user/assignable/search

Methods

GET 

/rest/api/2/user/assignable/search?username&project&issueKey&startAt&maxResults&actionDescriptorId

Returns a list of users that match the search string. This resource cannot be accessed anonymously. Please note that this resource should be called with an issue key when a list of assignable users is retrieved for editing. For create only a project key should be supplied. The list of assignable users may be incorrect if it's called with the project key for editing.

request query parameters
parametervaluedescription

username

string

the username

project

string

the key of the project we are finding assignable users for

issueKey

string

the issue key for the issue being edited we need to find assignable users for.

startAt

int

the index of the first user to return (0-based)

maxResults

int

the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.

actionDescriptorId

int

available response representations:

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

    Example
    {"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&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","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-user"},{"name":"jira-admin","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-admin"},{"name":"important","self":"http://www.example.com/jira/rest/api/2/group?groupname=important"}]},"expand":"groups"}

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

  • 400 [expand]

    Returned if no project or issue key was provided

  • 401 [expand]

    Returned if the current user is not authenticated.

  • 404 [expand]

    Returned if the requested user is not found.

/rest/api/2/user/avatar

Methods

POST 

/rest/api/2/user/avatar?username

Converts temporary avatar into a real avatar

request query parameters
parametervaluedescription

username

string

username

acceptable request representations:

  • application/json [expand]

    Example
    {"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"needsCropping":false}

available response representations:

  • 201 - application/json (avatar) [expand]

    Example
    {"id":"1000","owner":"fred","isSystemAvatar":true,"isSelected":false,"urls":{"16x16":"http://localhost:8090/jira/secure/useravatar?size=xsmall&avatarId=10040","24x24":"http://localhost:8090/jira/secure/useravatar?size=small&avatarId=10040","32x32":"http://localhost:8090/jira/secure/useravatar?size=medium&avatarId=10040","48x48":"http://localhost:8090/jira/secure/useravatar?avatarId=10040"},"selected":false}

    Returns created avatar

  • 400 [expand]

    Returned if the cropping coordinates are invalid

  • 403 [expand]

    Returned if the currently authenticated user does not have permission to pick avatar

  • 404 [expand]

    Returned if the currently authenticated user does not have EDIT PROJECT permission.

  • 500 [expand]

    Returned if an error occurs while converting temporary avatar to real avatar

PUT 

/rest/api/2/user/avatar?username
request query parameters
parametervaluedescription

username

string

acceptable request representations:

available response representations:

/rest/api/2/user/avatar/{id}

resource-wide template parameters
parametervaluedescription

id

long

database id for avatar

Methods

DELETE 

/rest/api/2/user/avatar/{id}?username

Deletes avatar

request query parameters
parametervaluedescription

username

string

username

available response representations:

  • 204 - application/json [expand]

    Returned if the avatar is successfully deleted.

  • 403 [expand]

    Returned if the currently authenticated user does not have permission to delete the avatar.

  • 404 [expand]

    Returned if the avatar does not exist or the currently authenticated user does not have permission to delete it.

/rest/api/2/user/avatar/temporary

Methods

POST 

/rest/api/2/user/avatar/temporary?username&filename&size

Creates temporary avatar. Creating a temporary avatar is part of a 3-step process in uploading a new avatar for a user: upload, crop, confirm.

The following examples shows these three steps using curl. The cookies (session) need to be preserved between requests, hence the use of -b and -c. The id created in step 2 needs to be passed to step 3 (you can simply pass the whole response of step 2 as the request of step 3). 

 curl -c cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \
   -H "Content-Type: image/png" --data-binary @mynewavatar.png \
   'http://localhost:8090/jira/rest/api/2/user/avatar/temporary?username=admin&filename=mynewavatar.png'

 curl -b cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \
   -H "Content-Type: application/json" --data '{"cropperWidth": "65","cropperOffsetX": "10","cropperOffsetY": "16"}' \
   -o tmpid.json \
   http://localhost:8090/jira/rest/api/2/user/avatar?username=admin

 curl -b cookiejar.txt -X PUT -u admin:admin -H "X-Atlassian-Token: no-check" \
   -H "Content-Type: application/json" --data-binary @tmpid.json \
   http://localhost:8090/jira/rest/api/2/user/avatar?username=admin

request query parameters
parametervaluedescription

username

string

username

filename

string

name of file being uploaded

size

long

size of file

available response representations:

  • 201 - application/json (avatar) [expand]

    Example
    {"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}

    temporary avatar cropping instructions

  • 403 [expand]

    Returned if the request does not conain a valid XSRF token

  • 404 [expand]

    Returned if the currently authenticated user does not have EDIT PROJECT permission.

  • 500 [expand]

    Returned if an error occurs while converting temporary avatar to real avatar

POST 

/rest/api/2/user/avatar/temporary?username

Creates temporary avatar using multipart. The response is sent back as JSON stored in a textarea. This is because the client uses remote iframing to submit avatars using multipart. So we must send them a valid HTML page back from which the client parses the JSON from.

Creating a temporary avatar is part of a 3-step process in uploading a new avatar for a user: upload, crop, confirm. This endpoint allows you to use a multipart upload instead of sending the image directly as the request body.

You *must* use "avatar" as the name of the upload parameter:

 curl -c cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \
   -F "avatar=@mynewavatar.png;type=image/png" \
   'http://localhost:8090/jira/rest/api/2/user/avatar/temporary?username=admin'

request query parameters
parametervaluedescription

username

string

Username

available response representations:

  • 201 - text/html (avatar) [expand]

    Example
    {"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}

    temporary avatar cropping instructions embeded in HTML page. Error messages will also be embeded in the page.

  • 404 [expand]

    Returned if user does NOT exist

  • 500 [expand]

    Returned if an error occurs while converting temporary avatar to real avatar

/rest/api/2/user/avatars

Methods

GET 

/rest/api/2/user/avatars?username

Returns all avatars which are visible for the currently logged in user.

request query parameters
parametervaluedescription

username

string

username

available response representations:

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

    Example
    {"system":[{"id":"1000","owner":"fred","isSystemAvatar":true,"isSelected":false,"urls":{"16x16":"http://localhost:8090/jira/secure/useravatar?size=xsmall&avatarId=10040","24x24":"http://localhost:8090/jira/secure/useravatar?size=small&avatarId=10040","32x32":"http://localhost:8090/jira/secure/useravatar?size=medium&avatarId=10040","48x48":"http://localhost:8090/jira/secure/useravatar?avatarId=10040"},"selected":false}],"custom":[{"id":"1010","owner":"andrew","isSystemAvatar":false,"isSelected":false,"urls":{"16x16":"http://localhost:8090/jira/secure/useravatar?size=xsmall&avatarId=10080","24x24":"http://localhost:8090/jira/secure/useravatar?size=small&avatarId=10080","32x32":"http://localhost:8090/jira/secure/useravatar?size=medium&avatarId=10080","48x48":"http://localhost:8090/jira/secure/useravatar?avatarId=10080"},"selected":false}]}

    Returns a map containing a list of avatars for both custom an system avatars

  • 401 [expand]

    Returned if the current user is not authenticated.

  • 404 [expand]

    Returned if the requested user is not found.

  • 500 [expand]

    Returned if an error occurs while retrieving the list of avatars.

/rest/api/2/user/columns

Methods

GET 

/rest/api/2/user/columns?username

Returns the default columns for the given user. Admin permission will be required to get columns for a user other than the currently logged in user.

request query parameters
parametervaluedescription

username

string

username

available response representations:

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

    Returns a list of columns for configured for the given user

  • 401 [expand]

    Returned if the current user is not permitted to request the columns for the given user.

  • 404 [expand]

    Returned if the requested user is not found.

  • 500 [expand]

    Returned if an error occurs while retrieving the column configuration.

PUT 

Sets the default columns for the given user. Admin permission will be required to get columns for a user other than the currently logged in user.

acceptable request representations:

  • application/x-www-form-urlencoded [expand]

available response representations:

  • 200 [expand]

    Returned when the columns is saved successfully

  • 500 [expand]

    Returned if an error occurs while retrieving the column configuration.

DELETE 

/rest/api/2/user/columns?username

Reset the default columns for the given user to the system default. Admin permission will be required to get columns for a user other than the currently logged in user.

request query parameters
parametervaluedescription

username

string

username

available response representations:

  • 204 [expand]

    Returned when the columns are reset successfully

  • 401 [expand]

    Returned if the current user is not permitted to request the columns for the given user.

  • 500 [expand]

    Returned if an error occurs while resetting the column configuration.

/rest/api/2/user/password

Methods

PUT  (experimental)

/rest/api/2/user/password?username&key

Modify user password.

request query parameters
parametervaluedescription

username

string

the username

key

string

user key

acceptable request representations:

  • application/json [expand]

    Example
    {"password":"abracadabra"}

available response representations:

  • 204 [expand]

    Returned if the user exists and the caller has permission to edit it.

  • 403 [expand]

    Returned if the caller does not have permission to change the user password.

  • 404 [expand]

    Returned if the caller does have permission to change user password but the user does not exist.

/rest/api/2/user/permission/search

Methods

GET 

/rest/api/2/user/permission/search?username&permissions&issueKey&projectKey&startAt&maxResults

Returns a list of active users that match the search string and have all specified permissions for the project or issue.
This resource can be accessed by users with ADMINISTER_PROJECT permission for the project or global ADMIN or SYSADMIN rights.

request query parameters
parametervaluedescription

username

string

the username filter, list includes all users if unspecified

permissions

string

comma separated list of permissions for project or issue returned users must have, see Permissions JavaDoc for the list of all possible permissions.

issueKey

string

the issue key for the issue for which returned users have specified permissions.

projectKey

string

the optional project key to search for users with if no issueKey is supplied.

startAt

int

the index of the first user to return (0-based)

maxResults

int

the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.

available response representations:

  • 200 - application/json (List of users) [expand]

    Example
    [{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},{"self":"http://www.example.com/jira/rest/api/2/user?username=andrew","name":"andrew","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=andrew","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=andrew","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=andrew","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=andrew"},"displayName":"Andrew Anderson","active":false}]

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

  • 400 [expand]

    Returned if no project or issue key was provided or when permissions list is empty or contains an invalid entry

  • 401 [expand]

    Returned if the current user is not authenticated.

  • 403 [expand]

    Returned if the current user does not have admin rights for the project.

  • 404 [expand]

    Returned if the requested issue or project is not found.

/rest/api/2/user/picker

Methods

GET 

/rest/api/2/user/picker?query&maxResults&showAvatar&exclude

Returns a list of users matching query with highlighting. This resource cannot be accessed anonymously.

request query parameters
parametervaluedescription

query

string

A string used to search username, Name or e-mail address

maxResults

int

the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.

showAvatar

boolean

exclude

string

available response representations:

  • 200 - application/json (List of users) [expand]

    Example
    {"users":[{"name":"fred","key":"fred","html":"fred@example.com","displayName":"Fred Grumble","avatarUrl":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred"}],"total":25,"header":"Showing 20 of 25 matching groups"}

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

  • 401 [expand]

    Returned if the current user is not authenticated.

  • 404 [expand]

    Returned if the requested user is not found.

/rest/api/2/user/search

Methods

GET 

/rest/api/2/user/search?username&startAt&maxResults&includeActive&includeInactive

Returns a list of users that match the search string. This resource cannot be accessed anonymously.

request query parameters
parametervaluedescription

username

string

A query string used to search username, name or e-mail address

startAt

int

the index of the first user to return (0-based)

maxResults

int

the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.

includeActive

boolean

If true, then active users are included in the results (default true)

includeInactive

boolean

If true, then inactive users are included in the results (default false)

available response representations:

  • 200 - application/json (List of users) [expand]

    Example
    [{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},{"self":"http://www.example.com/jira/rest/api/2/user?username=andrew","name":"andrew","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=andrew","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=andrew","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=andrew","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=andrew"},"displayName":"Andrew Anderson","active":false}]

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

  • 401 [expand]

    Returned if the current user is not authenticated.

  • 404 [expand]

    Returned if the requested user is not found.

/rest/api/2/user/viewissue/search

Methods

GET 

/rest/api/2/user/viewissue/search?username&issueKey&projectKey&startAt&maxResults

Returns a list of active users that match the search string. This resource cannot be accessed anonymously. Given an issue key this resource will provide a list of users that match the search string and have the browse issue permission for the issue provided.

request query parameters
parametervaluedescription

username

string

the username filter, no users returned if left blank

issueKey

string

the issue key for the issue being edited we need to find viewable users for.

projectKey

string

the optional project key to search for users with if no issueKey is supplied.

startAt

int

the index of the first user to return (0-based)

maxResults

int

the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated.

available response representations:

  • 200 - application/json (List of users) [expand]

    Example
    [{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=fred","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred"},"displayName":"Fred F. User","active":false},{"self":"http://www.example.com/jira/rest/api/2/user?username=andrew","name":"andrew","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=andrew","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=andrew","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&ownerId=andrew","48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=andrew"},"displayName":"Andrew Anderson","active":false}]

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

  • 400 [expand]

    Returned if no project or issue key was provided

  • 401 [expand]

    Returned if the current user is not authenticated.

  • 404 [expand]

    Returned if the requested issue or project is not found.

/rest/api/2/version

Methods

POST 

Create a version via POST.

acceptable request representations:

  • application/json [expand]

    Example
    {"description":"An excellent version","name":"New Version 1","archived":false,"released":true,"releaseDate":"2010-07-06","userReleaseDate":"6/Jul/2010","project":"PXA","projectId":10000}

available response representations:

  • 201 - application/json [expand]

    Example
    {"description":"An excellent version","name":"New Version 1","archived":false,"released":true,"releaseDate":"2010-07-06","userReleaseDate":"6/Jul/2010","project":"PXA","projectId":10000}

    Returned if the version is created successfully.

  • 403 [expand]

    Returned if the currently authenticated user does not have permission to edit the version.

  • 404 [expand]

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

/rest/api/2/version/{id}/move

resource-wide template parameters
parametervaluedescription

id

string

a String containing the version id

Methods

POST 

Modify a version's sequence within a project. The move version bean has 2 alternative field value pairs:

position
An absolute position, which may have a value of 'First', 'Last', 'Earlier' or 'Later'
after
A version to place this version after. The value should be the self link of another version

acceptable request representations:

  • application/json [expand]

    Example
    {"after":"http://www.example.com/jira/rest/api/2/version/10000"}

available response representations:

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

    Example
    {"self":"http://www.example.com/jira/rest/api/2/version/10000","id":"10000","description":"An excellent version","name":"New Version 1","archived":false,"released":true,"releaseDate":"2010-07-06","overdue":true,"userReleaseDate":"6/Jul/2010","projectId":10000}

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

  • 404 [expand]

    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.

/rest/api/2/version/{id}

resource-wide template parameters
parametervaluedescription

id

string

Methods

DELETE 

/rest/api/2/version/{id}?moveFixIssuesTo&moveAffectedIssuesTo

Delete a project version.

request query parameters
parametervaluedescription

moveFixIssuesTo

string

The version to set fixVersion to on issues where the deleted version is the fix version, If null then the fixVersion is removed.

moveAffectedIssuesTo

string

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:

  • 204 [expand]

    Returned if the version is successfully deleted.

  • 403 [expand]

    Returned if the currently authenticated user does not have permission to delete the version.

  • 404 [expand]

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

GET 

/rest/api/2/version/{id}?expand

Returns a project version.

request query parameters
parametervaluedescription

expand

string

available response representations:

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

    Example
    {"self":"http://www.example.com/jira/rest/api/2/version/10000","id":"10000","description":"An excellent version","name":"New Version 1","archived":false,"released":true,"releaseDate":"2010-07-06","overdue":true,"userReleaseDate":"6/Jul/2010","projectId":10000}

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

  • 404 [expand]

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

PUT 

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:

  • application/json [expand]

    Example
    {"self":"http://www.example.com/jira/rest/api/2/version/10000","id":"10000","description":"An excellent version","name":"New Version 1","archived":false,"released":true,"releaseDate":"2010-07-06","overdue":true,"userReleaseDate":"6/Jul/2010","projectId":10000}

available response representations:

  • 200 [expand]

    Returned if the version exists and the currently authenticated user has permission to edit it.

  • 403 [expand]

    Returned if the currently authenticated user does not have permission to edit the version.

  • 404 [expand]

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

/rest/api/2/version/{id}/relatedIssueCounts

resource-wide template parameters
parametervaluedescription

id

string

a String containing the version id

Methods

GET 

Returns a bean containing the number of fixed in and affected issues for the given version.

available response representations:

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

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

  • 404 [expand]

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

/rest/api/2/version/{id}/unresolvedIssueCount

resource-wide template parameters
parametervaluedescription

id

string

a String containing the version id

Methods

GET 

Returns the number of unresolved issues for the given version

available response representations:

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

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

  • 404 [expand]

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

/rest/api/2/version/{versionId}/remotelink

resource-wide template parameters
parametervaluedescription

versionId

string

The version for which to delete ALL existing remote version links

Methods

GET 

Returns the remote version links associated with the given version ID.

available response representations:

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

    Example
    {"links":[{"self":"http://www.example.com/version/10000/AnotherGlobalId","name":"Version 1","link":{ "globalId": "AnotherGlobalId", "myCustomLinkProperty": false, "colors": [ "cyan", "magenta", "yellow" ]}},{"self":"http://www.example.com/version/10000/SomeGlobalId","name":"Version 1","link":{ "globalId": "SomeGlobalId", "myCustomLinkProperty": true, "colors": [ "red", "green", "blue" ]}}]}

    Returned if the version exists and the currently authenticated user has permission to view it, which is restricted to those users with BROWSE permission for the project. Contains a full representation of the remote version links.

  • 404 [expand]

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

POST 

Create a remote version link via POST. The link's global ID will be taken from the JSON payload if provided; otherwise, it will be generated.

acceptable request representations:

  • application/json [expand]

    Example
    {"globalId":"SomeGlobalId","myCustomLinkProperty":true,"colors":["red","green","blue"],"notes":["Remote version links may take any well-formed JSON shape that is desired,","provided that they fit within the maximum buffer size allowed,","which is currently 32,768 characters."]}

available response representations:

  • 201 [expand]

    Example
    Returned if the remote version link is created or updated successfully.
      The document has no content, and a

    Returned if the version is created successfully. The document will has no content, and a {@code Location:} header contains the self-URI for the newly created link.

  • 400 [expand]

    Returned if the JSON payload is empty or malformed

  • 403 [expand]

    Returned if the currently authenticated user does not have permission to edit the version.

  • 404 [expand]

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

DELETE 

Delete all remote version links for a given version ID.

available response representations:

  • 204 [expand]

    Returned if the remote version links are successfully deleted.

  • 403 [expand]

    Returned if the currently authenticated user does not have administrative rights to the project and thereby cannot delete remote links to the version.

  • 404 [expand]

    Returned if the version does not exist, the currently authenticated user does not have permission to view it, or the version does not have any remote links to delete

/rest/api/2/version/{versionId}/remotelink/{globalId}

resource-wide template parameters
parametervaluedescription

versionId

string

The version ID of the remote link

globalId

string

The global ID of the remote link

Methods

GET 

A REST sub-resource representing a remote version link

available response representations:

  • 200 - application/json [expand]

    Example
    {"self":"http://www.example.com/version/10000/SomeGlobalId","name":"Version 1","link":{ "globalId": "SomeGlobalId", "myCustomLinkProperty": true, "colors": [ "red", "green", "blue" ]}}

    Information on the remote version link (or links)

  • 404 [expand]

    Returned if the version or remote version link does not exist or if the user does not have the BROWSE permission for the project that owns the specified version

POST 

Create a remote version link via POST. The link's global ID will be taken from the JSON payload if provided; otherwise, it will be generated.

acceptable request representations:

  • application/json [expand]

    Example
    {"globalId":"SomeGlobalId","myCustomLinkProperty":true,"colors":["red","green","blue"],"notes":["Remote version links may take any well-formed JSON shape that is desired,","provided that they fit within the maximum buffer size allowed,","which is currently 32,768 characters."]}

available response representations:

  • 201 [expand]

    Example
    Returned if the remote version link is created or updated successfully.
      The document has no content, and a

    Returned if the version is created successfully. The document will has no content, and a {@code Location:} header contains the self-URI for the newly created link.

  • 400 [expand]

    Returned if the JSON payload is empty or malformed

  • 403 [expand]

    Returned if the currently authenticated user does not have permission to edit the version.

  • 404 [expand]

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

DELETE 

Delete a specific remote version link with the given version ID and global ID.

available response representations:

  • 204 [expand]

    Returned if the remote version link is successfully deleted.

  • 403 [expand]

    Returned if the currently authenticated user does not have administrative rights to the project and thereby cannot delete remote links to the version.

  • 404 [expand]

    Returned if the version does not exist, the currently authenticated user does not have permission to view it, or the version does not have a link for the given global ID

/rest/api/2/version/remotelink

Methods

GET 

/rest/api/2/version/remotelink?globalId

Returns the remote version links for a given global ID.

request query parameters
parametervaluedescription

globalId

string

the global ID of the remote resource that is linked to the versions

available response representations:

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

    Example
    {"links":[{"self":"http://www.example.com/version/10000/SomeGlobalId","name":"Version 1","link":{ "globalId": "SomeGlobalId", "myCustomLinkProperty": true, "colors": [ "red", "green", "blue" ]}},{"self":"http://www.example.com/version/10101/SomeGlobalId","name":"Version 2","link":{ "globalId": "SomeGlobalId" }}]}

    Contains a list of remote version links. Any existing links that the user does not have permission to see will be filtered out. The user must have BROWSE permission for the project to see links to its versions.

/rest/api/2/workflow

REST resource for retrieving workflows.

Methods

GET 

/rest/api/2/workflow?workflowName

Returns all workflows.

request query parameters
parametervaluedescription

workflowName

string

available response representations:

  • 200 - application/json [expand]

    Returned if the currently authenticated user has administration permission. Contains a full representation of every workflow.

  • 401 [expand]

    Returned if the currently authenticated user does not have administration permission.

/rest/api/2/workflow/{id}/properties

resource-wide template parameters
parametervaluedescription

id

long

the ID of the transition within the workflow.

Methods

GET 

/rest/api/2/workflow/{id}/properties?includeReservedKeys&key&workflowName&workflowMode

Return the property or properties associated with a transition.

request query parameters
parametervaluedescription

includeReservedKeys

boolean

some keys under the "jira." prefix are editable, some are not. Set this to true in order to include the non-editable keys in the response.

key

string

the name of the property key to query. Can be left off the query to return all properties.

workflowName

string

the name of the workflow to use.

workflowMode

string

the type of workflow to use. Can either be "live" or "draft".

available response representations:

  • 200 - application/json [expand]

    Example
    {"key":"jira.i18n.title","value":"some.title","id":"jira.i18n.title"}

  • 403 [expand]

    Returned if the user does not have admin permission

DELETE 

/rest/api/2/workflow/{id}/properties?key&workflowName&workflowMode

Delete a property from the passed transition on the passed workflow. It is not an error to delete a property that does not exist.

request query parameters
parametervaluedescription

key

string

the name of the property to add.

workflowName

string

the name of the workflow to use.

workflowMode

string

the type of workflow to use. Can either be "live" or "draft".

available response representations:

  • 200 - application/json [expand]
  • 304 [expand]

    Returned if no changes were actually made by the request (e.g. trying to delete a property that does not exist).

  • 400 [expand]

    Returned if the request is invalid.

  • 403 [expand]

    Returned if the user does not have admin permission

POST 

/rest/api/2/workflow/{id}/properties?key&workflowName&workflowMode

Add a new property to a transition. Trying to add a property that already exists will fail.

request query parameters
parametervaluedescription

key

string

the name of the property to add.

workflowName

string

the name of the workflow to use.

workflowMode

string

the type of workflow to use. Can either be "live" or "draft".

acceptable request representations:

  • application/json [expand]

    Example
    {"value":"createissue"}

available response representations:

  • 200 - application/json [expand]

    Example
    {"key":"jira.i18n.title","value":"some.title","id":"jira.i18n.title"}

  • 400 [expand]

    Returned if the request is invalid.

  • 403 [expand]

    Returned if the user does not have admin permission

PUT 

/rest/api/2/workflow/{id}/properties?key&workflowName&workflowMode

Update/add new property to a transition. Trying to update a property that does not exist will result in a new property being added.

request query parameters
parametervaluedescription

key

string

the name of the property to add.

workflowName

string

the name of the workflow to use.

workflowMode

string

the type of workflow to use. Can either be "live" or "draft".

acceptable request representations:

  • application/json [expand]

    Example
    {"value":"createissue"}

available response representations:

  • 200 - application/json [expand]

    Example
    {"key":"jira.i18n.title","value":"some.title","id":"jira.i18n.title"}

  • 304 [expand]

    Returned if no changes were actually made by the request (e.g. updating a property to value it already holds).

  • 400 [expand]

    Returned if the request is invalid.

  • 403 [expand]

    Returned if the user does not have admin permission

/rest/api/2/workflowscheme

Methods

POST 

Create a new workflow scheme. The body contains a representation of the new scheme. Values not passed are assumed to be set to their defaults.

acceptable request representations:

  • application/json [expand]

    Example
    {"name":"New Workflow Scheme Name","description":"New Workflow Scheme Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId":"WorkflowName"}}

available response representations:

  • 201 [expand]

    Example
    {"id":101010,"name":"Workflow Scheme One","description":"Workflow Scheme One Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"draft":false,"self":"http://www.example.com/jira/rest/api/2/workflowscheme/101010"}

    The newly created scheme.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

/rest/api/2/workflowscheme/{id}

resource-wide template parameters
parametervaluedescription

id

long

the id of the scheme.

Methods

PUT 

Update the passed workflow scheme. The body of the request is a representation of the workflow scheme. Values not passed are assumed to indicate no change for that field. The passed representation can have its updateDraftIfNeeded flag set to true to indicate that the draft should be created and/or updated when the actual scheme cannot be edited (e.g. when the scheme is being used by a project). Values not appearing the body will not be touched.

acceptable request representations:

  • application/json [expand]

    Example
    {"id":57585,"name":"Updated Workflow Scheme Name","description":"Updated Workflow Scheme Name","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId":"WorkflowName"},"updateDraftIfNeeded":false}

available response representations:

  • 200 [expand]

    Example
    {"id":101010,"name":"Workflow Scheme One","description":"Workflow Scheme One Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"draft":false,"self":"http://www.example.com/jira/rest/api/2/workflowscheme/101010"}

    The updated scheme.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if the requested scheme does not exist.

GET 

/rest/api/2/workflowscheme/{id}?returnDraftIfExists

Returns the requested workflow scheme to the caller.

request query parameters
parametervaluedescription

returnDraftIfExists

boolean

Default: false

when true indicates that a scheme's draft, if it exists, should be queried instead of the scheme itself.

available response representations:

  • 200 - application/json [expand]

    Example
    {"id":101010,"name":"Workflow Scheme One","description":"Workflow Scheme One Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"draft":false,"self":"http://www.example.com/jira/rest/api/2/workflowscheme/101010"}

    Returned if the scheme exists and the caller has permission to see it.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if the requested scheme does not exist.

DELETE 

Delete the passed workflow scheme.

available response representations:

  • 204 [expand]

    If the scheme was deleted.

  • 400 [expand]

    Returned if the requested scheme is active (i.e. being used by JIRA).

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if the requested scheme does not exist.

/rest/api/2/workflowscheme/{id}/createdraft

resource-wide template parameters
parametervaluedescription

id

long

the id of the parent scheme.

Methods

POST 

Create a draft for the passed scheme. The draft will be a copy of the state of the parent.

available response representations:

  • 201 [expand]

    Example
    {"id":17218781,"name":"Workflow Scheme Two","description":"Workflow Scheme Two Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"originalDefaultWorkflow":"ParentsDefaultWorkflowName","originalIssueTypeMappings":{"IssueTypeId":"WorkflowName2"},"draft":true,"lastModifiedUser":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&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":[]}},"lastModified":"Today 12:45","self":"http://www.example.com/jira/rest/api/2/workflowscheme/17218781/draft"}

    The newly created scheme.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

/rest/api/2/workflowscheme/{id}/default

resource-wide template parameters
parametervaluedescription

id

long

the id of the scheme.

Methods

GET 

/rest/api/2/workflowscheme/{id}/default?returnDraftIfExists

Return the default workflow from the passed workflow scheme.

request query parameters
parametervaluedescription

returnDraftIfExists

boolean

Default: false

when true indicates that a scheme's draft, if it exists, should be queried instead of the scheme itself.

available response representations:

  • 200 [expand]

    Example
    {"workflow":"WorkflowName"}

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned when the workflow scheme does not exist.

DELETE 

/rest/api/2/workflowscheme/{id}/default?updateDraftIfNeeded

Remove the default workflow from the passed workflow scheme.

request query parameters
parametervaluedescription

updateDraftIfNeeded

boolean

when true will create and return a draft when the workflow scheme cannot be edited (e.g. when it is being used by a project).

available response representations:

  • 200 [expand]

    Example
    {"id":101010,"name":"Workflow Scheme One","description":"Workflow Scheme One Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"draft":false,"self":"http://www.example.com/jira/rest/api/2/workflowscheme/101010"}

    Returned on success.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if the scheme does not exist.

PUT 

Set the default workflow for the passed workflow scheme. The passed representation can have its updateDraftIfNeeded flag set to true to indicate that the draft should be created/updated when the actual scheme cannot be edited.

acceptable request representations:

  • application/json [expand]

    Example
    {"workflow":"WorkflowName","updateDraftIfNeeded":false}

available response representations:

  • 200 [expand]

    Example
    {"id":101010,"name":"Workflow Scheme One","description":"Workflow Scheme One Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"draft":false,"self":"http://www.example.com/jira/rest/api/2/workflowscheme/101010"}

    Returned on success.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if the scheme does not exist.

/rest/api/2/workflowscheme/{id}/draft

resource-wide template parameters
parametervaluedescription

id

long

the id of the parent scheme.

Methods

GET 

Returns the requested draft workflow scheme to the caller.

available response representations:

  • 200 - application/json [expand]

    Example
    {"id":17218781,"name":"Workflow Scheme Two","description":"Workflow Scheme Two Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"originalDefaultWorkflow":"ParentsDefaultWorkflowName","originalIssueTypeMappings":{"IssueTypeId":"WorkflowName2"},"draft":true,"lastModifiedUser":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&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":[]}},"lastModified":"Today 12:45","self":"http://www.example.com/jira/rest/api/2/workflowscheme/17218781/draft"}

    Returned if the scheme exists and the caller has permission to see it.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if the requested draft scheme does not exist.

DELETE 

Delete the passed draft workflow scheme.

available response representations:

  • 204 [expand]

    If the scheme was deleted.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if the requested draft scheme or parent scheme does not exist.

PUT 

Update a draft workflow scheme. The draft will created if necessary. The body is a representation of the workflow scheme. Values not passed are assumed to indicate no change for that field.

acceptable request representations:

  • application/json [expand]

    Example
    {"id":57585,"name":"Updated Workflow Scheme Name","description":"Updated Workflow Scheme Name","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId":"WorkflowName"},"updateDraftIfNeeded":false}

available response representations:

  • 200 [expand]

    Example
    {"id":17218781,"name":"Workflow Scheme Two","description":"Workflow Scheme Two Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"originalDefaultWorkflow":"ParentsDefaultWorkflowName","originalIssueTypeMappings":{"IssueTypeId":"WorkflowName2"},"draft":true,"lastModifiedUser":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&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":[]}},"lastModified":"Today 12:45","self":"http://www.example.com/jira/rest/api/2/workflowscheme/17218781/draft"}

    The updated/created scheme.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if the requested scheme does not exist.

/rest/api/2/workflowscheme/{id}/draft/default

resource-wide template parameters
parametervaluedescription

id

long

the id of the parent scheme.

Methods

GET 

Return the default workflow from the passed draft workflow scheme to the caller.

available response representations:

  • 200 [expand]

    Example
    {"workflow":"WorkflowName"}

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned when the workflow scheme does not exist.

DELETE 

Remove the default workflow from the passed draft workflow scheme.

available response representations:

  • 200 [expand]

    Example
    {"id":17218781,"name":"Workflow Scheme Two","description":"Workflow Scheme Two Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"originalDefaultWorkflow":"ParentsDefaultWorkflowName","originalIssueTypeMappings":{"IssueTypeId":"WorkflowName2"},"draft":true,"lastModifiedUser":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&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":[]}},"lastModified":"Today 12:45","self":"http://www.example.com/jira/rest/api/2/workflowscheme/17218781/draft"}

    Returned on success.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if the scheme does not exist.

PUT 

Set the default workflow for the passed draft workflow scheme.

acceptable request representations:

  • application/json [expand]

    Example
    {"workflow":"WorkflowName","updateDraftIfNeeded":false}

available response representations:

  • 200 [expand]

    Example
    {"id":17218781,"name":"Workflow Scheme Two","description":"Workflow Scheme Two Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"originalDefaultWorkflow":"ParentsDefaultWorkflowName","originalIssueTypeMappings":{"IssueTypeId":"WorkflowName2"},"draft":true,"lastModifiedUser":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&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":[]}},"lastModified":"Today 12:45","self":"http://www.example.com/jira/rest/api/2/workflowscheme/17218781/draft"}

    Returned on success.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if the scheme does not exist.

/rest/api/2/workflowscheme/{id}/draft/issuetype/{issueType}

resource-wide template parameters
parametervaluedescription

id

long

the id of the parent scheme.

issueType

string

the issue type being set.

Methods

GET 

Returns the issue type mapping for the passed draft workflow scheme.

available response representations:

  • 200 - application/json [expand]

    Example
    {"issueType":"IssueTypeId","workflow":"WorkflowName"}

    Returned on success.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if either the requested scheme or issue type does not exist.

DELETE 

Remove the specified issue type mapping from the draft scheme.

available response representations:

  • 200 [expand]

    Example
    {"id":17218781,"name":"Workflow Scheme Two","description":"Workflow Scheme Two Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"originalDefaultWorkflow":"ParentsDefaultWorkflowName","originalIssueTypeMappings":{"IssueTypeId":"WorkflowName2"},"draft":true,"lastModifiedUser":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&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":[]}},"lastModified":"Today 12:45","self":"http://www.example.com/jira/rest/api/2/workflowscheme/17218781/draft"}

    Returned on success.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if either the requested scheme or issue type does not exist.

PUT 

Set the issue type mapping for the passed draft scheme. The passed representation can have its updateDraftIfNeeded flag set to true to indicate that the draft should be created/updated when the actual scheme cannot be edited.

acceptable request representations:

  • application/json [expand]

    Example
    {"issueType":"IssueTypeId","workflow":"WorkflowName","updateDraftIfNeeded":false}

available response representations:

  • 200 [expand]

    Example
    {"id":17218781,"name":"Workflow Scheme Two","description":"Workflow Scheme Two Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"originalDefaultWorkflow":"ParentsDefaultWorkflowName","originalIssueTypeMappings":{"IssueTypeId":"WorkflowName2"},"draft":true,"lastModifiedUser":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"24x24":"http://www.example.com/jira/secure/useravatar?size=small&ownerId=fred","16x16":"http://www.example.com/jira/secure/useravatar?size=xsmall&ownerId=fred","32x32":"http://www.example.com/jira/secure/useravatar?size=medium&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":[]}},"lastModified":"Today 12:45","self":"http://www.example.com/jira/rest/api/2/workflowscheme/17218781/draft"}

    Returned on success.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if either the requested scheme or issue type does not exist.

/rest/api/2/workflowscheme/{id}/draft/workflow

resource-wide template parameters
parametervaluedescription

id

long

the id of the parent scheme.

Methods

GET 

/rest/api/2/workflowscheme/{id}/draft/workflow?workflowName

Returns the draft workflow mappings or requested mapping to the caller.

request query parameters
parametervaluedescription

workflowName

string

the workflow mapping to return. Null can be passed to return all mappings. Must be a valid workflow name.

available response representations:

  • 200 - application/json [expand]

    Example
    {"workflow":"WorkflowName","issueTypes":["IssueTypeId","IssueTypeId2"],"defaultMapping":false}

    Returned on success.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if either the requested scheme or workflow does not exist.

DELETE 

/rest/api/2/workflowscheme/{id}/draft/workflow?workflowName

Delete the passed workflow from the draft workflow scheme.

request query parameters
parametervaluedescription

workflowName

string

the name of the workflow to delete.

available response representations:

  • 200 [expand]

    The scheme with the workflow deleted.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if the requested scheme or workflow does not exist.

PUT 

/rest/api/2/workflowscheme/{id}/draft/workflow?workflowName

Update the draft scheme to include the passed mapping. The body is a representation of the workflow mapping. Values not passed are assumed to indicate no change for that field.

request query parameters
parametervaluedescription

workflowName

string

the name of the workflow mapping to update.

acceptable request representations:

  • application/json [expand]

    Example
    {"workflow":"WorkflowName3","issueTypes":["IssueTypeId"],"updateDraftIfNeeded":true}

available response representations:

  • 200 [expand]

    Example
    {"id":101010,"name":"Workflow Scheme One","description":"Workflow Scheme One Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"draft":false,"self":"http://www.example.com/jira/rest/api/2/workflowscheme/101010"}

    The updated scheme.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

/rest/api/2/workflowscheme/{id}/issuetype/{issueType}

resource-wide template parameters
parametervaluedescription

id

long

the id of the scheme.

issueType

string

the issue type being set.

Methods

GET 

/rest/api/2/workflowscheme/{id}/issuetype/{issueType}?returnDraftIfExists

Returns the issue type mapping for the passed workflow scheme.

request query parameters
parametervaluedescription

returnDraftIfExists

boolean

Default: false

when true indicates that a scheme's draft, if it exists, should be queried instead of the scheme itself.

available response representations:

  • 200 - application/json [expand]

    Example
    {"issueType":"IssueTypeId","workflow":"WorkflowName"}

    Returned on success.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if either the requested scheme or issue type does not exist.

DELETE 

/rest/api/2/workflowscheme/{id}/issuetype/{issueType}?updateDraftIfNeeded

Remove the specified issue type mapping from the scheme.

request query parameters
parametervaluedescription

updateDraftIfNeeded

boolean

when true will create and return a draft when the workflow scheme cannot be edited (e.g. when it is being used by a project).

available response representations:

  • 200 [expand]

    Example
    {"id":101010,"name":"Workflow Scheme One","description":"Workflow Scheme One Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"draft":false,"self":"http://www.example.com/jira/rest/api/2/workflowscheme/101010"}

    Returned on success.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if either the requested scheme or issue type does not exist.

PUT 

Set the issue type mapping for the passed scheme. The passed representation can have its updateDraftIfNeeded flag set to true to indicate that the draft should be created/updated when the actual scheme cannot be edited.

acceptable request representations:

  • application/json [expand]

    Example
    {"issueType":"IssueTypeId","workflow":"WorkflowName","updateDraftIfNeeded":false}

available response representations:

  • 200 [expand]

    Example
    {"id":101010,"name":"Workflow Scheme One","description":"Workflow Scheme One Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"draft":false,"self":"http://www.example.com/jira/rest/api/2/workflowscheme/101010"}

    Returned on success.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if either the requested scheme or issue type does not exist.

/rest/api/2/workflowscheme/{id}/workflow

resource-wide template parameters
parametervaluedescription

id

long

the id of the scheme.

Methods

GET 

/rest/api/2/workflowscheme/{id}/workflow?workflowName&returnDraftIfExists

Returns the workflow mappings or requested mapping to the caller for the passed scheme.

request query parameters
parametervaluedescription

workflowName

string

the workflow mapping to return. Null can be passed to return all mappings. Must be a valid workflow name.

returnDraftIfExists

boolean

Default: false

when true indicates that a scheme's draft, if it exists, should be queried instead of the scheme itself.

available response representations:

  • 200 - application/json [expand]

    Example
    {"workflow":"WorkflowName","issueTypes":["IssueTypeId","IssueTypeId2"],"defaultMapping":false}

    Returned on success.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if either the requested scheme or workflow does not exist.

DELETE 

/rest/api/2/workflowscheme/{id}/workflow?workflowName&updateDraftIfNeeded

Delete the passed workflow from the workflow scheme.

request query parameters
parametervaluedescription

workflowName

string

the name of the workflow to delete.

updateDraftIfNeeded

boolean

flag to indicate if a draft should be created if necessary to delete the workflow from the scheme.

available response representations:

  • 200 [expand]

    The scheme with the workflow deleted.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

  • 404 [expand]

    Returned if the requested scheme or workflow does not exist.

PUT 

/rest/api/2/workflowscheme/{id}/workflow?workflowName

Update the scheme to include the passed mapping. The body is a representation of the workflow mapping. Values not passed are assumed to indicate no change for that field. The passed representation can have its updateDraftIfNeeded flag set to true to indicate that the draft should be created/updated when the actual scheme cannot be edited.

request query parameters
parametervaluedescription

workflowName

string

the name of the workflow mapping to update.

acceptable request representations:

  • application/json [expand]

    Example
    {"workflow":"WorkflowName3","issueTypes":["IssueTypeId"],"updateDraftIfNeeded":true}

available response representations:

  • 200 [expand]

    Example
    {"id":101010,"name":"Workflow Scheme One","description":"Workflow Scheme One Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId2":"WorkflowName","IsueTypeId":"WorkflowName"},"draft":false,"self":"http://www.example.com/jira/rest/api/2/workflowscheme/101010"}

    The updated scheme.

  • 401 [expand]

    Returned if there is no user or if the user has not entered a websudo session.

/rest/auth/1/session

Implement a REST resource for acquiring a session cookie.

Methods

POST 

Creates a new session for a user in JIRA. Once a session has been successfully created it can be used to access any of JIRA's remote APIs and also the web UI by passing the appropriate HTTP Cookie header.

Note that it is generally preferrable to use HTTP BASIC authentication with the REST API. However, this resource may be used to mimic the behaviour of JIRA's log-in page (e.g. to display log-in errors to a user).

acceptable request representations:

  • application/json (credentials) [expand]

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

available response representations:

  • 200 [expand]

    Example
    {"session":{"name":"JSESSIONID","value":"12345678901234567890"},"loginInfo":{"failedLoginCount":10,"loginCount":127,"lastFailedLoginTime":"2016-03-03T09:32:00.277+0000","previousLoginTime":"2016-03-03T09:32:00.277+0000"}}

    Returns information about the caller's session if the caller is authenticated.

    Note that the response contains the Set-Cookie HTTP headers that must be honoured by the caller. If you are using a cookie-aware HTTP client then it will handle all Set-Cookie headers automatically. This is important because setting the JSESSIONID cookie alone may not be sufficient for the authentication to work.

  • 401 [expand]

    Returned if the login fails due to invalid credentials.

  • 403 [expand]

    Returned if the login is denied due to a CAPTCHA requirement, throtting, or any other reason. In case of a 403 status code it is possible that the supplied credentials are valid but the user is not allowed to log in at this point in time.

GET 

Returns information about the currently authenticated user's session. If the caller is not authenticated they will get a 401 Unauthorized status code.

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":"2016-03-03T09:32:00.277+0000","previousLoginTime":"2016-03-03T09:32:00.277+0000"}}

  • 401 [expand]

    Returned if the caller is not authenticated.

DELETE 

Logs the current user out of JIRA, destroying the existing session, if any.

available response representations:

  • 204 [expand]

    Returned if the user was successfully logged out.

  • 401 [expand]

    Returned if the caller is not authenticated.

/rest/auth/1/websudo

Methods

DELETE 

This method invalidates the any current WebSudo session.

available response representations:

  • 204 [expand]

    Returned if no error occurs