JIRA Cloud REST API Reference

JIRA 1000.824.0

Welcome to the JIRA Cloud REST API reference. You can use the JIRA REST API to build add-ons for JIRA, develop integrations between JIRA and other applications, or script interactions with JIRA. This page documents the REST resources available in JIRA, along with expected HTTP response codes and sample requests.

Looking for the REST API reference for a different JIRA version? Follow the links below.

Getting started

If you haven't integrated with JIRA Cloud before, read our Getting started guide. In the guide, you'll set up a development environment. You'll also build a basic add-on using Atlassian Connect, the framework for extending JIRA Cloud. Once you have the basics in place, you can try one of our JIRA add-on tutorials that use the JIRA REST API, like this one: Tutorial: Display your projects in JIRA.

Authentication

Authentication for Atlassian Connect add-ons

If you are integrating with the JIRA REST APIs via an Atlassian Connect add-on, API calls are authenticated via JWT (JSON Web Tokens). This is built into the supported Atlassian Connect libraries. At a high level, authentication works by the add-on exchanging a security context with the application. This context is used to create and validate JWT tokens, embedded in API calls. To learn more, read the Atlassian Connect authentication documentation.

Authentication for REST API requests

If you are integrating directly with the REST APIs, rather than via an Atlassian Connect add-on, use one of the authentication methods listed below:

  • OAuth (1.0a) - This token-based method is the recommended method. It is more flexible and secure than other options.
  • Basic HTTP - This method is only recommended for tools like scripts or bots. It is easier to implement, but much less secure.

Note, JIRA itself uses cookie-based authentication in the browser, so you can call REST from Javascript on the page and rely on the authentication that the browser has established. To reproduce the behavior of the JIRA log-in page (for example, to display authentication error messages to users) can POST to the /auth/1/session resource.

URI Structure

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:

  • auth - for authentication-related operations, and
  • api - for everything else.

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 order to simplify API responses, the JIRA REST API uses resource expansion. This means the API will only return parts of the resource when explicitly requested.

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.

Pagination

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.

Ordering

Some resources support ordering by a specific field. Ordering request is provided in the orderBy query parameter. See the docs for specific methods to see which fields they support and if they support ordering at all.

Ordering can be ascending or descending. By default it's ascending. To specify the ordering use "-" or "+" sign. Examples:

?orderBy=name
Order by "name" ascending
?orderBy=+name
Order by "name" ascending
?orderBy=-name
Order by "name" descending

Asynchronous methods

experimental

Some resources may trigger long-running or computationally expensive tasks. If so, the method will schedule an asynchronous task and return a 303 (See Other) response with the location of the task progress. This task may then be queried periodically to get updates.

When the task eventually finishes, the bean will contain the result field. This result may have a different type, depending on the method. See each method's documentation for more information.

Note that such tasks are not guaranteed to be run in order. In other words, if you rely on the sequence of execution of your tasks, you need to start the next one only after all the prerequisite tasks have finished.

Experimental methods

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

Special request and response headers

  • X-AUSERNAME - Response header which contains either username of the authenticated user or 'anonymous'.
  • X-Atlassian-Token - methods which accept multipart/form-data will only process requests with 'X-Atlassian-Token: no-check' header.

Error responses

Most resources will return a response body in addition to the status code. Usually, the JSON schema of the entity returned is the following: 

{"id":"https://docs.atlassian.com/jira/REST/schema/error-collection#","title":"Error Collection","type":"object","properties":{"errorMessages":{"type":"array","items":{"type":"string"}},"errors":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"status":{"type":"integer"}},"additionalProperties":false}

Resources

api/2/

Provide permission information for the current user.

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
parametertypedescription
projectKeystring

- key of project to scope returned permissions for.

projectIdstring

- id of project to scope returned permissions for.

issueKeystring

- key of the issue to scope returned permissions for.

issueIdstring

- id of the issue to scope returned permissions for.

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/permissions#","title":"Permissions","type":"object","properties":{"permissions":{"type":"object","patternProperties":{".+":{"title":"Permission","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["GLOBAL","PROJECT"]},"description":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}

  • Status 400
    Returned if the project or issue id is invalid.
  • Status 404
    Returned if the project or issue id or key is not found.

Returns all permissions that are present in the JIRA instance - Global, Project and the global ones added by plugins

Responses
  • Status 200 - application/json

    Example
    {"permissions":{"BULK_CHANGE":{"key":"BULK_CHANGE","name":"Bulk Change","type":"GLOBAL","description":"Ability to modify a collection of issues at once. For example, resolve multiple issues in one step."}}}

    Returns a list of all permissions in JIRA.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/permissions#","title":"Permissions","type":"object","properties":{"permissions":{"type":"object","patternProperties":{".+":{"title":"Permission","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["GLOBAL","PROJECT"]},"description":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}

  • Status 401
    Returned for unauthenticated requests
  • Status 403
    Returned for users without administer permissions

api/2/application-properties

Returns an application property.

Request
query parameters
parametertypedescription
keystring

a String containing the property key

permissionLevelstring

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

keyFilterstring

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.

Responses
  • Status 200 - application/json

    Example
    [{"id":"jira.home","key":"jira.home","value":"/var/jira/jira-home","name":"jira.home","desc":"JIRA home directory","type":"string","defaultValue":""},{"id":"jira.clone.prefix","key":"jira.clone.prefix","value":"CLONE -","name":"The prefix added to the Summary field of cloned issues","type":"string","defaultValue":"CLONE -"}]

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/property#","title":"Property","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"value":{"type":"string"},"name":{"type":"string"},"desc":{"type":"string"},"type":{"type":"string"},"defaultValue":{"type":"string"},"example":{"type":"string"},"allowedValues":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

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

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

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/application-property#","title":"Application Property","type":"object","properties":{"id":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 200
    Returned if the property exists and the currently authenticated user has permission to edit it.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/property#","title":"Property","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"value":{"type":"string"},"name":{"type":"string"},"desc":{"type":"string"},"type":{"type":"string"},"defaultValue":{"type":"string"},"example":{"type":"string"},"allowedValues":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

  • Status 403
    Returned if the currently authenticated user does not have permission to edit the property.
  • Status 404
    Returned if the property does not exist or the currently authenticated user does not have permission to view it.

Returns the properties that are displayed on the "General Configuration > Advanced Settings" page.

Responses
  • Status 200 - application/json

    Example
    [{"id":"jira.home","key":"jira.home","value":"/var/jira/jira-home","name":"jira.home","desc":"JIRA home directory","type":"string","defaultValue":""},{"id":"jira.clone.prefix","key":"jira.clone.prefix","value":"CLONE -","name":"The prefix added to the Summary field of cloned issues","type":"string","defaultValue":"CLONE -"}]

    Returns all properties to display in the "General Configuration > Advanced Settings" page.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-property#","title":"List of Property","type":"array","items":{"title":"Property","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"value":{"type":"string"},"name":{"type":"string"},"desc":{"type":"string"},"type":{"type":"string"},"defaultValue":{"type":"string"},"example":{"type":"string"},"allowedValues":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}}

  • Status 401
    Returned if the current user is not authenticated.
  • Status 403
    Returned if the current user is not an administrator.

api/2/applicationrole

Provides REST access to JIRA's Application Roles.

Returns all ApplicationRoles in the system. Will also return an ETag header containing a version hash of the collection of ApplicationRoles.

Responses
  • Status 200 - application/json

    Example
    [{"key":"jira-software","groups":["jira-software-users","jira-testers"],"name":"JIRA Software","defaultGroups":["jira-software-users"],"selectedByDefault":false,"defined":false,"numberOfSeats":10,"remainingSeats":5,"userCount":5,"userCountDescription":"5 developers","hasUnlimitedSeats":false,"platform":false},{"key":"jira-core","groups":["jira-core-users"],"name":"JIRA Core","defaultGroups":["jira-core-users"],"selectedByDefault":false,"defined":false,"numberOfSeats":1,"remainingSeats":1,"userCount":0,"userCountDescription":"0 users","hasUnlimitedSeats":false,"platform":true}]

    Returns all ApplicationRoles in the system

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-application-role#","title":"List of Application Role","type":"array","items":{"title":"Application Role","type":"object","properties":{"key":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"defaultGroups":{"type":"array","items":{"type":"string"}},"selectedByDefault":{"type":"boolean"},"defined":{"type":"boolean"},"numberOfSeats":{"type":"integer"},"remainingSeats":{"type":"integer"},"userCount":{"type":"integer"},"userCountDescription":{"type":"string"},"hasUnlimitedSeats":{"type":"boolean"},"platform":{"type":"boolean"}},"additionalProperties":false}}

  • Status 401
    Returned if the current user is not authenticated.
  • Status 403
    Returned if the current user is not an administrator.

Returns the ApplicationRole with passed key if it exists.

Responses
  • Status 200 - application/json

    Example
    {"key":"jira-software","groups":["jira-software-users","jira-testers"],"name":"JIRA Software","defaultGroups":["jira-software-users"],"selectedByDefault":false,"defined":false,"numberOfSeats":10,"remainingSeats":5,"userCount":5,"userCountDescription":"5 developers","hasUnlimitedSeats":false,"platform":false}

    Returns the ApplicationRole if it exists.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/application-role#","title":"Application Role","type":"object","properties":{"key":{"type":"string"},"groups":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"defaultGroups":{"type":"array","items":{"type":"string"}},"selectedByDefault":{"type":"boolean"},"defined":{"type":"boolean"},"numberOfSeats":{"type":"integer"},"remainingSeats":{"type":"integer"},"userCount":{"type":"integer"},"userCountDescription":{"type":"string"},"hasUnlimitedSeats":{"type":"boolean"},"platform":{"type":"boolean"}},"additionalProperties":false}

  • Status 401
    Returned if the current user is not authenticated.
  • Status 403
    Returned if the current user is not an administrator.
  • Status 404
    Returned if the role does not exist.

api/2/attachment

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

Responses
  • Status 200 - application/json

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"created":"2017-03-08T03:29:43.525+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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/attachment#","title":"Attachment","type":"object","properties":{"self":{"type":"string","format":"uri"},"filename":{"type":"string"},"author":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"created":{"type":"string"},"size":{"type":"integer"},"mimeType":{"type":"string"},"properties":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"content":{"type":"string"},"thumbnail":{"type":"string"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false,"required":["size"]}

  • Status 403
    The calling user is not permitted to view the requested attachment.
  • Status 404
    Any of:
    • there is no attachment with the requested id
    • attachments feature is disabled

Remove an attachment from an issue.

Responses
  • Status 204
    Removal was successful
  • Status 403
    The calling user is not permitted to remove the requested attachment.
  • Status 404
    Any of:
    • there is no attachment with the requested id
    • attachments feature is disabled

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

Responses
  • Status 200 - application/json

    Example
    {"id":7237823,"name":"images.zip","entries":[{"path":"MG00N067.JPG","index":0,"size":"119 kB","mediaType":"image/jpeg","label":"MG00N067.JPG"},{"path":"Allegro from Duet in C Major.mp3","index":1,"size":"1.36 MB","mediaType":"audio/mpeg","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","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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/human-readable-archive#","title":"Human Readable Archive","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"entries":{"type":"array","items":{"title":"Human Readable Archive Entry","type":"object","properties":{"path":{"type":"string"},"index":{"type":"integer"},"size":{"type":"string"},"mediaType":{"type":"string"},"label":{"type":"string"}},"additionalProperties":false,"required":["index"]}},"totalEntryCount":{"type":"integer"},"mediaType":{"type":"string"}},"additionalProperties":false,"required":["id","totalEntryCount"]}

  • Status 403
    The calling user is not permitted to view the requested attachment.
  • Status 404
    Any of:
    • there is no attachment with the requested id
    • attachments feature is disabled
  • Status 409
    The archive format is not supported.

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/attachment-archive-impl#","title":"Attachment Archive Impl","type":"object","properties":{"entries":{"type":"array","items":{"title":"Attachment Archive Entry","type":"object","properties":{"abbreviatedName":{"type":"string"},"entryIndex":{"type":"integer"},"mediaType":{"type":"string"},"name":{"type":"string"},"size":{"type":"integer"}},"additionalProperties":false,"required":["entryIndex","size"]}},"totalEntryCount":{"type":"integer"}},"additionalProperties":false,"required":["totalEntryCount"]}

  • Status 403
    The calling user is not permitted to view the requested attachment.
  • Status 404
    Any of:
    • there is no attachment with the requested id
    • attachments feature is disabled
  • Status 409
    The archive format is not supported.

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

Responses
  • Status 200 - application/json

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/attachment-meta#","title":"Attachment Meta","type":"object","properties":{"enabled":{"type":"boolean"},"uploadLimit":{"type":"integer"}},"additionalProperties":false,"required":["enabled"]}

api/2/auditing

Resource representing the auditing records

Returns auditing records filtered using provided parameters

Request
query parameters
parametertypedescription
offsetint

- the number of record from which search starts

limitint

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

filterstring

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

fromstring

- 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

tostring

- 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

Responses
  • Status 200 - application/json

    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","description":"Optional description","objectItem":{"id":"user","name":"user","typeName":"USER","parentId":"1","parentName":"JIRA Internal Directory"},"changedValues":[{"fieldName":"email","changedFrom":"user@atlassian.com","changedTo":"newuser@atlassian.com"}],"associatedItems":[{"id":"jira-software-users","name":"jira-software-users","typeName":"GROUP","parentId":"1","parentName":"JIRA Internal Directory"}]}

    Returns a list auditing records filtered with request query parameters

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/audit-record#","title":"Audit Record","type":"object","properties":{"id":{"type":"integer"},"summary":{"type":"string"},"remoteAddress":{"type":"string"},"authorKey":{"type":"string"},"created":{"type":"string"},"category":{"type":"string"},"eventSource":{"type":"string"},"description":{"type":"string"},"objectItem":{"$ref":"#/definitions/associated-item"},"changedValues":{"type":"array","items":{"title":"Changed Value","type":"object","properties":{"fieldName":{"type":"string"},"changedFrom":{"type":"string"},"changedTo":{"type":"string"}},"additionalProperties":false}},"associatedItems":{"type":"array","items":{"$ref":"#/definitions/associated-item"}}},"definitions":{"associated-item":{"title":"Associated Item","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"typeName":{"type":"string"},"parentId":{"type":"string"},"parentName":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

  • Status 400
    In case of unhandled error while fetching auditing records
  • Status 403
    Returned if the user does not have admin permission

api/2/avatar

Returns all system avatars of the given type.

Responses
  • Status 200 - application/json

    Example
    {"system":[{"id":"1000","owner":"fred","isSystemAvatar":true,"isSelected":false,"isDeletable":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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/system-avatars#","title":"System Avatars","type":"object","properties":{"system":{"type":"array","items":{"title":"Avatar","type":"object","properties":{"id":{"type":"string"},"owner":{"type":"string"},"isSystemAvatar":{"type":"boolean"},"isSelected":{"type":"boolean"},"isDeletable":{"type":"boolean"},"urls":{"type":"object","patternProperties":{"\\d\\dx\\d\\d":{"type":"string","format":"uri"}},"additionalProperties":false},"selected":{"type":"boolean"}},"additionalProperties":false,"required":["isSystemAvatar","isSelected","isDeletable","selected"]}}},"additionalProperties":false}

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

api/2/comment/{commentId}/properties

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-properties-keys#","title":"Entity Properties Keys","type":"object","properties":{"keys":{"type":"array","items":{"title":"Entity Property Key","type":"object","properties":{"self":{"type":"string"},"key":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 400
    Returned if the comment key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to browse the comment.
  • Status 404
    Returned if the comment with given key or id does not exist or if the property with given key is not found.

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.

Responses
  • Status 400
    Returned if the comment key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 204
    Returned if the comment property was removed successfully.
  • Status 403
    Returned if the calling user does not have permission to edit the comment.
  • Status 404
    Returned if the comment with given key or id does not exist or if the property with given key is not found.

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.

Responses
  • Status 200
    Returned if the comment property is successfully updated.
  • Status 201
    Returned if the comment property is successfully created.
  • Status 400
    Returned if the comment key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to administer the comment.
  • Status 404
    Returned if the comment with given key or id does not exist.

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.

Responses
  • Status 200 - application/json

    Example
    {"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}

    Returned if the comment property was found.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-property#","title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}

  • Status 400
    Returned if the comment key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to browse the comment.
  • Status 404
    Returned if the comment with given key or id does not exist or if the property with given key is not found.

api/2/component

Create a component via POST.

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/component#","title":"Component","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}

Responses
  • Status 201 - application/json

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"isAssigneeTypeValid":false,"project":"HSP","projectId":10000}

    Returned if the component is created successfully.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/component#","title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}

  • Status 401
    Returned if the caller is not logged in and does not have permission to create components in the project.
  • Status 403
    Returned if the caller is authenticated and does not have permission to create components in the project.
  • Status 404
    Returned if the project does not exist or the currently authenticated user does not have permission to view it.

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.

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/component#","title":"Component","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}

Responses
  • Status 200
    Returned if the component exists and the currently authenticated user has permission to edit it.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/component#","title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}

  • Status 403
    Returned if the currently authenticated user does not have permission to edit the component.
  • Status 404
    Returned if the component does not exist or the currently authenticated user does not have permission to view it.

Returns a project component.

Responses
  • Status 200 - application/json

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"isAssigneeTypeValid":false,"project":"HSP","projectId":10000}

    Returns a full JSON representation of a project component.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/component#","title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}

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

Delete a project component.

Request
query parameters
parametertypedescription
moveIssuesTostring

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.

Responses
  • Status 204
    Returned if the component is successfully deleted.
  • Status 403
    Returned if the currently authenticated user does not have permission to delete the component.
  • Status 404
    Returned if the component does not exist or the currently authenticated user does not have permission to view it.

Returns counts of issues related to this component.

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/component-issue-counts#","title":"Component Issue Counts","type":"object","properties":{"self":{"type":"string","format":"uri"},"issueCount":{"type":"integer"}},"additionalProperties":false,"required":["issueCount"]}

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

api/2/configuration

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.

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/configuration#","title":"Configuration","type":"object","properties":{"votingEnabled":{"type":"boolean"},"watchingEnabled":{"type":"boolean"},"unassignedIssuesAllowed":{"type":"boolean"},"subTasksEnabled":{"type":"boolean"},"issueLinkingEnabled":{"type":"boolean"},"timeTrackingEnabled":{"type":"boolean"},"attachmentsEnabled":{"type":"boolean"},"timeTrackingConfiguration":{"title":"Time Tracking Configuration","type":"object","properties":{"workingHoursPerDay":{"type":"number"},"workingDaysPerWeek":{"type":"number"},"timeFormat":{"type":"string","enum":["pretty","days","hours"]},"defaultUnit":{"type":"string","enum":["minute","hour","day","week"]}},"additionalProperties":false,"required":["workingHoursPerDay","workingDaysPerWeek"]}},"additionalProperties":false,"required":["votingEnabled","watchingEnabled","unassignedIssuesAllowed","subTasksEnabled","issueLinkingEnabled","timeTrackingEnabled","attachmentsEnabled"]}

  • Status 401
    Returned if the user is not logged in.

api/2/configuration/timetracking

Returns the currently selected time-tracking implementation

Responses
  • Status 200 - application/json

    Example
    {"key":"JIRA","name":"JIRA time tracking","url":"/example/config/url"}

    Returned if one of the available time tracking implementations is enabled

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/time-tracking-implementation#","title":"Time Tracking Implementation","type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}},"additionalProperties":false}

  • Status 401
    Returned if user is not logged in
  • Status 204
    Returned if none of the available time tracking implementations are enabled

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/time-tracking-implementation#","title":"Time Tracking Implementation","type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}},"additionalProperties":false}

  • Status 403
    Returned if the user is not an administrator

Selects a time tracking implementation

Request

Example
{"key":"JIRA"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/time-tracking-implementation#","title":"Time Tracking Implementation","type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 400
    Returned if the provided implementation does not exist
  • Status 401
    Returned if user is not logged in
  • Status 204
    Returned on success
  • Status 403
    Returned if the user is not an administrator

Disables time tracking

Responses
  • Status 401
    Returned if user is not logged in
  • Status 204
    Returned on success
  • Status 403
    Returned if the user is not an administrator

Retrieve the list of available time tracking implementations

Responses
  • Status 200 - application/json

    Example
    [{"key":"JIRA","name":"JIRA time tracking","url":"/example/config/url"}]

    Returns the available time tracking implementations

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-time-tracking-implementation#","title":"List of Time Tracking Implementation","type":"array","items":{"title":"Time Tracking Implementation","type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"}},"additionalProperties":false}}

Returns the configuration options for time tracking

Responses
  • Status 200

    Example
    {"workingHoursPerDay":8.0,"workingDaysPerWeek":5.0,"timeFormat":"pretty","defaultUnit":"hour"}

    Returned on success

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/time-tracking-configuration#","title":"Time Tracking Configuration","type":"object","properties":{"workingHoursPerDay":{"type":"number"},"workingDaysPerWeek":{"type":"number"},"timeFormat":{"type":"string","enum":["pretty","days","hours"]},"defaultUnit":{"type":"string","enum":["minute","hour","day","week"]}},"additionalProperties":false,"required":["workingHoursPerDay","workingDaysPerWeek"]}

  • Status 401
    Returned if user is not logged in
  • Status 403
    Returned if the user is not an administrator

Sets the options for time tracking

Request

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/time-tracking-configuration#","title":"Time Tracking Configuration","type":"object","properties":{"workingHoursPerDay":{"type":"number"},"workingDaysPerWeek":{"type":"number"},"timeFormat":{"type":"string","enum":["pretty","days","hours"]},"defaultUnit":{"type":"string","enum":["minute","hour","day","week"]}},"additionalProperties":false,"required":["workingHoursPerDay","workingDaysPerWeek"]}

Responses
  • Status 200

    Example
    {"workingHoursPerDay":8.0,"workingDaysPerWeek":5.0,"timeFormat":"pretty","defaultUnit":"hour"}

    Returned on success

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/time-tracking-configuration#","title":"Time Tracking Configuration","type":"object","properties":{"workingHoursPerDay":{"type":"number"},"workingDaysPerWeek":{"type":"number"},"timeFormat":{"type":"string","enum":["pretty","days","hours"]},"defaultUnit":{"type":"string","enum":["minute","hour","day","week"]}},"additionalProperties":false,"required":["workingHoursPerDay","workingDaysPerWeek"]}

  • Status 400
    Returned if the bean validation has failed
  • Status 401
    Returned if user is not logged in
  • Status 403
    Returned if the user is not an administrator

api/2/customFieldOption

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/custom-field-option#","title":"Custom Field Option","type":"object","properties":{"self":{"type":"string","format":"uri"},"value":{"type":"string"}},"additionalProperties":false}

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

api/2/dashboard

The /dashboard resource.

Returns a list of all dashboards, optionally filtering them.

Request
query parameters
parametertypedescription
filterstring

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.

startAtint

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

maxResultsint

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.

Responses
  • Status 200

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/dashboards#","title":"Dashboards","type":"object","properties":{"startAt":{"type":"integer"},"maxResults":{"type":"integer"},"total":{"type":"integer"},"prev":{"type":"string"},"next":{"type":"string"},"dashboards":{"type":"array","items":{"title":"Dashboard","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"self":{"type":"string"},"view":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

Returns a single dashboard.

Responses
  • Status 200

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/dashboard#","title":"Dashboard","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"self":{"type":"string"},"view":{"type":"string"}},"additionalProperties":false}

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

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

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-properties-keys#","title":"Entity Properties Keys","type":"object","properties":{"keys":{"type":"array","items":{"title":"Entity Property Key","type":"object","properties":{"self":{"type":"string"},"key":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 400
    Returned if the dashboard item id is invalid.
  • Status 404
    Returned if the dashboard item with given id does not exist or user does not have permissions to view it.

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.

Responses
  • Status 400
    Returned if the dashboard item id is invalid.
  • Status 204
    Returned if the dashboard item property was removed successfully.
  • Status 403
    Returned if the calling user does not have permission to edit the dashboard item.
  • Status 404
    Returned if the dashboard item with given id does not exist or user does not have permissions to view it.

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.

Responses
  • Status 200
    Returned if the dashboard item property is successfully updated.
  • Status 201
    Returned if the dashboard item property is successfully created.
  • Status 400
    Returned if the dashboard item id is invalid.
  • Status 403
    Returned if the calling user does not have permission to administer the dashboard item.
  • Status 404
    Returned if the dashboard item with given id does not exist or user does not have permissions to view it.

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.

Responses
  • Status 200 - application/json

    Example
    {"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}

    Returned if the dashboard item property was found.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-property#","title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}

  • Status 400
    Returned if the dashboard item id is invalid.
  • Status 404
    Returned if the dashboard item with given id does not exist or user does not have permissions to view it.

api/2/field

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

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/custom-field-definition#","title":"Custom Field Definition","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"},"searcherKey":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 201

    Example
    {"id":"customfield_10101","name":"New custom field","custom":true,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["cf[10101]","New custom field"],"schema":{"type":"project","custom":"com.atlassian.jira.plugin.system.customfieldtypes:project","customId":10101}}

    Returned if custom field was created.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/field#","title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false}

  • Status 400
    Returned if the input is invalid (e.g. invalid values).
  • Status 500
    Returned if exception occured during custom field creation.

Returns a list of all fields, both System and Custom

Responses
  • Status 200 - application/json

    Example
    [{"id":"description","name":"Description","custom":false,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["description"],"schema":{"type":"string","system":"description"}},{"id":"summary","key":"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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-field#","title":"List of Field","type":"array","items":{"title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false}}

api/2/field/{fieldKey}/option

This resource represents the options for a select list issue field on an issue.

Select list issue fields can be defined by a Connect add-on. The add-on that provided the field can add, remove and update the options using the methods defined in this resource. JIRA manages these options, making them available to users to select.

Each option consists of the following properties:

  • value - The option's name, which is displayed in the UI.
  • id - The unique identifier of the option. Note, each field has a separate pool of IDs.
  • properties - A custom JSON object that can hold any properties. These properties can be searched in JQL, if extractions are defined in the descriptor.
  • scope - The access permission for the option. Each option can be scoped to a list of projects. If the scope is not defined, then the option is available globally to all users in all projects.

Show more

Creates an option for a select list issue field, for a given field key. The Id will be automatically assigned. Only JIRA administrators or the add-ons that provided the field may use this method.

Request

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-field-option#","title":"Issue Field Option","type":"object","properties":{"id":{"type":"integer"},"value":{"type":"string"},"properties":{"title":"Object Node","type":"object"},"config":{"title":"Issue Field Option Config","type":"object","properties":{"scope":{"title":"Issue Field Option Scope","type":"object","properties":{"projects":{"type":"array","items":{"type":"integer"}}},"additionalProperties":false},"attributes":{"type":"array","items":{"type":"string","enum":["notSelectable"]}}},"additionalProperties":false}},"additionalProperties":false}

Responses
  • Status 200 - application/json

    Example
    {"value":"Team 1","properties":{"leader":{"name":"Leader Name","email":"lname@example.com"},"members":42,"description":"The team's description","founded":"2016-06-06"},"config":{"scope":{"projects":[10001,10020]},"attributes":[]}}

    Returned if the option has been successfully created.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-field-option#","title":"Issue Field Option","type":"object","properties":{"id":{"type":"integer"},"value":{"type":"string"},"properties":{"title":"Object Node","type":"object"},"config":{"title":"Issue Field Option Config","type":"object","properties":{"scope":{"title":"Issue Field Option Scope","type":"object","properties":{"projects":{"type":"array","items":{"type":"integer"}}},"additionalProperties":false},"attributes":{"type":"array","items":{"type":"string","enum":["notSelectable"]}}},"additionalProperties":false}},"additionalProperties":false}

  • Status 400
    Returned if the option is invalid.
  • Status 403
    Returned if the request is not authenticated as a JIRA administrator nor the add-on that provided the field.
  • Status 404
    Returned if the field does not exist or does not support options.

Returns all options defined for a select list issue field, for a given field key. Only JIRA administrators or the add-ons that provided the field may use this method.

The list of options will be ordered by the option Id and paginated.

Request
query parameters
parametertypedescription
startAtlong

The starting index of the returned objects. Base index: 0.

maxResultsint

The maximum number of items to return per page. Default: 50.

Responses
  • Status 200 - application/json

    Example
    {"self":"http://www.example.com/jira/rest/api/2/field/fieldKey/option?startAt=0&maxResults=1","nextPage":"http://www.example.com/jira/rest/api/2/field/fieldKey/option?startAt=1&maxResults=1","maxResults":1,"startAt":0,"total":10,"isLast":false,"values":[{"id":1,"value":"Team 1","properties":{"leader":{"name":"Leader Name","email":"lname@example.com"},"members":42,"description":"The team's description","founded":"2016-06-06"},"config":{"scope":{"projects":[10001,10020]},"attributes":[]}}]}

    Returned if the request is successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/page-of-issue-field-option#","title":"Page of Issue Field Option","type":"object","properties":{"self":{"type":"string","format":"uri"},"nextPage":{"type":"string","format":"uri"},"maxResults":{"type":"integer"},"startAt":{"type":"integer"},"total":{"type":"integer"},"isLast":{"type":"boolean"},"values":{"type":"array","items":{"title":"Issue Field Option","type":"object","properties":{"id":{"type":"integer"},"value":{"type":"string"},"properties":{"title":"Object Node","type":"object"},"config":{"title":"Issue Field Option Config","type":"object","properties":{"scope":{"title":"Issue Field Option Scope","type":"object","properties":{"projects":{"type":"array","items":{"type":"integer"}}},"additionalProperties":false},"attributes":{"type":"array","items":{"type":"string","enum":["notSelectable"]}}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false,"required":["maxResults","startAt"]}

  • Status 403
    Returned if the request is not authenticated as the JIRA administrator nor the add-on that provided the field.
  • Status 404
    Returned if the field does not exist or does not support options.

Creates or updates an option for a select list issue field, for a given field key and option Id. Only JIRA administrators or the add-ons that provided the field may use this method.

Request

Example
{"id":1,"value":"Team 1","properties":{"leader":{"name":"Leader Name","email":"lname@example.com"},"members":42,"description":"The team's description","founded":"2016-06-06"},"config":{"scope":{"projects":[10001,10020]},"attributes":[]}}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-field-option#","title":"Issue Field Option","type":"object","properties":{"id":{"type":"integer"},"value":{"type":"string"},"properties":{"title":"Object Node","type":"object"},"config":{"title":"Issue Field Option Config","type":"object","properties":{"scope":{"title":"Issue Field Option Scope","type":"object","properties":{"projects":{"type":"array","items":{"type":"integer"}}},"additionalProperties":false},"attributes":{"type":"array","items":{"type":"string","enum":["notSelectable"]}}},"additionalProperties":false}},"additionalProperties":false}

Responses
  • Status 200 - application/json

    Example
    {"id":1,"value":"Team 1","properties":{"leader":{"name":"Leader Name","email":"lname@example.com"},"members":42,"description":"The team's description","founded":"2016-06-06"},"config":{"scope":{"projects":[10001,10020]},"attributes":[]}}

    Returned if the option has been successfully created.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-field-option#","title":"Issue Field Option","type":"object","properties":{"id":{"type":"integer"},"value":{"type":"string"},"properties":{"title":"Object Node","type":"object"},"config":{"title":"Issue Field Option Config","type":"object","properties":{"scope":{"title":"Issue Field Option Scope","type":"object","properties":{"projects":{"type":"array","items":{"type":"integer"}}},"additionalProperties":false},"attributes":{"type":"array","items":{"type":"string","enum":["notSelectable"]}}},"additionalProperties":false}},"additionalProperties":false}

  • Status 400
    Returned if the option is invalid, or the option Id does not match the optionId path parameter.
  • Status 403
    Returned if the request is not authenticated as a JIRA administrator nor the add-on that provided the field.
  • Status 404
    Returned if field does not exist.

Returns an option for a select list issue field, for a given field key and option Id. Only JIRA administrators or the add-on that provided the field may use this method.

Responses
  • Status 200 - application/json

    Example
    {"id":1,"value":"Team 1","properties":{"leader":{"name":"Leader Name","email":"lname@example.com"},"members":42,"description":"The team's description","founded":"2016-06-06"},"config":{"scope":{"projects":[10001,10020]},"attributes":[]}}

    Returned if the request is successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-field-option#","title":"Issue Field Option","type":"object","properties":{"id":{"type":"integer"},"value":{"type":"string"},"properties":{"title":"Object Node","type":"object"},"config":{"title":"Issue Field Option Config","type":"object","properties":{"scope":{"title":"Issue Field Option Scope","type":"object","properties":{"projects":{"type":"array","items":{"type":"integer"}}},"additionalProperties":false},"attributes":{"type":"array","items":{"type":"string","enum":["notSelectable"]}}},"additionalProperties":false}},"additionalProperties":false}

  • Status 403
    Returned if the request is not authenticated as the JIRA administrator nor the add-on that provided the field.
  • Status 404
    Returned if the field does not exist or does not support options.

Deletes an option from a select list issue field, for a given field key and option Id. Only JIRA administrators or the add-ons that provided the field may use this method.

Responses
  • Status 204
    Returned if the field option has been successfully removed.
  • Status 403
    Returned if the request is not authenticated as a JIRA administrator nor the add-on that provided the field.
  • Status 404
    Returned if field does not exist or the option does not exist.
  • Status 409
    Returned if the option is selected for the field in any issue.

Removes an option from issues that it is set on. Issues may be narrowed down by a JQL filter. A replacement option may be specified.

This is an asynchronous method.

Request
query parameters
parametertypedescription
replaceWithlong

The replacement option.

jqlstring

The jql filter to narrow down the set of issues that should be affected.

Responses
  • Status 400
    Returned if the JQL query is invalid.
  • Status 303

    Example
    {"self":"http://www.example.com/jira/rest/api/2/task/1","id":"1","description":"Remove option 1 from issues matched by '*', and replace with option 3","status":"COMPLETE","result":{"modifiedIssues":[10001,10010],"unmodifiedIssues":[10005],"errors":{"errors":{},"errorMessages":["Option 2 cannot be set on issue MKY-5 as it is not in the correct scope"]}},"elapsedRuntime":42}

    Returned if the request is successful. Follow the "location" header to get the task progress.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/task-progress-of-remove-option-from-issues-result#","title":"Task Progress of Remove Option From Issues Result","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"description":"Description of the task","type":"string"},"status":{"description":"Current status of the task","type":"string","enum":["ENQUEUED","RUNNING","COMPLETE","FAILED","CANCEL_REQUESTED","CANCELLED","DEAD"]},"message":{"description":"Message regarding the current progress","type":"string"},"result":{"title":"Remove Option From Issues Result","description":"The eventual result, will be available when the task is finished successfully","type":"object","properties":{"modifiedIssues":{"description":"IDs of issues that were successfully modified","type":"array","items":{"type":"integer"}},"unmodifiedIssues":{"description":"IDs of issues that could not be changed due to errors","type":"array","items":{"type":"integer"}},"errors":{"title":"Simple Error Collection","description":"A collection of errors related to issues that could not be changed. The collection size is limited, which means not all errors will be returned if there are a lot of them.","type":"object","properties":{"errors":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"errorMessages":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"additionalProperties":false},"submittedBy":{"description":"Id of the user that submitted the task","type":"integer"},"progress":{"description":"The progress percentage (from 0 to 100)","type":"integer"},"elapsedRuntime":{"description":"How much time did running the task take (so far, this is updated in real time), in milliseconds","type":"integer"},"submitted":{"description":"The timestamp of when the task was submitted","type":"string"},"started":{"description":"The timestamp of when the task was started","type":"string"},"finished":{"description":"The timestamp of when the task processing was finished","type":"string"},"lastUpdate":{"description":"The timestamp of when the task progress was last updated","type":"string"}},"additionalProperties":false,"required":["self","id","status","submittedBy","progress","elapsedRuntime","submitted","started","lastUpdate"]}

  • Status 404
    Returned if the field does not exist or does not support options, or if the options to be replaced do not exist.

Returns the options defined for a select list issue field that are available to the currently logged-in user and can be assigned to an issue, for a given field key. Options which are not selectable are not returned. The list of options will be paginated.

Request
query parameters
parametertypedescription
startAtlong

The starting index of the returned objects. Base index: 0.

maxResultsint

The maximum number of items to return per page. Default: 50.

projectIdlong

Only options available for this project will be returned.

Responses
  • Status 200 - application/json

    Example
    {"self":"http://www.example.com/jira/rest/api/2/field/fieldKey/option/suggestions?startAt=0&maxResults=1","nextPage":"http://www.example.com/jira/rest/api/2/field/fieldKey/option/suggestions?startAt=1&maxResults=1","maxResults":1,"startAt":0,"total":10,"isLast":false,"values":[{"id":1,"value":"Team 1","properties":{"leader":{"name":"Leader Name","email":"lname@example.com"},"members":42,"description":"The team's description","founded":"2016-06-06"}}]}

    Returned if the request is successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/page-of-issue-field-option#","title":"Page of Issue Field Option","type":"object","properties":{"self":{"type":"string","format":"uri"},"nextPage":{"type":"string","format":"uri"},"maxResults":{"type":"integer"},"startAt":{"type":"integer"},"total":{"type":"integer"},"isLast":{"type":"boolean"},"values":{"type":"array","items":{"title":"Issue Field Option","type":"object","properties":{"id":{"type":"integer"},"value":{"type":"string"},"properties":{"title":"Object Node","type":"object"},"config":{"title":"Issue Field Option Config","type":"object","properties":{"scope":{"title":"Issue Field Option Scope","type":"object","properties":{"projects":{"type":"array","items":{"type":"integer"}}},"additionalProperties":false},"attributes":{"type":"array","items":{"type":"string","enum":["notSelectable"]}}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false,"required":["maxResults","startAt"]}

  • Status 404
    Returned if the field does not exist or does not support options.

Returns the options defined for a select list issue field that are available to the currently logged-in user, for a given field key. The list of options will be paginated.

Request
query parameters
parametertypedescription
startAtlong

The starting index of the returned objects. Base index: 0.

maxResultsint

The maximum number of items to return per page. Default: 50.

projectIdlong

Only options available for this project will be returned.

Responses
  • Status 200 - application/json

    Example
    {"self":"http://www.example.com/jira/rest/api/2/field/fieldKey/option/suggestions?startAt=0&maxResults=1","nextPage":"http://www.example.com/jira/rest/api/2/field/fieldKey/option/suggestions?startAt=1&maxResults=1","maxResults":1,"startAt":0,"total":10,"isLast":false,"values":[{"id":1,"value":"Team 1","properties":{"leader":{"name":"Leader Name","email":"lname@example.com"},"members":42,"description":"The team's description","founded":"2016-06-06"}}]}

    Returned if the request is successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/page-of-issue-field-option#","title":"Page of Issue Field Option","type":"object","properties":{"self":{"type":"string","format":"uri"},"nextPage":{"type":"string","format":"uri"},"maxResults":{"type":"integer"},"startAt":{"type":"integer"},"total":{"type":"integer"},"isLast":{"type":"boolean"},"values":{"type":"array","items":{"title":"Issue Field Option","type":"object","properties":{"id":{"type":"integer"},"value":{"type":"string"},"properties":{"title":"Object Node","type":"object"},"config":{"title":"Issue Field Option Config","type":"object","properties":{"scope":{"title":"Issue Field Option Scope","type":"object","properties":{"projects":{"type":"array","items":{"type":"integer"}}},"additionalProperties":false},"attributes":{"type":"array","items":{"type":"string","enum":["notSelectable"]}}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false,"required":["maxResults","startAt"]}

  • Status 404
    Returned if the field does not exist or does not support options.

api/2/filter

Resource for searches.

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

Request
query parameters
parametertypedescription
expandstring

the parameters to expand

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/filter#","title":"Filter","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"owner":{"$ref":"#/definitions/user"},"jql":{"type":"string"},"viewUrl":{"type":"string","format":"uri"},"searchUrl":{"type":"string","format":"uri"},"favourite":{"type":"boolean"},"sharePermissions":{"type":"array","items":{"title":"Filter Permission","type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"project":{"title":"Project","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"additionalProperties":false},"role":{"title":"Project Role","type":"object","properties":{"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}},"sharedUsers":{"title":"User Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/user"}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]},"subscriptions":{"title":"Filter Subscription Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"title":"Filter Subscription","type":"object","properties":{"id":{"type":"integer"},"user":{"$ref":"#/definitions/user"},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]}},"definitions":{"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false},"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/group"}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["favourite"]}

Responses
  • Status 200 - application/json

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"jql":"type = Bug and resolution is empty","viewUrl":"http://www.example.com/jira/issues/?filter=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":0,"start-index":0,"end-index":0}}

    Returns a JSON representation of a filter

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/filter#","title":"Filter","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"owner":{"$ref":"#/definitions/user"},"jql":{"type":"string"},"viewUrl":{"type":"string","format":"uri"},"searchUrl":{"type":"string","format":"uri"},"favourite":{"type":"boolean"},"sharePermissions":{"type":"array","items":{"title":"Filter Permission","type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"project":{"title":"Project","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"additionalProperties":false},"role":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}},"sharedUsers":{"title":"User Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/user"}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]},"subscriptions":{"title":"Filter Subscription Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"title":"Filter Subscription","type":"object","properties":{"id":{"type":"integer"},"user":{"$ref":"#/definitions/user"},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]}},"definitions":{"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/group"}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["favourite"]}

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

Updates an existing filter, and returns its new value.

Request
query parameters
parametertypedescription
expandstring

the parameters to expand

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/filter#","title":"Filter","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"owner":{"$ref":"#/definitions/user"},"jql":{"type":"string"},"viewUrl":{"type":"string","format":"uri"},"searchUrl":{"type":"string","format":"uri"},"favourite":{"type":"boolean"},"sharePermissions":{"type":"array","items":{"title":"Filter Permission","type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"project":{"title":"Project","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"additionalProperties":false},"role":{"title":"Project Role","type":"object","properties":{"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}},"sharedUsers":{"title":"User Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/user"}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]},"subscriptions":{"title":"Filter Subscription Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"title":"Filter Subscription","type":"object","properties":{"id":{"type":"integer"},"user":{"$ref":"#/definitions/user"},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]}},"definitions":{"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false},"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/group"}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["favourite"]}

Responses
  • Status 200 - application/json

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"jql":"type = Bug and resolution is empty","viewUrl":"http://www.example.com/jira/issues/?filter=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":0,"start-index":0,"end-index":0}}

    Returns a JSON representation of a filter

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/filter#","title":"Filter","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"owner":{"$ref":"#/definitions/user"},"jql":{"type":"string"},"viewUrl":{"type":"string","format":"uri"},"searchUrl":{"type":"string","format":"uri"},"favourite":{"type":"boolean"},"sharePermissions":{"type":"array","items":{"title":"Filter Permission","type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"project":{"title":"Project","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"additionalProperties":false},"role":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}},"sharedUsers":{"title":"User Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/user"}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]},"subscriptions":{"title":"Filter Subscription Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"title":"Filter Subscription","type":"object","properties":{"id":{"type":"integer"},"user":{"$ref":"#/definitions/user"},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]}},"definitions":{"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/group"}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["favourite"]}

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

Delete a filter.

Responses
  • Status 400
    Returned if an error occurs.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 204
    Returned if the filter was removed successfully.

Returns a filter given an id

Request
query parameters
parametertypedescription
expandstring

the parameters to expand

Responses
  • Status 200 - application/json

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"jql":"type = Bug and resolution is empty","viewUrl":"http://www.example.com/jira/issues/?filter=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":0,"start-index":0,"end-index":0}}

    Returns a JSON representation of a filter

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/filter#","title":"Filter","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"owner":{"$ref":"#/definitions/user"},"jql":{"type":"string"},"viewUrl":{"type":"string","format":"uri"},"searchUrl":{"type":"string","format":"uri"},"favourite":{"type":"boolean"},"sharePermissions":{"type":"array","items":{"title":"Filter Permission","type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"project":{"title":"Project","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"additionalProperties":false},"role":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}},"sharedUsers":{"title":"User Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/user"}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]},"subscriptions":{"title":"Filter Subscription Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"title":"Filter Subscription","type":"object","properties":{"id":{"type":"integer"},"user":{"$ref":"#/definitions/user"},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]}},"definitions":{"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/group"}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["favourite"]}

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

Sets the default columns for the given filter.

Request
Responses
  • Status 200
    Returned when the columns are saved successfully
  • Status 500
    Returned if an error occurs while retrieving the column configuration.

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

Responses
  • Status 500
    Returned if an error occurs while retrieving the column configuration.
  • Status 204
    Returned when the columns are reset/removed successfully

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

Responses
  • Status 200 - application/json
    Returns a list of columns for configured for the given user

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-column-layout-item#","title":"List of Column Layout Item","type":"array","items":{"title":"Column Layout Item","type":"object","properties":{"columnHeadingKey":{"type":"string"},"id":{"type":"string"},"navigableField":{"title":"Navigable Field","type":"object","properties":{"columnCssClass":{"type":"string"},"columnHeadingKey":{"type":"string"},"defaultSortOrder":{"type":"string"},"hiddenFieldId":{"type":"string"},"sortComparatorSource":{"title":"Field Comparator Source","type":"object"},"sorter":{"title":"Lucene Field Sorter","type":"object","properties":{"comparator":{"type":"object"},"documentConstant":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"position":{"type":"integer"}},"additionalProperties":false,"required":["position"]}}

  • Status 500
    Returned if an error occurs while retrieving the column configuration.
  • Status 404
    Returned if the filter does not have any columns.

Returns all share permissions of the given filter.

Responses
  • Status 200 - application/json

    Example
    [{"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":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","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"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}}},{"id":10010,"type":"project","project":{"self":"http://www.example.com/jira/rest/api/2/project/MKY","id":"10002","key":"MKY","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10002","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10002","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10002","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10002"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"role":{"self":"http://www.example.com/jira/rest/api/2/project/MKY/role/10360","name":"Developers","id":10360,"description":"A project role that represents developers in a project","actors":[{"id":10240,"displayName":"jira-developers","type":"atlassian-group-role-actor","name":"jira-developers"},{"id":10241,"displayName":"Fred F. User","type":"atlassian-user-role-actor","name":"fred"}]}},{"id":10010,"type":"group","group":{"name":"jira-administrators","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-administrators"}}]

    Returned if successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-filter-permission#","title":"List of Filter Permission","type":"array","items":{"title":"Filter Permission","type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"project":{"title":"Project","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"additionalProperties":false},"role":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false},"definitions":{"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/group"}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}

  • Status 401
    Returned if user is not logged in.
  • Status 404
    Returned when filter with given id does not exist or when the user does not have permissions to view the filter. .

Adds a share permissions to the given filter. Adding a global permission removes all previous permissions from the filter.

Request

Example
{"type":"group","groupname":"jira-administrators"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/share-permission-input#","title":"Share Permission Input","type":"object","properties":{"type":{"type":"string"},"projectId":{"type":"string"},"groupname":{"type":"string"},"projectRoleId":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 201 - application/json

    Example
    [{"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":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","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"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}}},{"id":10010,"type":"project","project":{"self":"http://www.example.com/jira/rest/api/2/project/MKY","id":"10002","key":"MKY","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10002","24x24":"http://www.example.com/jira/secure/projectavatar?size=small&pid=10002","16x16":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10002","32x32":"http://www.example.com/jira/secure/projectavatar?size=medium&pid=10002"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"role":{"self":"http://www.example.com/jira/rest/api/2/project/MKY/role/10360","name":"Developers","id":10360,"description":"A project role that represents developers in a project","actors":[{"id":10240,"displayName":"jira-developers","type":"atlassian-group-role-actor","name":"jira-developers"},{"id":10241,"displayName":"Fred F. User","type":"atlassian-user-role-actor","name":"fred"}]}},{"id":10010,"type":"group","group":{"name":"jira-administrators","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-administrators"}}]

    Returned if successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-filter-permission#","title":"List of Filter Permission","type":"array","items":{"title":"Filter Permission","type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"project":{"title":"Project","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"additionalProperties":false},"role":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false},"definitions":{"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/group"}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}

  • Status 400
    Returned given permission input bean is invalid or when user does not have the permission to share filters or when the user cannot edit the given filter.
  • Status 401
    Returned if user is not logged in.
  • Status 404
    Returned when filter with given id does not exist or when the user does not have permissions to view the filter. .

Returns a single share permission of the given filter.

Responses
  • Status 200 - application/json

    Example
    {"id":10000,"type":"global"}

    Returned if successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/filter-permission#","title":"Filter Permission","type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"project":{"title":"Project","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"additionalProperties":false},"role":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"group":{"$ref":"#/definitions/group"}},"definitions":{"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/group"}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

  • Status 401
    Returned if user is not logged in.
  • Status 404
    Returned when filter or permission with given id does not exist or when the user does not have permissions to view the filter.

Removes a share permissions from the given filter.

Responses
  • Status 200 - application/json
  • Status 204
    Returned if successful.
  • Status 404
    Returned when filter or permission with given id does not exist or when the user does not have permissions to view the filter.

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

Responses
  • Status 200 - application/json

    Example
    {"scope":"GLOBAL"}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/default-share-scope#","title":"Default Share Scope","type":"object","properties":{"scope":{"type":"string","enum":["GLOBAL","AUTHENTICATED","PRIVATE"]}},"additionalProperties":false}

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

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

Request

Example
{"scope":"GLOBAL"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/default-share-scope#","title":"Default Share Scope","type":"object","properties":{"scope":{"type":"string","enum":["GLOBAL","AUTHENTICATED","PRIVATE"]}},"additionalProperties":false}

Responses
  • Status 200 - application/json

    Example
    {"scope":"GLOBAL"}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/default-share-scope#","title":"Default Share Scope","type":"object","properties":{"scope":{"type":"string","enum":["GLOBAL","AUTHENTICATED","PRIVATE"]}},"additionalProperties":false}

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

Returns the favourite filters of the logged-in user.

Request
query parameters
parametertypedescription
expandstring

the parameters to expand

Responses
  • Status 200 - application/json

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"jql":"type = Bug and resolution is empty","viewUrl":"http://www.example.com/jira/issues/?filter=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":0,"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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"jql":"assignee = currentUser() and resolution is empty","viewUrl":"http://www.example.com/jira/issues/?filter=10010","searchUrl":"http://www.example.com/jira/rest/api/2/search?jql=assignee+in+%28currentUser%28%29%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":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","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"},"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":0,"start-index":0,"end-index":0}}]

    Returns a JSON representation of a list of filters

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-filter#","title":"List of Filter","type":"array","items":{"title":"Filter","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"owner":{"$ref":"#/definitions/user"},"jql":{"type":"string"},"viewUrl":{"type":"string","format":"uri"},"searchUrl":{"type":"string","format":"uri"},"favourite":{"type":"boolean"},"sharePermissions":{"type":"array","items":{"title":"Filter Permission","type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"project":{"title":"Project","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"additionalProperties":false},"role":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}},"sharedUsers":{"title":"User Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/user"}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]},"subscriptions":{"title":"Filter Subscription Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"title":"Filter Subscription","type":"object","properties":{"id":{"type":"integer"},"user":{"$ref":"#/definitions/user"},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]}},"additionalProperties":false,"required":["favourite"]},"definitions":{"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/group"}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}

Returns the user filters, which include personal and favourite filters (if {@code includeFavourites} is true).

Request
query parameters
parametertypedescription
expandstring

the parameters to expand

includeFavouritesboolean
Responses
  • Status 200 - application/json

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"jql":"type = Bug and resolution is empty","viewUrl":"http://www.example.com/jira/issues/?filter=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":0,"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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"jql":"assignee = currentUser() and resolution is empty","viewUrl":"http://www.example.com/jira/issues/?filter=10010","searchUrl":"http://www.example.com/jira/rest/api/2/search?jql=assignee+in+%28currentUser%28%29%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":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","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"},"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":0,"start-index":0,"end-index":0}}]

    Returns a JSON representation of a list of filters

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-filter#","title":"List of Filter","type":"array","items":{"title":"Filter","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"owner":{"$ref":"#/definitions/user"},"jql":{"type":"string"},"viewUrl":{"type":"string","format":"uri"},"searchUrl":{"type":"string","format":"uri"},"favourite":{"type":"boolean"},"sharePermissions":{"type":"array","items":{"title":"Filter Permission","type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"project":{"title":"Project","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"additionalProperties":false},"role":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}},"sharedUsers":{"title":"User Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/user"}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]},"subscriptions":{"title":"Filter Subscription Bean List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"title":"Filter Subscription","type":"object","properties":{"id":{"type":"integer"},"user":{"$ref":"#/definitions/user"},"group":{"$ref":"#/definitions/group"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]}},"additionalProperties":false,"required":["favourite"]},"definitions":{"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/definitions/group"}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}

api/2/group

Creates a group by given group parameter

Returns REST representation for the requested group.

Request

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/add-group#","title":"Add Group","type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 201 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/group#","title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"},"users":{"title":"Paged List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]},"expand":{"type":"string"}},"additionalProperties":false}

  • Status 400
    Returned if user requested an empty group name or group already exists
  • Status 401
    Returned if the current user is not authenticated.
  • Status 403
    Returned if the current user does not have administrator permissions.

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.

This resource is deprecated, please use group/member API instead.

Request
query parameters
parametertypedescription
groupnamestring

A name of requested group.

expandstring

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

Responses
  • Status - application/json

Deletes a group by given group parameter.

Returns no content

Request
query parameters
parametertypedescription
groupnamestring

(mandatory) The name of the group to delete.

swapGroupstring

If you delete a group and content is restricted to that group, the content will be hidden from all users. To prevent this, use this parameter to specify a different group to transfer the restrictions (comments and worklogs only) to.

Responses
  • Status 200 - application/json
    Returned if the group was deleted.
  • Status 400
    Returned if user requested an group that does not exist.
  • Status 401
    Returned if the current user is not authenticated.
  • Status 403
    Returned if the current user does not have administrator permissions.
  • Status 404
    Returned if the requested group was not found.

This resource returns a paginated list of users who are members of the specified group and its subgroups. Users in the page are ordered by user names. User of this resource is required to have sysadmin or admin permissions.

Request
query parameters
parametertypedescription
groupnamestring

a name of the group for which members will be returned.

includeInactiveUsersboolean

Default: false

inactive users will be included in the response if set to true.

startAtlong

Default: 0

the index of the first user in group to return (0 based).

maxResultsint

Default: 50

the maximum number of users to return (max 50).

Responses
  • Status 200 - application/json

    Example
    {"self":"http://www.example.com/jira/rest/api/2/group/member?groupname=jira-administrators&includeInactiveUsers=false&startAt=2&maxResults=2","nextPage":"http://www.example.com/jira/rest/api/2/group/member?groupname=jira-administrators&includeInactiveUsers=false&startAt=4&maxResults=2","maxResults":2,"startAt":3,"total":5,"isLast":false,"values":[{"self":"http://example/jira/rest/api/2/user?username=fred","name":"Fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","emailAddress":"fred@atlassian.com","avatarUrls":{},"displayName":"Fred","active":true,"timeZone":"Australia/Sydney"},{"self":"http://example/jira/rest/api/2/user?username=barney","name":"Barney","key":"barney","emailAddress":"barney@atlassian.com","avatarUrls":{},"displayName":"Barney","active":false,"timeZone":"Australia/Sydney"}]}

    Paginated list of users in the group.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/group#","title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"},"users":{"title":"Paged List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]},"expand":{"type":"string"}},"additionalProperties":false}

  • Status 400
    Returned if the name of the provided group is empty
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the calling user is not admin or sysadmin
  • Status 404
    Returned if the specified group does not exist

Adds given user to a group.

Returns the current state of the group.

Request
query parameters
parametertypedescription
groupnamestring

A name of requested group.

Example
{"name":"charlie"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/update-user-to-group#","title":"Update User To Group","type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 201 - application/json
    Returns full representation of a JIRA group in JSON format.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/group#","title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"},"users":{"title":"Paged List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"start-index":{"type":"integer"},"end-index":{"type":"integer"},"items":{"type":"array","items":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}}},"additionalProperties":false,"required":["size","max-results","start-index","end-index"]},"expand":{"type":"string"}},"additionalProperties":false}

  • Status 400
    Returned if user requested an empty group name or the user already belongs to the group.
  • Status 401
    Returned if the current user is not authenticated.
  • Status 403
    Returned if the current user does not have administrator permissions.
  • Status 404
    Returned if the requested group was not found or requested user was not found.

Removes given user from a group.

Returns no content

Request
query parameters
parametertypedescription
groupnamestring

A name of requested group.

usernamestring

User to remove from a group

Responses
  • Status 200 - application/json
    If the user was removed from the group.
  • Status 400
    Returned if user requested an empty group name
  • Status 401
    Returned if the current user is not authenticated.
  • Status 403
    Returned if the current user does not have administrator permissions.
  • Status 404
    Returned if the requested group was not found or the requested user wan not found

api/2/groups

REST endpoint for searching groups in a group picker

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
parametertypedescription
querystring

a String to match groups agains

excludestring
maxResultsint
userNamestring
Responses
  • Status 200 - application/json

    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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/group-suggestions#","title":"Group Suggestions","type":"object","properties":{"header":{"type":"string"},"total":{"type":"integer"},"groups":{"type":"array","items":{"title":"Group Suggestion","type":"object","properties":{"name":{"type":"string"},"html":{"type":"string"},"labels":{"type":"array","items":{"title":"Group Label","type":"object","properties":{"text":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","enum":["ADMIN","SINGLE","MULTIPLE"]}},"additionalProperties":false}}},"additionalProperties":false}}},"additionalProperties":false}

api/2/groupuserpicker

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

Request
query parameters
parametertypedescription
querystring

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

maxResultsint

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.

showAvatarboolean
fieldIdstring

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

projectIdstring

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.

issueTypeIdstring

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.

Responses
  • Status 200

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/users-and-groups#","title":"Users And Groups","type":"object","properties":{"users":{"title":"User Picker Results","type":"object","properties":{"users":{"type":"array","items":{"title":"User Picker User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"html":{"type":"string"},"displayName":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}},"total":{"type":"integer"},"header":{"type":"string"}},"additionalProperties":false},"groups":{"title":"Group Suggestions","type":"object","properties":{"header":{"type":"string"},"total":{"type":"integer"},"groups":{"type":"array","items":{"title":"Group Suggestion","type":"object","properties":{"name":{"type":"string"},"html":{"type":"string"},"labels":{"type":"array","items":{"title":"Group Label","type":"object","properties":{"text":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","enum":["ADMIN","SINGLE","MULTIPLE"]}},"additionalProperties":false}}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false}

api/2/issue

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.

Request

Example
{"update":{"worklog":[{"add":{"timeSpent":"60m","started":"2011-07-05T11:05:00.000+0000"}}]},"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_30000":["10000","10002"],"customfield_80000":{"value":"red"},"customfield_20000":"06/Jul/11 3:25 PM","customfield_40000":"this is a text field","customfield_70000":["jira-administrators","jira-software-users"],"customfield_60000":"jira-software-users","customfield_50000":"this is a text area. big text.","customfield_10000":"09/Jun/81"}}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-update#","title":"Issue Update","type":"object","properties":{"transition":{"title":"Transition","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"to":{"title":"Status","type":"object","properties":{"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"hasScreen":{"type":"boolean"},"fields":{"type":"object","patternProperties":{".+":{"title":"Field Meta","type":"object","properties":{"required":{"type":"boolean"},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false},"name":{"type":"string"},"key":{"type":"string"},"autoCompleteUrl":{"type":"string"},"hasDefaultValue":{"type":"boolean"},"operations":{"type":"array","items":{"type":"string"}},"allowedValues":{"type":"array","items":{}},"defaultValue":{}},"additionalProperties":false,"required":["required"]}},"additionalProperties":false}},"additionalProperties":false},"fields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"update":{"type":"object","patternProperties":{".+":{"type":"array","items":{"title":"Field Operation","type":"object"}}},"additionalProperties":false},"historyMetadata":{"title":"History Metadata","type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"descriptionKey":{"type":"string"},"activityDescription":{"type":"string"},"activityDescriptionKey":{"type":"string"},"emailDescription":{"type":"string"},"emailDescriptionKey":{"type":"string"},"actor":{"$ref":"#/definitions/history-metadata-participant"},"generator":{"$ref":"#/definitions/history-metadata-participant"},"cause":{"$ref":"#/definitions/history-metadata-participant"},"extraData":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"definitions":{"history-metadata-participant":{"title":"History Metadata Participant","type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"displayNameKey":{"type":"string"},"type":{"type":"string"},"avatarUrl":{"type":"string"},"url":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

Responses
  • Status 201 - application/json

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

    Returns a link to the created issue.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-create-response#","title":"Issue Create Response","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"self":{"type":"string"}},"additionalProperties":false}

  • Status 400

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

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

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

Request

Example
{"issueUpdates":[{"update":{"worklog":[{"add":{"timeSpent":"60m","started":"2011-07-05T11:05:00.000+0000"}}]},"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_30000":["10000","10002"],"customfield_80000":{"value":"red"},"customfield_20000":"06/Jul/11 3:25 PM","customfield_40000":"this is a text field","customfield_70000":["jira-administrators","jira-software-users"],"customfield_60000":"jira-software-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_30000":["10000","10002"],"customfield_80000":{"value":"red"},"customfield_20000":"06/Jul/11 3:25 PM","customfield_40000":"this is a text field","customfield_70000":["jira-administrators","jira-software-users"],"customfield_60000":"jira-software-users","customfield_50000":"this is a text area. big text.","customfield_10000":"09/Jun/81"}}]}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issues-update#","title":"Issues Update","type":"object","properties":{"issueUpdates":{"type":"array","items":{"title":"Issue Update","type":"object","properties":{"transition":{"title":"Transition","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"to":{"title":"Status","type":"object","properties":{"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"hasScreen":{"type":"boolean"},"fields":{"type":"object","patternProperties":{".+":{"title":"Field Meta","type":"object","properties":{"required":{"type":"boolean"},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false},"name":{"type":"string"},"key":{"type":"string"},"autoCompleteUrl":{"type":"string"},"hasDefaultValue":{"type":"boolean"},"operations":{"type":"array","items":{"type":"string"}},"allowedValues":{"type":"array","items":{}},"defaultValue":{}},"additionalProperties":false,"required":["required"]}},"additionalProperties":false}},"additionalProperties":false},"fields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"update":{"type":"object","patternProperties":{".+":{"type":"array","items":{"title":"Field Operation","type":"object"}}},"additionalProperties":false},"historyMetadata":{"title":"History Metadata","type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"descriptionKey":{"type":"string"},"activityDescription":{"type":"string"},"activityDescriptionKey":{"type":"string"},"emailDescription":{"type":"string"},"emailDescriptionKey":{"type":"string"},"actor":{"$ref":"#/definitions/history-metadata-participant"},"generator":{"$ref":"#/definitions/history-metadata-participant"},"cause":{"$ref":"#/definitions/history-metadata-participant"},"extraData":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"additionalProperties":false}}},"definitions":{"history-metadata-participant":{"title":"History Metadata Participant","type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"displayNameKey":{"type":"string"},"type":{"type":"string"},"avatarUrl":{"type":"string"},"url":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

Responses
  • Status 201 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-create-response#","title":"Issue Create Response","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"self":{"type":"string"}},"additionalProperties":false}

  • Status 400

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/bulk-operation-error-result#","title":"Bulk Operation Error Result","type":"object","properties":{"status":{"type":"integer"},"elementErrors":{"title":"Error Collection","type":"object","properties":{"errorMessages":{"type":"array","items":{"type":"string"}},"errors":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"status":{"type":"integer"}},"additionalProperties":false},"failedElementNumber":{"type":"integer"}},"additionalProperties":false}

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

The properties param is similar to fields and specifies a comma-separated list of issue properties to include. Unlike fields, properties are not included by default. To include them all send ?properties=*all. You can also include only specified properties or exclude some properties with a minus (-) sign.

  • *all - include all properties
  • *all, -prop1 - include all properties except prop1
  • prop1, prop1 - include prop1 and prop2 properties

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.

The expand param is used to include, hidden by default, parts of response. This can be used to include:

  • renderedFields - field values in HTML format
  • names - display name of each field
  • schema - schema for each field which describes a type of the field
  • transitions - all possible transitions for the given issue
  • operations - all possibles operations which may be applied on issue
  • editmeta - information about how each field may be edited. It contains field's schema as well.
  • changelog - history of all changes of the given issue
  • versionedRepresentations - REST representations of all fields. Some field may contain more recent versions. RESET representations are numbered. The greatest number always represents the most recent version. It is recommended that the most recent version is used. version for these fields which provide a more recent REST representation. After including versionedRepresentations "fields" field become hidden.
The updateHistory param adds the issues retrieved by this method to the current user's issue history, if set to true (by default, the issue history does not include issues retrieved via the REST API). You can view the issue history in the JIRA application, via the Issues dropdown or by using the lastViewed JQL field in an issue search.

Request
query parameters
parametertypedescription
fieldsstring

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

expandstring
propertiesstring

the list of properties to return for the issue. By default no properties are returned.

fieldsByKeysboolean

if true then fields in issues will be referenced by keys instead of ids

updateHistoryboolean
Responses
  • Status 200 - application/json

    Example
    {"expand":"renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations","id":"10002","self":"http://www.example.com/jira/rest/api/2/issue/10002","key":"EX-1","names":{"watcher":"watcher","attachment":"attachment","sub-tasks":"sub-tasks","description":"description","project":"project","comment":"comment","issuelinks":"issuelinks","worklog":"worklog","updated":"updated","timetracking":"timetracking"},"schema":{},"fields":{"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}]},"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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"created":"2017-03-08T03:29:43.525+0000","size":23123,"mimeType":"image/jpeg","content":"http://www.example.com/jira/attachments/10000","thumbnail":"http://www.example.com/jira/secure/thumbnail/10000"}],"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"}}}}],"description":"example bug report","project":{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","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"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}},"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":"2017-03-08T03:29:43.383+0000","updated":"2017-03-08T03:29:43.383+0000","visibility":{"type":"role","value":"Administrators"}}],"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"}}}}],"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.","updated":"2017-03-08T03:29:43.684+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T03:29:43.684+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}],"updated":1,"timetracking":{"originalEstimate":"10m","remainingEstimate":"3m","timeSpent":"6m","originalEstimateSeconds":600,"remainingEstimateSeconds":200,"timeSpentSeconds":400}}}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue#","title":"Issue","type":"object","properties":{"expand":{"type":"string"},"id":{"type":"string"},"self":{"type":"string","format":"uri"},"key":{"type":"string"},"renderedFields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"properties":{"title":"Properties","type":"object","properties":{"properties":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"names":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"schema":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/json-type"}},"additionalProperties":false},"transitions":{"type":"array","items":{"title":"Transition","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"to":{"title":"Status","type":"object","properties":{"self":{"type":"string"},"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"hasScreen":{"type":"boolean"},"fields":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/field-meta"}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false}},"operations":{"title":"Opsbar","type":"object","properties":{"linkGroups":{"type":"array","items":{"$ref":"#/definitions/link-group"}}},"additionalProperties":false},"editmeta":{"title":"Edit Meta","type":"object","properties":{"fields":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/field-meta"}},"additionalProperties":false}},"additionalProperties":false},"changelog":{"title":"Changelog","type":"object","properties":{"startAt":{"type":"integer"},"maxResults":{"type":"integer"},"total":{"type":"integer"},"histories":{"type":"array","items":{"title":"Change History","type":"object","properties":{"id":{"type":"string"},"author":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]},"created":{"type":"string"},"items":{"type":"array","items":{"title":"Change Item","type":"object","properties":{"field":{"type":"string"},"fieldtype":{"type":"string"},"from":{"type":"string"},"fromString":{"type":"string"},"to":{"type":"string"},"toString":{"type":"string"}},"additionalProperties":false}},"historyMetadata":{"title":"History Metadata","type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"descriptionKey":{"type":"string"},"activityDescription":{"type":"string"},"activityDescriptionKey":{"type":"string"},"emailDescription":{"type":"string"},"emailDescriptionKey":{"type":"string"},"actor":{"$ref":"#/definitions/history-metadata-participant"},"generator":{"$ref":"#/definitions/history-metadata-participant"},"cause":{"$ref":"#/definitions/history-metadata-participant"},"extraData":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false},"versionedRepresentations":{"type":"object","patternProperties":{".+":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false}},"additionalProperties":false},"fieldsToInclude":{"title":"Included Fields","type":"object"},"fields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false}},"definitions":{"field-meta":{"title":"Field Meta","type":"object","properties":{"required":{"type":"boolean"},"schema":{"$ref":"#/definitions/json-type"},"name":{"type":"string"},"key":{"type":"string"},"autoCompleteUrl":{"type":"string"},"hasDefaultValue":{"type":"boolean"},"operations":{"type":"array","items":{"type":"string"}},"allowedValues":{"type":"array","items":{}},"defaultValue":{}},"additionalProperties":false,"required":["required"]},"history-metadata-participant":{"title":"History Metadata Participant","type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"displayNameKey":{"type":"string"},"type":{"type":"string"},"avatarUrl":{"type":"string"},"url":{"type":"string"}},"additionalProperties":false},"json-type":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false},"link-group":{"title":"Link Group","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"header":{"$ref":"#/definitions/simple-link"},"weight":{"type":"integer"},"links":{"type":"array","items":{"$ref":"#/definitions/simple-link"}},"groups":{"type":"array","items":{"$ref":"#/definitions/link-group"}}},"additionalProperties":false},"simple-link":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false}

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

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
parametertypedescription
deleteSubtasksstring

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.

Responses
  • Status 400
    Returned if an error occurs.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 204
    Returned if the issue was removed successfully.
  • Status 403
    Returned if the calling user does not have permission to delete the issue.
  • Status 404
    Returned if the issue does not exist.

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; however connect add-on with admin scope are able to override the screen security.

If the issue cannot be edited in JIRA due to its workflow status (i.e. it is closed), then you will not be able to edit it with this method.

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.

Request
query parameters
parametertypedescription
notifyUsersboolean

Default: true

send the email with notification that the issue was updated to users that watch it. Admin or project admin permissions are required to disable the notification.

overrideScreenSecurityboolean

Default: false

allows to update fields that are not on the screen. Only connect add-on users with admin scope permission are allowed to use this flag.

overrideEditableFlagboolean

Default: false

Updates the issue even if the issue is not editable due to being in a status with jira.issue.editable set to false or missing. Only connect add-on users with admin scope permission are allowed to use this flag.

Example
{"update":{"summary":[{"set":"Bug in business logic"}],"components":[{"set":""}],"timetracking":[{"edit":{"originalEstimate":"1w 1d","remainingEstimate":"4d"}}],"labels":[{"add":"triaged"},{"remove":"blocker"}]},"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"}},"properties":[{"key":"key1","value":'properties' : 'can be set at issue create or update time'},{"key":"key2","value":'and' : 'there can be multiple properties'}]}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-update#","title":"Issue Update","type":"object","properties":{"transition":{"title":"Transition","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"to":{"title":"Status","type":"object","properties":{"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"hasScreen":{"type":"boolean"},"fields":{"type":"object","patternProperties":{".+":{"title":"Field Meta","type":"object","properties":{"required":{"type":"boolean"},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false},"name":{"type":"string"},"key":{"type":"string"},"autoCompleteUrl":{"type":"string"},"hasDefaultValue":{"type":"boolean"},"operations":{"type":"array","items":{"type":"string"}},"allowedValues":{"type":"array","items":{}},"defaultValue":{}},"additionalProperties":false,"required":["required"]}},"additionalProperties":false}},"additionalProperties":false},"fields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"update":{"type":"object","patternProperties":{".+":{"type":"array","items":{"title":"Field Operation","type":"object"}}},"additionalProperties":false},"historyMetadata":{"title":"History Metadata","type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"descriptionKey":{"type":"string"},"activityDescription":{"type":"string"},"activityDescriptionKey":{"type":"string"},"emailDescription":{"type":"string"},"emailDescriptionKey":{"type":"string"},"actor":{"$ref":"#/definitions/history-metadata-participant"},"generator":{"$ref":"#/definitions/history-metadata-participant"},"cause":{"$ref":"#/definitions/history-metadata-participant"},"extraData":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"definitions":{"history-metadata-participant":{"title":"History Metadata Participant","type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"displayNameKey":{"type":"string"},"type":{"type":"string"},"avatarUrl":{"type":"string"},"url":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

Responses
  • Status 400
    Returned if the requested issue update failed.
  • Status 204
    Returned if it updated the issue successfully.
  • Status 403
    Returned if the user tries to disable users notification or override screen security but doesn't have permission to do that.

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.

Request

Example
{"name":"harry"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/user#","title":"User","type":"object","properties":{"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false,"required":["active"]}

Responses
  • Status 400
    Returned if there is a problem with the received user representation.
  • Status 401
    Returned if the calling user does not have permission to assign the issue.
  • Status 204
    Returned if the issue is successfully assigned.
  • Status 404
    Returned if either the issue or the user does not exist.

Returns all comments for an issue.

Results can be ordered by the "created" field which means the date a comment was added.

Request
query parameters
parametertypedescription
startAtlong

the page offset, if not specified then defaults to 0

maxResultsint

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

orderBystring

ordering of the results.

expandstring

optional flags: renderedBody (provides body rendered in HTML)

Responses
  • Status 200 - application/json

    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":"2017-03-08T03:29:43.383+0000","updated":"2017-03-08T03:29:43.383+0000","visibility":{"type":"role","value":"Administrators"}}]}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/comments-with-pagination#","title":"Comments With Pagination","type":"object","properties":{"startAt":{"type":"integer"},"maxResults":{"type":"integer"},"total":{"type":"integer"},"comments":{"type":"array","items":{"title":"Comment","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"author":{"$ref":"#/definitions/user"},"body":{"type":"string"},"renderedBody":{"type":"string"},"updateAuthor":{"$ref":"#/definitions/user"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"additionalProperties":false}}},"definitions":{"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

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

Adds a new comment to an issue.

Request
query parameters
parametertypedescription
expandstring

optional flags: renderedBody (provides body rendered in HTML)

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/comment#","title":"Comment","type":"object","properties":{"id":{"type":"string"},"author":{"$ref":"#/definitions/user"},"body":{"type":"string"},"renderedBody":{"type":"string"},"updateAuthor":{"$ref":"#/definitions/user"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"definitions":{"user":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

Responses
  • Status 201

    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":"2017-03-08T03:29:43.383+0000","updated":"2017-03-08T03:29:43.383+0000","visibility":{"type":"role","value":"Administrators"}}

    Returned if add was successful

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/comment#","title":"Comment","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"author":{"$ref":"#/definitions/user"},"body":{"type":"string"},"renderedBody":{"type":"string"},"updateAuthor":{"$ref":"#/definitions/user"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"definitions":{"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

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

Updates an existing comment using its JSON representation.

Request
query parameters
parametertypedescription
expandstring

optional flags: renderedBody (provides body rendered in HTML)

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/comment#","title":"Comment","type":"object","properties":{"id":{"type":"string"},"author":{"$ref":"#/definitions/user"},"body":{"type":"string"},"renderedBody":{"type":"string"},"updateAuthor":{"$ref":"#/definitions/user"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"definitions":{"user":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

Responses
  • Status 200

    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":"2017-03-08T03:29:43.383+0000","updated":"2017-03-08T03:29:43.383+0000","visibility":{"type":"role","value":"Administrators"}}

    Returned if update was successful

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/comment#","title":"Comment","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"author":{"$ref":"#/definitions/user"},"body":{"type":"string"},"renderedBody":{"type":"string"},"updateAuthor":{"$ref":"#/definitions/user"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"definitions":{"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

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

Deletes an existing comment .

Responses
  • Status 400
    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
  • Status 204
    Returned if delete was successful

Returns a single comment.

Request
query parameters
parametertypedescription
expandstring

optional flags: renderedBody (provides body rendered in HTML)

Responses
  • Status 200 - application/json

    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":"2017-03-08T03:29:43.383+0000","updated":"2017-03-08T03:29:43.383+0000","visibility":{"type":"role","value":"Administrators"}}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/comments-with-pagination#","title":"Comments With Pagination","type":"object","properties":{"startAt":{"type":"integer"},"maxResults":{"type":"integer"},"total":{"type":"integer"},"comments":{"type":"array","items":{"title":"Comment","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"author":{"$ref":"#/definitions/user"},"body":{"type":"string"},"renderedBody":{"type":"string"},"updateAuthor":{"$ref":"#/definitions/user"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"additionalProperties":false}}},"definitions":{"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

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

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 editmeta unless overrideScreenSecurity param is set to true.

If the issue cannot be edited in JIRA due to its workflow status (i.e. it is closed), then no fields will be returned, unless overrideEditableFlag is true.

Request
query parameters
parametertypedescription
overrideScreenSecurityboolean

Default: false

also return the edit meta data about fields that are not on the screen. Only connect add-on users with admin scope permission are allowed to use this flag.

overrideEditableFlagboolean

Default: false

also return the edit meta data about fields that are not editable due to being in a status with the jira.issue.editable flag set to false or missing. Only connect add-on users with admin scope permission are allowed to use this flag.

Responses
  • Status 200 - application/json

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

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/edit-meta#","title":"Edit Meta","type":"object","properties":{"fields":{"type":"object","patternProperties":{".+":{"title":"Field Meta","type":"object","properties":{"required":{"type":"boolean"},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false},"name":{"type":"string"},"key":{"type":"string"},"autoCompleteUrl":{"type":"string"},"hasDefaultValue":{"type":"boolean"},"operations":{"type":"array","items":{"type":"string"}},"allowedValues":{"type":"array","items":{}},"defaultValue":{}},"additionalProperties":false,"required":["required"]}},"additionalProperties":false}},"additionalProperties":false}

  • Status 403
    Returned if the user tries to override screen security but doesn't have permission to do that
  • Status 404
    Returned if the requested issue is not found or the user does not have permission to view it.

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

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/notification#","title":"Notification","type":"object","properties":{"subject":{"type":"string"},"textBody":{"type":"string"},"htmlBody":{"type":"string"},"to":{"title":"To","type":"object","properties":{"reporter":{"type":"boolean"},"assignee":{"type":"boolean"},"watchers":{"type":"boolean"},"voters":{"type":"boolean"},"users":{"type":"array","items":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"groups":{"type":"array","items":{"$ref":"#/definitions/group"}}},"additionalProperties":false,"required":["reporter","assignee","watchers","voters"]},"restrict":{"title":"Restrict","type":"object","properties":{"groups":{"type":"array","items":{"$ref":"#/definitions/group"}},"permissions":{"type":"array","items":{"title":"Permission","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}},"definitions":{"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

Responses
  • Status 400
    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
  • Status 204
    Returned if adding to the mail queue was successful
  • Status 403
    Returned is outgoing emails are disabled OR no SMTP server is defined.

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

Request
query parameters
parametertypedescription
globalIdstring

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-remote-issue-link#","title":"List of Remote Issue Link","type":"array","items":{"title":"Remote Issue Link","type":"object","properties":{"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"globalId":{"type":"string"},"application":{"title":"Application","type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false},"relationship":{"type":"string"},"object":{"title":"Remote Object","type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"icon":{"$ref":"#/definitions/icon"},"status":{"title":"Status","type":"object","properties":{"resolved":{"type":"boolean"},"icon":{"$ref":"#/definitions/icon"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"definitions":{"icon":{"title":"Icon","type":"object","properties":{"url16x16":{"type":"string"},"title":{"type":"string"},"link":{"type":"string"}},"additionalProperties":false}}}

  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to view the remote issue links, or if issue linking is disabled.
  • Status 404
    Returned if the issue or remote issue link do not exist.

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.

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/remote-issue-link-create-or-update-request#","title":"Remote Issue Link Create Or Update Request","type":"object","properties":{"globalId":{"type":"string"},"application":{"title":"Application","type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false},"relationship":{"type":"string"},"object":{"title":"Remote Object","type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"icon":{"$ref":"#/definitions/icon"},"status":{"title":"Status","type":"object","properties":{"resolved":{"type":"boolean"},"icon":{"$ref":"#/definitions/icon"}},"additionalProperties":false}},"additionalProperties":false}},"definitions":{"icon":{"title":"Icon","type":"object","properties":{"url16x16":{"type":"string"},"title":{"type":"string"},"link":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/remote-issue-link-create-or-update-response#","title":"Remote Issue Link Create Or Update Response","type":"object","properties":{"id":{"type":"integer"},"self":{"type":"string"}},"additionalProperties":false}

  • Status 400

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

    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to create/update the remote issue link, or if issue linking is disabled.

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

Request
query parameters
parametertypedescription
globalIdstring

the global id of the remote issue link

Responses
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 204
    Returned if the remote issue link was removed successfully.
  • Status 403
    Returned if the calling user does not have permission to delete the remote issue link, or if issue linking is disabled.
  • Status 404
    Returned if the issue or remote issue link do not exist.

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/remote-issue-link#","title":"Remote Issue Link","type":"object","properties":{"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"globalId":{"type":"string"},"application":{"title":"Application","type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false},"relationship":{"type":"string"},"object":{"title":"Remote Object","type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"icon":{"$ref":"#/definitions/icon"},"status":{"title":"Status","type":"object","properties":{"resolved":{"type":"boolean"},"icon":{"$ref":"#/definitions/icon"}},"additionalProperties":false}},"additionalProperties":false}},"definitions":{"icon":{"title":"Icon","type":"object","properties":{"url16x16":{"type":"string"},"title":{"type":"string"},"link":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

  • Status 400
    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.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to view the remote issue link, or if issue linking is disabled.
  • Status 404
    Returned if the issue or remote issue link do not exist.

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

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/remote-issue-link-create-or-update-request#","title":"Remote Issue Link Create Or Update Request","type":"object","properties":{"globalId":{"type":"string"},"application":{"title":"Application","type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false},"relationship":{"type":"string"},"object":{"title":"Remote Object","type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"icon":{"$ref":"#/definitions/icon"},"status":{"title":"Status","type":"object","properties":{"resolved":{"type":"boolean"},"icon":{"$ref":"#/definitions/icon"}},"additionalProperties":false}},"additionalProperties":false}},"definitions":{"icon":{"title":"Icon","type":"object","properties":{"url16x16":{"type":"string"},"title":{"type":"string"},"link":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

Responses
  • Status 400

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

    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 204
    Returned if the remote issue link was updated successfully.
  • Status 403
    Returned if the calling user does not have permission to update the remote issue link, or if issue linking is disabled.

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

Responses
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 204
    Returned if the remote issue link was removed successfully.
  • Status 403
    Returned if the calling user does not have permission to delete the remote issue link, or if issue linking is disabled.
  • Status 404
    Returned if the issue or remote issue link do not exist.

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
parametertypedescription
transitionIdstring
skipRemoteOnlyConditionboolean

Default: false

flag to skip evaluation of {@link RemoteOnlyCondition}, can only be used by add-on users

Responses
  • Status 200 - application/json

    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"}},"hasScreen":false,"fields":{"summary":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My Multi Select","key":"field_key","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue"],"defaultValue":"red"}}},{"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"}},"hasScreen":true,"fields":{"summary":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My Multi Select","key":"field_key","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue"],"defaultValue":"red"},"colour":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My Multi Select","key":"field_key","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue"],"defaultValue":"red"}}}]}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/transitions-meta#","title":"Transitions Meta","type":"object","properties":{"expand":{"type":"string"},"transitions":{"type":"array","items":{"title":"Transition","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"to":{"title":"Status","type":"object","properties":{"self":{"type":"string"},"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"hasScreen":{"type":"boolean"},"fields":{"type":"object","patternProperties":{".+":{"title":"Field Meta","type":"object","properties":{"required":{"type":"boolean"},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false},"name":{"type":"string"},"key":{"type":"string"},"autoCompleteUrl":{"type":"string"},"hasDefaultValue":{"type":"boolean"},"operations":{"type":"array","items":{"type":"string"}},"allowedValues":{"type":"array","items":{}},"defaultValue":{}},"additionalProperties":false,"required":["required"]}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

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

Perform a transition on an issue. When performing the transition you can update 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.

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-update#","title":"Issue Update","type":"object","properties":{"transition":{"title":"Transition","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"to":{"title":"Status","type":"object","properties":{"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"hasScreen":{"type":"boolean"},"fields":{"type":"object","patternProperties":{".+":{"title":"Field Meta","type":"object","properties":{"required":{"type":"boolean"},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false},"name":{"type":"string"},"key":{"type":"string"},"autoCompleteUrl":{"type":"string"},"hasDefaultValue":{"type":"boolean"},"operations":{"type":"array","items":{"type":"string"}},"allowedValues":{"type":"array","items":{}},"defaultValue":{}},"additionalProperties":false,"required":["required"]}},"additionalProperties":false}},"additionalProperties":false},"fields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"update":{"type":"object","patternProperties":{".+":{"type":"array","items":{"title":"Field Operation","type":"object"}}},"additionalProperties":false},"historyMetadata":{"title":"History Metadata","type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"descriptionKey":{"type":"string"},"activityDescription":{"type":"string"},"activityDescriptionKey":{"type":"string"},"emailDescription":{"type":"string"},"emailDescriptionKey":{"type":"string"},"actor":{"$ref":"#/definitions/history-metadata-participant"},"generator":{"$ref":"#/definitions/history-metadata-participant"},"cause":{"$ref":"#/definitions/history-metadata-participant"},"extraData":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"definitions":{"history-metadata-participant":{"title":"History Metadata Participant","type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"displayNameKey":{"type":"string"},"type":{"type":"string"},"avatarUrl":{"type":"string"},"url":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

Responses
  • Status 400
    If there is no transition specified.
  • Status 204
    Returned if the transition was successful.
  • Status 404
    The issue does not exist or the user does not have permission to view it

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

Responses
  • Status 204
    Nothing is returned on success.
  • Status 404
    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.)

Cast your vote in favour of an issue.

Responses
  • Status 204
    Nothing is returned on success.
  • Status 404
    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.)

A REST sub-resource representing the voters on the issue.

Responses
  • Status 200 - application/json

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false}]}

    Information about voting on the current issue.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/vote#","title":"Vote","type":"object","properties":{"self":{"type":"string","format":"uri"},"votes":{"type":"integer"},"hasVoted":{"type":"boolean"},"voters":{}},"additionalProperties":false,"required":["votes","hasVoted"]}

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

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/watchers#","title":"Watchers","type":"object","properties":{"self":{"type":"string"},"isWatching":{"type":"boolean"},"watchCount":{"type":"integer"},"watchers":{"type":"array","items":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}}},"additionalProperties":false,"required":["watchCount"]}

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

Adds a user to an issue's watcher list.

Request

Example
"fred"

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/string#","title":"String","type":"string"}

Responses
  • Status 400
    Returned if there is a problem with the received user representation.
  • Status 401
    Returned if the calling user does not have permission to add the watcher to the issue's list of watchers.
  • Status 204
    Returned if the watcher was added successfully.
  • Status 404
    Returned if either the issue or the user does not exist.

Removes a user from an issue's watcher list.

Request
query parameters
parametertypedescription
usernamestring

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

Responses
  • Status 400
    Returned if a user name query parameter is not supplied.
  • Status 401
    Returned if the calling user does not have permission to remove the watcher from the issue's list of watchers.
  • Status 204
    Returned if the watcher was removed successfully.
  • Status 404
    Returned if either the issue does not exist.

Returns all work logs for an issue.
Note: Work logs won't be returned if the Log work field is hidden for the project.

Request
query parameters
parametertypedescription
expandstring

Default:

optional comma separated list of parameters to expand: properties (provides worklog properties).

Responses
  • Status 200 - application/json

    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.","updated":"2017-03-08T03:29:43.684+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T03:29:43.684+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}]}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/worklog-with-pagination#","title":"Worklog With Pagination","type":"object","properties":{"startAt":{"type":"integer"},"maxResults":{"type":"integer"},"total":{"type":"integer"},"worklogs":{"type":"array","items":{"title":"Worklog","type":"object","properties":{"self":{"type":"string","format":"uri"},"author":{"$ref":"#/definitions/user"},"updateAuthor":{"$ref":"#/definitions/user"},"comment":{"type":"string"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"started":{"type":"string"},"timeSpent":{"type":"string"},"timeSpentSeconds":{"type":"integer"},"id":{"type":"string"},"issueId":{"type":"string"},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"additionalProperties":false}}},"definitions":{"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

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

Adds a new worklog entry to an issue.

Request
query parameters
parametertypedescription
adjustEstimatestring

(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

newEstimatestring

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

reduceBystring

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

expandstring

Default:

optional comma separated list of parameters to expand: properties (provides worklog properties).

Example
{"comment":"I did some work here.","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T03:29:43.684+0000","timeSpentSeconds":12000}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/worklog#","title":"Worklog","type":"object","properties":{"author":{"$ref":"#/definitions/user"},"updateAuthor":{"$ref":"#/definitions/user"},"comment":{"type":"string"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"started":{"type":"string"},"timeSpent":{"type":"string"},"timeSpentSeconds":{"type":"integer"},"id":{"type":"string"},"issueId":{"type":"string"},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"definitions":{"user":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

Responses
  • Status 201
    Returned if add was successful

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/worklog#","title":"Worklog","type":"object","properties":{"self":{"type":"string","format":"uri"},"author":{"$ref":"#/definitions/user"},"updateAuthor":{"$ref":"#/definitions/user"},"comment":{"type":"string"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"started":{"type":"string"},"timeSpent":{"type":"string"},"timeSpentSeconds":{"type":"integer"},"id":{"type":"string"},"issueId":{"type":"string"},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"definitions":{"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

  • Status 400
    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
  • Status 403
    Returned if the calling user does not have permission to add the worklog

Returns a specific worklog.
Note: The work log won't be returned if the Log work field is hidden for the project.

Request
query parameters
parametertypedescription
expandstring

Default:

optional comma separated list of parameters to expand: properties (provides worklog properties).

Responses
  • Status 200 - application/json

    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.","updated":"2017-03-08T03:29:43.684+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T03:29:43.684+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/worklog#","title":"Worklog","type":"object","properties":{"self":{"type":"string","format":"uri"},"author":{"$ref":"#/definitions/user"},"updateAuthor":{"$ref":"#/definitions/user"},"comment":{"type":"string"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"started":{"type":"string"},"timeSpent":{"type":"string"},"timeSpentSeconds":{"type":"integer"},"id":{"type":"string"},"issueId":{"type":"string"},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"definitions":{"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

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

Updates an existing worklog entry.

Note that:

  • Fields possible for editing are: comment, visibility, started, timeSpent and timeSpentSeconds.
  • Either timeSpent or timeSpentSeconds can be set.
  • Fields which are not set will not be updated.
  • For a request to be valid, it has to have at least one field change.

Request
query parameters
parametertypedescription
adjustEstimatestring

(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

newEstimatestring

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

expandstring

Default:

optional comma separated list of parameters to expand: properties (provides worklog properties).

Example
{"comment":"I did some work here.","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T03:29:43.684+0000","timeSpentSeconds":12000}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/worklog#","title":"Worklog","type":"object","properties":{"author":{"$ref":"#/definitions/user"},"updateAuthor":{"$ref":"#/definitions/user"},"comment":{"type":"string"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"started":{"type":"string"},"timeSpent":{"type":"string"},"timeSpentSeconds":{"type":"integer"},"id":{"type":"string"},"issueId":{"type":"string"},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"definitions":{"user":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

Responses
  • Status 200

    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.","updated":"2017-03-08T03:29:43.684+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T03:29:43.684+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}

    Returned if update was successful

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/worklog#","title":"Worklog","type":"object","properties":{"self":{"type":"string","format":"uri"},"author":{"$ref":"#/definitions/user"},"updateAuthor":{"$ref":"#/definitions/user"},"comment":{"type":"string"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"started":{"type":"string"},"timeSpent":{"type":"string"},"timeSpentSeconds":{"type":"integer"},"id":{"type":"string"},"issueId":{"type":"string"},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"definitions":{"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

  • Status 400
    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
  • Status 403
    Returned if the calling user does not have permission to update the worklog

Deletes an existing worklog entry.

Request
query parameters
parametertypedescription
adjustEstimatestring

(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

newEstimatestring

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

increaseBystring

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

Responses
  • Status 400
    Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
  • Status 204
    Returned if delete was successful
  • Status 403
    Returned if the calling user does not have permission to delete the worklog

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
parametertypedescription
projectIdsstring

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.

projectKeysstring

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.

issuetypeIdsstring

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.

issuetypeNamesstring

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.

Responses
  • Status 200 - application/json

    Example
    {"expand":"projects","projects":[{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example Project","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?pid=10000&avatarId=10011","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"},"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","key":"issuetype","hasDefaultValue":false,"operations":["set"]}}}]}]}

    Returns the meta data for creating issues.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/create-meta#","title":"Create Meta","type":"object","properties":{"expand":{"type":"string"},"projects":{"type":"array","items":{"title":"Create Meta Project","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string"},"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"issuetypes":{"type":"array","items":{"title":"Create Meta Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"},"expand":{"type":"string"},"fields":{"type":"object","patternProperties":{".+":{"title":"Field Meta","type":"object","properties":{"required":{"type":"boolean"},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false},"name":{"type":"string"},"key":{"type":"string"},"autoCompleteUrl":{"type":"string"},"hasDefaultValue":{"type":"boolean"},"operations":{"type":"array","items":{"type":"string"}},"allowedValues":{"type":"array","items":{}},"defaultValue":{}},"additionalProperties":false,"required":["required"]}},"additionalProperties":false}},"additionalProperties":false,"required":["subtask"]}}},"additionalProperties":false}}},"additionalProperties":false}

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

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
parametertypedescription
querystring

the query.

currentJQLstring

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

currentIssueKeystring

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.

currentProjectIdstring

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

showSubTasksboolean

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

showSubTaskParentboolean

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.

Responses
  • Status 200 - application/json
    Returns a list of issues which match the picker parameters.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-picker-result#","title":"Issue Picker Result","type":"object","properties":{"sections":{"type":"array","items":{"title":"Issue Section","type":"object","properties":{"label":{"type":"string"},"sub":{"type":"string"},"id":{"type":"string"},"msg":{"type":"string"},"issues":{"type":"array","items":{"title":"Issue Picker Issue","type":"object","properties":{"key":{"type":"string"},"keyHtml":{"type":"string"},"img":{"type":"string"},"summary":{"type":"string"},"summaryText":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}}},"additionalProperties":false}

api/2/issue/{issueIdOrKey}/attachments

Issue attachments

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: no-check 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: no-check" -F "file=@myfile.txt" http://myhost/rest/api/2/issue/TEST-123/attachments

Responses
  • Status 200 - application/json

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"created":"2017-03-08T03:29:43.525+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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"created":"2017-03-08T03:29:43.525+0000","size":2460,"mimeType":"text/plain","content":"http://www.example.com/jira/attachments/10001","thumbnail":"http://www.example.com/jira/secure/thumbnail/10002"}]

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-attachment#","title":"List of Attachment","type":"array","items":{"title":"Attachment","type":"object","properties":{"self":{"type":"string","format":"uri"},"filename":{"type":"string"},"author":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"created":{"type":"string"},"size":{"type":"integer"},"mimeType":{"type":"string"},"properties":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"content":{"type":"string"},"thumbnail":{"type":"string"}},"additionalProperties":false,"required":["size"]},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}}}

  • Status 403
    Returned if attachments is disabled or if you don't have permission to add attachments to this issue.
  • Status 404
    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.

api/2/issue/{issueIdOrKey}/properties

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-properties-keys#","title":"Entity Properties Keys","type":"object","properties":{"keys":{"type":"array","items":{"title":"Entity Property Key","type":"object","properties":{"self":{"type":"string"},"key":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 400
    Returned if the issue key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to view the issue.
  • Status 404
    Returned if the issue with given key or id does not exist or if the property with given key is not found.

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.

Responses
  • Status 400
    Returned if the issue key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 204
    Returned if the issue property was removed successfully.
  • Status 403
    Returned if the calling user does not have permission to edit the issue.
  • Status 404
    Returned if the issue with given key or id does not exist or if the property with given key is not found.

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.

Responses
  • Status 200
    Returned if the issue property is successfully updated.
  • Status 201
    Returned if the issue property is successfully created.
  • Status 400
    Returned if the issue key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to edit the issue.
  • Status 404
    Returned if the issue with given key or id does not exist.

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.

Responses
  • Status 200 - application/json

    Example
    {"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}

    Returned if the issue property was found.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-property#","title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}

  • Status 400
    Returned if the issue key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to view the issue.
  • Status 404
    Returned if the issue with given key or id does not exist or if the property with given key is not found.

api/2/issue/{issueIdOrKey}/worklog/{worklogId}/properties

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

Responses
  • Status 200 - application/json

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

    Returned if the worklog was found.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-properties-keys#","title":"Entity Properties Keys","type":"object","properties":{"keys":{"type":"array","items":{"title":"Entity Property Key","type":"object","properties":{"self":{"type":"string"},"key":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 400
    Returned if the worklog key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to browse the worklog.
  • Status 404
    Returned if the worklog with given key or id does not exist or if the property with given key is not found.

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

Responses
  • Status 400
    Returned if the worklog key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 204
    Returned if the worklog property was removed successfully.
  • Status 403
    Returned if the calling user does not have permission to edit the worklog.
  • Status 404
    Returned if the worklog with given key or id does not exist or if the property with given key is not found.

Sets the value of the specified worklog's property.

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

Responses
  • Status 200
    Returned if the worklog property is successfully updated.
  • Status 201
    Returned if the worklog property is successfully created.
  • Status 400
    Returned if the worklog key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to administer the worklog.
  • Status 404
    Returned if the worklog with given key or id does not exist.

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

Responses
  • Status 200 - application/json

    Example
    {"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}

    Returned if the worklog property was found.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-property#","title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}

  • Status 400
    Returned if the worklog key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to browse the worklog.
  • Status 404
    Returned if the worklog with given key or id does not exist or if the property with given key is not found.

The Link Issue Resource provides functionality to manage issue links.

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

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/link-issue-request#","title":"Link Issue Request","type":"object","properties":{"type":{"title":"Issue Link Type","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"inward":{"type":"string"},"outward":{"type":"string"}},"additionalProperties":false},"inwardIssue":{"$ref":"#/definitions/issue-ref"},"outwardIssue":{"$ref":"#/definitions/issue-ref"},"comment":{"title":"Comment","type":"object","properties":{"id":{"type":"string"},"author":{"$ref":"#/definitions/user"},"body":{"type":"string"},"renderedBody":{"type":"string"},"updateAuthor":{"$ref":"#/definitions/user"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"additionalProperties":false}},"definitions":{"issue-ref":{"title":"Issue Ref","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"fields":{"title":"Fields","type":"object","properties":{"summary":{"type":"string"},"status":{"title":"Status","type":"object","properties":{"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"issuetype":{"title":"Issue Type","type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]},"priority":{"title":"Priority","type":"object","properties":{"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"user":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

Responses
  • Status 201 - application/json
    if the issue link was created successfully.
  • Status 400
    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.
  • Status 401
    if the user does not have the link issue permission for the issue, which will be linked to another issue.
  • Status 500
    if an error occurred when creating the issue link or the comment.
  • Status 404
    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.

Returns an issue link with the specified id.

Responses
  • Status 200 - application/json

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-link#","title":"Issue Link","type":"object","properties":{"id":{"type":"string"},"self":{"type":"string","format":"uri"},"type":{"title":"Issue Link Type","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"inward":{"type":"string"},"outward":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"inwardIssue":{"$ref":"#/definitions/issue-ref"},"outwardIssue":{"$ref":"#/definitions/issue-ref"}},"definitions":{"issue-ref":{"title":"Issue Ref","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"self":{"type":"string","format":"uri"},"fields":{"title":"Fields","type":"object","properties":{"summary":{"type":"string"},"status":{"title":"Status","type":"object","properties":{"self":{"type":"string"},"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"issuetype":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]},"priority":{"title":"Priority","type":"object","properties":{"self":{"type":"string"},"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}

  • Status 400
    If the specified issue link id is invalid.
  • Status 401
    if the user does not have the link issue permission for the issue, which will be linked to another issue.
  • Status 500
    if an error occurred when creating the issue link or the comment.
  • Status 404
    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.

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.

Responses
  • Status 200 - application/json
  • Status 400
    If the specified issue link id is invalid.
  • Status 401
    if the user does not have the link issue permission for the source or destination issue of the issue link.
  • Status 500
    if an error occurred when deleting the issue link or the comment.
  • Status 204
    If it successfully deleted the issue link.
  • Status 404
    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.

api/2/issueLinkType

Rest resource to retrieve a list of issue link types.

Returns a list of available issue link types, if issue linking is enabled. Each issue link type has an id, a name and a label for the outward and inward link relationship.

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-link-types#","title":"Issue Link Types","type":"object","properties":{"issueLinkTypes":{"type":"array","items":{"title":"Issue Link Type","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"inward":{"type":"string"},"outward":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 404
    Returned if issue linking is disabled.

Create a new issue link type.

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-link-type#","title":"Issue Link Type","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"inward":{"type":"string"},"outward":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 201 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-link-type#","title":"Issue Link Type","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"inward":{"type":"string"},"outward":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}

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

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-link-type#","title":"Issue Link Type","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"inward":{"type":"string"},"outward":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}

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

Delete the specified issue link type.

Responses
  • Status 204
  • Status 404
    Returned if issue linking is disabled or no issue link type with the given id exists.

Update the specified issue link type.

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-link-type#","title":"Issue Link Type","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"inward":{"type":"string"},"outward":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 200

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-link-type#","title":"Issue Link Type","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"inward":{"type":"string"},"outward":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}

  • Status 400
    Returned if the supplied id is not a number.
  • Status 404
    Returned if issue linking is disabled or no issue link type with the given id exists.

api/2/issuesecurityschemes

REST resource that allows to view security schemes defined in the product.

Returns all issue security schemes that are defined.

Responses
  • Status 200 - application/json

    Example
    {"issueSecuritySchemes":[{"self":"http://www.example.com/jira/rest/api/2/issuesecurityschemes/1000","id":1000,"name":"Default Issue Security Scheme","description":"Description for the default issue security scheme","defaultSecurityLevelId":10021}]}

    Returned if the user has the administrator permission.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/security-schemes#","title":"Security Schemes","type":"object","properties":{"issueSecuritySchemes":{"type":"array","items":{"title":"Security Scheme","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultSecurityLevelId":{"type":"integer"},"levels":{"type":"array","items":{"title":"Security Level","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not have the administrator permission.

Returns the issue security scheme along with that are defined.

Responses
  • Status 200 - application/json

    Example
    {"self":"http://www.example.com/jira/rest/api/2/issuesecurityschemes/1000","id":1000,"name":"Default Issue Security Scheme","description":"Description for the default issue security scheme","defaultSecurityLevelId":10021,"levels":[{"self":"http://www.example.com/jira/rest/api/2/securitylevel/10021","id":"10021","description":"Only the reporter and internal staff can see this issue.","name":"Reporter Only"}]}

    Returned if the user has the administrator permission or if the scheme is used in a project in which the user has the administrative permission.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/security-scheme#","title":"Security Scheme","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultSecurityLevelId":{"type":"integer"},"levels":{"type":"array","items":{"title":"Security Level","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not have the administrator permission and the scheme is not used in any project where the user has administrative permission.

api/2/issuetype

Returns a list of all issue types visible to the user

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-issue-type#","title":"List of Issue Type","type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}}

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

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-type-create#","title":"Issue Type Create","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["subtask","standard"]}},"additionalProperties":false}

Responses
  • Status 201 - application/json
    Returned if the issue type was successfully created.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-type#","title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}

  • Status 400
    Returned if the request is invalid. This happens when the name is invalid or issue type is subtask on instance which has subtasks disabled.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to administer JIRA.
  • Status 409
    Returned if there already exists an issue type with the specified name.

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-type#","title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}

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

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
parametertypedescription
alternativeIssueTypeIdstring

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

Responses
  • Status 400
    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.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 204 - application/json
    Returned if the issue type was successfully removed.
  • Status 403
    Returned if the calling user does not have permission to administer JIRA.
  • Status 404
    Returned if the issue type which is supposed to be removed does not exist or the alternative issue type does not exist.

Updates the specified issue type from a JSON representation.

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-type-update#","title":"Issue Type Update","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"avatarId":{"type":"integer"}},"additionalProperties":false}

Responses
  • Status 200 - application/json
    Returned if the issue type was successfully updated.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-type#","title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}

  • Status 400
    Returned if the request is invalid. This happens when the name is invalid or if the avatar with given id does not exist.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to administer JIRA.
  • Status 404
    Returned if the issue type to update does not exist.
  • Status 409
    Returned if there already exists an issue type with the specified name.

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.

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-issue-type#","title":"List of Issue Type","type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}}

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

Creates an avatar for an issue type, for a given issue type Id. The uploaded image will be cropped according to the crop parameters listed below. If no crop parameters are specified, the image will be cropped to a square. The square will originate at the top left of the image and the length of each side will be set to the smaller of the height or width of the image.

Request
query parameters
parametertypedescription
xint

(optional) The X coordinate of the top-left corner of the crop region. Default: 0.

yint

(optional) The Y coordinate of the top-left corner of the crop region. Default: 0.

sizeint

(optional) The length of each side of the crop region. The crop region can only be a square. If omitted and the top-left corner is at (0,0), this defaults to either the height or width of the image, whichever is smaller.

Responses
  • Status 201 - application/json

    Example
    {"id":"1000","owner":"fred","isSystemAvatar":true,"isSelected":false,"isDeletable":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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/avatar#","title":"Avatar","type":"object","properties":{"id":{"type":"string"},"owner":{"type":"string"},"isSystemAvatar":{"type":"boolean"},"isSelected":{"type":"boolean"},"isDeletable":{"type":"boolean"},"urls":{"type":"object","patternProperties":{"\\d\\dx\\d\\d":{"type":"string","format":"uri"}},"additionalProperties":false},"selected":{"type":"boolean"}},"additionalProperties":false,"required":["isSystemAvatar","isSelected","isDeletable","selected"]}

  • Status 400
    Returned if the cropping coordinates are invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to administer JIRA.
  • Status 404
    Returned if the issue type to update does not exist or if the request does not contain a valid XSRF token.

api/2/issuetype/{issueTypeId}/properties

This resource allows to store custom properties for issue types.

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

Responses
  • Status 200 - application/json

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

    Returned if the issue type was found.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-properties-keys#","title":"Entity Properties Keys","type":"object","properties":{"keys":{"type":"array","items":{"title":"Entity Property Key","type":"object","properties":{"self":{"type":"string"},"key":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 400
    Returned if the issue type id is invalid.
  • Status 404
    Returned if the issue type with given id does not exist or if the user does not have permissions to view this issue type.

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

Responses
  • Status 400
    Returned if the issue type id is invalid.
  • Status 204
    Returned if the issue type property was removed successfully.
  • Status 404
    Returned if the issue type with given id does not exist or if the property with given key is not found.

Sets the value of the specified issue type's property.

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

Responses
  • Status 200
    Returned if the issue type property is successfully updated.
  • Status 201
    Returned if the issue type property is successfully created.
  • Status 400
    Returned if the issue type id is invalid.
  • Status 404
    Returned if the issue type with given id does not exist or if the user does not have permissions to edit this issue type.

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

Responses
  • Status 200 - application/json

    Example
    {"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}

    Returned if the issue type property was found.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-property#","title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}

  • Status 400
    Returned if the issue type id is invalid.
  • Status 404
    Returned if the issue type with given id does not exist or if the user does not have permissions to view this issue type.

api/2/jql/autocompletedata

Resource for auto complete data for searches.

Returns the auto complete data required for JQL searches.

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/auto-complete-response#","title":"Auto Complete Response","type":"object","properties":{"visibleFieldNames":{"type":"array","items":{"type":"string"}},"visibleFunctionNames":{"type":"array","items":{"type":"string"}},"jqlReservedWords":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

  • Status 401
    Returned if the calling user is not authenticated.
  • Status 500
    Returned if an error occurs while generating the response.

Returns auto complete suggestions for JQL search.

Request
query parameters
parametertypedescription
fieldNamestring

the field name for which the suggestions are generated.

fieldValuestring

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

predicateNamestring

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

predicateValuestring

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/auto-complete-result-wrapper#","title":"Auto Complete Result Wrapper","type":"object","properties":{"results":{"type":"array","items":{"title":"Auto Complete Result","type":"object","properties":{"value":{"type":"string"},"displayName":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

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.Show more
Request

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/string#","title":"String","type":"string"}

Responses
  • Status - application/json

api/2/mypreferences

Provide preferences of the currently logged in user.

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
parametertypedescription
keystring

- key of the preference to be returned.

Responses
  • Status - application/json

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
parametertypedescription
keystring

- key of the preference to be set.

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/string#","title":"String","type":"string"}

Responses
  • Status - application/json

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
parametertypedescription
keystring

- key of the preference to be removed.

Responses
  • Status - application/json

api/2/myself

Currently logged user resource

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

The resource accepts the expand param that is used to include, hidden by default, parts of response. This can be used to include:

  • groups - all groups, including nested groups, to which user belongs
  • applicationRoles - application roles defines to which application user has access

Responses
  • Status 200 - application/json

    Example
    {"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"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"}]},"applicationRoles":{"size":1,"items":[]},"expand":"groups,applicationRoles"}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/user#","title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false,"required":["active"]}

  • Status 401
    Returned if the current user is not authenticated.

api/2/notificationscheme

Returns a paginated list of notification schemes. In order to access notification scheme, the calling user is required to have permissions to administer at least one project associated with the requested notification scheme. Each scheme contains a list of events and recipient configured to receive notifications for these events. Consumer should allow events without recipients to appear in response. The list is ordered by the scheme's name. Follow the documentation of /notificationscheme/{id} resource for all details about returned value.

Request
query parameters
parametertypedescription
startAtlong

the index of the first notification scheme to return (0 based).

maxResultsint

the maximum number of notification schemes to return (max 50).

expandstring
Responses
  • Status 200 - application/json

    Example
    {"maxResults":6,"startAt":1,"total":5,"isLast":false,"values":[{"expand":"notificationSchemeEvents,user,group,projectRole,field,all","id":10100,"self":"http://example.com/jira/rest/api/2/notificationscheme/10010","name":"notification scheme name","description":"description","notificationSchemeEvents":[{"event":{"id":1,"name":"Issue created","description":"Event published when issue is created"},"notifications":[{"id":1,"notificationType":"Group","parameter":"jira-administrators","group":{"name":"jira-administrators","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-administrators"},"expand":"group"},{"id":2,"notificationType":"CurrentAssignee"},{"id":3,"notificationType":"ProjectRole","parameter":"10360","projectRole":{"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"},{"id":10241,"displayName":"Fred F. User","type":"atlassian-user-role-actor","name":"fred"}]},"expand":"projectRole"},{"id":4,"notificationType":"EmailAddress","parameter":"rest-developer@atlassian.com","emailAddress":"rest-developer@atlassian.com"},{"id":5,"notificationType":"User","user":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"expand":"user"},{"id":6,"notificationType":"GroupCustomField","parameter":"customfield_10101","field":{"id":"customfield_10101","key":"custom_fields_may_have_friendly_keys","name":"New custom field","custom":true,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["cf[10101]","New custom field"],"schema":{"type":"project","custom":"com.atlassian.jira.plugin.system.customfieldtypes:project","customId":10101}},"expand":"field"}]},{"event":{"id":20,"name":"Custom event","description":"Custom event which is published together with issue created event","templateEvent":{"id":1,"name":"Issue created","description":"Event published when issue is created"}},"notifications":[{"id":1,"notificationType":"Group","parameter":"jira-administrators","group":{"name":"jira-administrators","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-administrators"},"expand":"group"},{"id":2,"notificationType":"CurrentAssignee"},{"id":3,"notificationType":"ProjectRole","parameter":"10360","projectRole":{"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"},{"id":10241,"displayName":"Fred F. User","type":"atlassian-user-role-actor","name":"fred"}]},"expand":"projectRole"},{"id":4,"notificationType":"EmailAddress","parameter":"rest-developer@atlassian.com","emailAddress":"rest-developer@atlassian.com"},{"id":5,"notificationType":"User","user":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"expand":"user"},{"id":6,"notificationType":"GroupCustomField","parameter":"customfield_10101","field":{"id":"customfield_10101","key":"custom_fields_may_have_friendly_keys","name":"New custom field","custom":true,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["cf[10101]","New custom field"],"schema":{"type":"project","custom":"com.atlassian.jira.plugin.system.customfieldtypes:project","customId":10101}},"expand":"field"}]}]}]}

    Paginated list of notification schemes to which the user has permissions.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/page-of-notification-scheme#","title":"Page of Notification Scheme","type":"object","properties":{"self":{"type":"string","format":"uri"},"nextPage":{"type":"string","format":"uri"},"maxResults":{"type":"integer"},"startAt":{"type":"integer"},"total":{"type":"integer"},"isLast":{"type":"boolean"},"values":{"type":"array","items":{"title":"Notification Scheme","type":"object","properties":{"expand":{"type":"string"},"id":{"type":"integer"},"self":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"notificationSchemeEvents":{"type":"array","items":{"title":"Notification Scheme Event","type":"object","properties":{"event":{"$ref":"#/definitions/notification-event"},"notifications":{"type":"array","items":{"title":"Notification","type":"object","anyOf":[{"$ref":"#/definitions/custom-field-value-notification"},{"$ref":"#/definitions/email-notification"},{"$ref":"#/definitions/group-notification"},{"$ref":"#/definitions/project-role-notification"},{"$ref":"#/definitions/role-notification"},{"$ref":"#/definitions/user-notification"}]}}},"additionalProperties":false}}},"additionalProperties":false}}},"definitions":{"custom-field-value-notification":{"title":"Custom Field Value Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"field":{"title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"email-notification":{"title":"Email Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"emailAddress":{"type":"string"}},"additionalProperties":false},"group-notification":{"title":"Group Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false},"notification-event":{"title":"Notification Event","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"templateEvent":{"$ref":"#/definitions/notification-event"}},"additionalProperties":false},"project-role-notification":{"title":"Project Role Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"projectRole":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false},"role-notification":{"title":"Role Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"}},"additionalProperties":false},"user-notification":{"title":"User Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}},"additionalProperties":false,"required":["maxResults","startAt"]}

Returns a full representation of the notification scheme for the given id. This resource will return a notification scheme containing a list of events and recipient configured to receive notifications for these events. Consumer should allow events without recipients to appear in response. User accessing the data is required to have permissions to administer at least one project associated with the requested notification scheme.

Notification recipients can be:

  • current assignee - the value of the notificationType is CurrentAssignee
  • issue reporter - the value of the notificationType is Reporter
  • current user - the value of the notificationType is CurrentUser
  • project lead - the value of the notificationType is ProjectLead
  • component lead - the value of the notificationType is ComponentLead
  • all watchers - the value of the notification type is AllWatchers
  • configured user - the value of the notification type is User. Parameter will contain key of the user. Information about the user will be provided if user expand parameter is used.
  • configured group - the value of the notification type is Group. Parameter will contain name of the group. Information about the group will be provided if group expand parameter is used.
  • configured email address - the value of the notification type is EmailAddress, additionally information about the email will be provided.
  • users or users in groups in the configured custom fields - the value of the notification type is UserCustomField or GroupCustomField. Parameter will contain id of the custom field. Information about the field will be provided if field expand parameter is used.
  • configured project role - the value of the notification type is ProjectRole. Parameter will contain project role id. Information about the project role will be provided if projectRole expand parameter is used.
Please see the example for reference.

The events can be JIRA system events or events configured by administrator. In case of the system events, data about theirs ids, names and descriptions is provided. In case of custom events, the template event is included as well.

Request
query parameters
parametertypedescription
expandstring
Responses
  • Status 200 - application/json

    Example
    {"expand":"notificationSchemeEvents,user,group,projectRole,field,all","id":10100,"self":"http://example.com/jira/rest/api/2/notificationscheme/10010","name":"notification scheme name","description":"description","notificationSchemeEvents":[{"event":{"id":1,"name":"Issue created","description":"Event published when issue is created"},"notifications":[{"id":1,"notificationType":"Group","parameter":"jira-administrators","group":{"name":"jira-administrators","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-administrators"},"expand":"group"},{"id":2,"notificationType":"CurrentAssignee"},{"id":3,"notificationType":"ProjectRole","parameter":"10360","projectRole":{"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"},{"id":10241,"displayName":"Fred F. User","type":"atlassian-user-role-actor","name":"fred"}]},"expand":"projectRole"},{"id":4,"notificationType":"EmailAddress","parameter":"rest-developer@atlassian.com","emailAddress":"rest-developer@atlassian.com"},{"id":5,"notificationType":"User","user":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"expand":"user"},{"id":6,"notificationType":"GroupCustomField","parameter":"customfield_10101","field":{"id":"customfield_10101","key":"custom_fields_may_have_friendly_keys","name":"New custom field","custom":true,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["cf[10101]","New custom field"],"schema":{"type":"project","custom":"com.atlassian.jira.plugin.system.customfieldtypes:project","customId":10101}},"expand":"field"}]},{"event":{"id":20,"name":"Custom event","description":"Custom event which is published together with issue created event","templateEvent":{"id":1,"name":"Issue created","description":"Event published when issue is created"}},"notifications":[{"id":1,"notificationType":"Group","parameter":"jira-administrators","group":{"name":"jira-administrators","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-administrators"},"expand":"group"},{"id":2,"notificationType":"CurrentAssignee"},{"id":3,"notificationType":"ProjectRole","parameter":"10360","projectRole":{"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"},{"id":10241,"displayName":"Fred F. User","type":"atlassian-user-role-actor","name":"fred"}]},"expand":"projectRole"},{"id":4,"notificationType":"EmailAddress","parameter":"rest-developer@atlassian.com","emailAddress":"rest-developer@atlassian.com"},{"id":5,"notificationType":"User","user":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"expand":"user"},{"id":6,"notificationType":"GroupCustomField","parameter":"customfield_10101","field":{"id":"customfield_10101","key":"custom_fields_may_have_friendly_keys","name":"New custom field","custom":true,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["cf[10101]","New custom field"],"schema":{"type":"project","custom":"com.atlassian.jira.plugin.system.customfieldtypes:project","customId":10101}},"expand":"field"}]}]}

    Returned if the notification scheme exists and is visible for the calling user

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/notification-scheme#","title":"Notification Scheme","type":"object","properties":{"expand":{"type":"string"},"id":{"type":"integer"},"self":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"notificationSchemeEvents":{"type":"array","items":{"title":"Notification Scheme Event","type":"object","properties":{"event":{"$ref":"#/definitions/notification-event"},"notifications":{"type":"array","items":{"title":"Notification","type":"object","anyOf":[{"$ref":"#/definitions/custom-field-value-notification"},{"$ref":"#/definitions/email-notification"},{"$ref":"#/definitions/group-notification"},{"$ref":"#/definitions/project-role-notification"},{"$ref":"#/definitions/role-notification"},{"$ref":"#/definitions/user-notification"}]}}},"additionalProperties":false}}},"definitions":{"custom-field-value-notification":{"title":"Custom Field Value Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"field":{"title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"email-notification":{"title":"Email Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"emailAddress":{"type":"string"}},"additionalProperties":false},"group-notification":{"title":"Group Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false},"notification-event":{"title":"Notification Event","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"templateEvent":{"$ref":"#/definitions/notification-event"}},"additionalProperties":false},"project-role-notification":{"title":"Project Role Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"projectRole":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false},"role-notification":{"title":"Role Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"}},"additionalProperties":false},"user-notification":{"title":"User Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}},"additionalProperties":false}

  • Status 404
    Returned if the notification scheme does not exist, or is not visible to the calling user

api/2/permissionscheme

Resource for managing permission schemes.

Permission scheme is a collection of permission grants. Each grant holds information about a permission granted to a group of users. These groups of users are called holders and are defined by two values: type and parameter. Type can be for example "group", or "user" and parameter is an additional specification. In case of groups the parameter will hold the group name, and in case of users: user id.

Types can be extended by plugins, but here is a list of all built-in types (expected parameter contents are given in parenthesis):

anyone
Grant for anonymous users.
group (group name)
Grant for the specified group
user (user id)
Grant for the specified user
projectRole (project role id)
Grant for the specified project role
reporter
Grant for an issue reported
projectLead
Grant for a project lead
assignee
Grant for a user assigned to an issue
userCustomField (custom field id)
Grant for a user selected in the specified custom field
groupCustomField (custom field id)
Grant for a user selected in the specified custom field

There are also two "hidden" holder types, which are not available in on-demand but can be used in enterprise instances:

reporterWithCreatePermission
This type can be used only with BROWSE_PROJECTS permission to show only projects where the user has create permission and issues within that where they are the reporter.
assigneeWithAssignablePermission
This type can be used only with BROWSE_PROJECTS permission to show only projects where the user has the assignable permission and issues within that where they are the assignee.

In addition to specifying the permission holder, a permission must be selected. That way a pair of (holder, permission) is created and it represents a single permission grant.

Custom permissions can be added by plugins, but below we present a set of built-in JIRA permissions.

  • ADMINISTER_PROJECTS
  • BROWSE_PROJECTS
  • VIEW_DEV_TOOLS
  • VIEW_READONLY_WORKFLOW
  • CREATE_ISSUES
  • EDIT_ISSUES
  • TRANSITION_ISSUES
  • SCHEDULE_ISSUES
  • MOVE_ISSUES
  • ASSIGN_ISSUES
  • ASSIGNABLE_USER
  • RESOLVE_ISSUES
  • CLOSE_ISSUES
  • MODIFY_REPORTER
  • DELETE_ISSUES
  • LINK_ISSUES
  • SET_ISSUE_SECURITY
  • VIEW_VOTERS_AND_WATCHERS
  • MANAGE_WATCHERS
  • ADD_COMMENTS
  • EDIT_ALL_COMMENTS
  • EDIT_OWN_COMMENTS
  • DELETE_ALL_COMMENTS
  • DELETE_OWN_COMMENTS
  • CREATE_ATTACHMENTS
  • DELETE_ALL_ATTACHMENTS
  • DELETE_OWN_ATTACHMENTS
  • WORK_ON_ISSUES
  • EDIT_OWN_WORKLOGS
  • EDIT_ALL_WORKLOGS
  • DELETE_OWN_WORKLOGS
  • DELETE_ALL_WORKLOGS

Show more

Returns a list of all permission schemes.

By default only shortened beans are returned. If you want to include permissions of all the schemes, then specify the permissions expand parameter. Permissions will be included also if you specify any other expand parameter.

Request
query parameters
parametertypedescription
expandstring
Responses
  • Status 200 - application/json

    Example
    {"permissionSchemes":[{"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/10000","name":"Example permission scheme","description":"description"}]}

    Returned if successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/permission-schemes#","title":"Permission Schemes","type":"object","properties":{"permissionSchemes":{"type":"array","items":{"title":"Permission Scheme","type":"object","properties":{"expand":{"type":"string"},"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"title":"Permission Grant","type":"object","properties":{"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"holder":{"title":"Permission Holder","type":"object","properties":{"type":{"type":"string"},"parameter":{"type":"string"},"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]},"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"field":{"title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false},"projectRole":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false},"permission":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 401
    Returned if user is not logged in.
  • Status 403
    Returned if user is not allowed to view permission schemes.

Create a new permission scheme. This method can create schemes with a defined permission set, or without.

Request
query parameters
parametertypedescription
expandstring

Example
{"name":"Example permission scheme","description":"description","permissions":[{"holder":{"type":"group","parameter":"jira-developers"},"permission":"ADMINISTER_PROJECTS"}]}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/permission-scheme#","title":"Permission Scheme","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"title":"Permission Grant","type":"object","properties":{"holder":{"title":"Permission Holder","type":"object","properties":{"type":{"type":"string"},"parameter":{"type":"string"}},"additionalProperties":false},"permission":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

Responses
  • Status 201 - application/json

    Example
    {"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/10000","name":"Example permission scheme","description":"description","permissions":[{"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/permission/10000","holder":{"type":"group","parameter":"jira-developers","expand":"group"},"permission":"ADMINISTER_PROJECTS"}]}

    Returned if the scheme is created successfully.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/permission-scheme#","title":"Permission Scheme","type":"object","properties":{"expand":{"type":"string"},"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"title":"Permission Grant","type":"object","properties":{"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"holder":{"title":"Permission Holder","type":"object","properties":{"type":{"type":"string"},"parameter":{"type":"string"},"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]},"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"field":{"title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false},"projectRole":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false},"permission":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 401
    Returned if the user is not logged.
  • Status 403
    Returned if the user is not allowed to create permission schemes.

Returns a permission scheme identified by the given id.

Request
query parameters
parametertypedescription
expandstring
Responses
  • Status 200 - application/json

    Example
    {"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/10000","name":"Example permission scheme","description":"description","permissions":[{"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/permission/10000","holder":{"type":"group","parameter":"jira-developers","expand":"group"},"permission":"ADMINISTER_PROJECTS"}]}

    Returned if successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/permission-scheme#","title":"Permission Scheme","type":"object","properties":{"expand":{"type":"string"},"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"title":"Permission Grant","type":"object","properties":{"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"holder":{"title":"Permission Holder","type":"object","properties":{"type":{"type":"string"},"parameter":{"type":"string"},"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]},"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"field":{"title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false},"projectRole":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false},"permission":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 401
    Returned if user is not logged in.
  • Status 403
    Returned if user is not allowed to view permission schemes.
  • Status 404
    Returned if the scheme doesn't exist.

Deletes a permission scheme identified by the given id.

Responses
  • Status 401
    Returned if user is not logged in.
  • Status 204 - application/json
    Returned if the permission scheme is successfully deleted.
  • Status 403
    Returned if user is not allowed to delete permission schemes.

Updates a permission scheme.

If the permissions list is present then it will be set in the permission scheme, which basically means it will overwrite any permission grants that existed in the permission scheme. Sending an empty list will remove all permission grants from the permission scheme.

To update just the name and description, do not send permissions list at all.

To add or remove a single permission grant instead of updating the whole list at once use the {schemeId}/permission/ resource.

Request
query parameters
parametertypedescription
expandstring

Example
{"name":"Example permission scheme","description":"description","permissions":[{"holder":{"type":"group","parameter":"jira-developers"},"permission":"ADMINISTER_PROJECTS"}]}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/permission-scheme#","title":"Permission Scheme","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"title":"Permission Grant","type":"object","properties":{"holder":{"title":"Permission Holder","type":"object","properties":{"type":{"type":"string"},"parameter":{"type":"string"}},"additionalProperties":false},"permission":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

Responses
  • Status 201 - application/json

    Example
    {"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/10000","name":"Example permission scheme","description":"description","permissions":[{"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/permission/10000","holder":{"type":"group","parameter":"jira-developers","expand":"group"},"permission":"ADMINISTER_PROJECTS"}]}

    Returned if the scheme is updated successfully.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/permission-scheme#","title":"Permission Scheme","type":"object","properties":{"expand":{"type":"string"},"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"title":"Permission Grant","type":"object","properties":{"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"holder":{"title":"Permission Holder","type":"object","properties":{"type":{"type":"string"},"parameter":{"type":"string"},"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]},"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"field":{"title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false},"projectRole":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false},"permission":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 401
    Returned if the user is not logged.
  • Status 403
    Returned if the user is not allowed to edit permission schemes.
  • Status 404
    Returned if the permission is not found.

Returns all permission grants of the given permission scheme.

Request
query parameters
parametertypedescription
expandstring
Responses
  • Status 200 - application/json

    Example
    {"permissions":[{"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/permission/10000","holder":{"type":"group","parameter":"jira-developers","expand":"group"},"permission":"ADMINISTER_PROJECTS"}],"expand":"user,group,projectRole,field,all"}

    Returned if successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/permission-grants#","title":"Permission Grants","type":"object","properties":{"permissions":{"type":"array","items":{"title":"Permission Grant","type":"object","properties":{"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"holder":{"title":"Permission Holder","type":"object","properties":{"type":{"type":"string"},"parameter":{"type":"string"},"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]},"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"field":{"title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false},"projectRole":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false},"permission":{"type":"string"}},"additionalProperties":false}},"expand":{"type":"string"}},"additionalProperties":false}

  • Status 401
    Returned if user is not logged in.
  • Status 403
    Returned if user is not allowed to view permission schemes.

Creates a permission grant in a permission scheme.

Request
query parameters
parametertypedescription
expandstring

Example
{"holder":{"type":"group","parameter":"jira-developers"},"permission":"ADMINISTER_PROJECTS"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/permission-grant#","title":"Permission Grant","type":"object","properties":{"holder":{"title":"Permission Holder","type":"object","properties":{"type":{"type":"string"},"parameter":{"type":"string"}},"additionalProperties":false},"permission":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 201 - application/json

    Example
    {"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/permission/10000","holder":{"type":"group","parameter":"jira-developers","expand":"group"},"permission":"ADMINISTER_PROJECTS"}

    Returned if the scheme permission is created successfully.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/permission-grant#","title":"Permission Grant","type":"object","properties":{"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"holder":{"title":"Permission Holder","type":"object","properties":{"type":{"type":"string"},"parameter":{"type":"string"},"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]},"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"field":{"title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false},"projectRole":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false},"permission":{"type":"string"}},"additionalProperties":false}

  • Status 401
    Returned if the user is not logged.
  • Status 403
    Returned if the user is not allowed to edit permission schemes.

Deletes a permission grant from a permission scheme.

Responses
  • Status 401
    Returned if the user is not logged.
  • Status 204 - application/json
    Returned if the permission grant is deleted successfully.
  • Status 403
    Returned if the user is not allowed to edit permission schemes.

Returns a permission grant identified by the given id.

Request
query parameters
parametertypedescription
expandstring
Responses
  • Status 200 - application/json

    Example
    {"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/permission/10000","holder":{"type":"group","parameter":"jira-developers","expand":"group"},"permission":"ADMINISTER_PROJECTS"}

    Returned if successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/permission-grant#","title":"Permission Grant","type":"object","properties":{"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"holder":{"title":"Permission Holder","type":"object","properties":{"type":{"type":"string"},"parameter":{"type":"string"},"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]},"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"field":{"title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false},"projectRole":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false},"permission":{"type":"string"}},"additionalProperties":false}

  • Status 401
    Returned if user is not logged in.
  • Status 403
    Returned if user is not allowed to view permission schemes.

api/2/priority

Returns a list of all issue priorities.

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-priority#","title":"List of Priority","type":"array","items":{"title":"Priority","type":"object","properties":{"self":{"type":"string"},"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"}},"additionalProperties":false}}

Returns an issue priority.

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/priority#","title":"Priority","type":"object","properties":{"self":{"type":"string"},"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"}},"additionalProperties":false}

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

api/2/project

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
parametertypedescription
expandstring

the parameters to expand

recentint

if this parameter is set then only projects recently accessed by the current user (if not logged in then based on HTTP session) will be returned (maximum count limited to the specified number but no more than 20).

Responses
  • Status 200 - application/json

    Example
    [{"self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","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"},"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":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10001","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"},"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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-project#","title":"List of Project","type":"array","items":{"title":"Project","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"additionalProperties":false},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}

Creates a new project.

Request

Example
{"key":"EX","name":"Example","projectTypeKey":"business","projectTemplateKey":"com.atlassian.jira-core-project-templates:jira-core-project-management","description":"Example Project description","lead":"Charlie","url":"http://atlassian.com","assigneeType":"PROJECT_LEAD","avatarId":10200,"issueSecurityScheme":10001,"permissionScheme":10011,"notificationScheme":10021,"categoryId":10120}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/project-input#","title":"Project Input","type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"projectTypeKey":{"type":"string"},"projectTemplateKey":{"type":"string"},"description":{"type":"string"},"lead":{"type":"string"},"url":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"avatarId":{"type":"integer"},"issueSecurityScheme":{"type":"integer"},"permissionScheme":{"type":"integer"},"notificationScheme":{"type":"integer"},"categoryId":{"type":"integer"}},"additionalProperties":false}

Responses
  • Status 201 - application/json

    Example
    {"self":"http://example/jira/rest/api/2/project/10042","id":10010,"key":"EX"}

    Returned if the project creation was successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-identity#","title":"Project Identity","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"integer"},"key":{"type":"string"}},"additionalProperties":false}

  • Status 400
    Returned if the request is not valid and the project could not be created.
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not have rights to create projects.

Updates a project.

Only non null values sent in JSON will be updated in the project.

Values available for the assigneeType field are: "PROJECT_LEAD" and "UNASSIGNED".

Request
query parameters
parametertypedescription
expandstring

the parameters to expand in returned project

Example
{"key":"EX","name":"Example","projectTypeKey":"business","projectTemplateKey":"com.atlassian.jira-core-project-templates:jira-core-project-management","description":"Example Project description","lead":"Charlie","url":"http://atlassian.com","assigneeType":"PROJECT_LEAD","avatarId":10200,"issueSecurityScheme":10001,"permissionScheme":10011,"notificationScheme":10021,"categoryId":10120}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/project-input#","title":"Project Input","type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"projectTypeKey":{"type":"string"},"projectTemplateKey":{"type":"string"},"description":{"type":"string"},"lead":{"type":"string"},"url":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"avatarId":{"type":"integer"},"issueSecurityScheme":{"type":"integer"},"permissionScheme":{"type":"integer"},"notificationScheme":{"type":"integer"},"categoryId":{"type":"integer"}},"additionalProperties":false}

Responses
  • Status 201 - application/json

    Example
    {"expand":"description,lead,issueTypes,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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"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":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","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"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}}

    Returned if the project update was successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project#","title":"Project","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

  • Status 400
    Returned if the request is not valid and the project could not be updated.
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not have rights to update projects.
  • Status 404
    Returned if the project does not exist.

Deletes a project.

Responses
  • Status 401
    Returned if the user is not logged in.
  • Status 204 - application/json
    Returned if the project is successfully deleted.
  • Status 403
    Returned if the currently authenticated user does not have permission to delete the project.
  • Status 404
    Returned if the project does not exist.

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
parametertypedescription
expandstring

the parameters to expand

Responses
  • Status 200 - application/json

    Example
    {"expand":"description,lead,issueTypes,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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"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":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","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"},"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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project#","title":"Project","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/avatar#","title":"Avatar","type":"object","properties":{"id":{"type":"string"},"owner":{"type":"string"},"isSystemAvatar":{"type":"boolean"},"isSelected":{"type":"boolean"},"isDeletable":{"type":"boolean"},"urls":{"type":"object","patternProperties":{"\\d\\dx\\d\\d":{"type":"string","format":"uri"}},"additionalProperties":false},"selected":{"type":"boolean"}},"additionalProperties":false,"required":["isSystemAvatar","isSelected","isDeletable","selected"]}

Responses
  • Status - application/json

Deletes avatar

Responses
  • Status 204 - application/json
    Returned if the avatar is successfully deleted.
  • Status 403
    Returned if the currently authenticated user does not have permission to delete the component.
  • Status 404
    Returned if the avatar does not exist or the currently authenticated user does not have permission to delete it.

Creates an avatar for a project, for a given project Id or project key. The uploaded image will be cropped according to the crop parameters listed below. If no crop parameters are specified, the image will be cropped to a square. The square will originate at the top left of the image and the length of each side will be set to the smaller of the height or width of the image.

Request
query parameters
parametertypedescription
xint

(optional) The X coordinate of the top-left corner of the crop region. Default: 0.

yint

(optional) The Y coordinate of the top-left corner of the crop region. Default: 0.

sizeint

(optional) The length of each side of the crop region. The crop region can only be a square. If omitted and the top-left corner is at (0,0), this defaults to either the height or width of the image, whichever is smaller.

Responses
  • Status 201 - application/json

    Example
    {"id":"1000","owner":"fred","isSystemAvatar":true,"isSelected":false,"isDeletable":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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/avatar#","title":"Avatar","type":"object","properties":{"id":{"type":"string"},"owner":{"type":"string"},"isSystemAvatar":{"type":"boolean"},"isSelected":{"type":"boolean"},"isDeletable":{"type":"boolean"},"urls":{"type":"object","patternProperties":{"\\d\\dx\\d\\d":{"type":"string","format":"uri"}},"additionalProperties":false},"selected":{"type":"boolean"}},"additionalProperties":false,"required":["isSystemAvatar","isSelected","isDeletable","selected"]}

  • Status 400
    Returned if the cropping coordinates are invalid.
  • Status 403
    Returned if the currently authenticated user does not have permission to pick an avatar or if the request does not contain a valid XSRF token.
  • Status 404
    Returned if the project does not exist or currently authenticated user does not have EDIT PROJECT permission.

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

Responses
  • Status 200 - application/json

    Example
    {"system":[{"id":"1000","owner":"fred","isSystemAvatar":true,"isSelected":false,"isDeletable":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,"isDeletable":true,"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.

    Schema
    {"type":"object","patternProperties":{".+":{"type":"array","items":{"title":"Avatar","type":"object","properties":{"id":{"type":"string"},"owner":{"type":"string"},"isSystemAvatar":{"type":"boolean"},"isSelected":{"type":"boolean"},"isDeletable":{"type":"boolean"},"urls":{"type":"object","patternProperties":{"\\d\\dx\\d\\d":{"type":"string","format":"uri"}},"additionalProperties":false},"selected":{"type":"boolean"}},"additionalProperties":false,"required":["isSystemAvatar","isSelected","isDeletable","selected"]}}},"additionalProperties":false}

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

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

Responses
  • Status 200 - application/json

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-component#","title":"List of Component","type":"array","items":{"title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}

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

Get all issue types with valid status values for a project

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-issue-type-with-status#","title":"List of Issue Type With Status","type":"array","items":{"title":"Issue Type With Status","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"statuses":{"type":"array","items":{"title":"Status","type":"object","properties":{"self":{"type":"string"},"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false,"required":["subtask"]}}

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

Updates the type of a project.

Responses
  • Status 200 - application/json

    Example
    {"expand":"description,lead,issueTypes,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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"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":{"48x48":"http://www.example.com/jira/secure/projectavatar?size=large&pid=10000","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"},"projectCategory":{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}}

    Returned if the update to the project type was successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project#","title":"Project","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"key":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"components":{"type":"array","items":{"title":"Component","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lead":{"$ref":"#/definitions/user"},"leadUserName":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"assignee":{"$ref":"#/definitions/user"},"realAssigneeType":{"type":"string","enum":["PROJECT_DEFAULT","COMPONENT_LEAD","PROJECT_LEAD","UNASSIGNED"]},"realAssignee":{"$ref":"#/definitions/user"},"isAssigneeTypeValid":{"type":"boolean"},"project":{"type":"string"},"projectId":{"type":"integer"}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}},"issueTypes":{"type":"array","items":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"url":{"type":"string"},"email":{"type":"string"},"assigneeType":{"type":"string","enum":["PROJECT_LEAD","UNASSIGNED"]},"versions":{"type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}},"name":{"type":"string"},"roles":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"projectKeys":{"type":"array","items":{"type":"string"}},"projectCategory":{"title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false},"projectTypeKey":{"type":"string"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]},"user":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}

  • Status 400
    Returned if the request is not valid and the project type could not be updated.
  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not have rights to update projects.
  • Status 404
    Returned if the project does not exist.

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

Results can be ordered by the following fields:

  • sequence
  • name
  • startDate
  • releaseDate

Request
query parameters
parametertypedescription
startAtlong

the page offset, if not specified then defaults to 0

maxResultsint

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

orderBystring

ordering of the results.

expandstring

the parameters to expand

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/page-of-version#","title":"Page of Version","type":"object","properties":{"self":{"type":"string","format":"uri"},"nextPage":{"type":"string","format":"uri"},"maxResults":{"type":"integer"},"startAt":{"type":"integer"},"total":{"type":"integer"},"isLast":{"type":"boolean"},"values":{"type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}}},"additionalProperties":false,"required":["maxResults","startAt"]}

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

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

Request
query parameters
parametertypedescription
expandstring

the parameters to expand

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-version#","title":"List of Version","type":"array","items":{"title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}}

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

api/2/project/{projectIdOrKey}/properties

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-properties-keys#","title":"Entity Properties Keys","type":"object","properties":{"keys":{"type":"array","items":{"title":"Entity Property Key","type":"object","properties":{"self":{"type":"string"},"key":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 400
    Returned if the project key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to browse the project.
  • Status 404
    Returned if the project with given key or id does not exist or if the property with given key is not found.

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.

Responses
  • Status 400
    Returned if the project key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 204
    Returned if the project property was removed successfully.
  • Status 403
    Returned if the calling user does not have permission to edit the project.
  • Status 404
    Returned if the project with given key or id does not exist or if the property with given key is not found.

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.

Responses
  • Status 200
    Returned if the project property is successfully updated.
  • Status 201
    Returned if the project property is successfully created.
  • Status 400
    Returned if the project key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to administer the project.
  • Status 404
    Returned if the project with given key or id does not exist.

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.

Responses
  • Status 200 - application/json

    Example
    {"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}

    Returned if the project property was found.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-property#","title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}

  • Status 400
    Returned if the project key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to browse the project.
  • Status 404
    Returned if the project with given key or id does not exist or if the property with given key is not found.

api/2/project/{projectIdOrKey}/role

Returns all roles in the given project Id or key, with links to full details on each role.

Responses
  • Status 200 - application/json

    Example
    {"Administrators":"http://www.example.com/jira/rest/api/2/project/MKY/role/10002","Users":"http://www.example.com/jira/rest/api/2/project/MKY/role/10001","Developers":"http://www.example.com/jira/rest/api/2/project/MKY/role/10000"}

    Returns a map of the roles to URIs containing full details for each role. The project must exist and the user must have permission to view it.

    Schema
    {"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false}

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

Returns the details for a given project role in a project together with project role actors.

The project role actor can be either a user or a group. Note that the name of a user actor is the user key.

If you would like to check if a user belongs to the role you need to get all groups to which the user belongs using /rest/user?userkey={userkey}&expand=groups resource and check if there is a user actor with the name same as the user key or if there is a group actor with the name as one of the group to which the user belongs.

Responses
  • Status 200 - application/json

    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"},{"id":10241,"displayName":"Fred F. User","type":"atlassian-user-role-actor","name":"fred"}]}

    Returns the role name, description, and project actors (users and groups) for the requested role. The project must exist and the user must have permission to view it.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-role#","title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}

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

Updates a project role to include the specified actors (users or groups).

Request

Example
{"id":10360,"categorisedActors":{"atlassian-user-role-actor":["admin"],"atlassian-group-role-actor":["jira-developers"]}}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/project-role-actors-update#","title":"Project Role Actors Update","type":"object","properties":{"id":{"type":"integer"},"categorisedActors":{"type":"object","patternProperties":{".+":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"additionalProperties":false}

Responses
  • Status 200 - application/json

    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"},{"id":10241,"displayName":"Fred F. User","type":"atlassian-user-role-actor","name":"fred"}]}

    Returns the role name, description, and project actors (users and groups) for the requested role. The project must exist and the user must have permission to view it.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-role#","title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 404
    Returned if the actor could not be added to the project role

Adds an actor (user or group) to a project role.

Request

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

Schema
{"type":"object","patternProperties":{".+":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

Responses
  • Status 200 - application/json

    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"},{"id":10241,"displayName":"Fred F. User","type":"atlassian-user-role-actor","name":"fred"}]}

    Returns the role name, description, and project actors (users and groups) for the requested role. The project must exist and the user must have permission to view it.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-role#","title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 404
    Returned if the actor could not be added to the project role

Deletes actors (users or groups) from a project role.

  • Delete a user from the role: /rest/api/2/project/{projectIdOrKey}/role/{roleId}?user={username}
  • Delete a group from the role: /rest/api/2/project/{projectIdOrKey}/role/{roleId}?group={groupname}

Request
query parameters
parametertypedescription
userstring

the username to remove from the project role

groupstring

the groupname to remove from the project role

Responses
  • Status 204
    Returned if the actor was successfully removed from the project role.
  • Status 404
    Returned if the project or role is not found, the calling user does not have permission to view it or does not have permission to modify the actors in the project role.

api/2/project/{projectKeyOrId}/issuesecuritylevelscheme

Resource for associating permission schemes and projects.

Returns the issue security scheme for project.

Responses
  • Status 200 - application/json

    Example
    {"self":"http://www.example.com/jira/rest/api/2/issuesecurityschemes/1000","id":1000,"name":"Default Issue Security Scheme","description":"Description for the default issue security scheme","defaultSecurityLevelId":10021,"levels":[{"self":"http://www.example.com/jira/rest/api/2/securitylevel/10021","id":"10021","description":"Only the reporter and internal staff can see this issue.","name":"Reporter Only"}]}

    Returned if the user has the administrator permission or if the scheme is used in a project in which the user has the administrative permission.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/security-scheme#","title":"Security Scheme","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultSecurityLevelId":{"type":"integer"},"levels":{"type":"array","items":{"title":"Security Level","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the project is visible for calling user, but the user doesn't have administrative permissions
  • Status 404
    Returned if the project does not exist, or is not visible to the calling user

api/2/project/{projectKeyOrId}/notificationscheme

Resource for associating notification schemes and projects.

Gets a notification scheme associated with the project. Follow the documentation of /notificationscheme/{id} resource for all details about returned value.

Request
query parameters
parametertypedescription
expandstring
Responses
  • Status 200 - application/json

    Example
    {"expand":"notificationSchemeEvents,user,group,projectRole,field,all","id":10100,"self":"http://example.com/jira/rest/api/2/notificationscheme/10010","name":"notification scheme name","description":"description","notificationSchemeEvents":[{"event":{"id":1,"name":"Issue created","description":"Event published when issue is created"},"notifications":[{"id":1,"notificationType":"Group","parameter":"jira-administrators","group":{"name":"jira-administrators","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-administrators"},"expand":"group"},{"id":2,"notificationType":"CurrentAssignee"},{"id":3,"notificationType":"ProjectRole","parameter":"10360","projectRole":{"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"},{"id":10241,"displayName":"Fred F. User","type":"atlassian-user-role-actor","name":"fred"}]},"expand":"projectRole"},{"id":4,"notificationType":"EmailAddress","parameter":"rest-developer@atlassian.com","emailAddress":"rest-developer@atlassian.com"},{"id":5,"notificationType":"User","user":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"expand":"user"},{"id":6,"notificationType":"GroupCustomField","parameter":"customfield_10101","field":{"id":"customfield_10101","key":"custom_fields_may_have_friendly_keys","name":"New custom field","custom":true,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["cf[10101]","New custom field"],"schema":{"type":"project","custom":"com.atlassian.jira.plugin.system.customfieldtypes:project","customId":10101}},"expand":"field"}]},{"event":{"id":20,"name":"Custom event","description":"Custom event which is published together with issue created event","templateEvent":{"id":1,"name":"Issue created","description":"Event published when issue is created"}},"notifications":[{"id":1,"notificationType":"Group","parameter":"jira-administrators","group":{"name":"jira-administrators","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-administrators"},"expand":"group"},{"id":2,"notificationType":"CurrentAssignee"},{"id":3,"notificationType":"ProjectRole","parameter":"10360","projectRole":{"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"},{"id":10241,"displayName":"Fred F. User","type":"atlassian-user-role-actor","name":"fred"}]},"expand":"projectRole"},{"id":4,"notificationType":"EmailAddress","parameter":"rest-developer@atlassian.com","emailAddress":"rest-developer@atlassian.com"},{"id":5,"notificationType":"User","user":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","name":"fred","displayName":"Fred F. User","active":false},"expand":"user"},{"id":6,"notificationType":"GroupCustomField","parameter":"customfield_10101","field":{"id":"customfield_10101","key":"custom_fields_may_have_friendly_keys","name":"New custom field","custom":true,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["cf[10101]","New custom field"],"schema":{"type":"project","custom":"com.atlassian.jira.plugin.system.customfieldtypes:project","customId":10101}},"expand":"field"}]}]}

    Returned if the notification scheme exists and is visible for the calling user

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/notification-scheme#","title":"Notification Scheme","type":"object","properties":{"expand":{"type":"string"},"id":{"type":"integer"},"self":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"notificationSchemeEvents":{"type":"array","items":{"title":"Notification Scheme Event","type":"object","properties":{"event":{"$ref":"#/definitions/notification-event"},"notifications":{"type":"array","items":{"title":"Notification","type":"object","anyOf":[{"$ref":"#/definitions/custom-field-value-notification"},{"$ref":"#/definitions/email-notification"},{"$ref":"#/definitions/group-notification"},{"$ref":"#/definitions/project-role-notification"},{"$ref":"#/definitions/role-notification"},{"$ref":"#/definitions/user-notification"}]}}},"additionalProperties":false}}},"definitions":{"custom-field-value-notification":{"title":"Custom Field Value Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"field":{"title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"email-notification":{"title":"Email Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"emailAddress":{"type":"string"}},"additionalProperties":false},"group-notification":{"title":"Group Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false},"notification-event":{"title":"Notification Event","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"templateEvent":{"$ref":"#/definitions/notification-event"}},"additionalProperties":false},"project-role-notification":{"title":"Project Role Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"projectRole":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false},"role-notification":{"title":"Role Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"}},"additionalProperties":false},"user-notification":{"title":"User Notification","type":"object","properties":{"id":{"type":"integer"},"notificationType":{"type":"string"},"parameter":{"type":"string"},"expand":{"type":"string"},"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}},"additionalProperties":false}

  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user is allowed to access the project, but is not an administrator of the project or JIRA and therefore can't see the notification scheme of the project.
  • Status 404
    Returned if the notification scheme does not exist, or is not visible to the calling user

api/2/project/{projectKeyOrId}/permissionscheme

Resource for associating permission schemes and projects.

Gets a permission scheme assigned with a project.

Request
query parameters
parametertypedescription
expandstring
Responses
  • Status 200 - application/json

    Example
    {"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/10000","name":"Example permission scheme","description":"description"}

    The associated permission scheme.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/permission-scheme#","title":"Permission Scheme","type":"object","properties":{"expand":{"type":"string"},"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"title":"Permission Grant","type":"object","properties":{"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"holder":{"title":"Permission Holder","type":"object","properties":{"type":{"type":"string"},"parameter":{"type":"string"},"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]},"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"field":{"title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false},"projectRole":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false},"permission":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not have permissions to view the project's configuration. In practice the user needs to be a JRA administrator or the project's administrator to get the assigned permission scheme.
  • Status 404
    Returned if the project is not found (or the user does not have permissions to view the project).

Assigns a permission scheme with a project.

Request
query parameters
parametertypedescription
expandstring

Example
{"id":10000}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/id#","title":"Id","type":"object","properties":{"id":{"type":"integer"}},"additionalProperties":false}

Responses
  • Status 200 - application/json

    Example
    {"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/10000","name":"Example permission scheme","description":"description"}

    Shortened details of the newly associated permission scheme.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/permission-scheme#","title":"Permission Scheme","type":"object","properties":{"expand":{"type":"string"},"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"name":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"title":"Permission Grant","type":"object","properties":{"id":{"type":"integer"},"self":{"type":"string","format":"uri"},"holder":{"title":"Permission Holder","type":"object","properties":{"type":{"type":"string"},"parameter":{"type":"string"},"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]},"group":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false},"field":{"title":"Field","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"},"custom":{"type":"boolean"},"orderable":{"type":"boolean"},"navigable":{"type":"boolean"},"searchable":{"type":"boolean"},"clauseNames":{"type":"array","items":{"type":"string"}},"schema":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false},"projectRole":{"title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false},"permission":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 401
    Returned if the user is not logged in.
  • Status 403
    Returned if the user does not have permissions to edit project's permission schemes. In practice the user needs to be a JIRA administrator.
  • Status 404
    Returned if the project or permission scheme is not found.

api/2/project/{projectKeyOrId}/securitylevel

Provide security level information of the given project for the current user.

Returns all security levels for the project that the current logged in user has access to. If the user does not have the Set Issue Security permission, the list will be empty.

Responses
  • Status 200 - application/json

    Example
    {"levels":[{"self":"http://www.example.com/jira/rest/api/2/securitylevel/100000","id":"100000","description":"security description","name":"securityLevelName"},{"self":"http://www.example.com/jira/rest/api/2/securitylevel/100001","id":"100001","description":"another security description","name":"secret"}]}

    Returns a list of all security levels in a project for which the current user has access.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/security-list-level#","title":"Security List Level","type":"object","properties":{"levels":{"type":"array","items":{"title":"Security Level","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 404
    Returned if the project is not found or the user does not have permissions to browse it.

api/2/project/type

Returns all the project types defined on the JIRA instance, not taking into account whether the license to use those project types is valid or not.

Responses
  • Status 200 - application/json

    Example
    [{"key":"business","formattedKey":"Business","descriptionI18nKey":"Project type for business projects","icon":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAxOC4xLjEsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjxzdmcgdmVyc2lvbj0iMS4xIiBpZD0iTGF5ZXJfMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgeD0iMHB4IiB5PSIwcHgiDQoJIHZpZXdCb3g9IjAgMCAzMiAzMiIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgMzIgMzIiIHhtbDpzcGFjZT0icHJlc2VydmUiPg0KPGc+DQoJPHBhdGggZmlsbD0iIzY2NjY2NiIgZD0iTTE2LDBDNy4yLDAsMCw3LjIsMCwxNmMwLDguOCw3LjIsMTYsMTYsMTZjOC44LDAsMTYtNy4yLDE2LTE2QzMyLDcuMiwyNC44LDAsMTYsMHogTTI1LjcsMjMNCgkJYzAsMS44LTEuNCwzLjItMy4yLDMuMkg5LjJDNy41LDI2LjIsNiwyNC44LDYsMjNWOS44QzYsOCw3LjUsNi42LDkuMiw2LjZoMTMuMmMwLjIsMCwwLjQsMCwwLjcsMC4xbC0yLjgsMi44SDkuMg0KCQlDOSw5LjQsOC44LDkuNiw4LjgsOS44VjIzYzAsMC4yLDAuMiwwLjQsMC40LDAuNGgxMy4yYzAuMiwwLDAuNC0wLjIsMC40LTAuNHYtNS4zbDIuOC0yLjhWMjN6IE0xNS45LDIxLjNMMTEsMTYuNGwyLTJsMi45LDIuOQ0KCQlMMjYuNCw2LjhjMC42LDAuNywxLjIsMS41LDEuNywyLjNMMTUuOSwyMS4zeiIvPg0KPC9nPg0KPC9zdmc+","color":"#FFFFFF"},{"key":"software","formattedKey":"Software","descriptionI18nKey":"Project type for software projects","icon":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAxOC4xLjEsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjxzdmcgdmVyc2lvbj0iMS4xIiBpZD0iTGF5ZXJfMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgeD0iMHB4IiB5PSIwcHgiDQoJIHZpZXdCb3g9IjAgMCAzMiAzMiIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgMzIgMzIiIHhtbDpzcGFjZT0icHJlc2VydmUiPg0KPGc+DQoJPHBhdGggZmlsbD0iIzY2NjY2NiIgZD0iTTE2LDBDNy4yLDAsMCw3LjIsMCwxNmMwLDguOCw3LjIsMTYsMTYsMTZjOC44LDAsMTYtNy4yLDE2LTE2QzMyLDcuMiwyNC44LDAsMTYsMHogTTI1LjcsMjMNCgkJYzAsMS44LTEuNCwzLjItMy4yLDMuMkg5LjJDNy41LDI2LjIsNiwyNC44LDYsMjNWOS44QzYsOCw3LjUsNi42LDkuMiw2LjZoMTMuMmMwLjIsMCwwLjQsMCwwLjcsMC4xbC0yLjgsMi44SDkuMg0KCQlDOSw5LjQsOC44LDkuNiw4LjgsOS44VjIzYzAsMC4yLDAuMiwwLjQsMC40LDAuNGgxMy4yYzAuMiwwLDAuNC0wLjIsMC40LTAuNHYtNS4zbDIuOC0yLjhWMjN6IE0xNS45LDIxLjNMMTEsMTYuNGwyLTJsMi45LDIuOQ0KCQlMMjYuNCw2LjhjMC42LDAuNywxLjIsMS41LDEuNywyLjNMMTUuOSwyMS4zeiIvPg0KPC9nPg0KPC9zdmc+","color":"#AAAAAA"}]

    Returns a list with all the project types defined on the JIRA instance.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-project-type#","title":"List of Project Type","type":"array","items":{"title":"Project Type","type":"object","properties":{"key":{"type":"string"},"formattedKey":{"type":"string"},"descriptionI18nKey":{"type":"string"},"icon":{"type":"string"},"color":{"type":"string"}},"additionalProperties":false}}

Returns the project type with the given key.

Responses
  • Status 200 - application/json

    Example
    {"key":"business","formattedKey":"Business","descriptionI18nKey":"Project type for business projects","icon":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAxOC4xLjEsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjxzdmcgdmVyc2lvbj0iMS4xIiBpZD0iTGF5ZXJfMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgeD0iMHB4IiB5PSIwcHgiDQoJIHZpZXdCb3g9IjAgMCAzMiAzMiIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgMzIgMzIiIHhtbDpzcGFjZT0icHJlc2VydmUiPg0KPGc+DQoJPHBhdGggZmlsbD0iIzY2NjY2NiIgZD0iTTE2LDBDNy4yLDAsMCw3LjIsMCwxNmMwLDguOCw3LjIsMTYsMTYsMTZjOC44LDAsMTYtNy4yLDE2LTE2QzMyLDcuMiwyNC44LDAsMTYsMHogTTI1LjcsMjMNCgkJYzAsMS44LTEuNCwzLjItMy4yLDMuMkg5LjJDNy41LDI2LjIsNiwyNC44LDYsMjNWOS44QzYsOCw3LjUsNi42LDkuMiw2LjZoMTMuMmMwLjIsMCwwLjQsMCwwLjcsMC4xbC0yLjgsMi44SDkuMg0KCQlDOSw5LjQsOC44LDkuNiw4LjgsOS44VjIzYzAsMC4yLDAuMiwwLjQsMC40LDAuNGgxMy4yYzAuMiwwLDAuNC0wLjIsMC40LTAuNHYtNS4zbDIuOC0yLjhWMjN6IE0xNS45LDIxLjNMMTEsMTYuNGwyLTJsMi45LDIuOQ0KCQlMMjYuNCw2LjhjMC42LDAuNywxLjIsMS41LDEuNywyLjNMMTUuOSwyMS4zeiIvPg0KPC9nPg0KPC9zdmc+","color":"#FFFFFF"}

    Returns a representation of the project type with the given id

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-type#","title":"Project Type","type":"object","properties":{"key":{"type":"string"},"formattedKey":{"type":"string"},"descriptionI18nKey":{"type":"string"},"icon":{"type":"string"},"color":{"type":"string"}},"additionalProperties":false}

Returns the project type with the given key, if it is accessible to the logged in user. This takes into account whether the user is licensed on the Application that defines the project type.

Responses
  • Status 200 - application/json

    Example
    {"key":"business","formattedKey":"Business","descriptionI18nKey":"Project type for business projects","icon":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAxOC4xLjEsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjxzdmcgdmVyc2lvbj0iMS4xIiBpZD0iTGF5ZXJfMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgeD0iMHB4IiB5PSIwcHgiDQoJIHZpZXdCb3g9IjAgMCAzMiAzMiIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgMzIgMzIiIHhtbDpzcGFjZT0icHJlc2VydmUiPg0KPGc+DQoJPHBhdGggZmlsbD0iIzY2NjY2NiIgZD0iTTE2LDBDNy4yLDAsMCw3LjIsMCwxNmMwLDguOCw3LjIsMTYsMTYsMTZjOC44LDAsMTYtNy4yLDE2LTE2QzMyLDcuMiwyNC44LDAsMTYsMHogTTI1LjcsMjMNCgkJYzAsMS44LTEuNCwzLjItMy4yLDMuMkg5LjJDNy41LDI2LjIsNiwyNC44LDYsMjNWOS44QzYsOCw3LjUsNi42LDkuMiw2LjZoMTMuMmMwLjIsMCwwLjQsMCwwLjcsMC4xbC0yLjgsMi44SDkuMg0KCQlDOSw5LjQsOC44LDkuNiw4LjgsOS44VjIzYzAsMC4yLDAuMiwwLjQsMC40LDAuNGgxMy4yYzAuMiwwLDAuNC0wLjIsMC40LTAuNHYtNS4zbDIuOC0yLjhWMjN6IE0xNS45LDIxLjNMMTEsMTYuNGwyLTJsMi45LDIuOQ0KCQlMMjYuNCw2LjhjMC42LDAuNywxLjIsMS41LDEuNywyLjNMMTUuOSwyMS4zeiIvPg0KPC9nPg0KPC9zdmc+","color":"#FFFFFF"}

    Returns a representation of the project type with the given id

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-type#","title":"Project Type","type":"object","properties":{"key":{"type":"string"},"formattedKey":{"type":"string"},"descriptionI18nKey":{"type":"string"},"icon":{"type":"string"},"color":{"type":"string"}},"additionalProperties":false}

  • Status 401
    A response status of 401 indicates that there is not a logged in user and therefore this operation can't be performed
  • Status 404
    A response status of 404 indicates that the project type is not accessible for the logged in user

api/2/projectCategory

Returns all project categories

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-project-category#","title":"List of Project Category","type":"array","items":{"title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false}}

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

Create a project category via POST.

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/project-category#","title":"Project Category","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 201 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-category#","title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false}

  • Status 401
    Returned if the caller is not logged in so does not have permission to create project categories.
  • Status 403
    Returned if the caller is authenticated and does not have permission to create project categories (is not global admin).
  • Status 409
    Returned if a project category with the given name already exists.

Contains a representation of a project category in JSON format.

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-category#","title":"Project Category","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false}

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

Delete a project category.

Responses
  • Status 401
    Returned if the caller is not logged in so does not have permission to delete project categories.
  • Status 204
    Returned if the project category is successfully deleted.
  • Status 403
    Returned if the caller is authenticated and does not have permission to delete project categories (is not global admin).
  • Status 404
    Returned if the project category does not exist or the currently authenticated user does not have permission to view it.

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.

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/project-category#","title":"Project Category","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}},"additionalProperties":false}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-category#","title":"Project Category","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}

  • Status 201

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-category#","title":"Project Category","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}

  • Status 401
    Returned if the caller is not logged in so does not have permission to change project categories.
  • Status 403
    Returned if the caller is authenticated and does not have permission to change project categories (is not global admin).
  • Status 404
    Returned if the project category does not exist or the currently authenticated user does not have permission to view it.

api/2/projectvalidate

Validates the project key and generated a valid project key if the supplied key is invalid.

Request
query parameters
parametertypedescription
keystring

the project key

Responses
  • Status 200 - application/json

    Example
    "VPNE"

    Returns a String containing a valid project key.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/string#","title":"String","type":"string"}

Validates a project name. If the name is invalid, an attempt is made to produce a valid name based on the supplied one. If no such valid name can be found, an empty string is returned.

Request
query parameters
parametertypedescription
namestring

the project name

Responses
  • Status 200 - application/json

    Example
    "Valid Project Name Example"

    Returns a String containing a valid project name, or the empty string.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/string#","title":"String","type":"string"}

Validates a project key.

Request
query parameters
parametertypedescription
keystring

the project key

Responses
  • Status 200 - application/json

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

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/error-collection#","title":"Error Collection","type":"object","properties":{"errorMessages":{"type":"array","items":{"type":"string"}},"errors":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"status":{"type":"integer"}},"additionalProperties":false}

api/2/reindex

REST resource for starting/stopping/querying indexing.

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

Note that some versions of JIRA may no longer require manual reindexing. In this case, this resource will no-op: a 200 OK response code will returned along with "progress details" that indicate the work is complete (progress=100%). Subsequent GETs will return 404 to indicate no actua reindex has taken place.

In the case that an index is actually triggered, this call will be asynchronous: it will return 202 immediately and then the caller can call GET on the resource to track progress of the task.

Request
query parameters
parametertypedescription
typestring

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

indexCommentsboolean

Default: false

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

indexChangeHistoryboolean

Default: false

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

indexWorklogsboolean

Default: false

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

Responses
  • Status 200 - application/json

    Example
    {"progressUrl":"/secure/admin/jira/IndexProgress.jspa?taskId=10000","currentProgress":50,"currentSubTask":"Currently reindexing Change History","type":"FOREGROUND","submittedTime":"2017-03-08T03:29:43.193+0000","startTime":"2017-03-08T03:29:43.193+0000","finishTime":"2017-03-08T03:29:43.193+0000","success":false}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/reindex#","title":"Reindex","type":"object","properties":{"progressUrl":{"type":"string"},"currentProgress":{"type":"integer"},"currentSubTask":{"type":"string"},"type":{"type":"string","enum":["FOREGROUND","BACKGROUND","BACKGROUND_PREFFERED","BACKGROUND_PREFERRED"]},"submittedTime":{"type":"string"},"startTime":{"type":"string"},"finishTime":{"type":"string"},"success":{"type":"boolean"}},"additionalProperties":false,"required":["success"]}

  • Status 202 - application/json

    Example
    {"progressUrl":"/secure/admin/jira/IndexProgress.jspa?taskId=10000","currentProgress":50,"currentSubTask":"Currently reindexing Change History","type":"FOREGROUND","submittedTime":"2017-03-08T03:29:43.193+0000","startTime":"2017-03-08T03:29:43.193+0000","finishTime":"2017-03-08T03:29:43.193+0000","success":false}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/reindex#","title":"Reindex","type":"object","properties":{"progressUrl":{"type":"string"},"currentProgress":{"type":"integer"},"currentSubTask":{"type":"string"},"type":{"type":"string","enum":["FOREGROUND","BACKGROUND","BACKGROUND_PREFFERED","BACKGROUND_PREFERRED"]},"submittedTime":{"type":"string"},"startTime":{"type":"string"},"finishTime":{"type":"string"},"success":{"type":"boolean"}},"additionalProperties":false,"required":["success"]}

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
parametertypedescription
taskIdlong

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.

Responses
  • Status 200 - application/json

    Example
    {"progressUrl":"/secure/admin/jira/IndexProgress.jspa?taskId=10000","currentProgress":50,"currentSubTask":"Currently reindexing Change History","type":"FOREGROUND","submittedTime":"2017-03-08T03:29:43.193+0000","startTime":"2017-03-08T03:29:43.193+0000","finishTime":"2017-03-08T03:29:43.193+0000","success":false}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/reindex#","title":"Reindex","type":"object","properties":{"progressUrl":{"type":"string"},"currentProgress":{"type":"integer"},"currentSubTask":{"type":"string"},"type":{"type":"string","enum":["FOREGROUND","BACKGROUND","BACKGROUND_PREFFERED","BACKGROUND_PREFERRED"]},"submittedTime":{"type":"string"},"startTime":{"type":"string"},"finishTime":{"type":"string"},"success":{"type":"boolean"}},"additionalProperties":false,"required":["success"]}

  • Status 404
    Returned if there is no re-indexing task found

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

Request
query parameters
parametertypedescription
issueIdstring

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

indexCommentsboolean

Default: false

Indicates that comments should also be reindexed.

indexChangeHistoryboolean

Default: false

Indicates that changeHistory should also be reindexed.

indexWorklogsboolean

Default: false

Indicates that changeHistory should also be reindexed.

Responses
  • Status 200 - application/json

    Example
    {"progressUrl":"/secure/admin/jira/IndexProgress.jspa?taskId=10000","currentProgress":50,"currentSubTask":"Currently reindexing Change History","type":"FOREGROUND","submittedTime":"2017-03-08T03:29:43.193+0000","startTime":"2017-03-08T03:29:43.193+0000","finishTime":"2017-03-08T03:29:43.193+0000","success":false}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/reindex#","title":"Reindex","type":"object","properties":{"progressUrl":{"type":"string"},"currentProgress":{"type":"integer"},"currentSubTask":{"type":"string"},"type":{"type":"string","enum":["FOREGROUND","BACKGROUND","BACKGROUND_PREFFERED","BACKGROUND_PREFERRED"]},"submittedTime":{"type":"string"},"startTime":{"type":"string"},"finishTime":{"type":"string"},"success":{"type":"boolean"}},"additionalProperties":false,"required":["success"]}

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
parametertypedescription
taskIdlong

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.

Responses
  • Status 200 - application/json

    Example
    {"progressUrl":"/secure/admin/jira/IndexProgress.jspa?taskId=10000","currentProgress":50,"currentSubTask":"Currently reindexing Change History","type":"FOREGROUND","submittedTime":"2017-03-08T03:29:43.193+0000","startTime":"2017-03-08T03:29:43.193+0000","finishTime":"2017-03-08T03:29:43.193+0000","success":false}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/reindex#","title":"Reindex","type":"object","properties":{"progressUrl":{"type":"string"},"currentProgress":{"type":"integer"},"currentSubTask":{"type":"string"},"type":{"type":"string","enum":["FOREGROUND","BACKGROUND","BACKGROUND_PREFFERED","BACKGROUND_PREFERRED"]},"submittedTime":{"type":"string"},"startTime":{"type":"string"},"finishTime":{"type":"string"},"success":{"type":"boolean"}},"additionalProperties":false,"required":["success"]}

  • Status 404
    Returned if there is no re-indexing task found

api/2/reindex/request

REST resource for querying and executing reindex requests.

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.

Responses
  • Status 200 - application/json
    Returns an array containing the reindex request IDs being processed.

    Schema
    {"type":"array","items":{"type":"integer"}}

Retrieves the progress of a single reindex request.

Responses
  • Status 200 - application/json

    Example
    {"id":10500,"status":"PENDING","type":"IMMEDIATE","requestTime":"2017-03-08T03:29:43.184+0000"}

    Details and status of the reindex request.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/reindex-request#","title":"Reindex Request","type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["PENDING","ACTIVE","RUNNING","FAILED","COMPLETE"]},"type":{"type":"string","enum":["IMMEDIATE","DELAYED"]},"requestTime":{"type":"string"},"startTime":{"type":"string"},"completionTime":{"type":"string"}},"additionalProperties":false,"required":["id"]}

  • Status 404
    Returned if no such reindex request exists.

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

Request
query parameters
parametertypedescription
requestIdstring

the reindex request IDs.

Responses
  • Status 200 - application/json

    Example
    {"id":10500,"status":"PENDING","type":"IMMEDIATE","requestTime":"2017-03-08T03:29:43.184+0000"}

    Details and status of the reindex request.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/reindex-request#","title":"Reindex Request","type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["PENDING","ACTIVE","RUNNING","FAILED","COMPLETE"]},"type":{"type":"string","enum":["IMMEDIATE","DELAYED"]},"requestTime":{"type":"string"},"startTime":{"type":"string"},"completionTime":{"type":"string"}},"additionalProperties":false,"required":["id"]}

api/2/resolution

Returns a list of all resolutions.

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-resolution#","title":"List of Resolution","type":"array","items":{"title":"Resolution","type":"object","properties":{"self":{"type":"string","format":"uri"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"}},"additionalProperties":false}}

Returns a resolution.

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/resolution#","title":"Resolution","type":"object","properties":{"self":{"type":"string","format":"uri"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"}},"additionalProperties":false}

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

api/2/role

Creates a new ProjectRole to be available in JIRA. The created role does not have any default actors assigned.

Request

Example
{"name":"MyRole","description":"role description"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/create-update-role-request#","title":"Create Update Role Request","type":"object","properties":{"description":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 200

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

    Returned if the user is authenticated

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-role#","title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 400
    Returned if the request json does not have a name field or the name field is invalid (empty or starts or ends with whitespace)
  • Status 401
    Returned if you are not logged in.
  • Status 403
    Returned if you do not have permissions to create a role.
  • Status 409
    Returned if a role with given name already exists.

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

Responses
  • Status 200

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

    Returned if the user is authenticated

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-role#","title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 401
    Returned if you do not have permissions or you are not logged in.
  • Status 403
    Returned if the requesting user is not an admin or a sysadmin.

Get a specific ProjectRole available in JIRA.

Responses
  • Status 200

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

    Returned if the user is authenticated

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-role#","title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 401
    Returned if you do not have permissions or you are not logged in.
  • Status 403
    Returned if the requesting user is not an admin or a sysadmin.
  • Status 404
    Returned if the role with the given id does not exist.

Partially updates a roles name or description.

Request

Example
{"name":"MyRole","description":"role description"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/create-update-role-request#","title":"Create Update Role Request","type":"object","properties":{"description":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 200

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

    Returned if the update was successful

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-role#","title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 400
    Returned when both name and description are not given or name field is invalid (empty or starts or ends with whitespace).
  • Status 401
    Returned if the requesting user is not logged in.
  • Status 403
    Returned if the requesting user is not an admin or a sysadmin.
  • Status 404
    Returned if the role with the given id does not exist.

Fully updates a roles. Both name and description must be given.

Request

Example
{"name":"MyRole","description":"role description"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/create-update-role-request#","title":"Create Update Role Request","type":"object","properties":{"description":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 200

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

    Returned if the update was successful

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-role#","title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 400
    Returned when name or description is not given or the name field is invalid (empty or starts or ends with whitespace)
  • Status 401
    Returned if the requesting user is not logged in.
  • Status 403
    Returned if the requesting user is not an admin or a sysadmin.
  • Status 404
    Returned if the role with the given id does not exist.

Deletes a role. May return 403 in the future

Request
query parameters
parametertypedescription
swaplong

if given, removes a role even if it is used in scheme by replacing the role with the given one

Responses
  • Status 400
    Returned if given role with given swap id does not exist.
  • Status 401
    Returned if the requesting user is not logged in.
  • Status 204
    Returned if the delete was successful.
  • Status 403
    Returned if the requesting user is not an admin or a sysadmin.
  • Status 404
    Returned if the role with the given id does not exist.
  • Status 409
    Returned if the project role is used in schemes and roleToSwap query parameter is not given.

Gets default actors for the given role.

Responses
  • Status 200

    Example
    {"actors":[{"id":10240,"displayName":"jira-developers","type":"atlassian-group-role-actor","name":"jira-developers"}]}

    Returned if the user is authenticated

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-role#","title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 401
    Returned if the requesting user is not logged in.
  • Status 403
    Returned if the requesting user is not an admin or a sysadmin.
  • Status 404
    Returned if the role with the given id does not exist.

Adds default actors to the given role. The request data should contain a list of usernames or a list of groups to add.

Request

Example
{"user":["admin"]}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/actor-input#","title":"Actor Input","type":"object","properties":{"user":{"type":"array","items":{"type":"string"}},"group":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

Responses
  • Status 200

    Example
    {"actors":[{"id":10240,"displayName":"jira-developers","type":"atlassian-group-role-actor","name":"jira-developers"}]}

    Returned if the update was successful

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/project-role#","title":"Project Role","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"id":{"type":"integer"},"description":{"type":"string"},"actors":{"type":"array","items":{"title":"Role Actor","type":"object","properties":{"id":{"type":"integer"},"displayName":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 400
    Returned if user and group are both given or none are given or group or user in their respective lists does not exist.
  • Status 401
    Returned if the requesting user is not logged in.
  • Status 403
    Returned if the requesting user is not an admin or a sysadmin.
  • Status 404
    Returned if the role with the given id does not exist.

Removes default actor from the given role.

Request
query parameters
parametertypedescription
userstring

if given, removes an actor from given role

groupstring

if given, removes an actor from given role

Responses
  • Status 200

    Example
    {"actors":[{"id":10240,"displayName":"jira-developers","type":"atlassian-group-role-actor","name":"jira-developers"}]}

    Returned if the update was successful.
  • Status 400
    Returned if user and group are not given, both user and group are given or provided group or user does not exist.
  • Status 401
    Returned if the requesting user is not logged in.
  • Status 403
    Returned if the requesting user is not an admin or a sysadmin.
  • Status 404
    Returned if the role with the given id does not exist.

api/2/screens

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

Responses
  • Status 200
    List of available fields for screen

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-screenable-tab#","title":"List of Screenable Tab","type":"array","items":{"title":"Screenable Tab","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"additionalProperties":false}}

  • Status 400
    Returned if screen does not exist
  • Status 401
    Returned if you do not have permissions

Returns a list of all tabs for the given screen

Request
query parameters
parametertypedescription
projectKeystring

the key of the project; this parameter is optional

Responses
  • Status 200 - application/json
    Contains a full representation of all visible tabs in JSON.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-screenable-tab#","title":"List of Screenable Tab","type":"array","items":{"title":"Screenable Tab","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"additionalProperties":false}}

  • Status 400
    Returned if screen does not exist
  • Status 401
    Returned if you do not have permissions

Creates tab for given screen

Request

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/screenable-tab#","title":"Screenable Tab","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 200 - application/json

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

    Newly created tab in JSON.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/screenable-tab#","title":"Screenable Tab","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"additionalProperties":false}

  • Status 400
    Returned if screen does not exist or tab name is invalid
  • Status 401
    Returned if you do not have permissions

Renames tab on given screen

Request

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/screenable-tab#","title":"Screenable Tab","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 200 - application/json

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

    Modified tab in JSON.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/screenable-tab#","title":"Screenable Tab","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"additionalProperties":false}

  • Status 400
    Returned if screen does not exist or tab name is invalid
  • Status 401
    Returned if you do not have permissions

Deletes tab to give screen

Responses
  • Status 201
    Successfully deleted tab
  • Status 400
    Returned if screen or tab does not exist
  • Status 401
    Returned if you do not have permissions

Gets all fields for a given tab

Request
query parameters
parametertypedescription
projectKeystring

the key of the project; this parameter is optional

Responses
  • Status 200
    List of fields for given tab

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-screenable-tab#","title":"List of Screenable Tab","type":"array","items":{"title":"Screenable Tab","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"additionalProperties":false}}

  • Status 400
    Returned if screen or tab does not exist
  • Status 401
    Returned if you do not have permissions

Adds field to the given tab.

Request

Example
{"fieldId":"summary"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/add-field#","title":"Add Field","type":"object","properties":{"fieldId":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 200

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

    Newly added field as json

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/screenable-field#","title":"Screenable Field","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}

  • Status 400
    Returned if screen,tab or field does not exist.
  • Status 401
    Returned if you do not have permissions

Removes field from given tab

Responses
  • Status 201
    Successfully removed field from tab
  • Status 400
    Returned if screen or tab does not exist
  • Status 401
    Returned if you do not have permissions

Moves field on the given tab

Request

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/move-field#","title":"Move Field","type":"object","properties":{"after":{"type":"string","format":"uri"},"position":{"type":"string","enum":["Earlier","Later","First","Last"]}},"additionalProperties":false}

Responses
  • Status 201
    Successfully moved tab
  • Status 400
    Returned if screen or tab does not exist. Or move cooridinates invalid.
  • Status 401
    Returned if you do not have permissions

Moves tab position

Responses
  • Status 201
    Successfully moved tab
  • Status 400
    Returned if screen or tab does not exist
  • Status 401
    Returned if you do not have permissions

Adds field or custom field to the default tab

Responses
  • Status 201
    Successfully added field to default screen / default tab
  • Status 400
    Returned if screen, tab or field does not exist or field is already present on a selected tab
  • Status 401
    Returned if you do not have administrator permissions

api/2/search

Resource for searches.

Performs a search using JQL.

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/search-request#","title":"Search Request","type":"object","properties":{"jql":{"type":"string"},"startAt":{"type":"integer"},"maxResults":{"type":"integer"},"fields":{"type":"array","items":{"type":"string"}},"validateQuery":{"type":"string"},"properties":{"type":"array","items":{"type":"string"}},"fieldsByKeys":{"type":"boolean"}},"additionalProperties":false,"required":["fieldsByKeys"]}

Responses
  • Status 200 - application/json

    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"}],"warningMessages":["The value 'splat' does not exist for the field 'Foo'."]}

    Returns a JSON representation of the search results.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/search-results#","title":"Search Results","type":"object","properties":{"expand":{"type":"string"},"startAt":{"type":"integer"},"maxResults":{"type":"integer"},"total":{"type":"integer"},"issues":{"type":"array","items":{"title":"Issue","type":"object","properties":{"expand":{"type":"string"},"id":{"type":"string"},"self":{"type":"string","format":"uri"},"key":{"type":"string"},"renderedFields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"properties":{"title":"Properties","type":"object","properties":{"properties":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"names":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"schema":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/json-type"}},"additionalProperties":false},"transitions":{"type":"array","items":{"title":"Transition","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"to":{"title":"Status","type":"object","properties":{"self":{"type":"string"},"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"hasScreen":{"type":"boolean"},"fields":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/field-meta"}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false}},"operations":{"title":"Opsbar","type":"object","properties":{"linkGroups":{"type":"array","items":{"$ref":"#/definitions/link-group"}}},"additionalProperties":false},"editmeta":{"title":"Edit Meta","type":"object","properties":{"fields":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/field-meta"}},"additionalProperties":false}},"additionalProperties":false},"changelog":{"title":"Changelog","type":"object","properties":{"startAt":{"type":"integer"},"maxResults":{"type":"integer"},"total":{"type":"integer"},"histories":{"type":"array","items":{"title":"Change History","type":"object","properties":{"id":{"type":"string"},"author":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]},"created":{"type":"string"},"items":{"type":"array","items":{"title":"Change Item","type":"object","properties":{"field":{"type":"string"},"fieldtype":{"type":"string"},"from":{"type":"string"},"fromString":{"type":"string"},"to":{"type":"string"},"toString":{"type":"string"}},"additionalProperties":false}},"historyMetadata":{"title":"History Metadata","type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"descriptionKey":{"type":"string"},"activityDescription":{"type":"string"},"activityDescriptionKey":{"type":"string"},"emailDescription":{"type":"string"},"emailDescriptionKey":{"type":"string"},"actor":{"$ref":"#/definitions/history-metadata-participant"},"generator":{"$ref":"#/definitions/history-metadata-participant"},"cause":{"$ref":"#/definitions/history-metadata-participant"},"extraData":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false},"versionedRepresentations":{"type":"object","patternProperties":{".+":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false}},"additionalProperties":false},"fieldsToInclude":{"title":"Included Fields","type":"object"},"fields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false}},"additionalProperties":false}},"warningMessages":{"type":"array","items":{"type":"string"}},"names":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"schema":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/json-type"}},"additionalProperties":false}},"definitions":{"field-meta":{"title":"Field Meta","type":"object","properties":{"required":{"type":"boolean"},"schema":{"$ref":"#/definitions/json-type"},"name":{"type":"string"},"key":{"type":"string"},"autoCompleteUrl":{"type":"string"},"hasDefaultValue":{"type":"boolean"},"operations":{"type":"array","items":{"type":"string"}},"allowedValues":{"type":"array","items":{}},"defaultValue":{}},"additionalProperties":false,"required":["required"]},"history-metadata-participant":{"title":"History Metadata Participant","type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"displayNameKey":{"type":"string"},"type":{"type":"string"},"avatarUrl":{"type":"string"},"url":{"type":"string"}},"additionalProperties":false},"json-type":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false},"link-group":{"title":"Link Group","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"header":{"$ref":"#/definitions/simple-link"},"weight":{"type":"integer"},"links":{"type":"array","items":{"$ref":"#/definitions/simple-link"}},"groups":{"type":"array","items":{"$ref":"#/definitions/link-group"}}},"additionalProperties":false},"simple-link":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false}

  • Status 400
    Returned if there is a problem with the JQL query.

Searches for issues using JQL.

Sorting: the jql parameter is a full JQL expression which can include an ORDER BY clause.

Fields: 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

Properties: The properties param is similar to fields and specifies a comma-separated list of issue properties to include. Unlike fields, properties are not included by default. It is also not allowed to request all properties. The number of different properties that may be requested in one query is limited to 5.

  • prop1,prop1 - include prop1 and prop2 properties

Query Validation: The validateQuery param offers control over whether to validate and how strictly to treat the validation.

  • strict - Strict validation: if any errors are found then a 400 will be returned with a list of all errors (and warnings).
  • warn - we validate, but all errors are demoted to warnings.
  • none - no validation is run.
  • true - deprecated. A legacy synonym for "strict".
  • false - deprecated. For legacy reasons this acts like "warn".
The default value is "strict". Note that this setting only effects semantic validation of the given JQL. If the JQL is syntactically invalid, we will not even be able to parse it and a 400 will be raised no matter what validateQuery value is given.

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
parametertypedescription
jqlstring

a JQL query string

startAtint

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

maxResultsint

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.

validateQuerystring

Default: true

Whether to validate the JQL query and how strictly to treat the validation results. Supported values: "strict", "warn", "none" + legacy synonyms "true" and "false"

fieldsstring

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

expandstring

A comma-separated list of the parameters to expand.

propertiesstring

the list of properties to return for each issue. By default no properties are returned.

fieldsByKeysboolean

if true then fields in issues will be referenced by keys instead of ids

Responses
  • Status 200 - application/json

    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"}],"warningMessages":["The value 'splat' does not exist for the field 'Foo'."]}

    Returns a JSON representation of the search results.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/search-results#","title":"Search Results","type":"object","properties":{"expand":{"type":"string"},"startAt":{"type":"integer"},"maxResults":{"type":"integer"},"total":{"type":"integer"},"issues":{"type":"array","items":{"title":"Issue","type":"object","properties":{"expand":{"type":"string"},"id":{"type":"string"},"self":{"type":"string","format":"uri"},"key":{"type":"string"},"renderedFields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"properties":{"title":"Properties","type":"object","properties":{"properties":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"names":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"schema":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/json-type"}},"additionalProperties":false},"transitions":{"type":"array","items":{"title":"Transition","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"to":{"title":"Status","type":"object","properties":{"self":{"type":"string"},"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"hasScreen":{"type":"boolean"},"fields":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/field-meta"}},"additionalProperties":false},"expand":{"type":"string"}},"additionalProperties":false}},"operations":{"title":"Opsbar","type":"object","properties":{"linkGroups":{"type":"array","items":{"$ref":"#/definitions/link-group"}}},"additionalProperties":false},"editmeta":{"title":"Edit Meta","type":"object","properties":{"fields":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/field-meta"}},"additionalProperties":false}},"additionalProperties":false},"changelog":{"title":"Changelog","type":"object","properties":{"startAt":{"type":"integer"},"maxResults":{"type":"integer"},"total":{"type":"integer"},"histories":{"type":"array","items":{"title":"Change History","type":"object","properties":{"id":{"type":"string"},"author":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]},"created":{"type":"string"},"items":{"type":"array","items":{"title":"Change Item","type":"object","properties":{"field":{"type":"string"},"fieldtype":{"type":"string"},"from":{"type":"string"},"fromString":{"type":"string"},"to":{"type":"string"},"toString":{"type":"string"}},"additionalProperties":false}},"historyMetadata":{"title":"History Metadata","type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"descriptionKey":{"type":"string"},"activityDescription":{"type":"string"},"activityDescriptionKey":{"type":"string"},"emailDescription":{"type":"string"},"emailDescriptionKey":{"type":"string"},"actor":{"$ref":"#/definitions/history-metadata-participant"},"generator":{"$ref":"#/definitions/history-metadata-participant"},"cause":{"$ref":"#/definitions/history-metadata-participant"},"extraData":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false},"versionedRepresentations":{"type":"object","patternProperties":{".+":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false}},"additionalProperties":false},"fieldsToInclude":{"title":"Included Fields","type":"object"},"fields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false}},"additionalProperties":false}},"warningMessages":{"type":"array","items":{"type":"string"}},"names":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"schema":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/json-type"}},"additionalProperties":false}},"definitions":{"field-meta":{"title":"Field Meta","type":"object","properties":{"required":{"type":"boolean"},"schema":{"$ref":"#/definitions/json-type"},"name":{"type":"string"},"key":{"type":"string"},"autoCompleteUrl":{"type":"string"},"hasDefaultValue":{"type":"boolean"},"operations":{"type":"array","items":{"type":"string"}},"allowedValues":{"type":"array","items":{}},"defaultValue":{}},"additionalProperties":false,"required":["required"]},"history-metadata-participant":{"title":"History Metadata Participant","type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"displayNameKey":{"type":"string"},"type":{"type":"string"},"avatarUrl":{"type":"string"},"url":{"type":"string"}},"additionalProperties":false},"json-type":{"title":"Json Type","type":"object","properties":{"type":{"type":"string"},"items":{"type":"string"},"system":{"type":"string"},"custom":{"type":"string"},"customId":{"type":"integer"}},"additionalProperties":false},"link-group":{"title":"Link Group","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"header":{"$ref":"#/definitions/simple-link"},"weight":{"type":"integer"},"links":{"type":"array","items":{"$ref":"#/definitions/simple-link"}},"groups":{"type":"array","items":{"$ref":"#/definitions/link-group"}}},"additionalProperties":false},"simple-link":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false}

  • Status 400
    Returned if there is a problem with the JQL query.

api/2/securitylevel

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

Responses
  • Status 200 - application/json

    Example
    {"self":"http://www.example.com/jira/rest/api/2/securitylevel/10021","id":"10021","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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/security-level#","title":"Security Level","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}

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

api/2/serverInfo

Returns general information about the current JIRA server.

Request
query parameters
parametertypedescription
doHealthCheckboolean
Responses
  • Status 200 - application/json

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

    Returns a full representation of the server info in JSON format

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/server-info#","title":"Server Info","type":"object","properties":{"baseUrl":{"type":"string"},"version":{"type":"string"},"versionNumbers":{"type":"array","items":{"type":"integer"}},"deploymentType":{"type":"string"},"buildNumber":{"type":"integer"},"buildDate":{"type":"string"},"serverTime":{"type":"string"},"scmInfo":{"type":"string"},"buildPartnerName":{"type":"string"},"serverTitle":{"type":"string"},"healthChecks":{"type":"array","items":{"title":"Health Check Result","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"passed":{"type":"boolean"}},"additionalProperties":false}}},"additionalProperties":false}

api/2/settings

REST resource for changing the JIRA system settings

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

Request

Example
http://jira.atlassian.com/

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/string#","title":"String","type":"string"}

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

Responses
  • Status 200 - application/json
    Returns a list of columns for configured for the given user

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-column-item#","title":"List of Column Item","type":"array","items":{"title":"Column Item","type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false}}

  • Status 500
    Returned if an error occurs while retrieving the column configuration.
  • Status 403
    Returned if the user does not have admin permission

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

Request
Responses
  • Status 200
    Returned when the columns is saved successfully
  • Status 500
    Returned if an error occurs while retrieving the column configuration.

api/2/status

Returns a list of all statuses

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-status#","title":"List of Status","type":"array","items":{"title":"Status","type":"object","properties":{"self":{"type":"string"},"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}

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

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/status#","title":"Status","type":"object","properties":{"self":{"type":"string"},"statusColor":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"id":{"type":"string"},"statusCategory":{"title":"Status Category","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

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

api/2/statuscategory

Returns a list of all status categories

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-status-category#","title":"List of Status Category","type":"array","items":{"title":"Status Category","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}}

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

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

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/status-category#","title":"Status Category","type":"object","properties":{"self":{"type":"string"},"id":{"type":"integer"},"key":{"type":"string"},"colorName":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}

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

api/2/task

Resource to check the status of long-running asynchronous tasks.

Returns a task progress. When the task is finished, it will contain the result. The result may be an arbitrary JSON, its shape is different for each task type. Consult the documentation of the method that created the task to know what it is.

Responses
  • Status 200 - application/json

    Example
    {"self":"http://www.example.com/jira/rest/api/2/task/1","id":"1","description":"Task description","status":"COMPLETE","result":"the task result, this may be any JSON","submittedBy":10000,"progress":100,"elapsedRuntime":156,"submitted":1488943783863,"started":1488943783964,"finished":1488943784064,"lastUpdate":1488943784064}

    Returned if successful.

    Schema
    {"title":"Task Progress","type":"object","properties":{"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"description":"Description of the task","type":"string"},"status":{"description":"Current status of the task","type":"string","enum":["ENQUEUED","RUNNING","COMPLETE","FAILED","CANCEL_REQUESTED","CANCELLED","DEAD"]},"message":{"description":"Message regarding the current progress","type":"string"},"result":{"description":"The eventual result, will be available when the task is finished successfully"},"submittedBy":{"description":"Id of the user that submitted the task","type":"integer"},"progress":{"description":"The progress percentage (from 0 to 100)","type":"integer"},"elapsedRuntime":{"description":"How much time did running the task take (so far, this is updated in real time), in milliseconds","type":"integer"},"submitted":{"description":"The timestamp of when the task was submitted","type":"string"},"started":{"description":"The timestamp of when the task was started","type":"string"},"finished":{"description":"The timestamp of when the task processing was finished","type":"string"},"lastUpdate":{"description":"The timestamp of when the task progress was last updated","type":"string"}},"additionalProperties":false,"required":["self","id","status","submittedBy","progress","elapsedRuntime","submitted","started","lastUpdate"]}

  • Status 401
    Returned if the user is not authenticated.
  • Status 404
    Returned if the task does not exist, or its trace has been already removed from the system.

Requests that the task that corresponds to the given task id is cancelled.

Responses
  • Status 202 - application/json
    Returned if successful.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/response#","title":"Response","type":"object"}

  • Status 401
    Returned if the user is not authenticated.
  • Status 403
    Returned if the user is not authorized to cancel the task.
  • Status 404
    Returned if the task does not exist, or its trace has been already removed from the system.

api/2/universal_avatar

Creates an avatar for a given entity, for the given entity ID and type of entity. For example, you can create an avatar for an issue type, given the issue type Id. Uploading an avatar is supported for different types of entities across the JIRA products. However, it is supported for the "project" and "issuetype" entity types for all JIRA products. The uploaded image will be cropped according to the crop parameters listed below. If no crop parameters are specified, the image will be cropped to a square. The square will originate at the top left of the image and the length of each side will be set to the smaller of the height or width of the image.

Request
query parameters
parametertypedescription
xint

(optional) The X coordinate of the top-left corner of the crop region. Default: 0.

yint

(optional) The Y coordinate of the top-left corner of the crop region. Default: 0.

sizeint

(optional) The length of each side of the crop region. The crop region can only be a square. If omitted and the top-left corner is at (0,0), this defaults to either the height or width of the image, whichever is smaller.

Responses
  • Status 201 - application/json

    Example
    {"id":"1000","owner":"fred","isSystemAvatar":true,"isSelected":false,"isDeletable":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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/avatar#","title":"Avatar","type":"object","properties":{"id":{"type":"string"},"owner":{"type":"string"},"isSystemAvatar":{"type":"boolean"},"isSelected":{"type":"boolean"},"isDeletable":{"type":"boolean"},"urls":{"type":"object","patternProperties":{"\\d\\dx\\d\\d":{"type":"string","format":"uri"}},"additionalProperties":false},"selected":{"type":"boolean"}},"additionalProperties":false,"required":["isSystemAvatar","isSelected","isDeletable","selected"]}

  • Status 400
    Returned if the cropping coordinates are invalid.
  • Status 401
    Returned if the user is not authenticated.
  • Status 403
    Returned if the user does not have permission to upload an avatar for the given entity.
  • Status 404
    Returned if the icon type is invalid or if the request does not contain a valid XSRF token.
Responses
  • Status - application/json

Deletes avatar

Responses
  • Status - application/json

api/2/user

Create user. By default created user will not be notified with email. If password field is not set then password will be randomly generated.

Request

Example
{"name":"charlie","password":"abracadabra","emailAddress":"charlie@atlassian.com","displayName":"Charlie of Atlassian","applicationKeys":["jira-core"]}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/user-write#","title":"User Write","type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"password":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"notification":{"type":"string"},"applicationKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

Responses
  • Status 201

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/user#","title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false,"required":["active"]}

  • Status 400
    Returned if the request is invalid.
  • Status 401
    Returned if the user is not authenticated.
  • Status 500
    Returned if the user was not created because of other error.
  • Status 403
    Returned if the caller user does not have permission to create the user.

Modify user. The "value" fields present will override the existing value. Fields skipped in request will not be changed.

Request
query parameters
parametertypedescription
usernamestring

the username

keystring

user key

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/user-write#","title":"User Write","type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"password":{"type":"string"},"emailAddress":{"type":"string"},"displayName":{"type":"string"},"notification":{"type":"string"},"applicationKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/user#","title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false,"required":["active"]}

  • Status 400
    Returned if the request is invalid.
  • Status 401
    Returned if the user is not authenticated.
  • Status 403
    Returned if the caller user does not have permission to edit the user.
  • Status 404
    Returned if the caller does have permission to edit the user but the user does not exist.

Removes user.

Request
query parameters
parametertypedescription
usernamestring

the username

keystring

user key

Responses
  • Status 400
    Returned if the request is invalid or some other server error occurred.
  • Status 401
    Returned if the user is not authenticated.
  • Status 204
    Returned if the user was deleted successfully.
  • Status 403
    Returned if the caller does not have permission to remove the user.
  • Status 404
    Returned if the caller does have permission to remove user but the user does not exist.

Returns a user. This resource cannot be accessed anonymously.

The resource accepts the expand param that is used to include, hidden by default, parts of response. This can be used to include:

  • groups - all groups, including nested groups, to which user belongs
  • applicationRoles - application roles defines to which application user has access

Request
query parameters
parametertypedescription
usernamestring

the username

keystring

user key

Responses
  • Status 200 - application/json

    Example
    {"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"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"}]},"applicationRoles":{"size":1,"items":[]},"expand":"groups,applicationRoles"}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/user#","title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false,"required":["active"]}

  • Status 401
    Returned if the current user is not authenticated.
  • Status 404
    Returned if the requested user is not found.

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
parametertypedescription
usernamestring

the username

projectKeysstring

the keys of the projects we are finding assignable users for, comma-separated

startAtint

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

maxResultsint

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.

Responses
  • Status 200 - application/json

    Example
    [{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},{"self":"http://www.example.com/jira/rest/api/2/user?username=andrew","key":"andrew","accountId":"99:e2a16dd9-2ffb-4a4b-a9bd-bd1145a020ee","name":"andrew","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=andrew","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"},"displayName":"Andrew Anderson","active":false}]

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-user#","title":"List of User","type":"array","items":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}}}

  • Status 401
    Returned if the current user is not authenticated.
  • Status 404
    Returned if the requested user is not found.

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
parametertypedescription
usernamestring

the username

projectstring

the key of the project we are finding assignable users for

issueKeystring

the issue key for the issue being edited we need to find assignable users for.

startAtint

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

maxResultsint

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.

actionDescriptorIdint
Responses
  • Status 200 - application/json

    Example
    {"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"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"}]},"applicationRoles":{"size":1,"items":[]},"expand":"groups,applicationRoles"}

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-user#","title":"List of User","type":"array","items":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}}}

  • Status 400
    Returned if no project or issue key was provided
  • Status 401
    Returned if the current user is not authenticated.
  • Status 404
    Returned if the requested user is not found.

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.

Request
Responses
  • Status 200
    Returned when the columns is saved successfully
  • Status 500
    Returned if an error occurs while retrieving the column configuration.

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
parametertypedescription
usernamestring

username

Responses
  • Status 401
    Returned if the current user is not permitted to request the columns for the given user.
  • Status 500
    Returned if an error occurs while resetting the column configuration.
  • Status 204
    Returned when the columns are reset successfully

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
parametertypedescription
usernamestring

username

Responses
  • Status 200 - application/json
    Returns a list of columns for configured for the given user

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-column-item#","title":"List of Column Item","type":"array","items":{"title":"Column Item","type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false}}

  • Status 401
    Returned if the current user is not permitted to request the columns for the given user.
  • Status 500
    Returned if an error occurs while retrieving the column configuration.
  • Status 404
    Returned if the requested user is not found.

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
parametertypedescription
usernamestring

the username filter, list includes all users if unspecified

permissionsstring

comma separated list of permissions for project or issue returned users must have, see Permissions JavaDoc for the list of all possible permissions.

issueKeystring

the issue key for the issue for which returned users have specified permissions.

projectKeystring

the optional project key to search for users with if no issueKey is supplied.

startAtint

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

maxResultsint

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.

Responses
  • Status 200 - application/json

    Example
    [{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},{"self":"http://www.example.com/jira/rest/api/2/user?username=andrew","key":"andrew","accountId":"99:e2a16dd9-2ffb-4a4b-a9bd-bd1145a020ee","name":"andrew","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=andrew","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"},"displayName":"Andrew Anderson","active":false}]

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-user#","title":"List of User","type":"array","items":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}}}

  • Status 400
    Returned if no project or issue key was provided or when permissions list is empty or contains an invalid entry
  • Status 401
    Returned if the current user is not authenticated.
  • Status 403
    Returned if the current user does not have admin rights for the project.
  • Status 404
    Returned if the requested issue or project is not found.

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

Request
query parameters
parametertypedescription
querystring

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

maxResultsint

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.

showAvatarboolean
excludestring
Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/user-picker-results#","title":"User Picker Results","type":"object","properties":{"users":{"type":"array","items":{"title":"User Picker User","type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"html":{"type":"string"},"displayName":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}},"additionalProperties":false}},"total":{"type":"integer"},"header":{"type":"string"}},"additionalProperties":false}

  • Status 401
    Returned if the current user is not authenticated.
  • Status 404
    Returned if the requested user is not found.

Returns a list of users that match the search string and/or property. This resource cannot be accessed anonymously.

Request
query parameters
parametertypedescription
usernamestring

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

startAtint

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

maxResultsint

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.

includeActiveboolean

If true, then active users are included in the results (default true)

includeInactiveboolean

If true, then inactive users are included in the results (default false)

propertystring

A query string used to search by property. Property key cannot contain dot or equal sign, value cannot be JSONObject. Example: for following property value: {"something":{"nested":1,"other":2}} you can search: propertyKey.something.nested=1

Responses
  • Status 200 - application/json

    Example
    [{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},{"self":"http://www.example.com/jira/rest/api/2/user?username=andrew","key":"andrew","accountId":"99:e2a16dd9-2ffb-4a4b-a9bd-bd1145a020ee","name":"andrew","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=andrew","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"},"displayName":"Andrew Anderson","active":false}]

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-user#","title":"List of User","type":"array","items":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}}}

  • Status 400
    Returned if username and property params are missing or property param is not valid. Example of valid params: propertyKey=value, propertyKey.path=value
  • Status 401
    Returned if the current user is not authenticated.
  • Status 404
    Returned if the requested user is not found.

Returns a list of active users that match the search string. This resource cannot be accessed anonymously and requires the Browse Users global permission. 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
parametertypedescription
usernamestring

the username filter, no users returned if left blank

issueKeystring

the issue key for the issue being edited we need to find viewable users for.

projectKeystring

the optional project key to search for users with if no issueKey is supplied.

startAtint

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

maxResultsint

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.

Responses
  • Status 200 - application/json

    Example
    [{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":false},{"self":"http://www.example.com/jira/rest/api/2/user?username=andrew","key":"andrew","accountId":"99:e2a16dd9-2ffb-4a4b-a9bd-bd1145a020ee","name":"andrew","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=andrew","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"},"displayName":"Andrew Anderson","active":false}]

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

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-user#","title":"List of User","type":"array","items":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}}}

  • Status 400
    Returned if no project or issue key was provided
  • Status 401
    Returned if the current user is not authenticated.
  • Status 404
    Returned if the requested issue or project is not found.

api/2/user/properties

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

Request
query parameters
parametertypedescription
userKeystring

key of the user whose properties are to be returned

usernamestring

username of the user whose properties are to be returned

Responses
  • Status 200 - application/json

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

    Returned if the user was found.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-properties-keys#","title":"Entity Properties Keys","type":"object","properties":{"keys":{"type":"array","items":{"title":"Entity Property Key","type":"object","properties":{"self":{"type":"string"},"key":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 400
    Returned if the user key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to browse the user.
  • Status 404
    Returned if the user with given key or id does not exist or if the property with given key is not found.

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

Request
query parameters
parametertypedescription
userKeystring

key of the user whose property is to be removed

usernamestring

username of the user whose property is to be removed

Responses
  • Status 400
    Returned if the user key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 204
    Returned if the user property was removed successfully.
  • Status 403
    Returned if the calling user does not have permission to edit the user.
  • Status 404
    Returned if the user with given key or id does not exist or if the property with given key is not found.

Sets the value of the specified user's property.

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

Request
query parameters
parametertypedescription
userKeystring

key of the user whose property is to be set

usernamestring

username of the user whose property is to be set

Responses
  • Status 200
    Returned if the user property is successfully updated.
  • Status 201
    Returned if the user property is successfully created.
  • Status 400
    Returned if the user key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to administer the user.
  • Status 404
    Returned if the user with given key or id does not exist.

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

Request
query parameters
parametertypedescription
userKeystring

key of the user whose property is to be returned

usernamestring

username of the user whose property is to be returned

Responses
  • Status 200 - application/json

    Example
    {"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}

    Returned if the user property was found.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/entity-property#","title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}

  • Status 400
    Returned if the user key or id is invalid.
  • Status 401
    Returned if the calling user is not authenticated.
  • Status 403
    Returned if the calling user does not have permission to browse the user.
  • Status 404
    Returned if the user with given key or id does not exist or if the property with given key is not found.

api/2/version

Create a version via POST.

Request

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}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/version#","title":"Version","type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}

Responses
  • Status 201 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/version#","title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 403
    Returned if the currently authenticated user does not have permission to edit the version.
  • Status 404
    Returned if the version does not exist or the currently authenticated user does not have permission to view it.

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

Request

Example
{"after":"http://www.example.com/jira/rest/api/2/version/10000"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/version-move#","title":"Version Move","type":"object","properties":{"after":{"type":"string","format":"uri"},"position":{"type":"string","enum":["Earlier","Later","First","Last"]}},"additionalProperties":false}

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/version#","title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}

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

Returns a project version.

Request
query parameters
parametertypedescription
expandstring
Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/version#","title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}

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

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.

Request

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}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/version#","title":"Version","type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}

Responses
  • Status 200
    Returned if the version exists and the currently authenticated user has permission to edit it.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/version#","title":"Version","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean"},"released":{"type":"boolean"},"overdue":{"type":"boolean"},"userStartDate":{"type":"string"},"userReleaseDate":{"type":"string"},"project":{"type":"string"},"projectId":{"type":"integer"},"moveUnfixedIssuesTo":{"type":"string","format":"uri"},"operations":{"type":"array","items":{"title":"Simple Link","type":"object","properties":{"id":{"type":"string"},"styleClass":{"type":"string"},"iconClass":{"type":"string"},"label":{"type":"string"},"title":{"type":"string"},"href":{"type":"string"},"weight":{"type":"integer"}},"additionalProperties":false}},"remotelinks":{"type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}},"additionalProperties":false}

  • Status 403
    Returned if the currently authenticated user does not have permission to edit the version.
  • Status 404
    Returned if the version does not exist or the currently authenticated user does not have permission to view it.

Delete a project version.

Request
query parameters
parametertypedescription
moveFixIssuesTostring

The version to set fixVersion to on issues where the deleted version is the fix version, If null then the fixVersion is removed.

moveAffectedIssuesTostring

The version to set affectedVersion to on issues where the deleted version is the affected version, If null then the affectedVersion is removed.

Responses
  • Status 204
    Returned if the version is successfully deleted.
  • Status 403
    Returned if the currently authenticated user does not have permission to delete the version.
  • Status 404
    Returned if the version does not exist or the currently authenticated user does not have permission to view it.

Merge versions

Responses
  • Status 204
    Returned if the version is successfully deleted.
  • Status 403
    Returned if the currently authenticated user does not have permission to delete the version.
  • Status 404
    Returned if the version does not exist or the currently authenticated user does not have permission to view it.

Returns a bean containing the number of fixed in and affected issues for the given version.

Responses
  • Status 200 - application/json

    Example
    {"self":"http://www.example.com/jira/rest/api/2/version/10000","issuesFixedCount":23,"issuesAffectedCount":101,"issueCountWithCustomFieldsShowingVersion":54,"customFieldUsage":[{"fieldName":"Field1","customFieldId":10000,"issueCountWithVersionInCustomField":2},{"fieldName":"Field2","customFieldId":10010,"issueCountWithVersionInCustomField":3}]}

    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, custom fields connected to this version.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/version-issue-counts#","title":"Version Issue Counts","type":"object","properties":{"self":{"type":"string","format":"uri"},"issuesFixedCount":{"type":"integer"},"issuesAffectedCount":{"type":"integer"},"issueCountWithCustomFieldsShowingVersion":{"type":"integer"},"customFieldUsage":{"type":"array","items":{"title":"Version Usage In Custom Fields","type":"object","properties":{"fieldName":{"type":"string"},"customFieldId":{"type":"integer"},"issueCountWithVersionInCustomField":{"type":"integer"}},"additionalProperties":false,"required":["customFieldId","issueCountWithVersionInCustomField"]}}},"additionalProperties":false,"required":["issuesFixedCount","issuesAffectedCount","issueCountWithCustomFieldsShowingVersion"]}

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

Delete a project version.

Request

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/delete-and-replace-version#","title":"Delete And Replace Version","type":"object"}

Responses
  • Status 204
    Returned if the version is successfully deleted.
  • Status 403
    Returned if the currently authenticated user does not have permission to delete the version.
  • Status 404
    Returned if the version does not exist or the currently authenticated user does not have permission to view it.

Returns the number of unresolved issues for the given version

Responses
  • Status 200 - application/json

    Example
    {"self":"http://www.example.com/jira/rest/api/2/version/10000","issuesUnresolvedCount":23,"issuesCount":30}

    Returned if the version exists and the currently authenticated user has permission to view it. Contains counts of issues unresolved in this version.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/version-unresolved-issue-counts#","title":"Version Unresolved Issue Counts","type":"object","properties":{"self":{"type":"string","format":"uri"},"issuesUnresolvedCount":{"type":"integer"},"issuesCount":{"type":"integer"}},"additionalProperties":false,"required":["issuesUnresolvedCount","issuesCount"]}

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

Returns the remote version links associated with the given version ID.

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/remote-entity-link#","title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}

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

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.

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/string#","title":"String","type":"string"}

Responses
  • Status 201

    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.
  • Status 400
    Returned if the JSON payload is empty or malformed
  • Status 403
    Returned if the currently authenticated user does not have permission to edit the version.
  • Status 404
    Returned if the version does not exist or the currently authenticated user does not have permission to view it.

Delete all remote version links for a given version ID.

Responses
  • Status 204
    Returned if the remote version links are successfully deleted.
  • Status 403
    Returned if the currently authenticated user does not have administrative rights to the project and thereby cannot delete remote links to the version.
  • Status 404
    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

A REST sub-resource representing a remote version link

Responses
  • Status 200 - application/json

    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)

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/remote-entity-link#","title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}

  • Status 404
    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

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.

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/string#","title":"String","type":"string"}

Responses
  • Status 201

    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.
  • Status 400
    Returned if the JSON payload is empty or malformed
  • Status 403
    Returned if the currently authenticated user does not have permission to edit the version.
  • Status 404
    Returned if the version does not exist or the currently authenticated user does not have permission to view it.

Delete a specific remote version link with the given version ID and global ID.

Responses
  • Status 204
    Returned if the remote version link is successfully deleted.
  • Status 403
    Returned if the currently authenticated user does not have administrative rights to the project and thereby cannot delete remote links to the version.
  • Status 404
    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

Returns the remote version links for a given global ID.

Request
query parameters
parametertypedescription
globalIdstring

the global ID of the remote resource that is linked to the versions

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-remote-entity-link#","title":"List of Remote Entity Link","type":"array","items":{"title":"Remote Entity Link","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"link":{}},"additionalProperties":false}}

api/2/workflow

REST resource for retrieving workflows.

Returns all workflows.

Request
query parameters
parametertypedescription
workflowNamestring
Responses
  • Status 200 - application/json
    Returned if the currently authenticated user has administration permission. Contains a full representation of every workflow.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow#","title":"Workflow","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"lastModifiedDate":{"type":"string"},"lastModifiedUser":{"type":"string"},"steps":{"type":"integer"},"isDefault":{"type":"boolean"}},"additionalProperties":false,"required":["isDefault"]}

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-workflow#","title":"List of Workflow","type":"array","items":{"title":"Workflow","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"lastModifiedDate":{"type":"string"},"lastModifiedUser":{"type":"string"},"steps":{"type":"integer"},"isDefault":{"type":"boolean"}},"additionalProperties":false,"required":["isDefault"]}}

  • Status 401
    Returned if the currently authenticated user does not have administration permission.

Add a new property to a transition. Trying to add a property that already exists will fail.

Request
query parameters
parametertypedescription
keystring

the name of the property to add.

workflowNamestring

the name of the workflow to use.

workflowModestring

the type of workflow to use. Can either be "live" or "draft".

Example
{"value":"createissue"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/property#","title":"Property","type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 200 - application/json

    Example
    {"key":"jira.i18n.title","value":"some.title","id":"jira.i18n.title"}

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/property#","title":"Property","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false}

  • Status 400
    Returned if the request is invalid.
  • Status 403
    Returned if the user does not have admin permission

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
parametertypedescription
keystring

the name of the property to add.

workflowNamestring

the name of the workflow to use.

workflowModestring

the type of workflow to use. Can either be "live" or "draft".

Example
{"value":"createissue"}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/property#","title":"Property","type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 200 - application/json

    Example
    {"key":"jira.i18n.title","value":"some.title","id":"jira.i18n.title"}

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/property#","title":"Property","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false}

  • Status 400
    Returned if the request is invalid.
  • Status 403
    Returned if the user does not have admin permission
  • Status 304
    Returned if no changes were actually made by the request (e.g. updating a property to value it already holds).

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
parametertypedescription
keystring

the name of the property to add.

workflowNamestring

the name of the workflow to use.

workflowModestring

the type of workflow to use. Can either be "live" or "draft".

Responses
  • Status 200 - application/json
  • Status 400
    Returned if the request is invalid.
  • Status 403
    Returned if the user does not have admin permission
  • Status 304
    Returned if no changes were actually made by the request (e.g. trying to delete a property that does not exist).

Return the property or properties associated with a transition.

Request
query parameters
parametertypedescription
includeReservedKeysboolean

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.

keystring

the name of the property key to query. Can be left off the query to return all properties.

workflowNamestring

the name of the workflow to use.

workflowModestring

the type of workflow to use. Can either be "live" or "draft".

Responses
  • Status 200 - application/json

    Example
    {"key":"jira.i18n.title","value":"some.title","id":"jira.i18n.title"}

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/property#","title":"Property","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false}

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-property#","title":"List of Property","type":"array","items":{"title":"Property","type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false}}

  • Status 403
    Returned if the user does not have admin permission

api/2/workflowscheme

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.

Request

Example
{"name":"New Workflow Scheme Name","description":"New Workflow Scheme Description","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId":"WorkflowName"}}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

Responses
  • Status 201

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"self":{"type":"string","format":"uri"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

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

Returns the requested workflow scheme to the caller.

Request
query parameters
parametertypedescription
returnDraftIfExistsboolean

Default: false

when true indicates that a scheme's draft, if it exists, should be queried instead of the scheme itself.

Responses
  • Status 200 - application/json

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"self":{"type":"string","format":"uri"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if the requested scheme does not exist.

Delete the passed workflow scheme.

Responses
  • Status 400
    Returned if the requested scheme is active (i.e. being used by JIRA).
  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 204
    If the scheme was deleted.
  • Status 404
    Returned if the requested scheme does not exist.

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.

Request

Example
{"id":57585,"name":"Updated Workflow Scheme Name","description":"Updated Workflow Scheme Name","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId":"WorkflowName"},"updateDraftIfNeeded":false}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

Responses
  • Status 200

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"self":{"type":"string","format":"uri"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if the requested scheme does not exist.

Create a draft for the passed scheme. The draft will be a copy of the state of the parent.

Responses
  • Status 201

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","groups":{"size":3,"items":[]},"applicationRoles":{"size":1,"items":[]}},"lastModified":"Today 12:45","self":"http://www.example.com/jira/rest/api/2/workflowscheme/17218781/draft"}

    The newly created scheme.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"self":{"type":"string","format":"uri"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

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

Remove the default workflow from the passed workflow scheme.

Request
query parameters
parametertypedescription
updateDraftIfNeededboolean

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

Responses
  • Status 200

    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.
  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if the scheme does not exist.

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.

Request

Example
{"workflow":"WorkflowName","updateDraftIfNeeded":false}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/default#","title":"Default","type":"object","properties":{"workflow":{"type":"string"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}

Responses
  • Status 200

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"self":{"type":"string","format":"uri"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if the scheme does not exist.

Return the default workflow from the passed workflow scheme.

Request
query parameters
parametertypedescription
returnDraftIfExistsboolean

Default: false

when true indicates that a scheme's draft, if it exists, should be queried instead of the scheme itself.

Responses
  • Status 200

    Example
    {"workflow":"WorkflowName"}

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/default#","title":"Default","type":"object","properties":{"workflow":{"type":"string"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned when the workflow scheme does not exist.

Returns the requested draft workflow scheme to the caller.

Responses
  • Status 200 - application/json

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","groups":{"size":3,"items":[]},"applicationRoles":{"size":1,"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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"self":{"type":"string","format":"uri"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if the requested draft scheme does not exist.

Delete the passed draft workflow scheme.

Responses
  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 204
    If the scheme was deleted.
  • Status 404
    Returned if the requested draft scheme or parent scheme does not exist.

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.

Request

Example
{"id":57585,"name":"Updated Workflow Scheme Name","description":"Updated Workflow Scheme Name","defaultWorkflow":"DefaultWorkflowName","issueTypeMappings":{"IsueTypeId":"WorkflowName"},"updateDraftIfNeeded":false}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

Responses
  • Status 200

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","groups":{"size":3,"items":[]},"applicationRoles":{"size":1,"items":[]}},"lastModified":"Today 12:45","self":"http://www.example.com/jira/rest/api/2/workflowscheme/17218781/draft"}

    The updated/created scheme.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"self":{"type":"string","format":"uri"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if the requested scheme does not exist.

Return the default workflow from the passed draft workflow scheme to the caller.

Responses
  • Status 200

    Example
    {"workflow":"WorkflowName"}

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/default#","title":"Default","type":"object","properties":{"workflow":{"type":"string"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned when the workflow scheme does not exist.

Remove the default workflow from the passed draft workflow scheme.

Responses
  • Status 200

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","groups":{"size":3,"items":[]},"applicationRoles":{"size":1,"items":[]}},"lastModified":"Today 12:45","self":"http://www.example.com/jira/rest/api/2/workflowscheme/17218781/draft"}

    Returned on success.
  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if the scheme does not exist.

Set the default workflow for the passed draft workflow scheme.

Request

Example
{"workflow":"WorkflowName","updateDraftIfNeeded":false}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/default#","title":"Default","type":"object","properties":{"workflow":{"type":"string"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}

Responses
  • Status 200

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","groups":{"size":3,"items":[]},"applicationRoles":{"size":1,"items":[]}},"lastModified":"Today 12:45","self":"http://www.example.com/jira/rest/api/2/workflowscheme/17218781/draft"}

    Returned on success.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"self":{"type":"string","format":"uri"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if the scheme does not exist.

Returns the issue type mapping for the passed draft workflow scheme.

Responses
  • Status 200 - application/json

    Example
    {"issueType":"IssueTypeId","workflow":"WorkflowName"}

    Returned on success.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-type-mapping#","title":"Issue Type Mapping","type":"object","properties":{"issueType":{"type":"string"},"workflow":{"type":"string"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if either the requested scheme or issue type does not exist.

Remove the specified issue type mapping from the draft scheme.

Responses
  • Status 200

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","groups":{"size":3,"items":[]},"applicationRoles":{"size":1,"items":[]}},"lastModified":"Today 12:45","self":"http://www.example.com/jira/rest/api/2/workflowscheme/17218781/draft"}

    Returned on success.
  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if either the requested scheme or issue type does not exist.

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.

Request

Example
{"issueType":"IssueTypeId","workflow":"WorkflowName","updateDraftIfNeeded":false}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-type-mapping#","title":"Issue Type Mapping","type":"object","properties":{"issueType":{"type":"string"},"workflow":{"type":"string"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}

Responses
  • Status 200

    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","key":"fred","accountId":"99:27935d01-92a7-4687-8272-a9b8d3b2ae2e","name":"fred","emailAddress":"fred@example.com","avatarUrls":{"48x48":"http://www.example.com/jira/secure/useravatar?size=large&ownerId=fred","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"},"displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","groups":{"size":3,"items":[]},"applicationRoles":{"size":1,"items":[]}},"lastModified":"Today 12:45","self":"http://www.example.com/jira/rest/api/2/workflowscheme/17218781/draft"}

    Returned on success.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"self":{"type":"string","format":"uri"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if either the requested scheme or issue type does not exist.

Returns the draft workflow mappings or requested mapping to the caller.

Request
query parameters
parametertypedescription
workflowNamestring

the workflow mapping to return. Null can be passed to return all mappings. Must be a valid workflow name.

Responses
  • Status 200 - application/json

    Example
    {"workflow":"WorkflowName","issueTypes":["IssueTypeId","IssueTypeId2"],"defaultMapping":false}

    Returned on success.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-mapping#","title":"Workflow Mapping","type":"object","properties":{"workflow":{"type":"string"},"issueTypes":{"type":"array","items":{"type":"string"}},"defaultMapping":{"type":"boolean"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-workflow-mapping#","title":"List of Workflow Mapping","type":"array","items":{"title":"Workflow Mapping","type":"object","properties":{"workflow":{"type":"string"},"issueTypes":{"type":"array","items":{"type":"string"}},"defaultMapping":{"type":"boolean"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if either the requested scheme or workflow does not exist.

Delete the passed workflow from the draft workflow scheme.

Request
query parameters
parametertypedescription
workflowNamestring

the name of the workflow to delete.

Responses
  • Status 200
    The scheme with the workflow deleted.
  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if the requested scheme or workflow does not exist.

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
parametertypedescription
workflowNamestring

the name of the workflow mapping to update.

Example
{"workflow":"WorkflowName3","issueTypes":["IssueTypeId"],"updateDraftIfNeeded":true}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/workflow-mapping#","title":"Workflow Mapping","type":"object","properties":{"workflow":{"type":"string"},"issueTypes":{"type":"array","items":{"type":"string"}},"defaultMapping":{"type":"boolean"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}

Responses
  • Status 200

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"self":{"type":"string","format":"uri"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

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

Returns the issue type mapping for the passed workflow scheme.

Request
query parameters
parametertypedescription
returnDraftIfExistsboolean

Default: false

when true indicates that a scheme's draft, if it exists, should be queried instead of the scheme itself.

Responses
  • Status 200 - application/json

    Example
    {"issueType":"IssueTypeId","workflow":"WorkflowName"}

    Returned on success.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/issue-type-mapping#","title":"Issue Type Mapping","type":"object","properties":{"issueType":{"type":"string"},"workflow":{"type":"string"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if either the requested scheme or issue type does not exist.

Remove the specified issue type mapping from the scheme.

Request
query parameters
parametertypedescription
updateDraftIfNeededboolean

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

Responses
  • Status 200

    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.
  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if either the requested scheme or issue type does not exist.

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.

Request

Example
{"issueType":"IssueTypeId","workflow":"WorkflowName","updateDraftIfNeeded":false}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-type-mapping#","title":"Issue Type Mapping","type":"object","properties":{"issueType":{"type":"string"},"workflow":{"type":"string"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}

Responses
  • Status 200

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"self":{"type":"string","format":"uri"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if either the requested scheme or issue type does not exist.

Returns the workflow mappings or requested mapping to the caller for the passed scheme.

Request
query parameters
parametertypedescription
workflowNamestring

the workflow mapping to return. Null can be passed to return all mappings. Must be a valid workflow name.

returnDraftIfExistsboolean

Default: false

when true indicates that a scheme's draft, if it exists, should be queried instead of the scheme itself.

Responses
  • Status 200 - application/json

    Example
    {"workflow":"WorkflowName","issueTypes":["IssueTypeId","IssueTypeId2"],"defaultMapping":false}

    Returned on success.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-mapping#","title":"Workflow Mapping","type":"object","properties":{"workflow":{"type":"string"},"issueTypes":{"type":"array","items":{"type":"string"}},"defaultMapping":{"type":"boolean"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-workflow-mapping#","title":"List of Workflow Mapping","type":"array","items":{"title":"Workflow Mapping","type":"object","properties":{"workflow":{"type":"string"},"issueTypes":{"type":"array","items":{"type":"string"}},"defaultMapping":{"type":"boolean"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}}

  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if either the requested scheme or workflow does not exist.

Delete the passed workflow from the workflow scheme.

Request
query parameters
parametertypedescription
workflowNamestring

the name of the workflow to delete.

updateDraftIfNeededboolean

flag to indicate if a draft should be created if necessary to delete the workflow from the scheme.

Responses
  • Status 200
    The scheme with the workflow deleted.
  • Status 401
    Returned if there is no user or if the user has not entered a websudo session.
  • Status 404
    Returned if the requested scheme or workflow does not exist.

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
parametertypedescription
workflowNamestring

the name of the workflow mapping to update.

Example
{"workflow":"WorkflowName3","issueTypes":["IssueTypeId"],"updateDraftIfNeeded":true}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/workflow-mapping#","title":"Workflow Mapping","type":"object","properties":{"workflow":{"type":"string"},"issueTypes":{"type":"array","items":{"type":"string"}},"defaultMapping":{"type":"boolean"},"updateDraftIfNeeded":{"type":"boolean"}},"additionalProperties":false}

Responses
  • Status 200

    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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/workflow-scheme#","title":"Workflow Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultWorkflow":{"type":"string"},"issueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"originalDefaultWorkflow":{"type":"string"},"originalIssueTypeMappings":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"draft":{"type":"boolean"},"lastModifiedUser":{"title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"accountId":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"}},"additionalProperties":false,"required":["active"]},"lastModified":{"type":"string"},"self":{"type":"string","format":"uri"},"updateDraftIfNeeded":{"type":"boolean"},"issueTypes":{"type":"object","patternProperties":{".+":{"title":"Issue Type","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"},"subtask":{"type":"boolean"},"avatarId":{"type":"integer"}},"additionalProperties":false,"required":["subtask"]}},"additionalProperties":false}},"definitions":{"simple-list-wrapper":{"title":"Simple List Wrapper","type":"object","properties":{"size":{"type":"integer"},"max-results":{"type":"integer"},"items":{"type":"array","items":{"title":"Group","type":"object","properties":{"name":{"type":"string"},"self":{"type":"string","format":"uri"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false}

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

api/2/worklog

Returns worklogs id and delete time of worklogs that was deleted since given time. The returns set of worklogs is limited to 1000 elements. This API will not return worklogs deleted during last minute.

Request
query parameters
parametertypedescription
sincelong

Default: 0

a date time in unix timestamp format since when deleted worklogs will be returned.

Responses
  • Status 200 - application/json

    Example
    {"values":[{"worklogId":103,"updatedTime":1438013671562,"properties":[]},{"worklogId":104,"updatedTime":1438013672165,"properties":[]},{"worklogId":105,"updatedTime":1438013693136,"properties":[]}],"since":1438013671562,"until":1438013693136,"self":"http://www.example.com/jira/worklog/updated/updated/deleted?since=1438013671136&since=1438013693136&since=1438013671136","nextPage":"http://www.example.com/jira/worklog/updated/updated/deleted/deleted?since=1438013671136&since=1438013693136&since=1438013671136&since=1438013693136","lastPage":true}

    Returns a JSON representation of the worklog changes.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/worklog-changed-since#","title":"Worklog Changed Since","type":"object","properties":{"values":{"type":"array","items":{"title":"Worklog Change","type":"object","properties":{"worklogId":{"type":"integer"},"updatedTime":{"type":"integer"},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"additionalProperties":false}},"since":{"type":"integer"},"until":{"type":"integer"},"isLastPage":{"type":"boolean"},"self":{"type":"string","format":"uri"},"nextPage":{"type":"string","format":"uri"}},"additionalProperties":false,"required":["isLastPage"]}

Returns worklogs for given worklog ids. Only worklogs to which the calling user has permissions, will be included in the result. The returns set of worklogs is limited to 1000 elements.

Request
query parameters
parametertypedescription
expandstring

Default:

optional comma separated list of parameters to expand: properties (provides worklog properties).

Example
{"ids":[1,2,5,10]}

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/worklog-ids-request#","title":"Worklog Ids Request","type":"object","properties":{"ids":{"type":"array","items":{"type":"integer"}}},"additionalProperties":false}

Responses
  • Status 200 - application/json

    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.","updated":"2017-03-08T03:29:43.684+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2017-03-08T03:29:43.684+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}

    Returns a JSON representation of the search results.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/list-of-worklog#","title":"List of Worklog","type":"array","items":{"title":"Worklog","type":"object","properties":{"self":{"type":"string","format":"uri"},"author":{"$ref":"#/definitions/user"},"updateAuthor":{"$ref":"#/definitions/user"},"comment":{"type":"string"},"created":{"type":"string"},"updated":{"type":"string"},"visibility":{"title":"Visibility","type":"object","properties":{"type":{"type":"string","enum":["group","role"]},"value":{"type":"string"}},"additionalProperties":false},"started":{"type":"string"},"timeSpent":{"type":"string"},"timeSpentSeconds":{"type":"integer"},"id":{"type":"string"},"issueId":{"type":"string"},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"additionalProperties":false},"definitions":{"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"accountId":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"timeZone":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}

  • Status 400
    Returned if the request contains more than 1000 ids or is null

Returns worklogs id and update time of worklogs that was updated since given time. The returns set of worklogs is limited to 1000 elements. This API will not return worklogs updated during last minute.

Request
query parameters
parametertypedescription
sincelong

Default: 0

a date time in unix timestamp format since when updated worklogs will be returned.

expandstring

Default:

optional comma separated list of parameters to expand: properties (provides worklog properties).

Responses
  • Status 200 - application/json

    Example
    {"values":[{"worklogId":103,"updatedTime":1438013671562,"properties":[]},{"worklogId":104,"updatedTime":1438013672165,"properties":[]},{"worklogId":105,"updatedTime":1438013693136,"properties":[]}],"since":1438013671562,"until":1438013693136,"self":"http://www.example.com/jira/worklog/updated?since=1438013671136","nextPage":"http://www.example.com/jira/worklog/updated/updated?since=1438013671136&since=1438013693136","lastPage":true}

    Returns a JSON representation of the worklog changes.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/worklog-changed-since#","title":"Worklog Changed Since","type":"object","properties":{"values":{"type":"array","items":{"title":"Worklog Change","type":"object","properties":{"worklogId":{"type":"integer"},"updatedTime":{"type":"integer"},"properties":{"type":"array","items":{"title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}}},"additionalProperties":false}},"since":{"type":"integer"},"until":{"type":"integer"},"isLastPage":{"type":"boolean"},"self":{"type":"string","format":"uri"},"nextPage":{"type":"string","format":"uri"}},"additionalProperties":false,"required":["isLastPage"]}

auth/1/session

Implement a REST resource for acquiring a session cookie.

Returns information about the currently authenticated user's session. If the caller is not authenticated they will get a 401 Unauthorized status code.

Responses
  • Status 200

    Example
    {"self":"http://www.example.com/jira/rest/api/2.0/user/fred","name":"fred","loginInfo":{"failedLoginCount":10,"loginCount":127,"lastFailedLoginTime":"2017-03-08T03:29:41.877+0000","previousLoginTime":"2017-03-08T03:29:41.877+0000"}}

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/current-user#","title":"Current User","type":"object","properties":{"self":{"type":"string","format":"uri"},"name":{"type":"string"},"loginInfo":{"title":"Login Info","type":"object","properties":{"failedLoginCount":{"type":"integer"},"loginCount":{"type":"integer"},"lastFailedLoginTime":{"type":"string"},"previousLoginTime":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

  • Status 401
    Returned if the caller is not authenticated.

Logs the current user out of JIRA, destroying the existing session, if any.

Responses
  • Status 401
    Returned if the caller is not authenticated.
  • Status 204
    Returned if the user was successfully logged out.

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

Request

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

Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/auth-params#","title":"Auth Params","type":"object","properties":{"username":{"type":"string"},"password":{"type":"string"}},"additionalProperties":false}

Responses
  • Status 200

    Example
    {"session":{"name":"seraph.rememberme.cookie","value":"12345678901234567890"},"loginInfo":{"failedLoginCount":10,"loginCount":127,"lastFailedLoginTime":"2017-03-08T03:29:41.877+0000","previousLoginTime":"2017-03-08T03:29:41.877+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.

    Schema
    {"id":"https://docs.atlassian.com/jira/REST/schema/auth-success#","title":"Auth Success","type":"object","properties":{"session":{"title":"Session Info","type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false},"loginInfo":{"title":"Login Info","type":"object","properties":{"failedLoginCount":{"type":"integer"},"loginCount":{"type":"integer"},"lastFailedLoginTime":{"type":"string"},"previousLoginTime":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}

  • Status 401
    Returned if the login fails due to invalid credentials.
  • Status 403
    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.