Jira Data Center platform REST API reference
Jira 9.17.0
Welcome to the Jira Data Center platform REST API reference. You can use this REST API to build apps for Jira, develop integrations between Jira and other applications, or script interactions with Jira. This page documents the REST resources available in Jira Data Center platform, 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 Data Center before, read the Getting started guide in the Jira Data Center developer documentation. You may also want to read our Jira REST API overview, which describes how the Jira REST APIs work, including a simple example of a REST call.
Authentication
The following authentication methods are supported for the Jira REST APIs:
- Recommended:
- OAuth 2.0 - This method provides APIs to allow external services to access resources on a user’s behalf with the OAuth 2.0 protocol. This protocol is not compatible with Oauth 1.0a.
- Personal access token (PAT) - This method incorporates the user account in the access token. It is a safe alternative to using username and password for authentication with various services.
- Other:
- OAuth 1.0a - This method provides APIs to allow external services to access resources on a user’s behalf with the OAuth 1.0 protocol. This protocol is deprecated.
- Basic HTTP - This method is only recommended for tools like scripts or bots. It is easier to implement but much less secure.
Jira uses cookie-based authentication in the browser, so you can call the REST API from Javascript on the page and rely on the authentication the browser has established. To reproduce the behavior of the Jira log-in page, you can POST
to the /auth/1/session
resource. You can use it, for example, to display authentication error messages to users.
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, andapi
- 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
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.
Get permissionsGET /rest/api/2/mypermissions
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
parameter | type | description |
---|---|---|
projectKey | string | - key of project to scope returned permissions for. |
projectId | string | - id of project to scope returned permissions for. |
issueKey | string | - key of the issue to scope returned permissions for. |
issueId | string | - id of the issue to scope returned permissions for. |
Responses
- Status
200 - application/jsonReturns a list of all permissions in Jira and whether the user has them.
Example
{"permissions":{"EDIT_ISSUE":{"id":"12","key":"EDIT_ISSUES","name":"Edit Issues","type":"PROJECT","description":"Ability to edit issues.","havePermission":true}}}
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
400Returned if the project or issue id is invalid.
- Status
401Returned if request is on behalf of anonymous user.
- Status
404Returned if the project or issue id or key is not found.
Get all permissionsGET /rest/api/2/permissions
Returns all permissions that are present in the Jira instance - Global, Project and the global ones added by plugins
Responses
- Status
200 - application/jsonReturns a list of all permissions in Jira.
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."}}}
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
401Returned for unauthenticated requests
- Status
403Returned for users without administer permissions
api/2/application-properties
Get propertyGET /rest/api/2/application-properties
Returns an application property.
Request
query parameters
parameter | type | description |
---|---|---|
key | string | a String containing the property key |
permissionLevel | string | when fetching a list specifies the permission level of all items in the list see {@link com.atlassian.jira.bc.admin.ApplicationPropertiesService.EditPermissionLevel} |
keyFilter | string | when fetching a list allows the list to be filtered by the property's start of key e.g. "jira.lf.*" whould fetch only those permissions that are editable and whose keys start with "jira.lf.". This is a regex. |
Responses
- Status
200 - application/jsonReturned if the property exists and the currently authenticated user has permission to view it. Contains a full representation of the property.
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 -"}]
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
404Returned if the property does not exist or the currently authenticated user does not have permission to view it.
Set property via restful tablePUT /rest/api/2/application-properties/{id}
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
200Returned 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
403Returned if the currently authenticated user does not have permission to edit the property.
- Status
404Returned if the property does not exist or the currently authenticated user does not have permission to view it.
Get advanced settingsGET /rest/api/2/application-properties/advanced-settings
Returns the properties that are displayed on the "General Configuration > Advanced Settings" page.
Responses
- Status
200 - application/jsonReturns all properties to display in the "General Configuration > Advanced Settings" page.
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 -"}]
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
401Returned if the current user is not authenticated.
- Status
403Returned if the current user is not an administrator.
api/2/applicationrole
Provides REST access to Jira's Application Roles.
Put bulkPUT /rest/api/2/applicationrole
Updates the ApplicationRoles with the passed data if the version hash is the same as the server. Only the groups and default groups setting of the role may be updated. Requests to change the key or the name of the role will be silently ignored. It is acceptable to pass only the roles that are updated as roles that are present in the server but not in data to update with, will not be deleted.
Request
header parameters
parameter | type | description |
---|---|---|
If-Match | string |
Example
{"key":"jira-software","groups":["jira-software-users","jira-testers"],"name":"Jira Software","defaultGroups":["jira-software-users"],"selectedByDefault":true}
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}}
Responses
- Status
200 - application/jsonReturns the updated ApplicationRole if the update was successful.
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}]
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
401Returned if the current user does not have permission to edit roles.
- Status
412Returned if the If-Match header is not null and contains a different version to the server.
- Status
403Returned if the current user is not an administrator.
- Status
404Returned if the role does not exist.
Get allGET /rest/api/2/applicationrole
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/jsonReturns all ApplicationRoles in the system
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}]
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
401Returned if the current user is not authenticated.
- Status
403Returned if the current user is not an administrator.
GetGET /rest/api/2/applicationrole/{key}
Returns the ApplicationRole with passed key if it exists.
Responses
- Status
200 - application/jsonReturns the ApplicationRole if it exists.
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}
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
401Returned if the current user is not authenticated.
- Status
403Returned if the current user is not an administrator.
- Status
404Returned if the role does not exist.
PutPUT /rest/api/2/applicationrole/{key}
Updates the ApplicationRole with the passed data. Only the groups and default groups setting of the role may be updated. Requests to change the key or the name of the role will be silently ignored.
Optional: If versionHash is passed through the If-Match header the request will be rejected if not the same as server
Request
header parameters
parameter | type | description |
---|---|---|
If-Match | string | the hash of the version to update. Optional Param |
Example
{"key":"jira-software","groups":["jira-software-users","jira-testers"],"name":"Jira Software","defaultGroups":["jira-software-users"],"selectedByDefault":true}
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}
Responses
- Status
200 - application/jsonReturns the updated ApplicationRole if the update was successful.
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}
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
401Returned if the current user does not have permission to edit roles.
- Status
412Returned if the If-Match header is not null and contains a different version to the server.
- Status
403Returned if the current user is not an administrator.
- Status
404Returned if the role does not exist.
api/2/attachment
Get attachmentGET /rest/api/2/attachment/{id}
Returns the meta-data for an attachment, including the URI of the actual attached file.
Responses
- Status
200 - application/jsonJSON 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.
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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"created":"2024-06-26T10:20:31.317+0000","size":23123,"mimeType":"image/jpeg","content":"http://www.example.com/jira/attachments/10000","thumbnail":"http://www.example.com/jira/secure/thumbnail/10000"}
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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"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
403The calling user is not permitted to view the requested attachment.
- Status
404Any of:
- there is no attachment with the requested id
- attachments feature is disabled
Remove attachmentDELETE /rest/api/2/attachment/{id}
Remove an attachment from an issue.
Responses
- Status
204Removal was successful
- Status
403The calling user is not permitted to remove the requested attachment.
- Status
404Any of:
- there is no attachment with the requested id
- attachments feature is disabled
Expand for humans
experimentalGET /rest/api/2/attachment/{id}/expand/human
Tries to expand an attachment. Output is human-readable and subject to change.
Responses
- Status
200 - application/jsonJSON 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.
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"}
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
403The calling user is not permitted to view the requested attachment.
- Status
404Any of:
- there is no attachment with the requested id
- attachments feature is disabled
- Status
409The archive format is not supported.
Expand for machines
experimentalGET /rest/api/2/attachment/{id}/expand/raw
Tries to expand an attachment. Output is raw and should be backwards-compatible through the course of time.
Responses
- Status
200 - application/jsonJSON 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.
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}
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"}},"additionalProperties":false,"required":["entryIndex"]}},"totalEntryCount":{"type":"integer"}},"additionalProperties":false,"required":["totalEntryCount"]}
- Status
403The calling user is not permitted to view the requested attachment.
- Status
404Any of:
- there is no attachment with the requested id
- attachments feature is disabled
- Status
409The archive format is not supported.
Get attachment metaGET /rest/api/2/attachment/meta
Returns the meta information for an attachments, specifically if they are enabled and the maximum upload size allowed.
Responses
- Status
200 - application/jsonJSON 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}.
Example
{"enabled":true,"uploadLimit":1000000}
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
Get records
deprecatedGET /rest/api/2/auditing/record
Returns auditing records filtered using provided parameters
Request
query parameters
parameter | type | description |
---|---|---|
offset | int | - the number of record from which search starts |
limit | int | - maximum number of returned results (if is limit is <= 0 or > 1000, it will be set do default value: 1000) |
filter | string | - text query; each record that will be returned must contain the provided text in one of its fields |
from | string | - timestamp in past; 'from' must be less or equal 'to', otherwise the result set will be empty only records that where created in the same moment or after the 'from' timestamp will be provided in response |
to | string | - timestamp in past; 'from' must be less or equal 'to', otherwise the result set will be empty only records that where created in the same moment or earlier than the 'to' timestamp will be provided in response |
projectIds | string | - list of project ids to look for |
userIds | string | - list of user ids to look for |
Responses
- Status
200 - application/jsonReturns a list auditing records filtered with request query parameters
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"}]}
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
400In case of unhandled error while fetching auditing records
- Status
403Returned if the user does not have admin permission
Add record
deprecatedPOST /rest/api/2/auditing/record
Store a record in audit log
Request
Example
{"summary":"User created","created":null,"category":"USER_MANAGEMENT","objectItem":{"id":"usr","name":"user","typeName":"USER","parentId":"1","parentName":"Jira Internal Directory"},"changedValues":[{"fieldName":"email","changedFrom":"user@atlassian.com","changedTo":"newuser@atlassian.com"}],"associatedItems":[{"id":"jira-software-users","name":"jira-software-users","typeName":"GROUP","parentId":"1","parentName":"Jira Internal Directory"}]}
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}
Responses
- Status
201Returned if the record is successfully stored.
- Status
400In case of unhandled error while fetching auditing records
- Status
403Returned if the user does not have admin permission
api/2/avatar
Get all system avatarsGET /rest/api/2/avatar/{type}/system
Returns all system avatars of the given type.
Responses
- Status
200 - application/jsonReturns 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.
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}]}
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
500Returned if an error occurs while retrieving the list of avatars.
- Status
401Returned if accessed by anonymous user
Store temporary avatarPOST /rest/api/2/avatar/{type}/temporary
Creates temporary avatar
Request
query parameters
parameter | type | description |
---|---|---|
filename | string | name of file being uploaded |
size | long | size of file |
Responses
- Status
201 - application/jsontemporary avatar cropping instructions
Example
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/avatar-cropping#","title":"Avatar Cropping","type":"object","properties":{"cropperWidth":{"type":"integer"},"cropperOffsetX":{"type":"integer"},"cropperOffsetY":{"type":"integer"},"url":{"type":"string"},"needsCropping":{"type":"boolean"}},"additionalProperties":false,"required":["cropperWidth","cropperOffsetX","cropperOffsetY","needsCropping"]}
- Status
400Valiation failed. For example filesize is beyond max attachment size.
- Status
500Returned if an error occurs while converting temporary avatar to real avatar
- Status
403Returned if the request does not conain a valid XSRF token
Create avatar from temporaryPOST /rest/api/2/avatar/{type}/temporaryCrop
Updates the cropping instructions of the temporary avatar.
Request
Example
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"needsCropping":false}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/avatar-cropping#","title":"Avatar Cropping","type":"object","properties":{"cropperWidth":{"type":"integer"},"cropperOffsetX":{"type":"integer"},"cropperOffsetY":{"type":"integer"},"url":{"type":"string"},"needsCropping":{"type":"boolean"}},"additionalProperties":false,"required":["cropperWidth","cropperOffsetX","cropperOffsetY","needsCropping"]}
Responses
- Status
201 - application/json
- Status
400Returned if the cropping coordinates are invalid
- Status
500Returned if an error occurs while cropping the temporary avatar
api/2/cluster
It gives possibility to manage old node in cluster.
Get all nodesGET /rest/api/2/cluster/nodes
Responses
- Status
401if the user doesn't have admin permissions
- Status
405if you call this method, but don't have Jira Data Center
Request current index from nodePUT /rest/api/2/cluster/index-snapshot/{nodeId}
request current index from node (the request is processed asynchronously)
Responses
- Status
401if the user doesn't have admin permissions
- Status
404if the node with this nodeID doesn't exist
- Status
405if you call this method, but don't have Jira Data Center
Delete nodeDELETE /rest/api/2/cluster/node/{nodeId}
Delete the node from the cluster if state of node is OFFLINE.
Responses
- Status
400if node's state is not offline
- Status
401if the user doesn't have admin permissions
- Status
500if the server can't delete the nod
- Status
404if the node with this nodeID doesn't exist
- Status
405if you call this method, but don't have Jira Data Center
Change node state to offlinePUT /rest/api/2/cluster/node/{nodeId}/offline
Change the node's state to offline if the node is reporting as active, but is not alive. Don't use this method as an equivalent of running ./stop-jira.sh. This method doesn't shut down a node, but only changes its state, so that other nodes don't communicate with it.
Responses
- Status
400if the node is active and alive, no need to use this method
- Status
401if the user doesn't have admin permissions
- Status
500if the server can't change the node's state
- Status
404if the node with this nodeID doesn't exist
- Status
405if you call this method, but don't have Jira Data Center
api/2/cluster/zdu
Approve upgradePOST /rest/api/2/cluster/zdu/approve
Responses
- Status - */*
Cancel upgradePOST /rest/api/2/cluster/zdu/cancel
Responses
- Status - application/json
Acknowledge errorsPOST /rest/api/2/cluster/zdu/retryUpgrade
Responses
- Status - */*
Set ready to upgradePOST /rest/api/2/cluster/zdu/start
Responses
- Status - */*
Get stateGET /rest/api/2/cluster/zdu/state
Responses
- Status - application/json
api/2/comment/{commentId}/properties
Get properties keys
experimentalGET /rest/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/jsonReturned if the comment was found.
Example
{"keys":[{"self":"http://www.example.com/jira/rest/api/2/issue/EX-2/properties/issue.support","key":"issue.support"}]}
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
400Returned if the comment key or id is invalid.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to browse the comment.
- Status
404Returned if the comment with given key or id does not exist or if the property with given key is not found.
Delete property
experimentalDELETE /rest/api/2/comment/{commentId}/properties/{propertyKey}
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
400Returned if the comment key or id is invalid.
- Status
401Returned if the calling user is not authenticated.
- Status
204Returned if the comment property was removed successfully.
- Status
403Returned if the calling user does not have permission to edit the comment.
- Status
404Returned if the comment with given key or id does not exist or if the property with given key is not found.
Set property
experimentalPUT /rest/api/2/comment/{commentId}/properties/{propertyKey}
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
200Returned if the comment property is successfully updated.
- Status
201Returned if the comment property is successfully created.
- Status
400Returned if the comment key or id is invalid.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to administer the comment.
- Status
404Returned if the comment with given key or id does not exist.
Get property
experimentalGET /rest/api/2/comment/{commentId}/properties/{propertyKey}
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/jsonReturned if the comment property was found.
Example
{"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/entity-property#","title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}
- Status
400Returned if the comment key or id is invalid.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to browse the comment.
- Status
404Returned 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 componentPOST /rest/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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}
Responses
- Status
201 - application/jsonReturned if the component is created successfully.
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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"isAssigneeTypeValid":false,"project":"HSP","projectId":10000}
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}
- Status
401Returned if the caller is not logged in and does not have permission to create components in the project.
- Status
403Returned if the caller is authenticated and does not have permission to create components in the project.
- Status
404Returned if the project does not exist or the currently authenticated user does not have permission to view it.
Update componentPUT /rest/api/2/component/{id}
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}
Responses
- Status
200Returned 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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}
- Status
403Returned if the currently authenticated user does not have permission to edit the component.
- Status
404Returned if the component does not exist or the currently authenticated user does not have permission to view it.
Get componentGET /rest/api/2/component/{id}
Returns a project component.
Responses
- Status
200 - application/jsonReturns a full JSON representation of a project component.
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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"isAssigneeTypeValid":false,"project":"HSP","projectId":10000}
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["isAssigneeTypeValid"]}
- Status
404Returned if there is no component with the given key, or if the calling user does not have permission to view the component.
DeleteDELETE /rest/api/2/component/{id}
Delete a project component.
Request
query parameters
parameter | type | description |
---|---|---|
moveIssuesTo | string | The new component applied to issues whose 'id' component will be deleted. If this value is null, then the 'id' component is simply removed from the related isues. |
Responses
- Status
204Returned if the component is successfully deleted.
- Status
403Returned if the currently authenticated user does not have permission to delete the component.
- Status
404Returned if the component does not exist or the currently authenticated user does not have permission to view it.
Get component related issuesGET /rest/api/2/component/{id}/relatedIssueCounts
Returns counts of issues related to this component.
Responses
- Status
200 - application/jsonReturned if the component exists and the currently authenticated user has permission to view it. Contains counts of issues related to this component.
Example
{"self":"http://www.example.com/jira/rest/api/2/component/10000","issueCount":23}
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
404Returned if the component does not exist or the currently authenticated user does not have permission to view it.
Get paginated components
experimentalGET /rest/api/2/component/page
Returns paginated list of filtered active components
Request
query parameters
parameter | type | description |
---|---|---|
startAt | long Default: 0 | the index of the first components to return |
maxResults | int Default: 100 | the maximum number of components to return |
query | string Default: | the string that components names will be matched with |
projectIds | string | the set of project ids to filter components |
Responses
- Status
200 - application/jsonReturns paginated list of components
Example
{"self":"http://www.example.com/jira/rest/api/2/component/page?startAt=0&maxResults=2","nextPage":"http://www.example.com/jira/rest/api/2/component/page?startAt=2&maxResults=2","maxResults":2,"startAt":0,"total":5,"isLast":false,"values":[{"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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"isAssigneeTypeValid":false,"project":"PROJECTKEY","projectId":10000}]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/page-of-component#","title":"Page of Component","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":"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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["maxResults","startAt"]}
api/2/configuration
Get configurationGET /rest/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/jsonReturned the configuration of optional features in Jira.
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"}}
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
401Returned if the user is not logged in.
api/2/customFieldOption
Get custom field optionGET /rest/api/2/customFieldOption/{id}
Returns a full representation of the Custom Field Option that has the given id.
Responses
- Status
200 - application/jsonReturned if the Custom Field Option exists and is visible by the calling user.
Example
{"self":"http://localhost:8090/jira/rest/api/2.0/customFieldOption/3","value":"Blue","disabled":false,"id":3}
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"},"disabled":{"type":"boolean"},"id":{"type":"integer"},"childrenIds":{"type":"array","items":{"type":"integer"}}},"additionalProperties":false}
- Status
404Returned if the Custom Field Option does not exist, or is not visible to the calling user.
api/2/customFields
Get custom fieldsGET /rest/api/2/customFields
Request
query parameters
parameter | type | description |
---|---|---|
startAt | long Default: 1 | |
maxResults | int Default: 50 | |
search | string | |
projectIds | string | |
screenIds | string | |
types | string | |
sortOrder | string | |
sortColumn | string | |
lastValueUpdate | long |
Responses
- Status
200 - application/json
Example
{"id":"customfield_10000","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/page-of-custom-field#","title":"Page of Custom Field","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":"Custom Field","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"},"searcherKey":{"type":"string"},"projectIds":{"type":"array","items":{"type":"integer"}},"issueTypeIds":{"type":"array","items":{"type":"string"}},"self":{"type":"string","format":"uri"},"numericId":{"type":"integer"},"isLocked":{"type":"boolean"},"isManaged":{"type":"boolean"},"isAllProjects":{"type":"boolean"},"isTrusted":{"type":"boolean"},"projectsCount":{"type":"integer"},"screensCount":{"type":"integer"},"lastValueUpdate":{"type":"string"},"issuesWithValue":{"type":"integer"}},"additionalProperties":false,"required":["isLocked","isManaged","isAllProjects","isTrusted","projectsCount","screensCount"]}}},"additionalProperties":false,"required":["maxResults","startAt"]}
Bulk delete custom fieldsDELETE /rest/api/2/customFields
Request
query parameters
parameter | type | description |
---|---|---|
ids | string |
Responses
- Status
200 - application/jsonReturned if at least one custom field was deleted
Example
{"message":"Custom fields bulk delete operation finished.","deletedCustomFields":["customfield_10000"],"notDeletedCustomFields":{"customfield_10001":"Validation for custom field deletion failed."}}
- Status
400Returned if no fields were removed
- Status
423Returned if could not obtain a cluster lock
- Status
503Returned if license or feature flag check failed
Get custom field options
experimentalGET /rest/api/2/customFields/{customFieldId}/options
Returns custom field's options defined in a given context composed of projects and issue types.
If the projects and issue types match more than one context or the context for such a combination does not exist then no options are returned.
Request
query parameters
parameter | type | description |
---|---|---|
projectIds | string | a list of projects in a context. |
issueTypeIds | string | a list of issue types in a context. |
query | string Default: | a string used to filter options. An option matches the query if any word in option's name starts with the given query. |
maxResults | int Default: 100 | a limit of results. |
page | int Default: 1 | the page of options to return. |
Responses
- Status
200 - application/jsonReturned if a custom field with the given {@code customFieldId} exists and user has permission to it.
Example
{"options":[{"self":"http://localhost:8090/jira/rest/api/2.0/customFieldOption/3","value":"Blue","disabled":false,"id":3}],"total":1}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/custom-field-options#","title":"Custom Field Options","type":"object","properties":{"options":{"type":"array","items":{"title":"Custom Field Option","type":"object","properties":{"self":{"type":"string","format":"uri"},"value":{"type":"string"},"disabled":{"type":"boolean"},"id":{"type":"integer"},"childrenIds":{"type":"array","items":{"type":"integer"}}},"additionalProperties":false}},"total":{"type":"integer"}},"additionalProperties":false}
- Status
404Returned if a custom field with the given {@code customFieldId} does not exist or the user does not have permission to view it.
api/2/dashboard
ListGET /rest/api/2/dashboard
Returns a list of all dashboards, optionally filtering them.
Request
query parameters
parameter | type | description |
---|---|---|
filter | string | an optional filter that is applied to the list of dashboards. Valid values include
|
startAt | int | the index of the first dashboard to return (0-based). must be 0 or a multiple of
|
maxResults | int | a hint as to the maximum number of dashboards to return in each call. Note that the
Jira server reserves the right to impose a |
Responses
- Status
200Returns a list of dashboards.
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"}]}
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}
Get dashboardGET /rest/api/2/dashboard/{id}
Returns a single dashboard.
Responses
- Status
200Returns a single dashboard.
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"}
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
404Returned 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
Get properties keysGET /rest/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/jsonReturned if the dashboard item was found.
Example
{"keys":[{"self":"http://www.example.com/jira/rest/api/2/issue/EX-2/properties/issue.support","key":"issue.support"}]}
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
400Returned if the dashboard item id is invalid.
- Status
404Returned if the dashboard item with given id does not exist or user does not have permissions to view it.
Delete propertyDELETE /rest/api/2/dashboard/{dashboardId}/items/{itemId}/properties/{propertyKey}
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
400Returned if the dashboard item id is invalid.
- Status
204Returned if the dashboard item property was removed successfully.
- Status
403Returned if the calling user does not have permission to edit the dashboard item.
- Status
404Returned if the dashboard item with given id does not exist or user does not have permissions to view it.
Set propertyPUT /rest/api/2/dashboard/{dashboardId}/items/{itemId}/properties/{propertyKey}
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
200Returned if the dashboard item property is successfully updated.
- Status
201Returned if the dashboard item property is successfully created.
- Status
400Returned if the dashboard item id is invalid.
- Status
403Returned if the calling user does not have permission to administer the dashboard item.
- Status
404Returned if the dashboard item with given id does not exist or user does not have permissions to view it.
Get propertyGET /rest/api/2/dashboard/{dashboardId}/items/{itemId}/properties/{propertyKey}
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/jsonReturned if the dashboard item property was found.
Example
{"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/entity-property#","title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}
- Status
400Returned if the dashboard item id is invalid.
- Status
404Returned if the dashboard item with given id does not exist or user does not have permissions to view it.
api/2/email-templates
Upload email templatesPOST /rest/api/2/email-templates
Extracts given zip file to temporary templates folder. If the folder already exists it will replace it's content
Request
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/input-stream#","title":"Input Stream","type":"object"}
Responses
- Status - application/json
Download email templatesGET /rest/api/2/email-templates
Creates a zip file containing email templates at local home and returns the file.
Responses
- Status - application/zip
Apply email templatesPOST /rest/api/2/email-templates/apply
Replaces the current email templates pack with previously uploaded one, if exists.
Responses
- Status - application/json
Revert email templates to defaultPOST /rest/api/2/email-templates/revert
Replaces the current email templates pack with default templates, which are copied over from Jira binaries.
Responses
- Status - application/json
Get email typesGET /rest/api/2/email-templates/types
Returns a list of root templates mapped with Event Types. The list can be used to decide which test emails to send.
Responses
- Status - application/json
api/2/field
Create custom fieldPOST /rest/api/2/field
Creates a custom field using a definition (object encapsulating custom field data)
Request
Example
{"id":"customfield_10000","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":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"},"searcherKey":{"type":"string"},"projectIds":{"type":"array","items":{"type":"integer"}},"issueTypeIds":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}
Responses
- Status
201Returned if custom field was created.
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}}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/field#","title":"Field","type":"object","properties":{"id":{"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
400Returned if the input is invalid (e.g. invalid values).
- Status
500Returned if exception occured during custom field creation.
Get fieldsGET /rest/api/2/field
Returns a list of all fields, both System and Custom
Responses
- Status
200 - application/jsonContains a full representation of all visible fields in JSON.
Example
[{"id":"description","name":"Description","custom":false,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["description"],"schema":{"type":"string","system":"description"}},{"id":"summary","name":"Summary","custom":false,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["summary"],"schema":{"type":"string","system":"summary"}}]
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"},"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
401Returned if user is not logged-in and don't have access to any project
api/2/filter
Resource for searches.
Create filterPOST /rest/api/2/filter
Creates a new filter, and returns newly created filter. Currently sets permissions just using the users default sharing permissions
Request
query parameters
parameter | type | description |
---|---|---|
expand | string | the parameters to expand |
Example
{"name":"All Open Bugs","description":"Lists all open bugs","jql":"type = Bug and resolution is empty","favourite":true,"editable":false}
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"user":{"$ref":"#/definitions/user"},"view":{"type":"boolean"},"edit":{"type":"boolean"}},"additionalProperties":false,"required":["view","edit"]}},"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"]},"editable":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["favourite","editable"]}
Responses
- Status
200 - application/jsonReturns a JSON representation of a filter
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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"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":[],"editable":false,"subscriptions":{"size":0,"items":[],"max-results":1000,"start-index":0,"end-index":0}}
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"user":{"$ref":"#/definitions/user"},"view":{"type":"boolean"},"edit":{"type":"boolean"}},"additionalProperties":false,"required":["view","edit"]}},"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"]},"editable":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["favourite","editable"]}
- Status
400Returned if the input is invalid (e.g. filter name was not provided).
Edit filterPUT /rest/api/2/filter/{id}
Updates an existing filter, and returns its new value.
The following properties of a filter can be updated: 'jql', 'name', 'description'. Additionally, administrators can also update the 'owner' field. To get, set or unset 'favourite', use rest/api/1.0/filters/{id}/favourite with GET, PUT and DELETE methods instead.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string | the parameters to expand |
Example
{"name":"All Open Bugs","description":"Lists all open bugs","jql":"type = Bug and resolution is empty","favourite":true,"editable":false}
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"user":{"$ref":"#/definitions/user"},"view":{"type":"boolean"},"edit":{"type":"boolean"}},"additionalProperties":false,"required":["view","edit"]}},"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"]},"editable":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["favourite","editable"]}
Responses
- Status
200 - application/jsonReturns a JSON representation of a filter
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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"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":[],"editable":false,"subscriptions":{"size":0,"items":[],"max-results":1000,"start-index":0,"end-index":0}}
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"user":{"$ref":"#/definitions/user"},"view":{"type":"boolean"},"edit":{"type":"boolean"}},"additionalProperties":false,"required":["view","edit"]}},"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"]},"editable":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["favourite","editable"]}
- Status
400Returned if there is a problem updating up the filter of the given id
Delete filterDELETE /rest/api/2/filter/{id}
Delete a filter.
Responses
- Status
400Returned if an error occurs.
- Status
401Returned if the calling user is not authenticated.
- Status
204Returned if the filter was removed successfully.
Get filterGET /rest/api/2/filter/{id}
Returns a filter given an id
Request
query parameters
parameter | type | description |
---|---|---|
expand | string | the parameters to expand |
Responses
- Status
200 - application/jsonReturns a JSON representation of a filter
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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"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":[],"editable":false,"subscriptions":{"size":0,"items":[],"max-results":1000,"start-index":0,"end-index":0}}
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"user":{"$ref":"#/definitions/user"},"view":{"type":"boolean"},"edit":{"type":"boolean"}},"additionalProperties":false,"required":["view","edit"]}},"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"]},"editable":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["favourite","editable"]}
- Status
400Returned if there is a problem looking up the filter given the id
Default columnsGET /rest/api/2/filter/{id}/columns
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/jsonReturns 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
500Returned if an error occurs while retrieving the column configuration.
- Status
404Returned if the filter does not have any columns.
Set columnsPUT /rest/api/2/filter/{id}/columns
Sets the default columns for the given filter.
Request
Responses
- Status
200Returned when the columns are saved successfully
- Status
500Returned if an error occurs while retrieving the column configuration.
Reset columnsDELETE /rest/api/2/filter/{id}/columns
Resets the columns for the given filter such that the filter no longer has its own column config.
Responses
- Status
500Returned if an error occurs while retrieving the column configuration.
- Status
204Returned when the columns are reset/removed successfully
Get share permissionsGET /rest/api/2/filter/{id}/permission
Returns all share permissions of the given filter.
Responses
- Status
200 - application/jsonReturned if successful.
Example
[{"id":10000,"type":"global","view":true,"edit":false},{"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"}},"view":true,"edit":false},{"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"}]},"view":true,"edit":false},{"id":10010,"type":"group","group":{"name":"jira-administrators","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-administrators"},"view":true,"edit":false}]
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"user":{"$ref":"#/definitions/user"},"view":{"type":"boolean"},"edit":{"type":"boolean"}},"additionalProperties":false,"required":["view","edit"]},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}
- Status
401Returned if user is not logged in.
- Status
404Returned when filter with given id does not exist or when the user does not have permissions to view the filter.
Add share permissionPOST /rest/api/2/filter/{id}/permission
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","view":true,"edit":false},{"type":"user","userKey":"userKey","view":true,"edit":true}]
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"},"userKey":{"type":"string"},"view":{"type":"boolean"},"edit":{"type":"boolean"}},"additionalProperties":false,"required":["view","edit"]}
Responses
- Status
201 - application/jsonReturned if successful.
Example
[{"id":10000,"type":"global","view":true,"edit":false},{"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"}},"view":true,"edit":false},{"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"}]},"view":true,"edit":false},{"id":10010,"type":"group","group":{"name":"jira-administrators","self":"http://www.example.com/jira/rest/api/2/group?groupname=jira-administrators"},"view":true,"edit":false}]
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"user":{"$ref":"#/definitions/user"},"view":{"type":"boolean"},"edit":{"type":"boolean"}},"additionalProperties":false,"required":["view","edit"]},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}
- Status
400Returned 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
401Returned if user is not logged in.
- Status
404Returned when filter with given id does not exist or when the user does not have permissions to view the filter.
Get share permissionGET /rest/api/2/filter/{id}/permission/{permissionId}
Returns a single share permission of the given filter.
Responses
- Status
200 - application/jsonReturned if successful.
Example
{"id":10000,"type":"global","view":true,"edit":false}
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"user":{"$ref":"#/definitions/user"},"view":{"type":"boolean"},"edit":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false,"required":["view","edit"]}
- Status
401Returned if user is not logged in.
- Status
404Returned when filter or permission with given id does not exist or when the user does not have permissions to view the filter.
Delete share permissionDELETE /rest/api/2/filter/{id}/permission/{permission-id}
Removes a share permissions from the given filter.
Responses
- Status 200 - application/json
- Status
204Returned if successful.
- Status
404Returned when filter or permission with given id does not exist or when the user does not have permissions to view the filter.
Get default share scopeGET /rest/api/2/filter/defaultShareScope
Returns the default share scope of the logged-in user.
Responses
- Status
200 - application/jsonReturns the default share scope of the logged-in user.
Example
{"scope":"AUTHENTICATED"}
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
400Returned if there is a problem looking up preferences for the logged-in user
Set default share scopePUT /rest/api/2/filter/defaultShareScope
Sets the default share scope of the logged-in user.
Available values are: AUTHENTICATED (for sharing with all logged-in users) and PRIVATE (for no shares).
Request
Example
{"scope":"AUTHENTICATED"}
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/jsonReturns the new default share scope of the logged-in user.
Example
{"scope":"AUTHENTICATED"}
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
400Returned if there is a problem setting the preferences for the logged-in user
Get favourite filtersGET /rest/api/2/filter/favourite
Returns the favourite filters of the logged-in user.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string | the parameters to expand |
Responses
- Status
200 - application/jsonReturns a JSON representation of a list of filters
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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"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":[],"editable":false,"subscriptions":{"size":0,"items":[],"max-results":1000,"start-index":0,"end-index":0}},{"self":"http://www.example.com/jira/rest/api/2/filter/10010","id":"10010","name":"My issues","description":"Issues assigned to me","owner":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"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","view":true,"edit":false},{"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"}},"view":true,"edit":false}],"editable":false,"subscriptions":{"size":0,"items":[],"max-results":1000,"start-index":0,"end-index":0}},{"name":"All Open Bugs","description":"Lists all open bugs","jql":"type = Bug and resolution is empty","favourite":true,"sharePermissions":[],"editable":true}]
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"user":{"$ref":"#/definitions/user"},"view":{"type":"boolean"},"edit":{"type":"boolean"}},"additionalProperties":false,"required":["view","edit"]}},"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"]},"editable":{"type":"boolean"}},"additionalProperties":false,"required":["favourite","editable"]},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}
api/2/group
Create groupPOST /rest/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/jsonReturns full representation of a Jira group in JSON format.
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"}
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"},"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
400Returned if user requested an empty group name or group already exists
- Status
401Returned if the current user is not authenticated.
- Status
403Returned if the current user does not have administrator permissions.
Get group
deprecatedGET /rest/api/2/group
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
parameter | type | description |
---|---|---|
groupname | string | A name of requested group. |
expand | string | List of fields to expand. Currently only available expand is "users". |
Responses
- Status - application/json
Remove groupDELETE /rest/api/2/group
Deletes a group by given group parameter.
Returns no content
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | (mandatory) The name of the group to delete. |
swapGroup | string | 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/jsonReturned if the group was deleted.
- Status
400Returned if user requested an group that does not exist.
- Status
401Returned if the current user is not authenticated.
- Status
403Returned if the current user does not have administrator permissions.
- Status
404Returned if the requested group was not found.
Get users from groupGET /rest/api/2/group/member
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
parameter | type | description |
---|---|---|
groupname | string | a name of the group for which members will be returned. |
includeInactiveUsers | boolean Default: false | inactive users will be included in the response if set to true. |
startAt | long Default: 0 | the index of the first user in group to return (0 based). |
maxResults | int Default: 50 | the maximum number of users to return (max 50). |
Responses
- Status
200 - application/jsonPaginated list of users in the group.
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","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"}]}
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"},"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
400Returned if the name of the provided group is empty
- Status
401Returned if the user is not logged in.
- Status
403Returned if the calling user is not admin or sysadmin
- Status
404Returned if the specified group does not exist
Add user to groupPOST /rest/api/2/group/user
Adds given user to a group.
Returns the current state of the group.
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | 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/jsonReturns 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"},"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
400Returned if user requested an empty group name or the user already belongs to the group.
- Status
401Returned if the current user is not authenticated.
- Status
403Returned if the current user does not have administrator permissions.
- Status
404Returned if the requested group was not found or requested user was not found.
Remove user from groupDELETE /rest/api/2/group/user
Removes given user from a group.
Returns no content
Request
query parameters
parameter | type | description |
---|---|---|
groupname | string | A name of requested group. |
username | string | User to remove from a group |
Responses
- Status
200 - application/jsonIf the user was removed from the group.
- Status
400Returned if user requested an empty group name
- Status
401Returned if the current user is not authenticated.
- Status
403Returned if the current user does not have administrator permissions.
- Status
404Returned 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
Find groupsGET /rest/api/2/groups/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
parameter | type | description |
---|---|---|
query | string | a String to match groups agains |
exclude | string | |
maxResults | int | |
userName | string |
Responses
- Status
200 - application/jsonReturned even if no groups match the given substring
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"}]}
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
Find users and groupsGET /rest/api/2/groupuserpicker
Returns a list of users and groups matching query with highlighting. This resource cannot be accessed anonymously.
Request
query parameters
parameter | type | description |
---|---|---|
query | string | A string used to search username, Name or e-mail address |
maxResults | int | the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated. |
showAvatar | boolean | |
fieldId | string | The custom field id, if this request comes from a custom field, such as a user picker. Optional. |
projectId | string | The list of project ids to further restrict the search This parameter can occur multiple times to pass in multiple project ids. Comma separated value is not supported. This parameter is only used when fieldId is present. |
issueTypeId | string | The list of issue type ids to further restrict the search. This parameter can occur multiple times to pass in multiple issue type ids. Comma separated value is not supported. Special values such as -1 (all standard issue types), -2 (all subtask issue types) are supported. This parameter is only used when fieldId is present. |
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}
- Status
403Returned if the user does not have permission to view users and groups
api/2/index/summary
REST resource for index summary
Get index summary
experimentalGET /rest/api/2/index/summary
Summarizes index condition of current node.
Returned data consists of:nodeId
- Node identifier.reportTime
- Time of this report creation.issueIndex
- Summary of issue index status.replicationQueues
- Map of index replication queues, where keys represent nodes from which replication operations came from.
issueIndex
can contain:
indexReadable
- Iffalse
the end point failed to read data from issue index (check Jira logs for detailed stack trace), otherwisetrue
. Whenfalse
other fields ofissueIndex
can be not visible.countInDatabase
- Count of issues found in database.countInIndex
- Count of issues found while querying index.lastUpdatedInDatabase
- Time of last update of issue found in database.lastUpdatedInIndex
- Time of last update of issue found while querying index.
replicationQueues
's map values can contain:
lastConsumedOperation
- Last executed index replication operation by current node from sending node's queue.lastConsumedOperation.id
- Identifier of the operation.lastConsumedOperation.replicationTime
- Time when the operation was sent to other nodes.lastOperationInQueue
- Last index replication operation in sending node's queue.lastOperationInQueue.id
- Identifier of the operation.lastOperationInQueue.replicationTime
- Time when the operation was sent to other nodes.queueSize
- Number of operations in queue from sending node to current node.
Responses
- Status
200 - application/jsonReturns object with data about condition of Jira node's index
Example
{"nodeId":"node1","reportTime":"2017-07-08T00:46:16.000+0000","issueIndex":{"indexReadable":true,"countInDatabase":12072,"countInIndex":10072,"countInArchive":2000,"lastUpdatedInDatabase":"2017-07-08T00:46:16.000+0000","lastUpdatedInIndex":"2017-07-07T23:48:53.000+0000"},"replicationQueues":{"node2":{"lastConsumedOperation":{"id":16822,"replicationTime":"2017-07-07T23:10:56.000+0000"},"lastOperationInQueue":{"id":16822,"replicationTime":"2017-07-07T23:10:56.000+0000"},"queueSize":0},"node3":{"lastConsumedOperation":{"id":16522},"lastOperationInQueue":{"id":16522},"queueSize":0}}}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/index-summary#","title":"Index Summary","type":"object","properties":{"nodeId":{"type":"string"},"reportTime":{"type":"object"},"issueIndex":{"title":"Issue Index Summary","type":"object","properties":{"indexReadable":{"type":"boolean"},"countInDatabase":{"type":"integer"},"countInIndex":{"type":"integer"},"countInArchive":{"type":"integer"},"lastUpdatedInDatabase":{"type":"object"},"lastUpdatedInIndex":{"type":"object"}},"additionalProperties":false},"replicationQueues":{"type":"object","patternProperties":{".+":{"title":"Index Replication Queue Summary","type":"object","properties":{"lastConsumedOperation":{"$ref":"#/definitions/index-replication-queue-entry"},"lastOperationInQueue":{"$ref":"#/definitions/index-replication-queue-entry"},"queueSize":{"type":"integer"}},"additionalProperties":false}},"additionalProperties":false}},"definitions":{"index-replication-queue-entry":{"title":"Index Replication Queue Entry","type":"object","properties":{"id":{"type":"integer"},"replicationTime":{"type":"object"}},"additionalProperties":false}},"additionalProperties":false}
- Status
403Returned when current authenticated user has no admin permission
api/2/index-snapshot
REST resource for index snapshot operations.
Create index snapshotPOST /rest/api/2/index-snapshot
Tries to start taking an index snapshot if no other snapshot creation process is in progress. Performs a cleanup of index snapshots directory so only a limited number of most recent snapshots are persisted. If another snapshot creation process is in progress, returns 409 without waiting for the other process to complete.
Only System Administrator can request creation of snapshot. There is no guarantee as to the time after which the snapshot will be available.
Responses
- Status
202 - application/jsonReturns the absolute path which index snapshot will be placed in, after it's created. To start taking the index snapshot user must be a System Administrator.
Example
{"futureAbsolutePath":"/home/atlassian/shared-home/export/indexsnapshots/IndexSnapshot_2021-Jul-21--2142-34-601.tar.sz"}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/index-snapshot-promise#","title":"Index Snapshot Promise","type":"object","properties":{"futureAbsolutePath":{"type":"string"}},"additionalProperties":false}
- Status
401Returned if the caller doesn't have sufficient privileges.
- Status
409Returned if snapshot creation is already in progress.
List index snapshotGET /rest/api/2/index-snapshot
Lists available index snapshots absolute paths with timestamps.
Only System Administrator can request listing index snapshots.
Responses
- Status
200 - application/jsonReturns the list consisting of absolute paths to currently available index snapshots.
Example
["/home/atlassian/shared-home/export/indexsnapshots/IndexSnapshot_2021-Jul-21--2142-34-601.tar.sz","/home/atlassian/shared-home/export/indexsnapshots/IndexSnapshot_2021-Jul-22--2111-41-632.tar.sz"]
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/list-of-index-snapshot#","title":"List of Index Snapshot","type":"array","items":{"title":"Index Snapshot","type":"object","properties":{"absolutePath":{"type":"string"},"timestamp":{"type":"integer"}},"additionalProperties":false,"required":["timestamp"]}}
- Status
401Returned if the caller doesn't have sufficient privileges.
Is index snapshot runningGET /rest/api/2/index-snapshot/isRunning
Answers true if index snapshot creation is currently running.
Only System Administrator can request current snapshot creation status.
Responses
- Status
200Returns status of current snapshot creation.
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/index-snapshot-status#","title":"Index Snapshot Status","type":"object","properties":{"running":{"type":"boolean"}},"additionalProperties":false,"required":["running"]}
- Status
401Returned if the caller doesn't have sufficient privileges.
api/2/issue
Create issuePOST /rest/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. - The
updateHistory
param adds the project that this issue is created in, to the current user's project history, if set to true (by default, the project history is not updated). - You can view the project history in the Jira application, via the Projects dropdown.
Request
query parameters
parameter | type | description |
---|---|---|
updateHistory | boolean Default: false | if true then the user's project history is updated |
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"},"description":{"type":"string"},"opsbarSequence":{"type":"integer"},"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},"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"},"fieldId":{"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/jsonReturns a link to the created issue.
Example
{"id":"10000","key":"TST-24","self":"http://www.example.com/jira/rest/api/2/issue/10000"}
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
400Returned if the input is invalid (e.g. missing required fields, invalid field values, and so forth).
Example
{"errorMessages":[],"errors":{"priority":"Could not find valid 'id' or 'name' in priority object."}}
Create issuesPOST /rest/api/2/issue/bulk
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(boolean, 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"},"description":{"type":"string"},"opsbarSequence":{"type":"integer"},"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},"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"},"fieldId":{"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/jsonReturns a link to the created issues.
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":[]}
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
400Returned if the input is invalid (e.g. missing required fields, invalid field values, and so forth).
Example
{"status":400,"elementErrors":{"errorMessages":[],"errors":{"priority":"Could not find valid 'id' or 'name' in priority object."}},"failedElementNumber":3}
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}
Get issueGET /rest/api/2/issue/{issueIdOrKey}
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 fieldssummary,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 {@code properties} param is similar to {@code fields} and specifies a comma-separated list of issue properties to include. Unlike {@code fields}, properties are not included by default. To include them all send {@code ?properties=*all}. You can also include only specified properties or exclude some properties with a minus (-) sign.
- {@code *all} - include all properties
- {@code *all, -prop1} - include all properties except {@code prop1}
- {@code prop1, prop1} - include {@code prop1} and {@code prop2} properties
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 formatnames
- display name of each fieldschema
- schema for each field which describes a type of the fieldtransitions
- all possible transitions for the given issueoperations
- all possibles operations which may be applied on issueeditmeta
- information about how each field may be edited. It contains field's schema as well.changelog
- history of all changes of the given issueversionedRepresentations
- 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 includingversionedRepresentations
"fields" field become hidden.
Request
query parameters
parameter | type | description |
---|---|---|
fields | string | the list of fields to return for the issue. By default, all fields are returned. |
expand | string | |
properties | string | the list of properties to return for the issue. By default no properties are returned. |
updateHistory | boolean |
Responses
- Status
200 - application/jsonReturns a full representation of a Jira issue in JSON format.
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","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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"created":"2024-06-26T10:20:31.317+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":"2024-06-26T10:20:31.144+0000","updated":"2024-06-26T10:20:31.144+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":"2024-06-26T10:20:31.368+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2024-06-26T10:20:31.368+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}},"names":{"watcher":"watcher","attachment":"attachment","sub-tasks":"sub-tasks","description":"description","project":"project","comment":"comment","issuelinks":"issuelinks","worklog":"worklog","updated":"updated","timetracking":"timetracking"},"schema":{}}
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"},"fields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"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"},"description":{"type":"string"},"opsbarSequence":{"type":"integer"},"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},"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"},"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"}},"definitions":{"field-meta":{"title":"Field Meta","type":"object","properties":{"required":{"type":"boolean"},"schema":{"$ref":"#/definitions/json-type"},"name":{"type":"string"},"fieldId":{"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}
- Status
404Returned if the requested issue is not found, or the user does not have permission to view it.
Delete issueDELETE /rest/api/2/issue/{issueIdOrKey}
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
parameter | type | description |
---|---|---|
deleteSubtasks | string | a String of true or false indicating that any subtasks should also be deleted. If the issue has no subtasks this parameter is ignored. If the issue has subtasks and this parameter is missing or false, then the issue will not be deleted and an error will be returned. |
Responses
- Status
400Returned if an error occurs.
- Status
401Returned if the calling user is not authenticated.
- Status
204Returned if the issue was removed successfully.
- Status
403Returned if the calling user does not have permission to delete the issue.
- Status
404Returned if the issue does not exist.
Edit issuePUT /rest/api/2/issue/{issueIdOrKey}
Edits an issue from a JSON representation.
The issue can either be updated by setting explicit the field value(s) or by using an operation to change the field value. The fields that can be updated, in either the fields parameter or the update parameter, can be determined using the /rest/api/2/issue/{issueIdOrKey}/editmeta resource.If a field is not configured to appear on the edit screen, then it will not be in the editmeta, and a field validation error will occur if it is submitted. Specifying a "field_id": field_value in the "fields" is a shorthand for a "set" operation in the "update" section.
Field should appear either in "fields" or "update", not in both.
Request
query parameters
parameter | type | description |
---|---|---|
notifyUsers | boolean 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. |
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"},"description":{"type":"string"},"opsbarSequence":{"type":"integer"},"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},"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"},"fieldId":{"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
400Returned if the requested issue update failed.
- Status
204Returned if it updated the issue successfully.
- Status
403Returned if the user doesn't have permissions to disable users notification.
Archive issuePUT /rest/api/2/issue/{issueIdOrKey}/archive
Archives an issue.
Request
query parameters
parameter | type | description |
---|---|---|
notifyUsers | boolean 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. |
Responses
- Status
401Returned if the user is not logged in.
- Status
204 - application/jsonReturned if the issue is successfully archived.
- Status
403Returned if the currently authenticated user does not have permission to archive the issue or doesn't have DC license or issue is already archived.
- Status
404Returned if the issue does not exist.
AssignPUT /rest/api/2/issue/{issueIdOrKey}/assignee
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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"lastLoginTime":{"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"}},"additionalProperties":false}}},"additionalProperties":false,"required":["size"]}},"additionalProperties":false,"required":["active"]}
Responses
- Status
400Returned if there is a problem with the received user representation.
- Status
401Returned if the calling user does not have permission to assign the issue.
- Status
204Returned if the issue is successfully assigned.
- Status
404Returned if either the issue or the user does not exist.
Get commentsGET /rest/api/2/issue/{issueIdOrKey}/comment
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
parameter | type | description |
---|---|---|
startAt | long | the page offset, if not specified then defaults to 0 |
maxResults | int | how many results on the page should be included. Defaults to 50. |
orderBy | string | ordering of the results. |
expand | string | optional flags: renderedBody (provides body rendered in HTML) |
Responses
- Status
200 - application/jsonreturns a collection of comments associated with the issue, with count and pagination information.
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":"2024-06-26T10:20:31.144+0000","updated":"2024-06-26T10:20:31.144+0000","visibility":{"type":"role","value":"Administrators"}}]}
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"},"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
404Returned if the issue with the given id/key does not exist or if the currently authenticated user does not have permission to view it.
Add commentPOST /rest/api/2/issue/{issueIdOrKey}/comment
Adds a new comment to an issue.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string | 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"},"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
201Returned if add was successful
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":"2024-06-26T10:20:31.144+0000","updated":"2024-06-26T10:20:31.144+0000","visibility":{"type":"role","value":"Administrators"}}
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"},"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
400Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
Update commentPUT /rest/api/2/issue/{issueIdOrKey}/comment/{id}
Updates an existing comment using its JSON representation.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string | 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"},"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
200Returned if update was successful
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":"2024-06-26T10:20:31.144+0000","updated":"2024-06-26T10:20:31.144+0000","visibility":{"type":"role","value":"Administrators"}}
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"},"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
400Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
Delete commentDELETE /rest/api/2/issue/{issueIdOrKey}/comment/{id}
Deletes an existing comment .
Responses
- Status
400Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
- Status
204Returned if delete was successful
Get commentGET /rest/api/2/issue/{issueIdOrKey}/comment/{id}
Returns a single comment.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string | optional flags: renderedBody (provides body rendered in HTML) |
Responses
- Status
200 - application/jsonReturns a full representation of a Jira comment in JSON format.
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":"2024-06-26T10:20:31.144+0000","updated":"2024-06-26T10:20:31.144+0000","visibility":{"type":"role","value":"Administrators"}}
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"},"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
404Returned if the requested comment is not found, or the user does not have permission to view it.
Set pin commentPUT /rest/api/2/issue/{issueIdOrKey}/comment/{id}/pin
Request
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/boolean#","title":"boolean","type":"boolean"}
Responses
- Status - application/json
Get edit issue metaGET /rest/api/2/issue/{issueIdOrKey}/editmeta
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.Responses
- Status
200 - application/jsonReturns a response containing a Map of FieldBeans for fields editable by the current user.
Example
{"fields":{"summary":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My Multi Select","fieldId":"customfield_10000","operations":["set","add"],"allowedValues":["red","blue"]}}}
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"},"fieldId":{"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
404Returned if the requested issue is not found or the user does not have permission to view it.
NotifyPOST /rest/api/2/issue/{issueIdOrKey}/notify
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"},"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
400Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
- Status
204Returned if adding to the mail queue was successful
- Status
403Returned is outgoing emails are disabled OR no SMTP server is defined.
Get pinned commentsGET /rest/api/2/issue/{issueIdOrKey}/pinned-comments
Returns all pinned to the issue comments.
Responses
- Status - application/json
Get remote issue linksGET /rest/api/2/issue/{issueIdOrKey}/remotelink
A REST sub-resource representing the remote issue links on the issue.
Request
query parameters
parameter | type | description |
---|---|---|
globalId | string | The id of the remote issue link to be returned. If null (not provided) all remote links for the issue are returned. For a fullexplanation of Issue Link fields please refer to https://developer.atlassian.com/display/JIRADEV/Fields+in+Remote+Issue+Links |
Responses
- Status
200 - application/jsonInformation on the remote issue links for the current issue.
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"}}}}]
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
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to view the remote issue links, or if issue linking is disabled.
- Status
404Returned if the issue or remote issue link do not exist.
Create or update remote issue linkPOST /rest/api/2/issue/{issueIdOrKey}/remotelink
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/jsonReturns a link to the created/updated remote issue link.
Example
{"id":10000,"self":"http://www.example.com/jira/rest/api/issue/MKY-1/remotelink/10000"}
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
400Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
Example
{"errorMessages":[],"errors":{"title":"'title' is required."}}
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to create/update the remote issue link, or if issue linking is disabled.
Delete remote issue link by global idDELETE /rest/api/2/issue/{issueIdOrKey}/remotelink
Delete the remote issue link with the given global id on the issue.
Request
query parameters
parameter | type | description |
---|---|---|
globalId | string | the global id of the remote issue link |
Responses
- Status
401Returned if the calling user is not authenticated.
- Status
204Returned if the remote issue link was removed successfully.
- Status
403Returned if the calling user does not have permission to delete the remote issue link, or if issue linking is disabled.
- Status
404Returned if the issue or remote issue link do not exist.
Get remote issue link by idGET /rest/api/2/issue/{issueIdOrKey}/remotelink/{linkId}
Get the remote issue link with the given id on the issue.
Responses
- Status
200 - application/jsonInformation on the remote issue link with the given id.
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"}}}}
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
400Returned 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
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to view the remote issue link, or if issue linking is disabled.
- Status
404Returned if the issue or remote issue link do not exist.
Update remote issue linkPUT /rest/api/2/issue/{issueIdOrKey}/remotelink/{linkId}
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
400Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
Example
{"errorMessages":[],"errors":{"title":"'title' is required."}}
- Status
401Returned if the calling user is not authenticated.
- Status
204Returned if the remote issue link was updated successfully.
- Status
403Returned if the calling user does not have permission to update the remote issue link, or if issue linking is disabled.
Delete remote issue link by idDELETE /rest/api/2/issue/{issueIdOrKey}/remotelink/{linkId}
Delete the remote issue link with the given id on the issue.
Responses
- Status
401Returned if the calling user is not authenticated.
- Status
204Returned if the remote issue link was removed successfully.
- Status
403Returned if the calling user does not have permission to delete the remote issue link, or if issue linking is disabled.
- Status
404Returned if the issue or remote issue link do not exist.
Restore issuePUT /rest/api/2/issue/{issueIdOrKey}/restore
Restores an archived issue.
Request
query parameters
parameter | type | description |
---|---|---|
notifyUsers | boolean 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. |
Responses
- Status
401Returned if the user is not logged in.
- Status
204 - application/jsonReturned if the issue is successfully restored.
- Status
403Returned if the currently authenticated user does not have permission to restore the issue or doesn't have DC license or issue is not archived.
- Status
404Returned if the issue does not exist.
Do transitionPOST /rest/api/2/issue/{issueIdOrKey}/transitions
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.
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
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"},"description":{"type":"string"},"opsbarSequence":{"type":"integer"},"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},"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"},"fieldId":{"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
400If there is no transition specified.
- Status
500If transition ID is incorrect.
- Status
204Returned if the transition was successful.
- Status
404The issue does not exist or the user does not have permission to view it
Get transitionsGET /rest/api/2/issue/{issueIdOrKey}/transitions
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 ifexpand=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
parameter | type | description |
---|---|---|
transitionId | string |
Responses
- Status
200 - application/jsonReturns a full representation of the transitions possible for the specified issue and the fields required to perform the transition.
Example
{"expand":"transitions","transitions":[{"id":"2","name":"Close Issue","opsbarSequence":10,"to":{"self":"http://localhost:8090/jira/rest/api/2.0/status/10000","description":"The issue is currently being worked on.","iconUrl":"http://localhost:8090/jira/images/icons/progress.gif","name":"In Progress","id":"10000","statusCategory":{"self":"http://localhost:8090/jira/rest/api/2.0/statuscategory/1","id":1,"key":"in-flight","colorName":"yellow","name":"In Progress"}},"fields":{"summary":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My Multi Select","fieldId":"customfield_10000","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue","default value"]}}},{"id":"711","name":"QA Review","opsbarSequence":20,"to":{"self":"http://localhost:8090/jira/rest/api/2.0/status/5","description":"The issue is closed.","iconUrl":"http://localhost:8090/jira/images/icons/closed.gif","name":"Closed","id":"5","statusCategory":{"self":"http://localhost:8090/jira/rest/api/2.0/statuscategory/9","id":9,"key":"completed","colorName":"green"}},"fields":{"summary":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My Multi Select","fieldId":"customfield_10000","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue","default value"]},"colour":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My Multi Select","fieldId":"customfield_10000","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue","default value"]}}}]}
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"},"description":{"type":"string"},"opsbarSequence":{"type":"integer"},"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},"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"},"fieldId":{"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
404Returned if the requested issue is not found or the user does not have permission to view it.
Remove voteDELETE /rest/api/2/issue/{issueIdOrKey}/votes
Remove your vote from an issue. (i.e. "unvote")
Responses
- Status
204Nothing is returned on success.
- Status
404Returned 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.)
Add votePOST /rest/api/2/issue/{issueIdOrKey}/votes
Cast your vote in favour of an issue.
Responses
- Status
204Nothing is returned on success.
- Status
404Returned if the user cannot vote for any reason. (The user is the reporter, the user does not have permission to vote, voting is disabled in the instance, the issue does not exist, etc.)
Get votesGET /rest/api/2/issue/{issueIdOrKey}/votes
A REST sub-resource representing the voters on the issue.
Responses
- Status
200 - application/jsonInformation about voting on the current issue.
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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"}]}
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
404Returned if the user cannot view the issue in question or voting is disabled.
Get issue watchersGET /rest/api/2/issue/{issueIdOrKey}/watchers
Returns the list of watchers for the issue with the given key.
Responses
- Status
200 - application/jsonReturns the list of watchers for an issue.
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}]}
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"},"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
404Returned if the requested issue is not found, or the user does not have permission to view it.
Add watcherPOST /rest/api/2/issue/{issueIdOrKey}/watchers
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
400Returned if there is a problem with the received user representation.
- Status
401Returned if the calling user does not have permission to add the watcher to the issue's list of watchers.
- Status
204Returned if the watcher was added successfully.
- Status
404Returned if either the issue or the user does not exist.
Remove watcherDELETE /rest/api/2/issue/{issueIdOrKey}/watchers
Removes a user from an issue's watcher list.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | a String containing the name of the user to remove from the watcher list. Must not be null. |
Responses
- Status
400Returned if a user name query parameter is not supplied.
- Status
401Returned if the calling user does not have permission to remove the watcher from the issue's list of watchers.
- Status
204Returned if the watcher was removed successfully.
- Status
404Returned if either the issue does not exist.
Get issue worklogGET /rest/api/2/issue/{issueIdOrKey}/worklog
Returns all work logs for an issue.
Note: Work logs won't be returned if the Log work field is hidden for the project.
Responses
- Status
200 - application/jsonreturns a collection of worklogs associated with the issue, with count and pagination information.
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":"2024-06-26T10:20:31.368+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2024-06-26T10:20:31.368+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}]}
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"}},"additionalProperties":false}}},"definitions":{"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"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
404Returned if the issue with the given id/key does not exist or if the currently authenticated user does not have permission to view it.
Add worklogPOST /rest/api/2/issue/{issueIdOrKey}/worklog
Adds a new worklog entry to an issue.
Request
query parameters
parameter | type | description |
---|---|---|
adjustEstimate | string | (optional) allows you to provide specific instructions to update the remaining time estimate of the issue. Valid values are
|
newEstimate | string | (required when "new" is selected for adjustEstimate) the new value for the remaining estimate field. e.g. "2d" |
reduceBy | string | (required when "manual" is selected for adjustEstimate) the amount to reduce the remaining estimate by e.g. "2d" |
Example
{"comment":"I did some work here.","visibility":{"type":"group","value":"jira-developers"},"started":"2024-06-26T10:20:31.368+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"}},"definitions":{"user":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"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
201Returned 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"}},"definitions":{"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"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
400Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
- Status
403Returned if the calling user does not have permission to add the worklog
Get worklogGET /rest/api/2/issue/{issueIdOrKey}/worklog/{id}
Returns a specific worklog.
Note: The work log won't be returned if the Log work field is hidden for the project.
Responses
- Status
200 - application/jsonReturned 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.
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":"2024-06-26T10:20:31.368+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2024-06-26T10:20:31.368+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}
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"}},"definitions":{"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"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
404Returned if the work log with the given id does not exist or if the currently authenticated user does not have permission to view it.
Update worklogPUT /rest/api/2/issue/{issueIdOrKey}/worklog/{id}
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
parameter | type | description |
---|---|---|
adjustEstimate | string | (optional) allows you to provide specific instructions to update the remaining time estimate of the issue. Valid values are
|
newEstimate | string | (required when "new" is selected for adjustEstimate) the new value for the remaining estimate field. |
Example
{"comment":"I did some work here.","visibility":{"type":"group","value":"jira-developers"},"started":"2024-06-26T10:20:31.368+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"}},"definitions":{"user":{"title":"User","type":"object","properties":{"name":{"type":"string"},"key":{"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
200Returned if update was successful
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":"2024-06-26T10:20:31.368+0000","visibility":{"type":"group","value":"jira-developers"},"started":"2024-06-26T10:20:31.368+0000","timeSpent":"3h 20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}
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"}},"definitions":{"user":{"title":"User","type":"object","properties":{"self":{"type":"string"},"name":{"type":"string"},"key":{"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
400Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
- Status
403Returned if the calling user does not have permission to update the worklog
Delete worklogDELETE /rest/api/2/issue/{issueIdOrKey}/worklog/{id}
Deletes an existing worklog entry.
Request
query parameters
parameter | type | description |
---|---|---|
adjustEstimate | string | (optional) allows you to provide specific instructions to update the remaining time estimate of the issue. Valid values are
|
newEstimate | string | (required when "new" is selected for adjustEstimate) the new value for the remaining estimate field. e.g. "2d" |
increaseBy | string | (required when "manual" is selected for adjustEstimate) the amount to increase the remaining estimate by e.g. "2d" |
Responses
- Status
400Returned if the input is invalid (e.g. missing required fields, invalid values, and so forth).
- Status
204Returned if delete was successful
- Status
403Returned if the calling user does not have permission to delete the worklog
Archive issuesPOST /rest/api/2/issue/archive
Archives a list of issues.
Request
query parameters
parameter | type | description |
---|---|---|
notifyUsers | boolean Default: false | 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. |
Schema
{"type":"array","items":{"type":"string"}}
Responses
- Status
401Returned if the user is not logged in.
- Status
204 - text/plainReturned if the issue is successfully archived.
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/streaming-output#","title":"Streaming Output","type":"object"}
- Status
403Returned if the currently authenticated user does not have permission to archive the issue or doesn't have DC license or issue is already archived.
- Status
404Returned if the issue does not exist.
Get create issue meta project issue typesGET /rest/api/2/issue/createmeta/{projectIdOrKey}/issuetypes
Returns the metadata for issue types used for creating issues. Data will not be returned if the user does not have permission to create issues in that project.
Request
query parameters
parameter | type | description |
---|---|---|
startAt | long Default: 0 | the page offset, if not specified then defaults to 0 |
maxResults | int Default: 50 | how many results on the page should be included. Defaults to 50. |
Responses
- Status
200 - application/jsonReturns the metadata for issue types used for creating issues.
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/page-of-create-meta-issue-type#","title":"Page of Create Meta Issue Type","type":"object","properties":{"last":{"type":"boolean"},"size":{"type":"integer"},"start":{"type":"integer"},"total":{"type":"integer"},"values":{"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"},"fieldId":{"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,"required":["last","size","start"]}
- Status
400Returned if the user does not have permission to view the requested project or project doesn't exist.
Get create issue meta fieldsGET /rest/api/2/issue/createmeta/{projectIdOrKey}/issuetypes/{issueTypeId}
Returns the metadata for issue types used for creating issues. Data will not be returned if the user does not have permission to create issues in that project.
Request
query parameters
parameter | type | description |
---|---|---|
startAt | long Default: 0 | the page offset, if not specified then defaults to 0 |
maxResults | int Default: 50 | how many results on the page should be included. Defaults to 50. |
Responses
- Status
200 - application/jsonReturns the metadata for issue types used for creating issues.
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/page-of-field-meta#","title":"Page of Field Meta","type":"object","properties":{"last":{"type":"boolean"},"size":{"type":"integer"},"start":{"type":"integer"},"total":{"type":"integer"},"values":{"type":"array","items":{"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"},"fieldId":{"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,"required":["last","size","start"]}
- Status
400Returned if the user does not have permission to view the requested project or project doesn't exist.
Get issue picker resourceGET /rest/api/2/issue/picker
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
parameter | type | description |
---|---|---|
query | string | the query. |
currentJQL | string | the JQL in context of which the request is executed. Only issues which match this JQL query will be included in results. |
currentIssueKey | string | the key of the issue in context of which the request is executed. The issue which is in context will not be included in the auto-completion result, even if it matches the query. |
currentProjectId | string | the id of the project in context of which the request is executed. Suggested issues will be only from this project. |
showSubTasks | boolean | if set to false, subtasks will not be included in the list. |
showSubTaskParent | boolean | if set to false and request is executed in context of a subtask, the parent issue will not be included in the auto-completion result, even if it matches the query. |
Responses
- Status
200 - application/jsonReturns 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 attachmentPOST /rest/api/2/issue/{issueIdOrKey}/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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"created":"2024-06-26T10:20:31.317+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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"created":"2024-06-26T10:20:31.317+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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"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
403Returned if attachments is disabled or if you don't have permission to add attachments to this issue.
- Status
404Returned 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
Get properties keys
experimentalGET /rest/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/jsonReturned if the issue was found.
Example
{"keys":[{"self":"http://www.example.com/jira/rest/api/2/issue/EX-2/properties/issue.support","key":"issue.support"}]}
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
400Returned if the issue key or id is invalid.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to view the issue.
- Status
404Returned if the issue with given key or id does not exist or if the property with given key is not found.
Delete property
experimentalDELETE /rest/api/2/issue/{issueIdOrKey}/properties/{propertyKey}
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
400Returned if the issue key or id is invalid.
- Status
401Returned if the calling user is not authenticated.
- Status
204Returned if the issue property was removed successfully.
- Status
403Returned if the calling user does not have permission to edit the issue.
- Status
404Returned if the issue with given key or id does not exist or if the property with given key is not found.
Set property
experimentalPUT /rest/api/2/issue/{issueIdOrKey}/properties/{propertyKey}
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
200Returned if the issue property is successfully updated.
- Status
201Returned if the issue property is successfully created.
- Status
400Returned if the issue key or id is invalid.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to edit the issue.
- Status
404Returned if the issue with given key or id does not exist.
Get property
experimentalGET /rest/api/2/issue/{issueIdOrKey}/properties/{propertyKey}
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/jsonReturned if the issue property was found.
Example
{"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/entity-property#","title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}
- Status
400Returned if the issue key or id is invalid.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to view the issue.
- Status
404Returned 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}/subtask
Get sub tasksGET /rest/api/2/issue/{issueIdOrKey}/subtask
Returns an issue's subtask list
Responses
- Status
200
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/response#","title":"Response","type":"object"}
- Status
403Returned if the user is not allowed to edit the issue
- Status
404Returned if the issue doesn't exist
Move sub tasksPOST /rest/api/2/issue/{issueIdOrKey}/subtask/move
Reorders an issue's subtasks by moving the subtask at index "from" to index "to".
Request
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-sub-task-move-position#","title":"Issue Sub Task Move Position","type":"object","properties":{"current":{"type":"integer"}},"additionalProperties":false,"required":["current"]}
Responses
- Status
400Returned if the from or to parameters are out of bounds
- Status
204Returned if the request was successful
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/response#","title":"Response","type":"object"}
- Status
403Returned if the user is not allowed to edit the issue
- Status
404Returned if the parent issue doesn't exist
Can move sub taskGET /rest/api/2/issue/{issueIdOrKey}/subtask/move
Responses
- Status - application/json
api/2/issueLink
The Link Issue Resource provides functionality to manage issue links.
Link issuesPOST /rest/api/2/issueLink
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"},"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/jsonif the issue link was created successfully.
- Status
400if 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
401if the user does not have the link issue permission for the issue, which will be linked to another issue.
- Status
500if an error occurred when creating the issue link or the comment.
- Status
404If 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.
Get issue linkGET /rest/api/2/issueLink/{linkId}
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
400If the specified issue link id is invalid.
- Status
401if the user does not have the link issue permission for the issue, which will be linked to another issue.
- Status
500if an error occurred when creating the issue link or the comment.
- Status
404If 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.
Delete issue linkDELETE /rest/api/2/issueLink/{linkId}
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
400If the specified issue link id is invalid.
- Status
401if the user does not have the link issue permission for the source or destination issue of the issue link.
- Status
500if an error occurred when deleting the issue link or the comment.
- Status
204If it successfully deleted the issue link.
- Status
404If 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.
Get issue link typesGET /rest/api/2/issueLinkType
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/jsonReturns a list of all available issue link types.
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"}]}
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
401Returned if user is not logged-in.
- Status
404Returned if issue linking is disabled.
Create issue link typePOST /rest/api/2/issueLinkType
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/jsonThe new issue link type has been created.
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
404Issue linking is disabled or you do not have permission to create issue link types.
Get issue link typeGET /rest/api/2/issueLinkType/{issueLinkTypeId}
Returns for a given issue link type id all information about this issue link type.
Responses
- Status
200 - application/jsonReturns the issue link type with the given id.
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
401Returned if user is not logged-in.
- Status
404Returned if issue linking is disabled or no issue link type with the given id exists.
Delete issue link typeDELETE /rest/api/2/issueLinkType/{issueLinkTypeId}
Delete the specified issue link type.
Responses
- Status
204
- Status
404Returned if issue linking is disabled or no issue link type with the given id exists.
Update issue link typePUT /rest/api/2/issueLinkType/{issueLinkTypeId}
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
400Returned if the supplied id is not a number.
- Status
404Returned 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.
Get issue security schemesGET /rest/api/2/issuesecurityschemes
Returns all issue security schemes that are defined.
Responses
- Status
200 - application/jsonReturned if the user has the administrator permission.
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}]}
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
401Returned if the user is not logged in.
- Status
403Returned if the user does not have the administrator permission.
Get issue security schemeGET /rest/api/2/issuesecurityschemes/{id}
Returns the issue security scheme along with that are defined.
Responses
- Status
200 - application/jsonReturned if the user has the administrator permission or if the scheme is used in a project in which the user has the administrative permission.
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"}]}
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
401Returned if the user is not logged in.
- Status
403Returned 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
Get issue all typesGET /rest/api/2/issuetype
Returns a list of all issue types visible to the user
Responses
- Status
200 - application/jsonReturned if the issue type exists and is visible by the calling user.
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}]
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"]}}
Create issue typePOST /rest/api/2/issuetype
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/jsonReturned 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
400Returned if the request is invalid. This happens when the name is invalid or issue type is subtask on instance which has subtasks disabled.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to administer Jira.
- Status
409Returned if there already exists an issue type with the specified name.
Get issue typeGET /rest/api/2/issuetype/{id}
Returns a full representation of the issue type that has the given id.
Responses
- Status
200 - application/jsonReturned if the issue type exists and is visible by the calling user.
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}
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
404Returned if the issue type does not exist, or is not visible to the calling user.
Delete issue typeDELETE /rest/api/2/issuetype/{id}
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
parameter | type | description |
---|---|---|
alternativeIssueTypeId | string | the id of an issue type to which issues associated with the removed issue type will be migrated. |
Responses
- Status
400Returned 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
401Returned if the calling user is not authenticated.
- Status
204 - application/jsonReturned if the issue type was successfully removed.
- Status
403Returned if the calling user does not have permission to administer Jira.
- Status
404Returned if the issue type which is supposed to be removed does not exist or the alternative issue type does not exist.
Update issue typePUT /rest/api/2/issuetype/{id}
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/jsonReturned 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
400Returned if the request is invalid. This happens when the name is invalid or if the avatar with given id does not exist.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to administer Jira.
- Status
404Returned if the issue type to update does not exist.
- Status
409Returned if there already exists an issue type with the specified name.
Get alternative issue typesGET /rest/api/2/issuetype/{id}/alternatives
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/jsonReturned if the issue type exists and is visible by the calling user.
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}]
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
404Returned if the issue type does not exist, or is not visible to the calling user.
Create avatar from temporaryPOST /rest/api/2/issuetype/{id}/avatar
Converts temporary avatar into a real avatar
Request
Example
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"needsCropping":false}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/avatar-cropping#","title":"Avatar Cropping","type":"object","properties":{"cropperWidth":{"type":"integer"},"cropperOffsetX":{"type":"integer"},"cropperOffsetY":{"type":"integer"},"url":{"type":"string"},"needsCropping":{"type":"boolean"}},"additionalProperties":false,"required":["cropperWidth","cropperOffsetX","cropperOffsetY","needsCropping"]}
Responses
- Status
201 - application/jsonReturns created avatar
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}
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
400Returned if the cropping coordinates are invalid
- Status
500Returned if an error occurs while converting temporary avatar to real avatar
- Status
403Returned if the currently authenticated user does not have permission to pick avatar
- Status
404Returned if the currently authenticated user does not have EDIT PROJECT permission.
Store temporary avatarPOST /rest/api/2/issuetype/{id}/avatar/temporary
Creates temporary avatar. Creating a temporary avatar is part of a 3-step process in uploading a new avatar for an issue type: upload, crop, confirm.
The following examples shows these three steps using curl. The cookies (session) need to be preserved between requests, hence the use of -b and -c. The id created in step 2 needs to be passed to step 3 (you can simply pass the whole response of step 2 as the request of step 3).
curl -c cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \ -H "Content-Type: image/png" --data-binary @mynewavatar.png \ 'http://localhost:8090/jira/rest/api/2/issuetype/1/avatar/temporary?filename=mynewavatar.png' curl -b cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \ -H "Content-Type: application/json" --data '{"cropperWidth": "65","cropperOffsetX": "10","cropperOffsetY": "16"}' \ -o tmpid.json \ http://localhost:8090/jira/rest/api/2/issuetype/1/avatar curl -b cookiejar.txt -X PUT -u admin:admin -H "X-Atlassian-Token: no-check" \ -H "Content-Type: application/json" --data-binary @tmpid.json \ http://localhost:8090/jira/rest/api/2/issuetype/1/avatar
Request
query parameters
parameter | type | description |
---|---|---|
filename | string | name of file being uploaded |
size | long | size of file |
Responses
- Status
201 - application/jsontemporary avatar cropping instructions
Example
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/avatar-cropping#","title":"Avatar Cropping","type":"object","properties":{"cropperWidth":{"type":"integer"},"cropperOffsetX":{"type":"integer"},"cropperOffsetY":{"type":"integer"},"url":{"type":"string"},"needsCropping":{"type":"boolean"}},"additionalProperties":false,"required":["cropperWidth","cropperOffsetX","cropperOffsetY","needsCropping"]}
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to administer Jira.
- Status
404Returned if the issue type to update does not exist or if the request does not contain valid XSRF token.
Store temporary avatar using multi partPOST /rest/api/2/issuetype/{id}/avatar/temporary
Creates temporary avatar using multipart. The response is sent back as JSON stored in a textarea. This is because the client uses remote iframing to submit avatars using multipart. So we must send them a valid HTML page back from which the client parses the JSON from.
Creating a temporary avatar is part of a 3-step process in uploading a new avatar for an issue type: upload, crop, confirm. This endpoint allows you to use a multipart upload instead of sending the image directly as the request body.
You *must* use "avatar" as the name of the upload parameter:
curl -c cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \ -F "avatar=@mynewavatar.png;type=image/png" \ 'http://localhost:8090/jira/rest/api/2/issuetype/1/avatar/temporary'
Responses
- Status
201 - text/htmltemporary avatar cropping instructions embeded in HTML page. Error messages will also be embeded in the page.
Example
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/avatar-cropping#","title":"Avatar Cropping","type":"object","properties":{"cropperWidth":{"type":"integer"},"cropperOffsetX":{"type":"integer"},"cropperOffsetY":{"type":"integer"},"url":{"type":"string"},"needsCropping":{"type":"boolean"}},"additionalProperties":false,"required":["cropperWidth","cropperOffsetX","cropperOffsetY","needsCropping"]}
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to administer Jira.
- Status
404Returned if the issue type to update does not exist or if the request does not contain valid XSRF token.
Get paginated issue types
experimentalGET /rest/api/2/issuetype/page
Returns paginated list of filtered issue types
Request
query parameters
parameter | type | description |
---|---|---|
startAt | long Default: 0 | the index of the first issue type to return |
maxResults | int Default: 100 | the maximum number of issue type to return |
query | string Default: | the string that issue type names will be matched with |
projectIds | string | the set of project ids to filter issue types |
header parameters
parameter | type | description |
---|---|---|
X-Requested-With | string |
Responses
- Status
200 - application/jsonReturns paginated list of issue types
Example
{"self":"http://www.example.com/jira/rest/api/2//issueTypes/page?startAt=0&maxResults=2","nextPage":"http://www.example.com/jira/rest/api/2//issueTypes/page?startAt=2&maxResults=2","maxResults":2,"startAt":0,"total":5,"isLast":false,"values":[{"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}]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/page-of-issue-type#","title":"Page of Issue Type","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 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,"required":["maxResults","startAt"]}
api/2/issuetype/{issueTypeId}/properties
This resource allows to store custom properties for issue types.
Get property keys
experimentalGET /rest/api/2/issuetype/{issueTypeId}/properties
Returns the keys of all properties for the issue type identified by the id.
Responses
- Status
200 - application/jsonReturned if the issue type was found.
Example
{"keys":[{"self":"http://www.example.com/jira/rest/api/2/issue/EX-2/properties/issue.support","key":"issue.support"}]}
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
400Returned if the issue type id is invalid.
- Status
404Returned if the issue type with given id does not exist or if the user does not have permissions to view this issue type.
Delete property
experimentalDELETE /rest/api/2/issuetype/{issueTypeId}/properties/{propertyKey}
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
400Returned if the issue type id is invalid.
- Status
204Returned if the issue type property was removed successfully.
- Status
404Returned if the issue type with given id does not exist or if the property with given key is not found.
Set property
experimentalPUT /rest/api/2/issuetype/{issueTypeId}/properties/{propertyKey}
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
200Returned if the issue type property is successfully updated.
- Status
201Returned if the issue type property is successfully created.
- Status
400Returned if the issue type id is invalid.
- Status
404Returned if the issue type with given id does not exist or if the user does not have permissions to edit this issue type.
Get property
experimentalGET /rest/api/2/issuetype/{issueTypeId}/properties/{propertyKey}
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/jsonReturned if the issue type property was found.
Example
{"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/entity-property#","title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}
- Status
400Returned if the issue type id is invalid.
- Status
404Returned 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/issuetypescheme
Create issue type schemePOST /rest/api/2/issuetypescheme
Creates an issue type scheme from a JSON representation. (Admin required)
Request
Example
{"name":"new name","description":"some new description of the scheme","defaultIssueTypeId":"3","issueTypeIds":["1","4","3"]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-type-scheme-create-update#","title":"Issue Type Scheme Create Update","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"defaultIssueTypeId":{"type":"string"},"issueTypeIds":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}
Responses
- Status
200 - application/jsonReturned if the issue type scheme was successfully created.
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-type-scheme#","title":"Issue Type Scheme","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"defaultIssueType":{"$ref":"#/definitions/issue-type"},"issueTypes":{"type":"array","items":{"$ref":"#/definitions/issue-type"}}},"definitions":{"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"]}},"additionalProperties":false}
- Status
400Returned if the request is invalid. This happens when the name or associated issue types are invalid. It also occurs when the default issue type isn't found in the collection of associated issue types.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to administer Jira.
Get all issue type schemesGET /rest/api/2/issuetypescheme
Returns a list of all issue type schemes visible to the user (must be admin).
All issue types associated with the scheme will only be returned if an additional query parameter is provided:
expand=schemes.issueTypes
.
Similarly, the default issue type associated with the scheme (if one exists) will only be returned if
additional an query parameter is provided: expand=schemes.defaultIssueType
.
Note that both query parameters can be used together: expand=schemes.issueTypes,schemes.defaultIssueType
.
Responses
- Status
200 - application/jsonReturned if issue type schemes are visible by the calling user
Example
{"expand":"defaultIssueType,issueTypes","self":"http://localhost:8090/jira/rest/api/2/issuetypescheme/10100","id":"10100","name":"Some grouping of issue types for the greater good.","description":"A brief explanation of this issue type scheme.","defaultIssueType":{"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},"issueTypes":[{"self":"http://localhost:8090/jira/rest/api/2.0/issuetype/1","id":"1","description":"a problem with the software.","iconUrl":"http://localhost:8090/jira/image","name":"bug","subtask":false,"avatarId":10002},{"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}]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-type-scheme-list#","title":"Issue Type Scheme List","type":"object","properties":{"expand":{"type":"string"},"schemes":{"type":"array","items":{"title":"Issue Type Scheme","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"defaultIssueType":{"$ref":"#/definitions/issue-type"},"issueTypes":{"type":"array","items":{"$ref":"#/definitions/issue-type"}}},"additionalProperties":false}}},"definitions":{"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"]}},"additionalProperties":false}
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to administer Jira.
Get issue type schemeGET /rest/api/2/issuetypescheme/{schemeId}
Returns a full representation of the issue type scheme that has the given id (must be admin).
Responses
- Status
200 - application/jsonReturned if the issue type scheme exists and is visible by the calling user.
Example
{"expand":"defaultIssueType,issueTypes","self":"http://localhost:8090/jira/rest/api/2/issuetypescheme/10100","id":"10100","name":"Some grouping of issue types for the greater good.","description":"A brief explanation of this issue type scheme.","defaultIssueType":{"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},"issueTypes":[{"self":"http://localhost:8090/jira/rest/api/2.0/issuetype/1","id":"1","description":"a problem with the software.","iconUrl":"http://localhost:8090/jira/image","name":"bug","subtask":false,"avatarId":10002},{"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}]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-type-scheme#","title":"Issue Type Scheme","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"defaultIssueType":{"$ref":"#/definitions/issue-type"},"issueTypes":{"type":"array","items":{"$ref":"#/definitions/issue-type"}}},"definitions":{"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"]}},"additionalProperties":false}
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to administer Jira.
- Status
404Returned if the issue type scheme does not exist.
Update issue type schemePUT /rest/api/2/issuetypescheme/{schemeId}
Updates the specified issue type scheme from a JSON representation. (Admin required)
Request
Example
{"name":"new name","description":"some new description of the scheme","defaultIssueTypeId":"3","issueTypeIds":["1","4","3"]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-type-scheme-create-update#","title":"Issue Type Scheme Create Update","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"defaultIssueTypeId":{"type":"string"},"issueTypeIds":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}
Responses
- Status
200 - application/jsonReturned if the issue type was successfully updated.
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/issue-type-scheme#","title":"Issue Type Scheme","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"defaultIssueType":{"$ref":"#/definitions/issue-type"},"issueTypes":{"type":"array","items":{"$ref":"#/definitions/issue-type"}}},"definitions":{"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"]}},"additionalProperties":false}
- Status
400Returned if the request is invalid. This happens when the name or issue types are invalid. It also occurs when the default issue type isn't found in the associated issue types collection.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to administer Jira.
- Status
404Returned if the issue type scheme to update does not exist.
Delete issue type schemeDELETE /rest/api/2/issuetypescheme/{schemeId}
Deletes the specified issue type scheme. Any projects associated with this IssueTypeScheme will be automatically associated with the global default IssueTypeScheme. (Admin required)
Responses
- Status
400Returned 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
401Returned if the calling user is not authenticated.
- Status
204 - application/jsonReturned if the issue type scheme was successfully removed.
- Status
403Returned if the calling user does not have permission to administer Jira or if an attempt is made to delete the default IssueTypeScheme.
- Status
404Returned if the issue type scheme which is supposed to be removed does not exist.
Add project associations to schemePOST /rest/api/2/issuetypescheme/{schemeId}/associations
Adds additional projects to those already associated with the specified issue type scheme. (Admin required)
Request
Example
{"idsOrKeys":["100034","13543","FOOPROJ","BAZZPROJ"]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/associate-projects#","title":"Associate Projects","type":"object","properties":{"idsOrKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}
Responses
- Status
200Returned if the association succeeded
- Status 201 - application/json
- Status
400Returned if the request is invalid. This occurs when the supplied project ids/keys are invalid. It also happens if performing the association would require an issue type migration for any of the projects.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to administer Jira.
- Status
404Returned if the issue type scheme to update does not exist.
Get associated projectsGET /rest/api/2/issuetypescheme/{schemeId}/associations
For the specified issue type scheme, returns all of the associated projects. (Admin required)
Request
query parameters
parameter | type | description |
---|---|---|
expand | string | the parameters to expand on the returned projects; defaults to none. |
Responses
- Status
200Returned if the scheme's associations were successfully retrieved
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}
- Status
201 - application/json
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to administer Jira
- Status
404Returned if the specified issue type scheme does not exist
Set project associations for schemePUT /rest/api/2/issuetypescheme/{schemeId}/associations
Associates the given projects with the specified issue type scheme. Any existing project-associations the issue type scheme has will be overwritten. (Admin required)
Request
Example
{"idsOrKeys":["100034","13543","FOOPROJ","BAZZPROJ"]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/associate-projects#","title":"Associate Projects","type":"object","properties":{"idsOrKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}
Responses
- Status
200Returned if the associations were successfully updated
- Status 201 - application/json
- Status
400Returned if the request is invalid. This occurs when the supplied project ids/keys are invalid. It also happens if performing the association would require an issue type migration for any of the newly associated projects.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to administer Jira.
- Status
404Returned if the issue type scheme to update does not exist.
Remove all project associationsDELETE /rest/api/2/issuetypescheme/{schemeId}/associations
Removes all project associations for the specified issue type scheme. These projects revert to an association with the default/global issue type scheme.(Admin required)
Responses
- Status 201 - application/json
- Status
401Returned if the calling user is not authenticated.
- Status
204Returned if the associations were successfully removed
- Status
403Returned if the calling user does not have permission to administer Jira--or if an attempt is made to remove associations for the default/global issue type scheme.
- Status
404Returned if the specified issue type scheme does not exist
Remove project associationDELETE /rest/api/2/issuetypescheme/{schemeId}/associations/{projIdOrKey}
For the specified issue type scheme, removes the given project association . This project reverts to an association with the default/global issue type scheme.(Admin required)
Responses
- Status 201 - application/json
- Status
401Returned if the calling user is not authenticated.
- Status
204Returned if the association was successfully removed
- Status
403Returned if the calling user does not have permission to administer Jira--or if an attempt is made to remove an association for the default/global issue type scheme.
- Status
404Returned if the specified issue type scheme or project does not exist
api/2/jql/autocompletedata
Resource for auto complete data for searches.
Get auto completeGET /rest/api/2/jql/autocompletedata
Returns the auto complete data required for JQL searches.
Responses
- Status
200 - application/jsonThe auto complete data required for JQL searches.
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\"]}"
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
401Returned if the calling user is not authenticated.
- Status
500Returned if an error occurs while generating the response.
Get field auto complete for query stringGET /rest/api/2/jql/autocompletedata/suggestions
Returns auto complete suggestions for JQL search.
Request
query parameters
parameter | type | description |
---|---|---|
fieldName | string | the field name for which the suggestions are generated. |
fieldValue | string | the portion of the field value that has already been provided by the user. |
predicateName | string | the predicate for which the suggestions are generated. Suggestions are generated only for: "by", "from" and "to". |
predicateValue | string | the portion of the predicate value that has already been provided by the user. |
Responses
- Status
200 - application/jsonThe autocompletion suggestions for JQL search.
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)"}]}
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
ValidatePOST /rest/api/2/licenseValidator
Request
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/string#","title":"String","type":"string"}
Responses
- Status
- application/json
api/2/monitoring/app
Describes endpoint for controlling the App Monitoring feature
Is app monitoring enabledGET /rest/api/2/monitoring/app
Responses
- Status - application/json
Set app monitoring enabledPOST /rest/api/2/monitoring/app
Request
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/app-monitoring-rest-entity#","title":"App Monitoring Rest Entity","type":"object"}
Responses
- Status - application/json
api/2/monitoring/ipd
Describes endpoint for controlling the IPD Monitoring feature
Is ipd monitoring enabledGET /rest/api/2/monitoring/ipd
Responses
- Status - application/json
Set app monitoring enabledPOST /rest/api/2/monitoring/ipd
Request
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/ipd-monitoring-rest-entity#","title":"Ipd Monitoring Rest Entity","type":"object"}
Responses
- Status - application/json
api/2/monitoring/jmx
Are metrics exposedGET /rest/api/2/monitoring/jmx/areMetricsExposed
Responses
- Status - application/json
Get available metricsGET /rest/api/2/monitoring/jmx/getAvailableMetrics
Responses
- Status - application/json
StartPOST /rest/api/2/monitoring/jmx/startExposing
Responses
- Status - application/json
StopPOST /rest/api/2/monitoring/jmx/stopExposing
Responses
- Status - application/json
api/2/mypreferences
Provide preferences of the currently logged in user.
Set preferencePUT /rest/api/2/mypreferences
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
parameter | type | description |
---|---|---|
key | string | - 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
Remove preferenceDELETE /rest/api/2/mypreferences
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
parameter | type | description |
---|---|---|
key | string | - key of the preference to be removed. |
Responses
- Status - application/json
Get preferenceGET /rest/api/2/mypreferences
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
parameter | type | description |
---|---|---|
key | string | - key of the preference to be returned. |
Responses
- Status - application/json
api/2/myself
Currently logged user resource
Update userPUT /rest/api/2/myself
Modify currently logged user. The "value" fields present will override the existing value. Fields skipped in request will not be changed. Only email and display name can be change that way. Requires user password.
Request
Example
{"password":"abracadabra","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"},"active":{"type":"boolean"},"applicationKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}
Responses
- Status
200 - application/jsonReturned if the user exists and the caller has permission to edit it.
Example
{"self":"http://www.example.com/jirahttp://www.example.com/jira/rest/api/2/user/charlie","key":"charlie","name":"eddie","emailAddress":"eddie@atlassian.com","displayName":"Eddie of Atlassian"}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/user#","title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"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
400Returned if the request is invalid including incorrect password.
- Status
401Returned if the user is not authenticated.
- Status
403Returned if the directory is read-only.
- Status
404Returned if the the user could not be found.
Get userGET /rest/api/2/myself
Returns currently logged user. This resource cannot be accessed anonymously.
Responses
- Status
200 - application/jsonReturns a full representation of a Jira user in JSON format.
Example
{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","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","lastLoginTime":"2023-08-30T16:37:01+1000"}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/user#","title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"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
401Returned if the current user is not authenticated.
Change my passwordPUT /rest/api/2/myself/password
Modify caller password.
Request
Example
{"password":"new password","currentPassword":"current password"}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/password#","title":"Password","type":"object","properties":{"password":{"type":"string"},"currentPassword":{"type":"string"}},"additionalProperties":false}
Responses
- Status
400Returned if new password is incorrect/missing or current password is incorrect.
- Status
401Returned if the user is not authenticated.
- Status
204Returned if the user exists and the caller has permission to edit it.
- Status
403Returned if the directory is read-only.
- Status
404Returned if the caller does have permission to change user password but the user does not exist.
api/2/notificationscheme
Get notification schemesGET /rest/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
parameter | type | description |
---|---|---|
startAt | long | the index of the first notification scheme to return (0 based). |
maxResults | int | the maximum number of notification schemes to return (max 50). |
expand | string |
Responses
- Status
200 - application/jsonPaginated list of notification schemes to which the user has permissions.
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"}]},"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","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"}]},"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","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"}]}]}]}
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"},"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"},"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"]}
Get notification schemeGET /rest/api/2/notificationscheme/{id}
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.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string |
Responses
- Status
200 - application/jsonReturned if the notification scheme exists and is visible for the calling user
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"}]},"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","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"}]},"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","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"}]}]}
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"},"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"},"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
404Returned if the notification scheme does not exist, or is not visible to the calling user
api/2/password
REST resource for operations related to passwords and the password policy.
Get password policyGET /rest/api/2/password/policy
Returns the list of requirements for the current password policy. For example, "The password must have at least 10 characters.", "The password must not be similar to the user's name or email address.", etc.
Request
query parameters
parameter | type | description |
---|---|---|
hasOldPassword | boolean Default: false | whether or not the user will be required to enter their current password. Use {@code false} (the default) if this is a new user or if an administrator is forcibly changing another user's password. |
Responses
- Status
200 - application/jsonReturns an array of message strings.
Schema
{"type":"array","items":{"type":"string"}}
Policy check create userPOST /rest/api/2/password/policy/createUser
Returns a list of statements explaining why the password policy would disallow a proposed password for a new user.
You can use this method to test the password policy validation. This could be done prior to an action
where a new user and related password are created, using methods like the ones in
UserService.
For example, you could use this to validate a password in a create user form in the user interface, as the user enters it.
The username and new password must be not empty to perform the validation.
Note, this method will help you validate against the policy only. It won't check any other validations that might be performed
when creating a new user, e.g. checking whether a user with the same name already exists.
Request
Example
{"username":"fred","displayName":"Fred Normal","emailAddress":"fred@example.com","password":"secret"}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/password-policy-create-user#","title":"Password Policy Create User","type":"object","properties":{"username":{"type":"string"},"displayName":{"type":"string"},"emailAddress":{"type":"string"},"password":{"type":"string"}},"additionalProperties":false}
Responses
- Status
200 - application/jsonReturns an array of message strings.
Schema
{"type":"array","items":{"type":"string"}}
- Status
400Returned if the request is invalid, such as if the username or password is left unspecified.
Policy check update userPOST /rest/api/2/password/policy/updateUser
Returns a list of statements explaining why the password policy would disallow a proposed new password for a user with an existing password.
You can use this method to test the password policy validation. This could be done prior to an action where the password
is actually updated, using methods like ChangePassword
or ResetPassword.
For example, you could use this to validate a password in a change password form in the user interface, as the user enters it.
The user must exist and the username and new password must be not empty, to perform the validation.
Note, this method will help you validate against the policy only. It won't check any other validations that might be performed
when submitting a password change/reset request, e.g. verifying whether the old password is valid.
Request
Example
{"username":"fred","oldPassword":"secret","newPassword":"correcthorsebatterystaple"}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/password-policy-update-user#","title":"Password Policy Update User","type":"object","properties":{"username":{"type":"string"},"oldPassword":{"type":"string"},"newPassword":{"type":"string"}},"additionalProperties":false}
Responses
- Status
200 - application/jsonReturns an array of message strings.
Schema
{"type":"array","items":{"type":"string"}}
- Status
400Returned if the request is invalid, such as if the username or new password is left unspecified.
- Status
404Returned if the username does not correspond to any existing user.
api/2/permissionscheme
Get permission schemesGET /rest/api/2/permissionscheme
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
parameter | type | description |
---|---|---|
expand | string |
Responses
- Status
200 - application/jsonReturned if successful.
Example
{"permissionSchemes":[{"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/10000","name":"Example permission scheme","description":"description"}]}
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"},"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"},"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
401Returned if user is not logged in.
- Status
403Returned if user is not allowed to view permission schemes.
Create permission schemePOST /rest/api/2/permissionscheme
Create a new permission scheme. This method can create schemes with a defined permission set, or without.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string |
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/jsonReturned if the scheme is created successfully.
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"}]}
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"},"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"},"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
401Returned if the user is not logged.
- Status
403Returned if the user is not allowed to create permission schemes.
Get scheme attribute
experimentalGET /rest/api/2/permissionscheme/{permissionSchemeId}/attribute/{attributeKey}
Responses
- Status
200 - application/jsonReturned if successful.
Example
{"key":"ADMINISTER_PROJECTS.extended.enabled","value":"true"}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/permission-scheme-attribute#","title":"Permission Scheme Attribute","type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false}
- Status
401Returned if the user is not authenticated.
- Status
403Returned if the user is not an admin.
- Status
404Returned if there is no such attribute.
Set scheme attribute
experimentalPUT /rest/api/2/permissionscheme/{permissionSchemeId}/attribute/{key}
Updates or inserts the attribute for a permission scheme specified by permission scheme id. The attribute consists of the key and the value. The value will be converted to Boolean using Boolean#valueOf.
Request
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/string#","title":"String","type":"string"}
Responses
- Status
401Returned if the user is not authenticated.
- Status
500Returned if there was an error related to attribute upsert.
- Status
204 - application/jsonReturned if successful.
- Status
403Returned if the user is not an admin.
Delete permission schemeDELETE /rest/api/2/permissionscheme/{schemeId}
Deletes a permission scheme identified by the given id.
Responses
- Status
401Returned if user is not logged in.
- Status
204 - application/jsonReturned if the permission scheme is successfully deleted.
- Status
403Returned if user is not allowed to delete permission schemes.
Update permission schemePUT /rest/api/2/permissionscheme/{schemeId}
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
parameter | type | description |
---|---|---|
expand | string |
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/jsonReturned if the scheme is updated successfully.
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"}]}
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"},"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"},"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
401Returned if the user is not logged.
- Status
403Returned if the user is not allowed to edit permission schemes.
- Status
404Returned if the permission is not found.
Get permission schemeGET /rest/api/2/permissionscheme/{schemeId}
Returns a permission scheme identified by the given id.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string |
Responses
- Status
200 - application/jsonReturned if successful.
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"}]}
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"},"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"},"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
401Returned if user is not logged in.
- Status
403Returned if user is not allowed to view permission schemes.
- Status
404Returned if the scheme doesn't exist.
Get permission scheme grantsGET /rest/api/2/permissionscheme/{schemeId}/permission
Returns all permission grants of the given permission scheme.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string |
Responses
- Status
200 - application/jsonReturned if successful.
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"}
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"},"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"},"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
401Returned if user is not logged in.
- Status
403Returned if user is not allowed to view permission schemes.
Create permission grantPOST /rest/api/2/permissionscheme/{schemeId}/permission
Creates a permission grant in a permission scheme.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string |
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/jsonReturned if the scheme permission is created successfully.
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"}
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"},"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"},"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
401Returned if the user is not logged.
- Status
403Returned if the user is not allowed to edit permission schemes.
Delete permission scheme entityDELETE /rest/api/2/permissionscheme/{schemeId}/permission/{permissionId}
Deletes a permission grant from a permission scheme.
Responses
- Status
401Returned if the user is not logged.
- Status
204 - application/jsonReturned if the permission grant is deleted successfully.
- Status
403Returned if the user is not allowed to edit permission schemes.
Get permission scheme grantGET /rest/api/2/permissionscheme/{schemeId}/permission/{permissionId}
Returns a permission grant identified by the given id.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string |
Responses
- Status
200 - application/jsonReturned if successful.
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"}
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"},"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"},"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
401Returned if user is not logged in.
- Status
403Returned if user is not allowed to view permission schemes.
api/2/priority
Get prioritiesGET /rest/api/2/priority
Returns a list of all issue priorities.
Responses
- Status
200 - application/jsonReturned if the priorities exists and the user has permission to view it. Contains a full representation of the priority in JSON format.
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"}]
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}}
- Status
401Returned if the user is not authenticated.
Get priorityGET /rest/api/2/priority/{id}
Returns an issue priority.
Responses
- Status
200 - application/jsonReturned if the issue priority exists and is visible by the calling user. Contains a full representation of the issue priority in 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"}
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
401Returned if the user is not authenticated.
- Status
404Returned if the issue priority does not exist or is not visible to the calling user.
Get prioritiesGET /rest/api/2/priority/page
Returns a list of all issue priorities.
Request
query parameters
parameter | type | description |
---|---|---|
startAt | long Default: 0 | |
maxResults | int Default: 100 | |
query | string Default: | |
projectIds | string |
Responses
- Status
200 - application/jsonReturned if the priorities exists and the user has permission to view it. Contains a full representation of the priority in JSON format.
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"}]
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}}
- Status
401Returned if the user is not authenticated.
api/2/priorityschemes
Resource for managing priority schemes.
Create priority scheme
experimentalPOST /rest/api/2/priorityschemes
Creates new priority scheme.
Request
Example
{"name":"New priority scheme","description":"Priority scheme for very important projects","defaultOptionId":"3","optionIds":["1","2","3","4","5"]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/priority-scheme#","title":"Priority Scheme","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultOptionId":{"type":"string"},"optionIds":{"type":"array","items":{"type":"string"}},"defaultScheme":{"type":"boolean"},"projectKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"required":["defaultScheme"]}
Responses
- Status
201Returned if the priority scheme was created.
Example
{"expand":"projectKeys","self":"http://www.example.com/jira/rest/api/2/priorityschemes/123","id":123,"name":"New priority scheme","description":"Priority scheme for very important projects","defaultOptionId":"3","optionIds":["1","2","3","4","5"],"defaultScheme":false}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/priority-scheme#","title":"Priority Scheme","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultOptionId":{"type":"string"},"optionIds":{"type":"array","items":{"type":"string"}},"defaultScheme":{"type":"boolean"},"projectKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"required":["defaultScheme"]}
- Status
400Returned if the request is invalid.
- Status
401Returned if the user is not authenticated.
- Status
500Returned if the priority scheme was not created because of other error.
- Status
403Returned if the caller user does not have permission to create priority scheme.
Get priority schemes
experimentalGET /rest/api/2/priorityschemes
Returns all priority schemes.
All project keys associated with the priority scheme will only be returned if additional query parameter is provided expand=schemes.projectKeys
.
Request
query parameters
parameter | type | description |
---|---|---|
startAt | long | the page offset, if not specified then defaults to 0 |
maxResults | int | how many results on the page should be included. Defaults to 100, maximum is 1000. |
Responses
- Status
200 - application/jsonReturns a list of priority schemes.
Example
{"expand":"schemes","schemes":[{"expand":"projectKeys","self":"http://www.example.com/jira/rest/api/2/priorityschemes/4","id":4,"name":"4th priority scheme","description":"Some description","defaultOptionId":"13","optionIds":["11","12","13","14","15"],"defaultScheme":false,"projectKeys":["MNKY","HSP"]},{"expand":"projectKeys","self":"http://www.example.com/jira/rest/api/2/priorityschemes/1","id":1,"name":"Default priority scheme","description":"Some description","defaultOptionId":"2","optionIds":["1","2","3"],"defaultScheme":true,"projectKeys":["TEST","OTHER"]}],"startAt":0,"maxResults":2,"total":10}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/priority-scheme-list#","title":"Priority Scheme List","type":"object","properties":{"expand":{"type":"string"},"schemes":{"type":"array","items":{"title":"Priority Scheme","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultOptionId":{"type":"string"},"optionIds":{"type":"array","items":{"type":"string"}},"defaultScheme":{"type":"boolean"},"projectKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"required":["defaultScheme"]}},"startAt":{"type":"integer"},"maxResults":{"type":"integer"},"total":{"type":"integer"}},"additionalProperties":false}
- Status
403Returned if the user does not have rights to view priority schemes.
Delete priority scheme
experimentalDELETE /rest/api/2/priorityschemes/{schemeId}
Deletes a priority scheme. All projects using deleted scheme will use default priority scheme afterwards. Default priority scheme can't be deleted.
Responses
- Status
401Returned if the user is not logged in.
- Status
204 - application/jsonReturned if the priority scheme is successfully deleted.
- Status
403Returned if the currently authenticated user does not have permission to delete priority scheme.
- Status
404Returned if the priority scheme does not exist.
Update priority scheme
experimentalPUT /rest/api/2/priorityschemes/{schemeId}
Updates a priority scheme.
Update will be rejected if issue migration would be needed as a result of scheme update.
Priority scheme update with migration is possible from the UI.
All project keys associated with the priority scheme will only be returned if additional query parameter is provided expand=projectKeys
.
Request
Example
{"name":"Updated priority scheme","description":"Updated description","defaultOptionId":"8","optionIds":["5","6","7","8","9"]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/priority-scheme-update#","title":"Priority Scheme Update","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultOptionId":{"type":"string"},"optionIds":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}
Responses
- Status
200 - application/jsonReturned if the priority scheme update was successful.
Example
{"expand":"projectKeys","self":"http://www.example.com/jira/rest/api/2/priorityschemes/123","id":123,"name":"Updated priority scheme","description":"Updated description","defaultOptionId":"8","optionIds":["5","6","7","8","9"],"defaultScheme":false,"projectKeys":["MNKY","HSP"]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/priority-scheme#","title":"Priority Scheme","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultOptionId":{"type":"string"},"optionIds":{"type":"array","items":{"type":"string"}},"defaultScheme":{"type":"boolean"},"projectKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"required":["defaultScheme"]}
- Status
400Returned if the request is not valid and the priority scheme could not be updated.
- Status
401Returned if the user is not logged in.
- Status
403Returned if the user does not have rights to update priority scheme.
- Status
404Returned if the priority scheme does not exist.
Get priority scheme
experimentalGET /rest/api/2/priorityschemes/{schemeId}
Gets a full representation of a priority scheme in JSON format.
All project keys associated with the priority scheme will only be returned if additional query parameter is provided expand=projectKeys
.
Responses
- Status
200 - application/jsonReturned if the priority scheme exists and the user has permission to view it.
Example
{"expand":"projectKeys","self":"http://www.example.com/jira/rest/api/2/priorityschemes/4","id":4,"name":"4th priority scheme","description":"Some description","defaultOptionId":"13","optionIds":["11","12","13","14","15"],"defaultScheme":false,"projectKeys":["MNKY","HSP"]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/priority-scheme#","title":"Priority Scheme","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultOptionId":{"type":"string"},"optionIds":{"type":"array","items":{"type":"string"}},"defaultScheme":{"type":"boolean"},"projectKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"required":["defaultScheme"]}
- Status
403Returned if the user does not have rights to view priority scheme.
- Status
404Returned if the priority scheme is not found.
api/2/project
Get all projectsGET /rest/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
parameter | type | description |
---|---|---|
expand | string | the parameters to expand |
recent | int | 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). |
includeArchived | boolean | whether to include archived projects in response, default: false |
browseArchive | boolean | whether to include only projects where current user can browse archive |
Responses
- Status
200 - application/jsonReturns a list of projects for which the user has the BROWSE, ADMINISTER or PROJECT_ADMIN project permission.
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"}}]
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}
Create projectPOST /rest/api/2/project
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,"workflowSchemeId":10031,"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"},"workflowSchemeId":{"type":"integer"},"categoryId":{"type":"integer"}},"additionalProperties":false}
Responses
- Status
201 - application/jsonReturned if the project creation was successful.
Example
{"self":"http://example/jira/rest/api/2/project/10042","id":10010,"key":"EX"}
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
400Returned if the request is not valid and the project could not be created.
- Status
401Returned if the user is not logged in.
- Status
403Returned if the user does not have rights to create projects.
- Status
409Returned if requested workflowScheme could not be assigned to created project.
Update projectPUT /rest/api/2/project/{projectIdOrKey}
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
parameter | type | description |
---|---|---|
expand | string | 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-update#","title":"Project Update","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/jsonReturned if the project update was successful.
Example
{"expand":"description,lead,url,projectKeys","self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","description":"This project was created as an example for REST.","lead":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"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"},"archived":false}
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}
- Status
400Returned if the request is not valid and the project could not be updated.
- Status
401Returned if the user is not logged in.
- Status
403Returned if the user does not have rights to update projects.
- Status
404Returned if the project does not exist.
Delete projectDELETE /rest/api/2/project/{projectIdOrKey}
Deletes a project.
Responses
- Status
401Returned if the user is not logged in.
- Status
204 - application/jsonReturned if the project is successfully deleted.
- Status
403Returned if the currently authenticated user does not have permission to delete the project.
- Status
404Returned if the project does not exist.
Get projectGET /rest/api/2/project/{projectIdOrKey}
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
parameter | type | description |
---|---|---|
expand | string | the parameters to expand |
Responses
- Status
200 - application/jsonReturned if the project exists and the user has permission to view it. Contains a full representation of a project in JSON format.
Example
{"expand":"description,lead,url,projectKeys","self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","description":"This project was created as an example for REST.","lead":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"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"},"archived":false}
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}
- Status
404Returned if the project is not found, or the calling user does not have permission to view it.
Archive projectPUT /rest/api/2/project/{projectIdOrKey}/archive
Archives a project.
Responses
- Status
401Returned if the user is not logged in.
- Status
204 - application/jsonReturned if the project is successfully archived.
- Status
403Returned if the currently authenticated user does not have permission to archive the project or doesn't have DC license or project is already archived.
- Status
404Returned if the project does not exist.
Create avatar from temporaryPOST /rest/api/2/project/{projectIdOrKey}/avatar
Converts the temporary avatar into the final one. This is step 2/3 of changing an avatar for a project:
- Upload (store temporary avatar)
- Crop (create avatar from temporary)
- Update (update project avatar)
Request
Example
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"needsCropping":false}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/avatar-cropping#","title":"Avatar Cropping","type":"object","properties":{"cropperWidth":{"type":"integer"},"cropperOffsetX":{"type":"integer"},"cropperOffsetY":{"type":"integer"},"url":{"type":"string"},"needsCropping":{"type":"boolean"}},"additionalProperties":false,"required":["cropperWidth","cropperOffsetX","cropperOffsetY","needsCropping"]}
Responses
- Status
201 - application/jsonReturns information about the created avatar.
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}
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
400Returned if the cropping coordinates are invalid
- Status
403Returned if the currently authenticated user does not have permission to pick avatar
- Status
404Returned if the currently authenticated user does not have EDIT PROJECT permission.
Update project avatarPUT /rest/api/2/project/{projectIdOrKey}/avatar
Updates an avatar for a project. This is step 3/3 of changing an avatar for a project:
- Upload (store temporary avatar)
- Crop (create avatar from temporary)
- Update (update project avatar)
Request
Example
{"id":"1000","isSystemAvatar":false,"isSelected":false,"isDeletable":true,"selected":false}
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
400Returned if the avatar does not exist
- Status
401Returned if the user is not logged in
- Status
204 - application/jsonReturned if the avatar was updated successfully
- Status
404Returned if the project does not exist.
Delete avatarDELETE /rest/api/2/project/{projectIdOrKey}/avatar/{id}
Deletes avatar
Responses
- Status
204 - application/jsonReturned if the avatar is successfully deleted.
- Status
403Returned if the currently authenticated user does not have permission to delete the avatar.
- Status
404Returned if the avatar or project does not exist.
Store temporary avatarPOST /rest/api/2/project/{projectIdOrKey}/avatar/temporary
Uploads an image and creates a temporary avatar. This is step 1/3 of changing an avatar for a project:
- Upload (store temporary avatar)
- Crop (create avatar from temporary)
- Update (update project avatar)
Supported image formats:
- BMP
- GIF
- JPEG
- PNG
- WBMP
curl \ -X POST \ -u admin:admin \ -H "X-Atlassian-Token: no-check" \ -H "Content-Type: image/png" \ --data-binary @mynewavatar.png \ 'http://localhost:8090/jira/rest/api/2/user/avatar/temporary?username=admin&filename=mynewavatar.png'
Request
query parameters
parameter | type | description |
---|---|---|
filename | string | name of file being uploaded |
size | long | size of the image file |
Responses
- Status
201 - application/jsonReturns coordinates for cropping the temporary avatar. You'll need them in the next step.
Example
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/avatar-cropping#","title":"Avatar Cropping","type":"object","properties":{"cropperWidth":{"type":"integer"},"cropperOffsetX":{"type":"integer"},"cropperOffsetY":{"type":"integer"},"url":{"type":"string"},"needsCropping":{"type":"boolean"}},"additionalProperties":false,"required":["cropperWidth","cropperOffsetX","cropperOffsetY","needsCropping"]}
- Status
400Validation failed. Usually returned when the file exceeds the size limit, or when the size attribute doesn't match the actual size of the uploaded image.
- Status
403Returned if the request does not contain a valid XSRF token
- Status
404Returned if the currently authenticated user does not have EDIT PROJECT permission.
Store temporary avatar using multi partPOST /rest/api/2/project/{projectIdOrKey}/avatar/temporary
Creates temporary avatar using multipart. The response is sent back as JSON stored in a textarea. This is because the client uses remote iframing to submit avatars using multipart. So we must send them a valid HTML page back from which the client parses the JSON.
Responses
- Status
201 - text/htmltemporary avatar cropping instructions embeded in HTML page. Error messages will also be embeded in the page.
Example
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/avatar-cropping#","title":"Avatar Cropping","type":"object","properties":{"cropperWidth":{"type":"integer"},"cropperOffsetX":{"type":"integer"},"cropperOffsetY":{"type":"integer"},"url":{"type":"string"},"needsCropping":{"type":"boolean"}},"additionalProperties":false,"required":["cropperWidth","cropperOffsetX","cropperOffsetY","needsCropping"]}
- Status
404Returned if the currently authenticated user does not have EDIT PROJECT permission.
Get all avatarsGET /rest/api/2/project/{projectIdOrKey}/avatars
Returns all avatars which are visible for the currently logged in user. The avatars are grouped into system and custom.
Responses
- Status
200 - application/jsonReturns a map containing a list of avatars for both custom an system avatars, which the user has the BROWSE project permission.
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}]}
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
404Returned if the currently authenticated user does not have VIEW PROJECT permission.
Get project componentsGET /rest/api/2/project/{projectIdOrKey}/components
Contains a full representation of a the specified project's components.
Responses
- Status
200 - application/jsonReturned 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.
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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"isAssigneeTypeValid":false,"project":"PROJECTKEY","projectId":10000}]
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}}}
- Status
404Returned if the project is not found, or the calling user does not have permission to view it.
Restore projectPUT /rest/api/2/project/{projectIdOrKey}/restore
Restore an archived project. In case of success restored project should be re-indexed.
Responses
- Status
202 - application/jsonReturned if the project is successfully restored.
- Status
401Returned if the user is not logged in.
- Status
403Returned if the currently authenticated user does not have permission to restore the project or doesn't have DC license or project is already restored.
- Status
404Returned if the project does not exist.
Get all statusesGET /rest/api/2/project/{projectIdOrKey}/statuses
Get all issue types with valid status values for a project
Responses
- Status
200 - application/jsonReturned 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.
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"}]}]
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
400Returned if the project is not found, or the calling user does not have permission to view it.
Update project typePUT /rest/api/2/project/{projectIdOrKey}/type/{newProjectTypeKey}
Updates the type of a project.
Responses
- Status
200 - application/jsonReturned if the update to the project type was successful.
Example
{"expand":"description,lead,url,projectKeys","self":"http://www.example.com/jira/rest/api/2/project/EX","id":"10000","key":"EX","description":"This project was created as an example for REST.","lead":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"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":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"assigneeType":"PROJECT_LEAD","assignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},"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"},"archived":false}
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"},"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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"},"archived":{"type":"boolean"}},"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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"type":"string"}},"additionalProperties":false,"required":["active"]}},"additionalProperties":false}
- Status
400Returned if the request is not valid and the project type could not be updated.
- Status
401Returned if the user is not logged in.
- Status
403Returned if the user does not have rights to update projects.
- Status
404Returned if the project does not exist.
Get project versions paginatedGET /rest/api/2/project/{projectIdOrKey}/version
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
parameter | type | description |
---|---|---|
startAt | long | the page offset, if not specified then defaults to 0 |
maxResults | int | how many results on the page should be included. Defaults to 50. |
orderBy | string | ordering of the results. |
expand | string | the parameters to expand |
Responses
- Status
200 - application/jsonOne page of versions for the project.
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}]}
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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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
404Returned if the project is not found, or the calling user does not have permission to view it.
Get project versionsGET /rest/api/2/project/{projectIdOrKey}/versions
Contains a full representation of a the specified project's versions.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string | the parameters to expand |
Responses
- Status
200 - application/jsonReturned 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.
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}]
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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"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
404Returned if the project is not found, or the calling user does not have permission to view it.
api/2/project/{projectIdOrKey}/properties
Get properties keys
experimentalGET /rest/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/jsonReturned if the project was found.
Example
{"keys":[{"self":"http://www.example.com/jira/rest/api/2/issue/EX-2/properties/issue.support","key":"issue.support"}]}
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
400Returned if the project key or id is invalid.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to browse the project.
- Status
404Returned if the project with given key or id does not exist or if the property with given key is not found.
Delete property
experimentalDELETE /rest/api/2/project/{projectIdOrKey}/properties/{propertyKey}
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
400Returned if the project key or id is invalid.
- Status
401Returned if the calling user is not authenticated.
- Status
204Returned if the project property was removed successfully.
- Status
403Returned if the calling user does not have permission to edit the project.
- Status
404Returned if the project with given key or id does not exist or if the property with given key is not found.
Set property
experimentalPUT /rest/api/2/project/{projectIdOrKey}/properties/{propertyKey}
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
200Returned if the project property is successfully updated.
- Status
201Returned if the project property is successfully created.
- Status
400Returned if the project key or id is invalid.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to administer the project.
- Status
404Returned if the project with given key or id does not exist.
Get property
experimentalGET /rest/api/2/project/{projectIdOrKey}/properties/{propertyKey}
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/jsonReturned if the project property was found.
Example
{"key":"issue.support","value":{"hipchat.room.id":"support-123","support.time":"1m"}}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/entity-property#","title":"Entity Property","type":"object","properties":{"key":{"type":"string"},"value":{}},"additionalProperties":false}
- Status
400Returned if the project key or id is invalid.
- Status
401Returned if the calling user is not authenticated.
- Status
403Returned if the calling user does not have permission to browse the project.
- Status
404Returned 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
Get project rolesGET /rest/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/jsonReturns 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.
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"}
Schema
{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false}
- Status
404Returned if the project is not found, or the calling user does not have permission to view it.
Get project roleGET /rest/api/2/project/{projectIdOrKey}/role/{id}
Returns the details for a given project role in a project.
Responses
- Status
200 - application/jsonReturns 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.
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"}]}
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
404Returned if the project or role is not found, or the calling user does not have permission to view it.
Add actor usersPOST /rest/api/2/project/{projectIdOrKey}/role/{id}
Adds an actor (user or group) to a project role.
For user actors, their usernames should be used.
Request
Example
{ "user" : ["admin"] } or
{ "group" : ["jira-developers"] }
Schema
{"type":"object","patternProperties":{".+":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}
Responses
- Status
200 - application/jsonReturns 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.
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"}]}
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
410Returned if none of the specified groups and users exist.
- Status
404Returned if the actor could not be added to the project role
Delete actorDELETE /rest/api/2/project/{projectIdOrKey}/role/{id}
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
parameter | type | description |
---|---|---|
user | string | the username of the user to remove from the project role |
group | string | the groupname to remove from the project role |
Responses
- Status
410Returned if none of the specified groups and users exist.
- Status
204Returned if the actor was successfully removed from the project role.
- Status
404Returned 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.
Set actorsPUT /rest/api/2/project/{projectIdOrKey}/role/{id}
Updates a project role to include the specified actors (users or groups). Can be also used to clear roles to not include any users or groups.
For user actors, their usernames should be used.
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/jsonReturns 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.
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"}]}
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
404Returned if the actor could not be added to the project role
api/2/project/{projectKeyOrId}/issuesecuritylevelscheme
Resource for associating permission schemes and projects.
Get issue security schemeGET /rest/api/2/project/{projectKeyOrId}/issuesecuritylevelscheme
Returns the issue security scheme for project.
Responses
- Status
200 - application/jsonReturned if the user has the administrator permission or if the scheme is used in a project in which the user has the administrative permission.
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"}]}
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
401Returned if the user is not logged in.
- Status
403Returned if the project is visible for calling user, but the user doesn't have administrative permissions
- Status
404Returned 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.
Get notification schemeGET /rest/api/2/project/{projectKeyOrId}/notificationscheme
Gets a notification scheme associated with the project. Follow the documentation of /notificationscheme/{id} resource for all details about returned value.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string |
Responses
- Status
200 - application/jsonReturned if the notification scheme exists and is visible for the calling user
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"}]},"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","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"}]},"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","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"}]}]}
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"},"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"},"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
401Returned if the user is not logged in.
- Status
403Returned 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
404Returned 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.
Assign permission schemePUT /rest/api/2/project/{projectKeyOrId}/permissionscheme
Assigns a permission scheme with a project.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string |
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/jsonShortened details of the newly associated permission scheme.
Example
{"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/10000","name":"Example permission scheme","description":"description"}
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"},"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"},"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
401Returned if the user is not logged in.
- Status
403Returned if the user does not have permissions to edit project's permission schemes. In practice the user needs to be a Jira administrator.
- Status
404Returned if the project or permission scheme is not found.
Get assigned permission schemeGET /rest/api/2/project/{projectKeyOrId}/permissionscheme
Gets a permission scheme assigned with a project.
Request
query parameters
parameter | type | description |
---|---|---|
expand | string |
Responses
- Status
200 - application/jsonThe associated permission scheme.
Example
{"id":10000,"self":"http://www.example.com/jira/rest/api/2/permissionscheme/10000","name":"Example permission scheme","description":"description"}
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"},"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"},"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
401Returned if the user is not logged in.
- Status
403Returned 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
404Returned if the project is not found (or the user does not have permissions to view the project).
api/2/project/{projectKeyOrId}/priorityscheme
Resource for associating priority schemes and projects.
Assign priority scheme
experimentalPUT /rest/api/2/project/{projectKeyOrId}/priorityscheme
Assigns project with priority scheme.
Priority scheme assign with migration is possible from the UI.
Operation will fail if migration is needed as a result of operation eg. there are issues with priorities invalid in the destination scheme.
All project keys associated with the priority scheme will only be returned if additional query parameter is provided expand=projectKeys
.
Request
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/jsonAffected priority scheme.
Example
{"expand":"projectKeys","self":"http://www.example.com/jira/rest/api/2/priorityschemes/4","id":4,"name":"4th priority scheme","description":"Some description","defaultOptionId":"13","optionIds":["11","12","13","14","15"],"defaultScheme":false,"projectKeys":["MNKY","HSP"]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/priority-scheme#","title":"Priority Scheme","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultOptionId":{"type":"string"},"optionIds":{"type":"array","items":{"type":"string"}},"defaultScheme":{"type":"boolean"},"projectKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"required":["defaultScheme"]}
- Status
400Returned if the request is not valid and the priority scheme could not be updated. Eg. migration is needed as a result of operation.
- Status
403Returned if the user does not have rights to assign priority schemes.
- Status
404Returned if project or priority scheme is not found.
Get assigned priority scheme
experimentalGET /rest/api/2/project/{projectKeyOrId}/priorityscheme
Gets a full representation of a priority scheme in JSON format used by specified project.
User must be global administrator or project administrator.
All project keys associated with the priority scheme will only be returned if additional query parameter is provided expand=projectKeys
.
Responses
- Status
200 - application/jsonReturned if the priority scheme exists and the user has permission to view it.
Example
{"expand":"projectKeys","self":"http://www.example.com/jira/rest/api/2/priorityschemes/4","id":4,"name":"4th priority scheme","description":"Some description","defaultOptionId":"13","optionIds":["11","12","13","14","15"],"defaultScheme":false,"projectKeys":["MNKY","HSP"]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/priority-scheme#","title":"Priority Scheme","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultOptionId":{"type":"string"},"optionIds":{"type":"array","items":{"type":"string"}},"defaultScheme":{"type":"boolean"},"projectKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"required":["defaultScheme"]}
- Status
403Returned if the user does not have rights to view priority scheme.
- Status
404Returned if project or priority scheme is not found.
Unassign priority scheme
experimentalDELETE /rest/api/2/project/{projectKeyOrId}/priorityscheme/{schemeId}
Unassigns project from priority scheme.
Operation will fail for defualt priority scheme, project is not found or project is not associated with provided priority scheme.
All project keys associated with the priority scheme will only be returned if additional query parameter is provided expand=projectKeys
.
Responses
- Status
200 - application/jsonAffected priority scheme.
Example
{"expand":"projectKeys","self":"http://www.example.com/jira/rest/api/2/priorityschemes/4","id":4,"name":"4th priority scheme","description":"Some description","defaultOptionId":"13","optionIds":["11","12","13","14","15"],"defaultScheme":false,"projectKeys":["MNKY","HSP"]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/priority-scheme#","title":"Priority Scheme","type":"object","properties":{"expand":{"type":"string"},"self":{"type":"string","format":"uri"},"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"defaultOptionId":{"type":"string"},"optionIds":{"type":"array","items":{"type":"string"}},"defaultScheme":{"type":"boolean"},"projectKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"required":["defaultScheme"]}
- Status
400Returned if the request is not valid and the priority scheme could not be updated. Eg. provided scheme is default priority scheme or project is not associated with scheme.
- Status
403Returned if the user does not have rights to assign priority schemes.
- Status
404Returned if project or priority scheme is not found.
api/2/project/{projectKeyOrId}/securitylevel
Provide security level information of the given project for the current user.
Get security levels for projectGET /rest/api/2/project/{projectKeyOrId}/securitylevel
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/jsonReturns a list of all security levels in a project for which the current user has access.
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"}]}
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
404Returned if the project is not found or the user does not have permissions to browse it.
api/2/project/{projectKeyOrId}/workflowscheme
Get workflow scheme for projectGET /rest/api/2/project/{projectKeyOrId}/workflowscheme
Returns the workflow scheme that is associated with requested project.
Responses
- Status
200 - application/jsonReturned if requested project exist and has associated workflow scheme, and the user has permission to see it.
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"}
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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"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
401Returned if the requested user is not authenticated.
- Status
403Returned if the requested user does not have permission to administer Jira.
- Status
404Returned if the requested project does not exist.
api/2/project/type
Get all project typesGET /rest/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. In case of anonymous checks if they can access at least one project.
Responses
- Status
200 - application/jsonReturns a list with all the project types defined on the Jira instance
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"}]
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}}
Get project type by keyGET /rest/api/2/project/type/{projectTypeKey}
Returns the project type with the given key. In case of anonymous checks if they can access at least one project.
Responses
- Status
200 - application/jsonReturns a representation of the project type with the given id
Example
{"key":"business","formattedKey":"Business","descriptionI18nKey":"Project type for business projects","icon":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAxOC4xLjEsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjxzdmcgdmVyc2lvbj0iMS4xIiBpZD0iTGF5ZXJfMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgeD0iMHB4IiB5PSIwcHgiDQoJIHZpZXdCb3g9IjAgMCAzMiAzMiIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgMzIgMzIiIHhtbDpzcGFjZT0icHJlc2VydmUiPg0KPGc+DQoJPHBhdGggZmlsbD0iIzY2NjY2NiIgZD0iTTE2LDBDNy4yLDAsMCw3LjIsMCwxNmMwLDguOCw3LjIsMTYsMTYsMTZjOC44LDAsMTYtNy4yLDE2LTE2QzMyLDcuMiwyNC44LDAsMTYsMHogTTI1LjcsMjMNCgkJYzAsMS44LTEuNCwzLjItMy4yLDMuMkg5LjJDNy41LDI2LjIsNiwyNC44LDYsMjNWOS44QzYsOCw3LjUsNi42LDkuMiw2LjZoMTMuMmMwLjIsMCwwLjQsMCwwLjcsMC4xbC0yLjgsMi44SDkuMg0KCQlDOSw5LjQsOC44LDkuNiw4LjgsOS44VjIzYzAsMC4yLDAuMiwwLjQsMC40LDAuNGgxMy4yYzAuMiwwLDAuNC0wLjIsMC40LTAuNHYtNS4zbDIuOC0yLjhWMjN6IE0xNS45LDIxLjNMMTEsMTYuNGwyLTJsMi45LDIuOQ0KCQlMMjYuNCw2LjhjMC42LDAuNywxLjIsMS41LDEuNywyLjNMMTUuOSwyMS4zeiIvPg0KPC9nPg0KPC9zdmc+","color":"#FFFFFF"}
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}
Get accessible project type by keyGET /rest/api/2/project/type/{projectTypeKey}/accessible
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/jsonReturns a representation of the project type with the given id
Example
{"key":"business","formattedKey":"Business","descriptionI18nKey":"Project type for business projects","icon":"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAxOC4xLjEsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjxzdmcgdmVyc2lvbj0iMS4xIiBpZD0iTGF5ZXJfMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgeD0iMHB4IiB5PSIwcHgiDQoJIHZpZXdCb3g9IjAgMCAzMiAzMiIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgMzIgMzIiIHhtbDpzcGFjZT0icHJlc2VydmUiPg0KPGc+DQoJPHBhdGggZmlsbD0iIzY2NjY2NiIgZD0iTTE2LDBDNy4yLDAsMCw3LjIsMCwxNmMwLDguOCw3LjIsMTYsMTYsMTZjOC44LDAsMTYtNy4yLDE2LTE2QzMyLDcuMiwyNC44LDAsMTYsMHogTTI1LjcsMjMNCgkJYzAsMS44LTEuNCwzLjItMy4yLDMuMkg5LjJDNy41LDI2LjIsNiwyNC44LDYsMjNWOS44QzYsOCw3LjUsNi42LDkuMiw2LjZoMTMuMmMwLjIsMCwwLjQsMCwwLjcsMC4xbC0yLjgsMi44SDkuMg0KCQlDOSw5LjQsOC44LDkuNiw4LjgsOS44VjIzYzAsMC4yLDAuMiwwLjQsMC40LDAuNGgxMy4yYzAuMiwwLDAuNC0wLjIsMC40LTAuNHYtNS4zbDIuOC0yLjhWMjN6IE0xNS45LDIxLjNMMTEsMTYuNGwyLTJsMi45LDIuOQ0KCQlMMjYuNCw2LjhjMC42LDAuNywxLjIsMS41LDEuNywyLjNMMTUuOSwyMS4zeiIvPg0KPC9nPg0KPC9zdmc+","color":"#FFFFFF"}
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
401A response status of 401 indicates that there is not a logged in user and therefore this operation can't be performed
- Status
404A response status of 404 indicates that the project type is not accessible for the logged in user
api/2/projectCategory
Get all project categoriesGET /rest/api/2/projectCategory
Returns all project categories
Responses
- Status
200 - application/jsonReturns a list of project categories.
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"}]
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
500Returned if an error occurs while retrieving the list of projects.
Create project categoryPOST /rest/api/2/projectCategory
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/jsonReturned if the project category is created successfully.
Example
{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10100","id":"10100","name":"CREATED","description":"Created Project Category"}
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
401Returned if the caller is not logged in so does not have permission to create project categories.
- Status
403Returned if the caller is authenticated and does not have permission to create project categories (is not global admin).
- Status
409Returned if a project category with the given name already exists.
Get project category by idGET /rest/api/2/projectCategory/{id}
Contains a representation of a project category in JSON format.
Responses
- Status
200 - application/jsonReturned if the project category exists. Contains representation of a project category in JSON format.
Example
{"self":"http://www.example.com/jira/rest/api/2/projectCategory/10000","id":"10000","name":"FIRST","description":"First Project Category"}
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
404Returned if the project category does not exist or the currently authenticated user does not have permission to view it.
Remove project categoryDELETE /rest/api/2/projectCategory/{id}
Delete a project category.
Responses
- Status
401Returned if the caller is not logged in so does not have permission to delete project categories.
- Status
204Returned if the project category is successfully deleted.
- Status
403Returned if the caller is authenticated and does not have permission to delete project categories (is not global admin).
- Status
404Returned if the project category does not exist or the currently authenticated user does not have permission to view it.
Update project categoryPUT /rest/api/2/projectCategory/{id}
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
200Returned 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
401Returned if the caller is not logged in so does not have permission to change project categories.
- Status
403Returned if the caller is authenticated and does not have permission to change project categories (is not global admin).
- Status
404Returned if the project category does not exist or the currently authenticated user does not have permission to view it.
api/2/projects/picker
Search for projectsGET /rest/api/2/projects/picker
Returns a list of projects visible to the user where project name and/or key is matching the given query.
Passing an empty (or whitespace only) query will match no projects. The project matches will contain a field with the query highlighted.
The number of projects returned can be controlled by passing a value for "maxResults", but a hard limit of no more than 100 projects is enforced. The projects are wrapped in a single response object that contains a header for use in the picker, specifically Showing X of Y matching projects and the total number of matches for the query.
Request
query parameters
parameter | type | description |
---|---|---|
query | string Default: | a sequence of characters expected to be found in the word-prefix of project name and/or key. |
maxResults | int Default: 0 | maximum number of matches to return. Zero means a default limit of 100 and negative numbers return no results. |
allowEmptyQuery | boolean Default: false | if true, and the query is empty, the method will return first results limited to the value of "maxResults" or default limit of 100. |
Responses
- Status
200 - application/jsonReturned even when no projects match the given query.
Example
{"projects":[{"html":"Example <strong>pro</strong>ject name (EXAM)","name":"Example project name","key":"EXAM","id":"10000","avatar":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10000"},{"html":"<strong>Pro</strong>ject name (<strong>PRO</strong>J)","name":"Project name","key":"PROJ","id":"10001","avatar":"http://www.example.com/jira/secure/projectavatar?size=xsmall&pid=10001"}],"total":5,"header":"Showing 2 of 5 matching projects"}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/project-picker-result-wrapper#","title":"Project Picker Result Wrapper","type":"object","properties":{"projects":{"type":"array","items":{"title":"Project Picker Item","type":"object","properties":{"html":{"type":"string"},"name":{"type":"string"},"key":{"type":"string"},"id":{"type":"string"},"avatar":{"type":"string"}},"additionalProperties":false}},"total":{"type":"integer"},"header":{"type":"string"}},"additionalProperties":false}
api/2/projectvalidate
Get projectGET /rest/api/2/projectvalidate/key
Validates a project key.
Request
query parameters
parameter | type | description |
---|---|---|
key | string | the project key |
Responses
- Status
200 - application/jsonReturns an ErrorCollection containing any validation errors for the project key.
Example
{"errorMessages":[],"errors":{"projectKey":"A project with that project key already exists."}}
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}
- Status
401Returned if the user is not logged in.
api/2/reindex
REST resource for starting/stopping/querying indexing.
ReindexPOST /rest/api/2/reindex
Kicks off a reindex. Need Admin permissions to perform this reindex.
Request
query parameters
parameter | type | description |
---|---|---|
type | string | Case insensitive String indicating type of reindex. If omitted, then defaults to BACKGROUND_PREFERRED. |
indexComments | boolean Default: false | Indicates that comments should also be reindexed. Not relevant for foreground reindex, where comments are always reindexed. |
indexChangeHistory | boolean Default: false | Indicates that changeHistory should also be reindexed. Not relevant for foreground reindex, where changeHistory is always reindexed. |
indexWorklogs | boolean Default: false | Indicates that worklogs should also be reindexed. Not relevant for foreground reindex, where worklogs are always reindexed. |
Responses
- Status
202 - application/jsonReturns a representation of the progress of the re-index operation.
Example
{"progressUrl":"http://localhost:8080/jira","currentProgress":0,"currentSubTask":"Currently reindexing Change History","type":"FOREGROUND","submittedTime":"2024-06-26T10:20:31.124+0000","startTime":"2024-06-26T10:20:31.124+0000","finishTime":"2024-06-26T10:20:31.124+0000","success":true}
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"]}
Get reindex infoGET /rest/api/2/reindex
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
parameter | type | description |
---|---|---|
taskId | long | the id of an indexing task you wish to obtain details on. If omitted, then defaults to the standard behaviour and returns information on the active reindex task, or the last task to run if no reindex is taking place. . If there is no reindexing task with that id then a 404 is returned. |
Responses
- Status
200 - application/jsonReturns a representation of the progress of the re-index operation.
Example
{"progressUrl":"http://localhost:8080/jira","currentProgress":0,"currentSubTask":"Currently reindexing Change History","type":"FOREGROUND","submittedTime":"2024-06-26T10:20:31.124+0000","startTime":"2024-06-26T10:20:31.124+0000","finishTime":"2024-06-26T10:20:31.124+0000","success":true}
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
404Returned if there is no re-indexing task found
Reindex issuesPOST /rest/api/2/reindex/issue
Reindexes one or more individual issues. Indexing is performed synchronously - the call returns when indexing of the issues has completed or a failure occurs.
Use either explicitly specified issue IDs or a JQL query to select issues to reindex.
Request
query parameters
parameter | type | description |
---|---|---|
issueId | string | the IDs or keys of one or more issues to reindex. |
indexComments | boolean Default: false | Indicates that comments should also be reindexed. |
indexChangeHistory | boolean Default: false | Indicates that changeHistory should also be reindexed. |
indexWorklogs | boolean Default: false | Indicates that worklogs should also be reindexed. |
Responses
- Status
202 - application/jsonReturns a representation of the progress of the re-index operation.
Example
{"progressUrl":"http://localhost:8080/jira","currentProgress":0,"currentSubTask":"Currently reindexing Change History","type":"FOREGROUND","submittedTime":"2024-06-26T10:20:31.124+0000","startTime":"2024-06-26T10:20:31.124+0000","finishTime":"2024-06-26T10:20:31.124+0000","success":true}
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"]}
Get reindex progressGET /rest/api/2/reindex/progress
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
parameter | type | description |
---|---|---|
taskId | long | the id of an indexing task you wish to obtain details on. If omitted, then defaults to the standard behaviour and returns information on the active reindex task, or the last task to run if no reindex is taking place. . If there is no reindexing task with that id then a 404 is returned. |
Responses
- Status
200 - application/jsonReturns a representation of the progress of the re-index operation.
Example
{"progressUrl":"http://localhost:8080/jira","currentProgress":0,"currentSubTask":"Currently reindexing Change History","type":"FOREGROUND","submittedTime":"2024-06-26T10:20:31.124+0000","startTime":"2024-06-26T10:20:31.124+0000","finishTime":"2024-06-26T10:20:31.124+0000","success":true}
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
404Returned if there is no re-indexing task found
api/2/reindex/request
REST resource for querying and executing reindex requests.
Process requestsPOST /rest/api/2/reindex/request
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/jsonReturns an array containing the reindex request IDs being processed.
Schema
{"type":"array","items":{"type":"integer"}}
Get progressGET /rest/api/2/reindex/request/{requestId}
Retrieves the progress of a single reindex request.
Responses
- Status
200 - application/jsonDetails and status of the reindex request.
Example
{"id":10500,"status":"PENDING","type":"IMMEDIATE","requestTime":"2024-06-26T10:20:31.120+0000"}
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
404Returned if no such reindex request exists.
Get progress bulkGET /rest/api/2/reindex/request/bulk
Retrieves the progress of a multiple reindex requests. Only reindex requests that actually exist will be returned in the results.
Request
query parameters
parameter | type | description |
---|---|---|
requestId | string | the reindex request IDs. |
Responses
- Status
200 - application/jsonDetails and status of the reindex request.
Example
{"id":10500,"status":"PENDING","type":"IMMEDIATE","requestTime":"2024-06-26T10:20:31.120+0000"}
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
Get resolutionsGET /rest/api/2/resolution
Returns a list of all resolutions.
Responses
- Status
200 - application/jsonReturned if the resolutions exists and the user has permission to view them. Contains a full representation of the resolution in JSON format.
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"}]
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}}
Get resolutionGET /rest/api/2/resolution/{id}
Returns a resolution.
Responses
- Status
200 - application/jsonReturned if the resolution exists and the user has permission to view it. Contains a full representation of the resolution in JSON format.
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"}
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
404Returned if the resolution does not exist or the user does not have permission to view it.
Get paginated resolutions
experimentalGET /rest/api/2/resolution/page
Returns paginated list of filtered resolutions
Request
query parameters
parameter | type | description |
---|---|---|
startAt | long Default: 0 | the index of the first status to return |
maxResults | int Default: 100 | the maximum number of statuses to return |
query | string Default: | the string that status names will be matched with |
Responses
- Status
200 - application/jsonReturns paginated list of resolutions
Example
{"self":"http://www.example.com/jira/rest/api/2//resolution/page?startAt=0&maxResults=2","nextPage":"http://www.example.com/jira/rest/api/2//resolution/page?startAt=2&maxResults=2","maxResults":2,"startAt":0,"total":5,"isLast":false,"values":[{"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"}]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/page-of-resolution#","title":"Page of Resolution","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":"Resolution","type":"object","properties":{"self":{"type":"string"},"id":{"type":"string"},"description":{"type":"string"},"iconUrl":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false,"required":["maxResults","startAt"]}
api/2/role
Get project rolesGET /rest/api/2/role
Get all the ProjectRoles available in Jira. Currently this list is global.
Responses
- Status
200Returned if the user is authenticated
Example
{"name":"Developers","id":10360,"description":"A project role that represents developers in a project"}
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
401Returned if you do not have permissions or you are not logged in.
- Status
403Returned if the requesting user is not an admin or a sysadmin.
Create project rolePOST /rest/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"}},"additionalProperties":false}
Responses
- Status
200Returned if the user is authenticated
Example
{"name":"Developers","id":10360,"description":"A project role that represents developers in a project"}
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
400Returned if the request json does not have a name field or the name field is invalid (empty or starts or ends with whitespace)
- Status
401Returned if you are not logged in.
- Status
403Returned if you do not have permissions to create a role.
- Status
409Returned if a role with given name already exists.
Get project roles by idGET /rest/api/2/role/{id}
Get a specific ProjectRole available in Jira.
Responses
- Status
200Returned if the user is authenticated
Example
{"name":"Developers","id":10360,"description":"A project role that represents developers in a project"}
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
401Returned if you do not have permissions or you are not logged in.
- Status
403Returned if the requesting user is not an admin or a sysadmin.
- Status
404Returned if the role with the given id does not exist.
Partial update project rolePOST /rest/api/2/role/{id}
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"}},"additionalProperties":false}
Responses
- Status
200Returned if the update was successful
Example
{"name":"Developers","id":10360,"description":"A project role that represents developers in a project"}
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
400Returned when both name and description are not given or name field is invalid (empty or starts or ends with whitespace).
- Status
401Returned if the requesting user is not logged in.
- Status
403Returned if the requesting user is not an admin or a sysadmin.
- Status
404Returned if the role with the given id does not exist.
Fully update project rolePUT /rest/api/2/role/{id}
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"}},"additionalProperties":false}
Responses
- Status
200Returned if the update was successful
Example
{"name":"Developers","id":10360,"description":"A project role that represents developers in a project"}
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
400Returned when name or description is not given or the name field is invalid (empty or starts or ends with whitespace)
- Status
401Returned if the requesting user is not logged in.
- Status
403Returned if the requesting user is not an admin or a sysadmin.
- Status
404Returned if the role with the given id does not exist.
Delete project roleDELETE /rest/api/2/role/{id}
Deletes a role. May return 403 in the future
Request
query parameters
parameter | type | description |
---|---|---|
swap | long | if given, removes a role even if it is used in scheme by replacing the role with the given one |
Responses
- Status
400Returned if given role with given swap id does not exist.
- Status
401Returned if the requesting user is not logged in.
- Status
204Returned if the delete was successful.
- Status
403Returned if the requesting user is not an admin or a sysadmin.
- Status
404Returned if the role with the given id does not exist.
- Status
409Returned if the project role is used in schemes and roleToSwap query parameter is not given.
Get project role actors for roleGET /rest/api/2/role/{id}/actors
Gets default actors for the given role.
Responses
- Status
200Returned if the user is authenticated
Example
{"actors":[{"id":10240,"displayName":"jira-developers","type":"atlassian-group-role-actor","name":"jira-developers"}]}
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
401Returned if the requesting user is not logged in.
- Status
403Returned if the requesting user is not an admin or a sysadmin.
- Status
404Returned if the role with the given id does not exist.
Add project role actors to rolePOST /rest/api/2/role/{id}/actors
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
200Returned if the update was successful
Example
{"actors":[{"id":10240,"displayName":"jira-developers","type":"atlassian-group-role-actor","name":"jira-developers"}]}
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
400Returned if user and group are both given or none are given or group or user in their respective lists does not exist.
- Status
401Returned if the requesting user is not logged in.
- Status
403Returned if the requesting user is not an admin or a sysadmin.
- Status
404Returned if the role with the given id does not exist.
Delete project role actors from roleDELETE /rest/api/2/role/{id}/actors
Removes default actor from the given role.
Request
query parameters
parameter | type | description |
---|---|---|
user | string | if given, removes an actor from given role |
group | string | if given, removes an actor from given role |
Responses
- Status
200Returned if the update was successful.
Example
{"actors":[{"id":10240,"displayName":"jira-developers","type":"atlassian-group-role-actor","name":"jira-developers"}]}
- Status
400Returned if user and group are not given, both user and group are given or provided group or user does not exist.
- Status
401Returned if the requesting user is not logged in.
- Status
403Returned if the requesting user is not an admin or a sysadmin.
- Status
404Returned if the role with the given id does not exist.
api/2/screens
Get all screensGET /rest/api/2/screens
Gets available field screens
Request
query parameters
parameter | type | description |
---|---|---|
startAt | string | offset from which the response starts |
maxResults | string | amount of field screens to return |
expand | string | |
search | string |
Responses
- Status
200List of available field screens
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/list-of-screen#","title":"List of Screen","type":"array","items":{"title":"Screen","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"fieldScreenSchemes":{"type":"array","items":{"title":"Screen Scheme","type":"object","properties":{"id":{"type":"integer"},"description":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"fieldScreenWorkflows":{"type":"array","items":{"title":"Screen Workflow","type":"object","properties":{"name":{"type":"string"},"actions":{"type":"array","items":{"title":"Action Descriptor","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"firstStep":{"type":"integer"},"global":{"type":"boolean"}},"additionalProperties":false,"required":["id","global"]}},"mode":{"type":"string"}},"additionalProperties":false}},"deletable":{"type":"boolean"},"fieldScreenTabList":{"type":"array","items":{"title":"Screenable Tab","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"additionalProperties":false}},"expand":{"type":"string"}},"additionalProperties":false}}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/screens-with-pagination#","title":"Screens With Pagination","type":"object","properties":{"startAt":{"type":"integer"},"maxResults":{"type":"integer"},"total":{"type":"integer"},"screens":{"type":"array","items":{"title":"Screen","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string"},"fieldScreenSchemes":{"type":"array","items":{"title":"Screen Scheme","type":"object","properties":{"id":{"type":"integer"},"description":{"type":"string"},"name":{"type":"string"}},"additionalProperties":false}},"fieldScreenWorkflows":{"type":"array","items":{"title":"Screen Workflow","type":"object","properties":{"name":{"type":"string"},"actions":{"type":"array","items":{"title":"Action Descriptor","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"firstStep":{"type":"integer"},"global":{"type":"boolean"}},"additionalProperties":false,"required":["id","global"]}},"mode":{"type":"string"}},"additionalProperties":false}},"deletable":{"type":"boolean"},"fieldScreenTabList":{"type":"array","items":{"title":"Screenable Tab","type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"additionalProperties":false}},"expand":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}
- Status
400Returned if offset or count params cannot be parsed
- Status
401Returned if you do not have administrator permissions
Get fields to addGET /rest/api/2/screens/{screenId}/availableFields
Gets available fields for screen. i.e ones that haven't already been added.
Responses
- Status
200List 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
400Returned if screen does not exist
- Status
401Returned if you do not have permissions
Get all tabsGET /rest/api/2/screens/{screenId}/tabs
Returns a list of all tabs for the given screen
Request
query parameters
parameter | type | description |
---|---|---|
projectKey | string | the key of the project; this parameter is optional |
Responses
- Status
200 - application/jsonContains 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
400Returned if screen does not exist
- Status
401Returned if you do not have permissions
Add tabPOST /rest/api/2/screens/{screenId}/tabs
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/jsonNewly created tab in JSON.
Example
{"id":10000,"name":"Fields Tab"}
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
400Returned if screen does not exist or tab name is invalid
- Status
401Returned if you do not have permissions
Rename tabPUT /rest/api/2/screens/{screenId}/tabs/{tabId}
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/jsonModified tab in JSON.
Example
{"id":10000,"name":"Fields Tab"}
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
400Returned if screen does not exist or tab name is invalid
- Status
401Returned if you do not have permissions
Delete tabDELETE /rest/api/2/screens/{screenId}/tabs/{tabId}
Deletes tab to give screen
Responses
- Status
201Successfully deleted tab
- Status
400Returned if screen or tab does not exist
- Status
401Returned if you do not have permissions
- Status
412Returned if tab can not be deleted due to a pre-condition (there has to be at least one tab left)
Add fieldPOST /rest/api/2/screens/{screenId}/tabs/{tabId}/fields
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
200Newly added field as json
Example
{"id":"summary","name":"Summary","showWhenEmpty":false}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/screenable-field#","title":"Screenable Field","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"showWhenEmpty":{"type":"boolean"}},"additionalProperties":false,"required":["showWhenEmpty"]}
- Status
400Returned if screen,tab or field does not exist.
- Status
401Returned if you do not have permissions
Get all fieldsGET /rest/api/2/screens/{screenId}/tabs/{tabId}/fields
Gets all fields for a given tab
Request
query parameters
parameter | type | description |
---|---|---|
projectKey | string | the key of the project; this parameter is optional |
Responses
- Status
200List 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
400Returned if screen or tab does not exist
- Status
401Returned if you do not have permissions
Remove fieldDELETE /rest/api/2/screens/{screenId}/tabs/{tabId}/fields/{id}
Removes field from given tab
Responses
- Status
201Successfully removed field from tab
- Status
400Returned if screen or tab does not exist
- Status
401Returned if you do not have permissions
Move fieldPOST /rest/api/2/screens/{screenId}/tabs/{tabId}/fields/{id}/move
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
201Successfully moved tab
- Status
400Returned if screen or tab does not exist. Or move cooridinates invalid.
- Status
401Returned if you do not have permissions
Update show when empty indicatorPUT /rest/api/2/screens/{screenId}/tabs/{tabId}/fields/{id}/updateShowWhenEmptyIndicator/{newValue}
Update 'showWhenEmptyIndicator' for given field on screen
Responses
- Status
400Returned if screen or tab does not exist
- Status
401Returned if you do not have permissions
- Status
204Returned if operation was successful
- Status
403Returned if XSRF check failed
Move tabPOST /rest/api/2/screens/{screenId}/tabs/{tabId}/move/{pos}
Moves tab position
Responses
- Status
201Successfully moved tab
- Status
400Returned if screen or tab does not exist
- Status
401Returned if you do not have permissions
Add field to default screenPOST /rest/api/2/screens/addToDefault/{fieldId}
Adds field or custom field to the default tab
Responses
- Status
201Successfully added field to default screen / default tab
- Status
400Returned if screen, tab or field does not exist or field is already present on a selected tab
- Status
401Returned if you do not have administrator permissions
api/2/search
Resource for searches.
Search using search requestPOST /rest/api/2/search
Performs a search using JQL.
Request
Example
{"jql":"project = HSP","startAt":0,"maxResults":15,"fields":["summary","status","assignee"]}
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":"boolean"}},"additionalProperties":false}
Responses
- Status
200 - application/jsonReturns a JSON representation of the search results.
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"}]}
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"},"fields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"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"},"description":{"type":"string"},"opsbarSequence":{"type":"integer"},"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},"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"},"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"}},"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"},"fieldId":{"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}
- Status
400Returned if there is a problem with the JQL query.
SearchGET /rest/api/2/search
Searches for issues using JQL.
Sorting
the jql
parameter is a full JQL
expression, and includes an ORDER BY
clause.
The fields
param (which can be specified multiple times) gives a comma-separated list of fields
to include in the response. This can be used to retrieve a subset of fields.
A particular field can be excluded by prefixing it with a minus.
By default, only navigable (*navigable
) fields are returned in this search resource. Note: the default is different
in the get-issue resource -- the default there all fields (*all
).
*all
- include all fields*navigable
- include just navigable fieldssummary,comment
- include just the summary and comments-description
- include navigable fields except the description (the default is*navigable
for search)*all,-comment
- include everything except comments
GET vs POST: If the JQL query is too large to be encoded as a query param you should instead POST to this resource.
Expanding Issues in the Search Result: It is possible to expand the issues returned by directly specifying the expansion on the expand parameter passed in to this resources.
For instance, to expand the "changelog" for all the issues on the search result, it is neccesary to specify "changelog" as one of the values to expand.
Request
query parameters
parameter | type | description |
---|---|---|
jql | string | a JQL query string |
startAt | int | the index of the first issue to return (0-based) |
maxResults | int | the maximum number of issues to return (defaults to 50). The maximum allowable value is dictated by the Jira property 'jira.search.views.default.max'. If you specify a value that is higher than this number, your search results will be truncated. |
validateQuery | boolean Default: true | whether to validate the JQL query |
fields | string | the list of fields to return for each issue. By default, all navigable fields are returned. |
expand | string | A comma-separated list of the parameters to expand. |
Responses
- Status
200 - application/jsonReturns a JSON representation of the search results.
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"}]}
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"},"fields":{"type":"object","patternProperties":{".+":{}},"additionalProperties":false},"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"},"description":{"type":"string"},"opsbarSequence":{"type":"integer"},"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},"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"},"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"}},"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"},"fieldId":{"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"},"params":{"type":"object","patternProperties":{".+":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false}
- Status
400Returned if there is a problem with the JQL query.
api/2/securitylevel
Get issuesecuritylevelGET /rest/api/2/securitylevel/{id}
Returns a full representation of the security level that has the given id.
Responses
- Status
200 - application/jsonReturned if the issue type exists and is visible by the calling user.
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"}
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
404Returned if the issue type does not exist, or is not visible to the calling user.
api/2/serverInfo
Get server infoGET /rest/api/2/serverInfo
Returns general information about the current Jira server.
Request
query parameters
parameter | type | description |
---|---|---|
doHealthCheck | boolean |
Responses
- Status
200 - application/jsonReturns a full representation of the server info in JSON format
Example
{"baseUrl":"http://localhost:8080/jira","version":"5.0-SNAPSHOT","versionNumbers":[5,0,0],"buildNumber":581,"buildDate":"2024-06-26T10:20:30.812+0000","serverTime":"2024-06-26T10:20:30.812+0000","scmInfo":"1f51473f5c7b75c1a69a0090f4832cdc5053702a","buildPartnerName":"Example Partner Co.","serverTitle":"My Shiny New Jira Server"}
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"},"databaseBuildNumber":{"type":"integer"},"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
Set base u r lPUT /rest/api/2/settings/baseUrl
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"}
Get issue navigator default columnsGET /rest/api/2/settings/columns
Returns the default system columns for issue navigator. Admin permission will be required.
Responses
- Status
200 - application/jsonReturns 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
500Returned if an error occurs while retrieving the column configuration.
- Status
403Returned if the user does not have admin permission
Set issue navigator default columnsPUT /rest/api/2/settings/columns
Sets the default system columns for issue navigator. Admin permission will be required.
Request
Responses
- Status
200Returned when the columns is saved successfully
- Status
500Returned if an error occurs while retrieving the column configuration.
api/2/status
Get statusesGET /rest/api/2/status
Returns a list of all statuses
Responses
- Status
200 - application/jsonReturns a list of all Jira issue statuses in JSON format, that are visible to the user.
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"}}]
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
404Returned if the requested issue status is not found, or the user does not have permission to view it.
Get statusGET /rest/api/2/status/{idOrName}
Returns a full representation of the Status having the given id or name.
Responses
- Status
200 - application/jsonReturns a full representation of a Jira issue status in JSON format.
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"}}
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
404Returned if the requested issue status is not found, or the user does not have permission to view it.
Get paginated statuses
experimentalGET /rest/api/2/status/page
Returns paginated list of filtered statuses
Request
query parameters
parameter | type | description |
---|---|---|
startAt | long Default: 0 | the index of the first status to return |
maxResults | int Default: 100 | the maximum number of statuses to return |
query | string Default: | the string that status names will be matched with |
projectIds | string | the list of project ids to filter statuses |
issueTypeIds | string | the list of issue type ids to filter statuses |
Responses
- Status
200 - application/jsonReturns paginated list of statuses
Example
{"self":"http://www.example.com/jira/rest/api/2//status/page?startAt=0&maxResults=2","nextPage":"http://www.example.com/jira/rest/api/2//status/page?startAt=2&maxResults=2","maxResults":2,"startAt":0,"total":5,"isLast":false,"values":[{"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"}}]}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/page-of-status#","title":"Page of Status","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":"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":["maxResults","startAt"]}
api/2/statuscategory
Get status categoriesGET /rest/api/2/statuscategory
Returns a list of all status categories
Responses
- Status
200 - application/jsonReturns a list of all Jira issue status categories in JSON format, that are visible to the user.
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"}]
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
404Returned if no status categories are found, or the user does not have permission to view them.
Get status categoryGET /rest/api/2/statuscategory/{idOrKey}
Returns a full representation of the StatusCategory having the given id or key
Responses
- Status
200 - application/jsonReturns a full representation of a Jira issue status category in JSON format.
Example
{"self":"http://localhost:8090/jira/rest/api/2.0/statuscategory/1","id":1,"key":"in-flight","colorName":"yellow","name":"In Progress"}
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
404Returned if the requested issue status category is not found, or the user does not have permission to view it.
api/2/terminology/entries
Enables customizing the default words "epic" and "sprint".
Get all terminology entries
experimentalGET /rest/api/2/terminology/entries
Returns the list of all defined names for the default words "epic" and "sprint".
Responses
- Status - application/json
Set terminology entries
experimentalPOST /rest/api/2/terminology/entries
Change epic/sprint names from {"originalName"} to {"newName"}. The {"newName"} will be displayed in Jira instead of {"originalName"}.
{"originalName"} must be equal to "epic" or "sprint". There can be only one entry per unique {"originalName"}.
{"newName"} can only consist of alphanumeric characters and spaces e.g. {"newName": "iteration number 2"}.
{"newName"} must be between 1 to 100 characters. It can't use the already defined {"newName"} values or restricted JQL words .
To reset {"newName"} to the default value, enter the {"originalName"} value as the value for {"newName"}. For example, if you want to return to {"originalName": "sprint"}, enter {"newName": "sprint"}.
Request
Example
[{"originalName":"sprint","newName":"iteration","newNamePlural":"iterations"},{"originalName":"epic","newName":"odyssey","newNamePlural":"odysseys"}]
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/collection-of-terminology-request#","title":"Collection of Terminology Request","type":"array","items":{"title":"Terminology Request","type":"object","properties":{"originalName":{"type":"string"},"newName":{"type":"string"},"newNamePlural":{"type":"string"}},"additionalProperties":false}}
Responses
- Status
400Returned if the provided data isn't valid.
- Status
403Returned if the user doesn't have admin permissions.
- Status
404Returned if the feature is turned off via a feature flag.
Get terminology entry
experimentalGET /rest/api/2/terminology/entries/{originalName}
Returns epic or sprint name as specified in the {originalName} path param.
Responses
- Status
404Returned if there is no epic or sprint name defined in the {originalName}.
api/2/universal_avatar
Get avatarsGET /rest/api/2/universal_avatar/type/{type}/owner/{owningObjectId}
Responses
- Status - application/json
Create avatar from temporaryPOST /rest/api/2/universal_avatar/type/{type}/owner/{owningObjectId}/avatar
Request
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/avatar-cropping#","title":"Avatar Cropping","type":"object","properties":{"cropperWidth":{"type":"integer"},"cropperOffsetX":{"type":"integer"},"cropperOffsetY":{"type":"integer"},"url":{"type":"string"},"needsCropping":{"type":"boolean"}},"additionalProperties":false,"required":["cropperWidth","cropperOffsetX","cropperOffsetY","needsCropping"]}
Responses
- Status - application/json
Delete avatarDELETE /rest/api/2/universal_avatar/type/{type}/owner/{owningObjectId}/avatar/{id}
Deletes avatar
Responses
- Status - application/json
Store temporary avatarPOST /rest/api/2/universal_avatar/type/{type}/owner/{owningObjectId}/temp
Creates temporary avatar
Request
query parameters
parameter | type | description |
---|---|---|
filename | string | name of file being uploaded |
size | long | size of file |
Responses
- Status - application/json
Store temporary avatar using multi partPOST /rest/api/2/universal_avatar/type/{type}/owner/{owningObjectId}/temp
Responses
- Status - text/html
api/2/upgrade
REST resource for executing and querying delayed upgrades.
Get upgrade resultGET /rest/api/2/upgrade
Returns the result of the last upgrade task. Returns {@link javax.ws.rs.core.Response#seeOther(java.net.URI)} if still running.
Responses
- Status
200 - application/jsonReturned if the upgrade is complete
Example
{"startTime":"2024-06-26T10:20:31.620+0000","duration":2001,"outcome":"SUCCESS","message":""}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/upgrade-result#","title":"Upgrade Result","type":"object","properties":{"startTime":{"type":"string"},"duration":{"type":"integer"},"outcome":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}
- Status
303Returned if the upgrade task is still running.
- Status
404Returned if no prior upgrade task exists.
Run upgrades nowPOST /rest/api/2/upgrade
Runs any pending delayed upgrade tasks. Need Admin permissions to do this.
Responses
- Status - application/json
api/2/user
Create user
experimentalPOST /rest/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"},"active":{"type":"boolean"},"applicationKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}
Responses
- Status
201Returned if the user was created.
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"}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/user#","title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"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
400Returned if the request is invalid.
- Status
401Returned if the user is not authenticated.
- Status
500Returned if the user was not created because of other error.
- Status
403Returned if the caller user does not have permission to create the user.
Update user
experimentalPUT /rest/api/2/user
Modify user. The "value" fields present will override the existing value. Fields skipped in request will not be changed.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | the username |
key | string | user key |
Example
{"name":"eddie","emailAddress":"eddie@atlassian.com","displayName":"Eddie of Atlassian","active":true}
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"},"active":{"type":"boolean"},"applicationKeys":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}
Responses
- Status
200 - application/jsonReturned if the user exists and the caller has permission to edit it.
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"}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/user#","title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"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
400Returned if the request is invalid.
- Status
401Returned if the user is not authenticated.
- Status
403Returned if the caller user does not have permission to edit the user.
- Status
404Returned if the caller does have permission to edit the user but the user does not exist.
Remove user
experimentalDELETE /rest/api/2/user
Removes user and its references (like project roles associations, watches, history).
Note: user references will not be removed if multiple User Directories are used and there is a user with
the same name existing in another directory (shadowing user).
Request
query parameters
parameter | type | description |
---|---|---|
username | string | the username |
key | string | user key |
Responses
- Status
400Returned if the request is invalid or some other server error occurred.
- Status
401Returned if the user is not authenticated.
- Status
204Returned if the user was deleted successfully.
- Status
403Returned if the caller does not have permission to remove the user.
- Status
404Returned if the caller does have permission to remove user but the user does not exist.
Get userGET /rest/api/2/user
Returns a user. This resource cannot be accessed anonymously.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | the username |
key | string | user key |
includeDeleted | boolean Default: false | whether deleted users should be returned (flag available to users with global ADMIN rights) |
Responses
- Status
200 - application/jsonReturns a full representation of a Jira user in JSON format.
Example
{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","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","lastLoginTime":"2023-08-30T16:37:01+1000"}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/user#","title":"User","type":"object","properties":{"self":{"type":"string","format":"uri"},"key":{"type":"string"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"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
401Returned if the current user is not authenticated.
- Status
403Returned if the caller does not have permission to perform operation.
- Status
404Returned if the requested user is not found.
Add user to application
experimentalPOST /rest/api/2/user/application
Add user to given application. Admin permission will be required to perform this operation.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | username |
applicationKey | string | application key |
Responses
- Status
200Returned if the user exists, the caller has permission to add user to application and user was successfully added to application.
- Status
400Returned if the request is invalid.
- Status
401Returned if the user is not authenticated.
- Status
403Returned if the caller user does not have permission to add user to application.
Remove user from application
experimentalDELETE /rest/api/2/user/application
Remove user from given application. Admin permission will be required to perform this operation.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | username |
applicationKey | string | application key |
Responses
- Status
400Returned if the request is invalid.
- Status
401Returned if the user is not authenticated.
- Status
204Returned if the user exists, the caller has permission to remove user from application and the user was successfully removed from application.
- Status
403Returned if the caller user does not have permission to remove user from application.
Find bulk assignable usersGET /rest/api/2/user/assignable/multiProjectSearch
Returns a list of users that match the search string and can be assigned issues for all the given projects.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | the username |
projectKeys | string | the keys of the projects we are finding assignable users for, comma-separated |
maxResults | int Default: 50 | the maximum number of users to return (defaults to 50). The maximum allowed value is 100. If you specify a value that is higher than this number, your search results will be truncated. |
Responses
- Status
200 - application/jsonReturns a full representation of a Jira user in JSON format.
Example
[{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},{"self":"http://www.example.com/jira/rest/api/2/user?username=andrew","key":"JIRAUSER10200","name":"andrew","emailAddress":"andrew@example.com","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,"deleted":false,"timeZone":"Europe/Warsaw","locale":"en_UK","lastLoginTime":"2023-08-30T16:37:01+1000"}]
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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"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
404Returned if the current user has no permission to browse project.
Find assignable usersGET /rest/api/2/user/assignable/search
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
parameter | type | description |
---|---|---|
username | string | the username |
project | string | the key of the project we are finding assignable users for |
issueKey | string | the issue key for the issue being edited we need to find assignable users for. |
maxResults | int Default: 50 | the maximum number of users to return (defaults to 50). The maximum allowed value is 100. If you specify a value that is higher than this number, your search results will be truncated. |
actionDescriptorId | int |
Responses
- Status
200 - application/jsonReturns a full representation of a Jira user in JSON format.
Example
{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","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","lastLoginTime":"2023-08-30T16:37:01+1000"}
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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"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
400Returned if no project or issue key was provided
- Status
401Returned if the current user is not authenticated.
- Status
404Returned if the requested user is not found.
Create avatar from temporaryPOST /rest/api/2/user/avatar
Converts temporary avatar into a real avatar
Request
query parameters
parameter | type | description |
---|---|---|
username | string | username |
Example
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"needsCropping":false}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/avatar-cropping#","title":"Avatar Cropping","type":"object","properties":{"cropperWidth":{"type":"integer"},"cropperOffsetX":{"type":"integer"},"cropperOffsetY":{"type":"integer"},"url":{"type":"string"},"needsCropping":{"type":"boolean"}},"additionalProperties":false,"required":["cropperWidth","cropperOffsetX","cropperOffsetY","needsCropping"]}
Responses
- Status
201 - application/jsonReturns created avatar
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}
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
400Returned if the cropping coordinates are invalid
- Status
401Returned if the user is not authenticated.
- Status
500Returned if an error occurs while converting temporary avatar to real avatar
- Status
403Returned if the currently authenticated user does not have permission to pick avatar
- Status
404Returned if user from parameter does not exist
Update user avatarPUT /rest/api/2/user/avatar
Request
query parameters
parameter | type | description |
---|---|---|
username | string |
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
Delete avatarDELETE /rest/api/2/user/avatar/{id}
Deletes avatar
Request
query parameters
parameter | type | description |
---|---|---|
username | string | username |
Responses
- Status
401Returned if the user is not authenticated.
- Status
204 - application/jsonReturned if the avatar is successfully deleted.
- Status
403Returned if the currently authenticated user does not have permission to delete the avatar.
- Status
404Returned if the avatar does not exist.
Store temporary avatarPOST /rest/api/2/user/avatar/temporary
Creates temporary avatar. Creating a temporary avatar is part of a 3-step process in uploading a new avatar for a user: upload, crop, confirm.
The following examples shows these three steps using curl. The cookies (session) need to be preserved between requests, hence the use of -b and -c. The id created in step 2 needs to be passed to step 3 (you can simply pass the whole response of step 2 as the request of step 3).
curl -c cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \ -H "Content-Type: image/png" --data-binary @mynewavatar.png \ 'http://localhost:8090/jira/rest/api/2/user/avatar/temporary?username=admin&filename=mynewavatar.png' curl -b cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \ -H "Content-Type: application/json" --data '{"cropperWidth": "65","cropperOffsetX": "10","cropperOffsetY": "16"}' \ -o tmpid.json \ http://localhost:8090/jira/rest/api/2/user/avatar?username=admin curl -b cookiejar.txt -X PUT -u admin:admin -H "X-Atlassian-Token: no-check" \ -H "Content-Type: application/json" --data-binary @tmpid.json \ http://localhost:8090/jira/rest/api/2/user/avatar?username=admin
Request
query parameters
parameter | type | description |
---|---|---|
username | string | username |
filename | string | name of file being uploaded |
size | long | size of file |
Responses
- Status
201 - application/jsontemporary avatar cropping instructions
Example
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/avatar-cropping#","title":"Avatar Cropping","type":"object","properties":{"cropperWidth":{"type":"integer"},"cropperOffsetX":{"type":"integer"},"cropperOffsetY":{"type":"integer"},"url":{"type":"string"},"needsCropping":{"type":"boolean"}},"additionalProperties":false,"required":["cropperWidth","cropperOffsetX","cropperOffsetY","needsCropping"]}
- Status
401Returned if the user is not authenticated.
- Status
500Returned if an error occurs while converting temporary avatar to real avatar
- Status
403Returned if the currently authenticated user does not have permission to store the avatar or XSRF token is invalid.
- Status
404Returned if the user passed in parameter does not exist.
Store temporary avatar using multi partPOST /rest/api/2/user/avatar/temporary
Creates temporary avatar using multipart. The response is sent back as JSON stored in a textarea. This is because the client uses remote iframing to submit avatars using multipart. So we must send them a valid HTML page back from which the client parses the JSON from.
Creating a temporary avatar is part of a 3-step process in uploading a new avatar for a user: upload, crop, confirm. This endpoint allows you to use a multipart upload instead of sending the image directly as the request body.
You *must* use "avatar" as the name of the upload parameter:
curl -c cookiejar.txt -X POST -u admin:admin -H "X-Atlassian-Token: no-check" \ -F "avatar=@mynewavatar.png;type=image/png" \ 'http://localhost:8090/jira/rest/api/2/user/avatar/temporary?username=admin'
Request
query parameters
parameter | type | description |
---|---|---|
username | string | Username |
Responses
- Status
201 - text/htmltemporary avatar cropping instructions embeded in HTML page. Error messages will also be embeded in the page.
Example
{"cropperWidth":120,"cropperOffsetX":50,"cropperOffsetY":50,"url":"http://example.com/jira/secure/temporaryavatar?cropped=true","needsCropping":true}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/avatar-cropping#","title":"Avatar Cropping","type":"object","properties":{"cropperWidth":{"type":"integer"},"cropperOffsetX":{"type":"integer"},"cropperOffsetY":{"type":"integer"},"url":{"type":"string"},"needsCropping":{"type":"boolean"}},"additionalProperties":false,"required":["cropperWidth","cropperOffsetX","cropperOffsetY","needsCropping"]}
- Status
401Returned if the user is not authenticated.
- Status
500Returned if an error occurs while converting temporary avatar to real avatar
- Status
403Returned if the currently authenticated user does not have permission to store the avatar or XSRF token is invalid.
- Status
404Returned if user does NOT exist
Get all avatarsGET /rest/api/2/user/avatars
Returns all avatars which are visible for the currently logged in user.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | username |
Responses
- Status
200 - application/jsonReturns a map containing a list of avatars for both custom an system avatars
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}]}
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
401Returned if the current user is not authenticated.
- Status
500Returned if an error occurs while retrieving the list of avatars.
- Status
404Returned if the requested user is not found.
Default columnsGET /rest/api/2/user/columns
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
parameter | type | description |
---|---|---|
username | string | username |
Responses
- Status
200 - application/jsonReturns 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
401Returned if the current user is not permitted to request the columns for the given user.
- Status
500Returned if an error occurs while retrieving the column configuration.
- Status
404Returned if the requested user is not found.
Set columnsPUT /rest/api/2/user/columns
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
200Returned when the columns is saved successfully
- Status
500Returned if an error occurs while retrieving the column configuration.
Reset columnsDELETE /rest/api/2/user/columns
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
parameter | type | description |
---|---|---|
username | string | username |
Responses
- Status
401Returned if the current user is not permitted to request the columns for the given user.
- Status
500Returned if an error occurs while resetting the column configuration.
- Status
204Returned when the columns are reset successfully
Get duplicated users count
experimentalGET /rest/api/2/user/duplicated/count
Returns the number of users whose accounts are duplicated. Duplicated means that the user has an account in more than one directory and either more than one account is active or the only active account does not belong to the directory with the highest priority. The data returned by this endpoint is cached for 10 minutes and the cache is flushed when any User Directory is added, removed, enabled, disabled, or synchronized. A System Administrator can also flush the cache manually. Related JAC ticket: https://jira.atlassian.com/browse/JRASERVER-68797
Request
query parameters
parameter | type | description |
---|---|---|
flush | boolean | if set to true forces cache flush, user must be sysadmin for this parameter to have an effect. |
Responses
- Status
200Returned if request is successful.
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/duplicated-users-count#","title":"Duplicated Users Count","type":"object","properties":{"count":{"type":"integer"}},"additionalProperties":false,"required":["count"]}
- Status
401Returned if user is unauthenticated.
- Status
403Returned if user is not an admin.
Get duplicated users mapping
experimentalGET /rest/api/2/user/duplicated/list
Returns duplicated users mapped to their directories with an indication if their accounts are active or not. Duplicated means that the user has an account in more than one directory and either more than one account is active or the only active account does not belong to the directory with the highest priority. The data returned by this endpoint is cached for 10 minutes and the cache is flushed when any User Directory is added, removed, enabled, disabled, or synchronized. A System Administrator can also flush the cache manually. Related JAC ticket: https://jira.atlassian.com/browse/JRASERVER-68797
Request
query parameters
parameter | type | description |
---|---|---|
flush | boolean | if set to true forces cache flush, user must be sysadmin for this parameter to have an effect. |
Responses
- Status
200Returned if request is successful.
Schema
{"type":"object","patternProperties":{".+":{"type":"object"}},"additionalProperties":false}
- Status
401Returned if user is unauthenticated.
- Status
403Returned if user is not an admin.
Change user password
experimentalPUT /rest/api/2/user/password
Modify user password.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | the username |
key | string | user key |
Example
{"password":"new password"}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/password#","title":"Password","type":"object","properties":{"password":{"type":"string"},"currentPassword":{"type":"string"}},"additionalProperties":false}
Responses
- Status
400Returned if the request is invalid.
- Status
401Returned if the user is not authenticated.
- Status
204Returned if the user exists and the caller has permission to edit it.
- Status
403Returned if the caller does not have permission to change the user password.
- Status
404Returned if the caller does have permission to change user password but the user does not exist.
Find users with all permissions
deprecatedGET /rest/api/2/user/permission/search
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.
This endpoint can cause serious performance issues and will be removed in Jira 9.0.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | the username filter, list includes all users if unspecified |
permissions | string | comma separated list of permissions for project or issue returned users must have, see Permissions JavaDoc for the list of all possible permissions. |
issueKey | string | the issue key for the issue for which returned users have specified permissions. |
projectKey | string | the optional project key to search for users with if no issueKey is supplied. |
startAt | int | the index of the first user to return (0-based) |
maxResults | int | the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated. |
Responses
- Status
200 - application/jsonReturns a full representation of a Jira user in JSON format.
Example
[{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},{"self":"http://www.example.com/jira/rest/api/2/user?username=andrew","key":"JIRAUSER10200","name":"andrew","emailAddress":"andrew@example.com","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,"deleted":false,"timeZone":"Europe/Warsaw","locale":"en_UK","lastLoginTime":"2023-08-30T16:37:01+1000"}]
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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"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
400Returned if no project or issue key was provided or when permissions list is empty or contains an invalid entry
- Status
401Returned if the current user is not authenticated.
- Status
403Returned if the current user does not have admin rights for the project.
- Status
404Returned if the requested issue or project is not found.
Find users for pickerGET /rest/api/2/user/picker
Returns a list of users matching query with highlighting.
Request
query parameters
parameter | type | description |
---|---|---|
query | string | A string used to search username, Name or e-mail address |
maxResults | int | the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated. |
showAvatar | boolean | |
exclude | string |
Responses
- Status
200 - application/jsonReturns a full representation of a Jira user in JSON format.
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"}
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
404Returned if the current user has no permission to browse users.
Find usersGET /rest/api/2/user/search
Returns a list of users that match the search string. This resource cannot be accessed anonymously.
Request
query parameters
parameter | type | description |
---|---|---|
username | string | A query string used to search username, name or e-mail address |
startAt | int | the index of the first user to return (0-based) |
maxResults | int | the maximum number of users to return (defaults to 50). The maximum allowed value is 1000. If you specify a value that is higher than this number, your search results will be truncated. |
includeActive | boolean | If true, then active users are included in the results (default true) |
includeInactive | boolean | If true, then inactive users are included in the results (default false) |
Responses
- Status
200 - application/jsonReturns a full representation of a Jira user in JSON format.
Example
[{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},{"self":"http://www.example.com/jira/rest/api/2/user?username=andrew","key":"JIRAUSER10200","name":"andrew","emailAddress":"andrew@example.com","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,"deleted":false,"timeZone":"Europe/Warsaw","locale":"en_UK","lastLoginTime":"2023-08-30T16:37:01+1000"}]
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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"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
400Returned if an invalid parameter value was provided with more details in the response body.
- Status
401Returned if the current user is not authenticated.
- Status
404Returned if the requested user is not found.
Find users with browse permissionGET /rest/api/2/user/viewissue/search
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
parameter | type | description |
---|---|---|
username | string | the username filter, no users returned if left blank |
issueKey | string | the issue key for the issue being edited we need to find viewable users for. |
projectKey | string | the optional project key to search for users with if no issueKey is supplied. |
maxResults | int | the maximum number of users to return (defaults to 50). The maximum allowed value is 100. If you specify a value that is higher than this number, your search results will be truncated. |
Responses
- Status
200 - application/jsonReturns a full representation of a Jira user in JSON format.
Example
[{"self":"http://www.example.com/jira/rest/api/2/user?username=fred","key":"JIRAUSER10100","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,"deleted":false,"timeZone":"Australia/Sydney","locale":"en_AU","lastLoginTime":"2023-08-30T16:37:01+1000"},{"self":"http://www.example.com/jira/rest/api/2/user?username=andrew","key":"JIRAUSER10200","name":"andrew","emailAddress":"andrew@example.com","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,"deleted":false,"timeZone":"Europe/Warsaw","locale":"en_UK","lastLoginTime":"2023-08-30T16:37:01+1000"}]
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"},"name":{"type":"string"},"emailAddress":{"type":"string"},"avatarUrls":{"type":"object","patternProperties":{".+":{"type":"string","format":"uri"}},"additionalProperties":false},"displayName":{"type":"string"},"active":{"type":"boolean"},"deleted":{"type":"boolean"},"timeZone":{"type":"string"},"locale":{"type":"string"},"groups":{"$ref":"#/definitions/simple-list-wrapper"},"applicationRoles":{"$ref":"#/definitions/simple-list-wrapper"},"expand":{"type":"string"},"lastLoginTime":{"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
400Returned if no project or issue key was provided
- Status
401Returned if the current user is not authenticated.
- Status
404Returned if the requested issue or project is not found.
api/2/user/a11y/personal-settings
Get a11y personal settingsGET /rest/api/2/user/a11y/personal-settings
Returns available accessibility personal settings along with `enabled` property that indicates the currently logged-in user preference.
Responses
- Status
200 - application/jsonReturned when validation succeeded.
Example
{"key":"a11y-setting-underlined-links","label":"Underlined links","description":"Underline links across Jira to make them more visible.","image":{"url":"https://jira.example.com/optional-image-url.png","altText":"An example of what underlined links would look like, shown on multiple links on the issue view."},"enabled":false}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/list-of-a11y-personal-setting#","title":"List of A11y Personal Setting","type":"array","items":{"title":"A11y Personal Setting","type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"image":{"title":"A11y Personal Setting Image","type":"object","properties":{"url":{"type":"string"},"altText":{"type":"string"}},"additionalProperties":false},"enabled":{"type":"boolean"}},"additionalProperties":false,"required":["enabled"]}}
api/2/user/anonymization
Validate user anonymizationGET /rest/api/2/user/anonymization
Validates user anonymization process.
Request
query parameters
parameter | type | description |
---|---|---|
userKey | string | the key of the user to validate anonymization for. |
expand | string | Parameter used to include parts of the response. This can be used to include: affectedEntities. Affected entities will only be returned if |
Responses
- Status
200 - application/jsonReturned when validation succeeded.
Example
{"errors":{},"warnings":{},"expand":"affectedEntities","userKey":"JIRAUSER10100","userName":"fred","displayName":"Fred Flinston","deleted":false,"email":"fred@example.com","success":true,"affectedEntities":{"ANONYMIZE":[{"type":"ANONYMIZE","description":"User Profile","numberOfOccurrences":1,"uriDisplayName":"User Profile","uri":"/jira/secure/ViewProfile.jspa?name=fred"}]},"operations":["USER_TRANSFER_OWNERSHIP_PLUGIN_POINTS","USER_DISABLE","USER_KEY_CHANGE_PLUGIN_POINTS","USER_KEY_CHANGE","USER_NAME_CHANGE_PLUGIN_POINTS","USER_NAME_CHANGE","USER_EXTERNAL_ID_CHANGE","USER_ANONYMIZE_PLUGIN_POINTS"],"businessLogicValidationFailed":false}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/user-anonymization-validation#","title":"User Anonymization Validation","type":"object","properties":{"errors":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/error-collection"}},"additionalProperties":false},"warnings":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/error-collection"}},"additionalProperties":false},"expand":{"type":"string"},"userKey":{"type":"string"},"userName":{"type":"string"},"displayName":{"type":"string"},"deleted":{"type":"boolean"},"email":{"type":"string"},"success":{"type":"boolean"},"affectedEntities":{"type":"object","patternProperties":{".+":{"type":"array","items":{"title":"Affected Entity","type":"object","properties":{"type":{"type":"string","enum":["ANONYMIZE","TRANSFER_OWNERSHIP","REMOVE","MANUAL"]},"description":{"type":"string"},"numberOfOccurrences":{"type":"integer"},"uriDisplayName":{"type":"string"},"uri":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false},"operations":{"type":"array","items":{"type":"string"}},"businessLogicValidationFailed":{"type":"boolean"}},"definitions":{"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}},"additionalProperties":false,"required":["deleted","success","businessLogicValidationFailed"]}
- Status
400Returned if a mandatory parameter was not provided or validation failed.
Example
{"errors":{"GENERAL":{"errorMessages":["An error coming from general validation, e.g. permission validation or a user trying to anonymize themselves"],"errors":{}},"USER_KEY_CHANGE":{"errorMessages":["Error coming from a particular operation step"],"errors":{}}},"warnings":{"com.atlassian.jira.example:plugin-module":{"errorMessages":["Some warning message","Another warning message"],"errors":{}},"com.atlassian.jira.example2:different-plugin-module":{"errorMessages":["An oopsie! Something went wrong!"],"errors":{}}},"expand":"affectedEntities","userKey":"JIRAUSER10100","deleted":false,"success":false,"affectedEntities":{},"operations":[],"businessLogicValidationFailed":false}
- Status
403Returned if the logged-in user cannot anonymize users.
Schedule user anonymizationPOST /rest/api/2/user/anonymization
Schedules a user anonymization process. Requires system admin permission.
Request
Example
{"userKey":"JIRAUSER10100","newOwnerKey":"admin"}
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/user-anonymization-request#","title":"User Anonymization Request","type":"object","properties":{"userKey":{"type":"string"},"newOwnerKey":{"type":"string"}},"additionalProperties":false}
Responses
- Status
202 - application/jsonReturned if the process was scheduled. Note that it can still fail the extended validation once its execution starts.
Schema
{"id":"https://docs.atlassian.com/jira/REST/schema/user-anonymization-progress#","title":"User Anonymization Progress","type":"object","properties":{"errors":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/error-collection"}},"additionalProperties":false},"warnings":{"type":"object","patternProperties":{".+":{"$ref":"#/definitions/error-collection"}},"additionalProperties":false},"userKey":{"type":"string"},"userName":{"type":"string"},"fullName":{"type":"string"},"progressUrl":{"type":"string"},"currentProgress":{"type":"integer"},"currentSubTask":{"type":"string"},"submittedTime":{"type":"string"},"startTime":{"type":"string"},"finishTime":{"type":"string"},"operations":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["COMPLETED","INTERRUPTED","IN_PROGRESS","VALIDATION_FAILED"]},"executingNode":{"type":"string"},"isRerun":{"type":"boolean"}},"definitions":{"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}},"additionalProperties":false,"required":["currentProgress","isRerun"]}
- Status
400Returned if a mandatory parameter was not provided.
- Status
403Returned if the logged-in user cannot anonymize users.
- Status
409Returned if another user anonymization process is already in progress.
Validate user anonymization rerunGET /rest/api/2/user/anonymization/rerun
Validates user anonymization re-run process.
Request
query parameters
parameter | type | description |
---|---|---|
userKey | string | the key of the user to validate anonymization for |
oldUserKey | string | user key before anonymization, only needed when current value is anonymized. If there is no old key, e.g. because the user was already created using the new key generation strategy, provide a value equal to the current key. |
oldUserName | string | user name before anonymization, only needed when the current value is anonymized. If there is no old name, provide a value equal to the current name. |
expand | string | Parameter used to include parts of the response. This can be used to include: affectedEntities. Affected entities will only be returned if |
Responses
- Status 200 - application/json