Skip to content

Instantly share code, notes, and snippets.

@alexmcco

alexmcco/atlassian-openapi.yaml

Created April 16, 2023 02:03
Show Gist options
  • Save alexmcco/96f9316c1ad4aeaa9348ca42c2755372 to your computer and use it in GitHub Desktop.
Save alexmcco/96f9316c1ad4aeaa9348ca42c2755372 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
atlassian-openapi.yaml
This file has been truncated, but you can view the full file.
openapi: 3.0.1
info:
title: The Jira Cloud platform REST API
description: Jira Cloud platform REST API documentation
termsOfService: 'http://atlassian.com/terms/'
contact:
email: ecosystem@atlassian.com
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
version: 1001.0.0-SNAPSHOT
externalDocs:
description: Find out more about Atlassian products and services.
url: 'http://www.atlassian.com'
servers:
- url: 'https://your-domain.atlassian.net'
tags:
- name: Announcement banner
description: >-
This resource represents an announcement banner. Use it to retrieve and
update banner configuration.
- name: Application roles
description: >-
This resource represents application roles. Use it to get details of an
application role or all application roles.
- name: Audit records
description: >-
This resource represents audits that record activities undertaken in Jira.
Use it to get a list of audit records.
- name: Avatars
description: >-
This resource represents system and custom avatars. Use it to obtain the
details of system or custom avatars, add and remove avatars from a project
or issue type, and obtain avatar images.
- name: Dashboards
description: >-
This resource represents dashboards. Use it to obtain the details of
dashboards as well as get, create, update, or remove item properties and
gadgets from dashboards.
- name: Filters
description: >-
This resource represents
[filters](https://confluence.atlassian.com/x/eQiiLQ). Use it to get,
create, update, or delete filters. Also use it to configure the columns
for a filter and set favorite filters.
- name: Filter sharing
description: >-
This resource represents options for sharing
[filters](#api-group-Filters). Use it to get share scopes as well as add
and remove share scopes from filters.
- name: Group and user picker
description: >-
This resource represents a list of users and a list of groups. Use it to
obtain the details to populate user and group picker suggestions list.
- name: Groups
description: >-
This resource represents groups of users. Use it to get, create, find, and
delete groups as well as add and remove users from groups. (\[WARNING\]
The standard Atlassian group names are default names only and can be
edited or deleted. For example, an admin or Atlassian support could delete
the default group jira-software-users or rename it to jsw-users at any
point. See
https://support.atlassian.com/user-management/docs/create-and-update-groups/
for details.)
- name: Instance information
description: >-
This resource represents information about the Jira instance. Use it to
get license details.
- name: Issues
description: |-
This resource represents Jira issues. Use it to:
* create or edit issues, individually or in bulk.
* retrieve metadata about the options for creating or editing issues.
* delete an issue.
* assign a user to an issue.
* get issue changelogs.
* send notifications about an issue.
* get details of the transitions available for an issue.
* transition an issue.
- name: UI modifications (apps)
description: >-
UI modifications is an experimental feature available for **Forge apps
only**. It enables Forge apps to control how selected Jira fields behave
on global create issue dialog. For example: hide specific fields, set them
as required, etc.
- name: Issue attachments
description: >-
This resource represents issue attachments and the attachment settings for
Jira. Use it to get the metadata for an attachment, delete an attachment,
and view the metadata for the contents of an attachment. Also, use it to
get the attachment settings for Jira.
- name: Issue comments
description: |-
This resource represents issue comments. Use it to:
* get, create, update, and delete a comment from an issue.
* get all comments from issue.
* get a list of comments by comment ID.
- name: Issue comment properties
description: >-
This resource represents [issue comment](#api-group-Issue-comments)
properties, which provides for storing custom data against an issue
comment. Use is to get, set, and delete issue comment properties as well
as obtain the keys of all properties on a comment. Comment properties are
a type of [entity
property](https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/).
- name: Issue fields
description: >-
This resource represents issue fields, both system and custom fields. Use
it to get fields, field configurations, and create custom fields.
- name: Issue field configurations
description: >-
This resource represents issue field configurations. Use it to get, set,
and delete field configurations and field configuration schemes.
- name: Issue custom field contexts
description: |-
This resource represents issue custom field contexts. Use it to:
* get, create, update, and delete custom field contexts.
* get context to issue types and projects mappings.
* get custom field contexts for projects and issue types.
* assign custom field contexts to projects.
* remove custom field contexts from projects.
* add issue types to custom field contexts.
- name: Issue custom field options
description: >-
This resource represents custom issue field select list options created in
Jira or using the REST API. This resource supports the following field
types:
* Checkboxes.
* Radio Buttons.
* Select List (single choice).
* Select List (multiple choices).
* Select List (cascading).
See [Issue custom field options
(apps)](#api-group-Issue-custom-field-options--apps-) to manipulate custom
issue field select list options created by a Connect app.
Use it to retrieve, create, update, order, and delete custom field
options.
- name: Issue custom field options (apps)
description: >-
This resource represents custom issue field select list options created by
a Connect app. See [Issue custom field
options](#api-group-Issue-custom-field-options) to manipulate options
created in Jira or using the REST API.
A select list issue field is a type of [issue
field](https://developer.atlassian.com/cloud/jira/platform/modules/issue-field/)
that enables a user to select an option from a list. Use it to add,
remove, and update the options of a select list issue field.
- name: Issue custom field values (apps)
description: >-
This resource represents the values of custom fields added by [Forge
apps](https://developer.atlassian.com/platform/forge/). Use it to update
the value of a custom field on issues.
- name: Issue custom field configuration (apps)
description: >-
This resource represents configurations stored against a custom field
context by a [Forge app](https://developer.atlassian.com/platform/forge/).
Configurations are information used by the Forge app at runtime to
determine how to handle or process the data in a custom field in a given
context. Use this resource to set and read configurations.
- name: Issue links
description: >-
This resource represents links between issues. Use it to get, create, and
delete links between issues.
To use it, the site must have [issue
linking](https://confluence.atlassian.com/x/yoXKM) enabled.
- name: Issue link types
description: >-
This resource represents [issue link](#api-group-Issue-links) types. Use
it to get, create, update, and delete link issue types as well as get
lists of all link issue types.
To use it, the site must have [issue
linking](https://confluence.atlassian.com/x/yoXKM) enabled.
- name: Issue navigator settings
description: >-
This resource represents issue navigator settings. Use it to get and set
issue navigator default columns.
- name: Issue notification schemes
description: >-
This resource represents notification schemes, lists of events and the
recipients who will receive notifications for those events. Use it to get
details of a notification scheme and a list of notification schemes.
### About notification schemes ###
A notification scheme is a list of events and recipients who will receive
notifications for those events. The list is contained within the
`notificationSchemeEvents` object and contains pairs of `events` and
`notifications`:
* `event` Identifies the type of event. The events can be [Jira system events](https://support.atlassian.com/jira-cloud-administration/docs/configure-notification-schemes/) (see the *Events* section) or [custom events](https://support.atlassian.com/jira-cloud-administration/docs/add-a-custom-event/).
* `notifications` Identifies the [recipients](https://confluence.atlassian.com/x/8YdKLg#Creatinganotificationscheme-recipientsRecipients) of notifications for each event. Recipients can be any of the following types:
* `CurrentAssignee`
* `Reporter`
* `CurrentUser`
* `ProjectLead`
* `ComponentLead`
* `User` (the `parameter` is the user key)
* `Group` (the `parameter` is the group name)
* `ProjectRole` (the `parameter` is the project role ID)
* `EmailAddress`
* `AllWatchers`
* `UserCustomField` (the `parameter` is the ID of the custom field)
* `GroupCustomField`(the `parameter` is the ID of the custom field)
- name: Issue priorities
description: >-
This resource represents issue priorities. Use it to get, create and
update issue priorities and details for individual issue priorities.
- name: Issue properties
description: >-
This resource represents [issue](#api-group-Issues) properties, which
provides for storing custom data against an issue. Use it to get, set, and
delete issue properties as well as obtain details of all properties on an
issue. Operations to bulk update and delete issue properties are also
provided. Issue properties are a type of [entity
property](https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/).
- name: Issue remote links
description: >-
This resource represents remote issue links, a way of linking Jira to
information in other systems. Use it to get, create, update, and delete
remote issue links either by ID or global ID. The global ID provides a way
of accessing remote issue links using information about the item's remote
system host and remote system identifier.
- name: Issue resolutions
description: >-
This resource represents issue resolution values. Use it to obtain a list
of all issue resolution values and the details of individual resolution
values.
- name: Issue search
description: >-
This resource represents various ways to search for issues. Use it to
search for issues with a JQL query and find issues to populate an issue
picker.
- name: Issue security level
description: >-
This resource represents issue security levels. Use it to obtain the
details of any issue security level. For more information about issue
security levels, see [Configuring issue-level
security](https://confluence.atlassian.com/x/J4lKLg).
- name: Issue security schemes
description: >-
This resource represents issue security schemes. Use it to get an issue
security scheme or list of issues security schemes.
Issue security schemes control which users or groups of users can view an
issue. When an issue security scheme is associated with a project, its
security levels can be applied to issues in that project. Sub-tasks also
inherit the security level of their parent issue.
- name: Issue security scheme
description: >-
This resource represents issue security schemes, issue security levels,
and issue security level members. Use it to get, create, update, and
delete issue security schemes or issue security scheme details. Note that
only company-managed (classic) projects are supported.
### About issue security schemes ###
Issue security schemes control which users or groups of users can view an
issue. An issue security scheme is made up of multiple security levels.
Each level can have users or groups of users assigned to it. The following
are valid security level members:
* Individual users
* Groups of users
* Project roles
* Issue roles
* "Anyone", for example to allow anonymous access
* A (multi-)user or (multi-)group picker custom field
- name: Issue types
description: |-
This resource represents issues types. Use it to:
* get, create, update, and delete issue types.
* get all issue types for a user.
* get alternative issue types.
* set an avatar for an issue type.
- name: Issue type schemes
description: >-
This resource represents issue type schemes in classic projects. Use it
to:
* get issue type schemes and a list of the projects that use them.
* associate issue type schemes with projects.
* add issue types to issue type schemes.
* delete issue types from issue type schemes.
* create, update, and delete issue type schemes.
* change the order of issue types in issue type schemes.
- name: Issue type screen schemes
description: |-
This resource represents issue type screen schemes. Use it to:
* get issue type screen schemes and a list of the projects that use them.
* create issue type screen schemes.
* update issue type screen schemes.
* delete issue type screen schemes.
* associate issue type screen schemes with projects.
* append issue type to screen scheme mappings to issue type screen schemes.
* remove issue type to screen scheme mappings from issue type screen schemes.
* update default screen scheme of issue type screen scheme.
- name: Issue type properties
description: >-
This resource represents [issue type](#api-group-Issue-types) properties,
which provides for storing custom data against an issue type. Use it to
get, create, and delete issue type properties as well as obtain the keys
of all properties on a issues type. Issue type properties are a type of
[entity
property](https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/).
- name: Issue votes
description: >-
This resource represents votes cast by users on an issue. Use it to get
details of votes on an issue as well as cast and withdrawal votes.
- name: Issue watchers
description: >-
This resource represents users watching an issue. Use it to get details of
users watching an issue as well as start and stop a user watching an
issue.
- name: Issue worklogs
description: |-
This resource represents issue worklogs. Use it to:
* get, create, update, and delete worklogs.
* obtain lists of updated or deleted worklogs.
- name: Issue worklog properties
description: >-
This resource represents [issue worklog](#api-group-Issue-worklogs)
properties, which provides for storing custom data against an issue
worklog. Use it to get, create, and delete issue worklog properties as
well as obtain the keys of all properties on a issue worklog. Issue
worklog properties are a type of [entity
property](https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/).
- name: Jira expressions
description: >-
This resource is a collection of operations for [Jira
expressions](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/).
- name: Jira settings
description: >-
This resource represents various settings in Jira. Use it to get and
update Jira settings and properties.
- name: JQL
description: >-
This resource represents JQL search auto-complete details. Use it to
obtain JQL search auto-complete data and suggestions for use in
programmatic construction of queries or custom query builders. It also
provides operations to:
* convert one or more JQL queries with user identifiers (username or user key) to equivalent JQL queries with account IDs.
* convert readable details in one or more JQL queries to IDs where a user doesn't have permission to view the entity whose details are readable.
- name: Labels
description: >-
This resource represents available labels. Use it to get available labels
for the global label field.
- name: License metrics
description: >-
This resource represents license metrics. Use it to get available metrics
for Jira licences.
- name: Myself
description: >-
This resource represents information about the current user, such as basic
details, group membership, application roles, preferences, and locale. Use
it to get, create, update, and delete (restore default) values of the
user's preferences and locale.
- name: Permissions
description: >-
This resource represents permissions. Use it to obtain details of all
permissions and determine whether the user has certain permissions.
- name: Permission schemes
description: >-
This resource represents permission schemes. Use it to get, create,
update, and delete permission schemes as well as get, create, update, and
delete details of the permissions granted in those schemes.
- name: Projects
description: >-
This resource represents projects. Use it to get, create, update, and
delete projects. Also get statuses available to a project, a project's
notification schemes, and update a project's type.
- name: Project avatars
description: >-
This resource represents avatars associated with a project. Use it to get,
load, set, and remove project avatars.
- name: Project categories
description: >-
This resource represents project categories. Use it to create, update, and
delete project categories as well as obtain a list of all project
categories and details of individual categories. For more information on
managing project categories, see [Adding, assigning, and deleting project
categories](https://confluence.atlassian.com/x/-A5WMg).
- name: Project components
description: >-
This resource represents project components. Use it to get, create,
update, and delete project components. Also get components for project and
get a count of issues by component.
- name: Project email
description: >-
This resource represents the email address used to send a project's
notifications. Use it to get and set the [project's sender email
address](https://confluence.atlassian.com/x/dolKLg).
- name: Project features
description: >-
This resource represents project features. Use it to get the list of
features for a project and modify the state of a feature. The project
feature endpoint is available only for Jira Software, both for team- and
company-managed projects.
- name: Project key and name validation
description: This resource provides validation for project keys and names.
- name: Project permission schemes
description: >-
This resource represents permission schemes for a project. Use this
resource to:
* get details of a project's issue security levels available to the calling user.
* get the permission scheme associated with the project or assign different permission scheme to the project.
* get details of a project's issue security scheme.
See [Managing project
permissions](https://confluence.atlassian.com/x/yodKLg) for more
information about permission schemes.
- name: Project properties
description: >-
This resource represents [project](#api-group-Projects) properties, which
provides for storing custom data against a project. Use it to get, create,
and delete project properties as well as get a list of property keys for a
project. Project properties are a type of [entity
property](https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/).
- name: Project roles
description: >-
This resource represents the roles that users can play in projects. Use
this resource to get, create, update, and delete project roles.
- name: Project role actors
description: >-
This resource represents the users assigned to [project
roles](#api-group-Issue-comments). Use it to get, add, and remove default
users from project roles. Also use it to add and remove users from a
project role associated with a project.
- name: Project types
description: >-
This resource represents project types. Use it to obtain a list of all
project types, a list of project types accessible to the calling user, and
details of a project type.
- name: Project versions
description: >-
This resource represents project versions. Use it to get, get lists of,
create, update, move, merge, and delete project versions. This resource
also provides counts of issues by version.
- name: Screens
description: >-
This resource represents the screens used to record issue details. Use it
to:
* get details of all screens.
* get details of all the fields available for use on screens.
* create screens.
* delete screens.
* update screens.
* add a field to the default screen.
- name: Screen tabs
description: >-
This resource represents the screen tabs used to record issue details. Use
it to get, create, update, move, and delete screen tabs.
- name: Screen tab fields
description: >-
This resource represents the screen tab fields used to record issue
details. Use it to get, add, move, and remove fields from screen tabs.
- name: Screen schemes
description: >-
This resource represents screen schemes in classic projects. Use it to
get, create, update, and delete screen schemes.
- name: Server info
description: This resource provides information about the Jira instance.
- name: Status
description: >-
This resource represents statuses. Use it to search, get, create, delete,
and change statuses.
- name: Tasks
description: >-
This resource represents a [long-running asynchronous
tasks](#async-operations). Use it to obtain details about the progress of
a long-running task or cancel a long-running task.
- name: Time tracking
description: >-
This resource represents time tracking and time tracking providers. Use it
to get and set the time tracking provider, get and set the time tracking
options, and disable time tracking.
- name: Users
description: |-
This resource represent users. Use it to:
* get, get a list of, create, and delete users.
* get, set, and reset a user's default issue table columns.
* get a list of the groups the user belongs to.
* get a list of user account IDs for a list of usernames or user keys.
- name: User properties
description: >-
This resource represents [user](#api-group-Users) properties and provides
for storing custom data against a user. Use it to get, create, and delete
user properties as well as get a list of property keys for a user. This
resourse is designed for integrations and apps to store per-user data and
settings. This enables data used to customized the user experience to be
kept in the Jira Cloud instance's database. User properties are a type of
[entity
property](https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/).
This resource does not access the [user
properties](https://confluence.atlassian.com/x/8YxjL) created and
maintained in Jira.
- name: User search
description: >-
This resource represents various ways to search for and find users. Use it
to obtain list of users including users assignable to projects and issues,
users with permissions, user lists for pickup fields, and user lists
generated using structured queries. Note that the operations in this
resource only return users found within the first 1000 users.
- name: Webhooks
description: >-
This resource represents webhooks. Webhooks are calls sent to a URL when
an event occurs in Jira for issues specified by a JQL query. Only Connect
and OAuth 2.0 apps can register and manage webhooks. For more information,
see
[Webhooks](https://developer.atlassian.com/cloud/jira/platform/webhooks/#registering-a-webhook-via-the-jira-rest-api-for-connect-apps).
- name: Workflows
description: |-
This resource represents workflows. Use it to:
* get workflows.
* create workflows.
* delete inactive workflows.
- name: Workflow transition rules
description: >-
This resource represents workflow transition rules. Workflow transition
rules define a Connect or a Forge app routine, such as a [workflow post
functions](https://developer.atlassian.com/cloud/jira/platform/modules/workflow-post-function/)
that is executed in association with the workflow. Use it to read and
modify configuration of workflow transition rules.
- name: Workflow schemes
description: >-
This resource represents workflow schemes. Use it to manage workflow
schemes and the workflow scheme's workflows and issue types.
A workflow scheme maps issue types to workflows. A workflow scheme can be
associated with one or more projects, which enables the projects to use
the workflow-issue type mappings.
Active workflow schemes (workflow schemes that are used by projects)
cannot be edited. When an active workflow scheme is edited, a draft copy
of the scheme is created. The draft workflow scheme is then be edited and
published (replacing the active scheme).
See [Configuring workflow
schemes](https://confluence.atlassian.com/x/tohKLg) for more information.
- name: Workflow scheme project associations
description: >-
This resource represents the associations between workflow schemes and
projects.
For more information, see [Managing your
workflows](https://confluence.atlassian.com/x/q4hKLg).
- name: Workflow scheme drafts
description: >-
This resource represents draft workflow schemes. Use it to manage drafts
of workflow schemes.
A workflow scheme maps issue types to workflows. A workflow scheme can be
associated with one or more projects, which enables the projects to use
the workflow-issue type mappings.
Active workflow schemes (workflow schemes that are used by projects)
cannot be edited. Editing an active workflow scheme creates a draft copy
of the scheme. The draft workflow scheme can then be edited and published
(replacing the active scheme).
See [Configuring workflow
schemes](https://confluence.atlassian.com/x/tohKLg) for more information.
- name: Workflow statuses
description: >-
This resource represents issue workflow statuses. Use it to obtain a list
of all statuses associated with workflows and the details of a status.
- name: Workflow status categories
description: >-
This resource represents status categories. Use it to obtain a list of all
status categories and the details of a category. Status categories
provided a mechanism for categorizing
[statuses](#api-group-Workflow-statuses).
- name: Workflow transition properties
description: >-
This resource represents workflow transition properties, which provides
for storing custom data against a workflow transition. Use it to get,
create, and delete workflow transition properties as well as get a list of
property keys for a workflow transition. Workflow transition properties
are a type of [entity
property](https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/).
- name: App properties
description: >-
This resource represents app properties. Use it to store arbitrary data
for your
[Connect
app](https://developer.atlassian.com/cloud/jira/platform/index/#connect-apps).
- name: Dynamic modules
description: >-
This resource represents [modules registered
dynamically](https://developer.atlassian.com/cloud/jira/platform/dynamic-modules/)
by [Connect
apps](https://developer.atlassian.com/cloud/jira/platform/index/#connect-apps).
- name: App migration
description: >-
This resource supports [app
migrations](https://developer.atlassian.com/platform/app-migration/). Use
it to:
- [to request migrated workflow rules
details](https://developer.atlassian.com/platform/app-migration/tutorials/migration-app-workflow-rules/).
- [perform bulk updates of entity
properties](https://developer.atlassian.com/platform/app-migration/tutorials/entity-properties-bulk-api/).
- [perform bulk updates of issue custom field
values](https://developer.atlassian.com/platform/app-migration/tutorials/migrating-app-custom-fields/).
paths:
/rest/api/3/announcementBanner:
get:
tags:
- Announcement banner
summary: Get announcement banner configuration
description: >-
Returns the current announcement banner configuration.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getBanner
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/AnnouncementBannerConfiguration'
example: >-
{"message":"This is a public, enabled, non-dismissible banner,
set using the
API","isDismissible":false,"isEnabled":true,"hashId":"9HN2FJK9DM8BHRWERVW3RRTGDJ4G4D5C","visibility":"public"}
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: '"Only admins can read banner configuration."'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-experimental: true
x-atlassian-connect-scope: ADMIN
put:
tags:
- Announcement banner
summary: Update announcement banner configuration
description: >-
Updates the announcement banner configuration.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: setBanner
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AnnouncementBannerConfigurationUpdate'
example:
isDismissible: false
isEnabled: true
message: >-
This is a public, enabled, non-dismissible banner, set using the
API
visibility: public
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if an invalid parameter is passed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: '"Banner message cannot be null."'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: '"Only admins can update banner configuration."'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/app/field/value:
post:
tags:
- Issue custom field values (apps)
summary: Update custom fields
description: >-
Updates the value of one or more custom fields on one or more issues.
Combinations of custom field and issue should be unique within the
request. Custom fields can only be updated by the Forge app that created
them.
**[Permissions](#permissions) required:** Only the app that created the
custom field can update its values with this operation.
operationId: updateMultipleCustomFieldValues
parameters:
- name: generateChangelog
in: query
description: Whether to generate a changelog for this update.
schema:
type: boolean
default: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MultipleCustomFieldValuesUpdateDetails'
example:
updates:
- customField: customfield_10010
issueIds:
- 10010
- 10011
value: new value
- customField: customfield_10011
issueIds:
- 10010
value: 1000
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
'403':
description: >-
Returned if the request is not authenticated as the app that
provided all the fields.
'404':
description: Returned if any field is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes: []
- state: Beta
scheme: OAuth2
scopes: []
x-experimental: true
x-atlassian-connect-scope: INACCESSIBLE
'/rest/api/3/app/field/{fieldIdOrKey}/context/configuration':
get:
tags:
- Issue custom field configuration (apps)
summary: Get custom field configurations
description: >-
Returns a [paginated](#pagination) list of configurations for a custom
field created by a [Forge
app](https://developer.atlassian.com/platform/forge/).
The result can be filtered by one of these criteria:
* `id`.
* `fieldContextId`.
* `issueId`.
* `projectKeyOrId` and `issueTypeId`.
Otherwise, all configurations are returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg). Jira permissions
are not required for the Forge app that created the custom field.
operationId: getCustomFieldConfiguration
parameters:
- name: fieldIdOrKey
in: path
description: 'The ID or key of the custom field, for example `customfield_10000`.'
required: true
schema:
type: string
- name: id
in: query
description: >-
The list of configuration IDs. To include multiple configurations,
separate IDs with an ampersand: `id=10000&id=10001`. Can't be
provided with `fieldContextId`, `issueId`, `projectKeyOrId`, or
`issueTypeId`.
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
- name: fieldContextId
in: query
description: >-
The list of field context IDs. To include multiple field contexts,
separate IDs with an ampersand:
`fieldContextId=10000&fieldContextId=10001`. Can't be provided with
`id`, `issueId`, `projectKeyOrId`, or `issueTypeId`.
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
- name: issueId
in: query
description: >-
The ID of the issue to filter results by. If the issue doesn't
exist, an empty list is returned. Can't be provided with
`projectKeyOrId`, or `issueTypeId`.
schema:
type: integer
format: int64
- name: projectKeyOrId
in: query
description: >-
The ID or key of the project to filter results by. Must be provided
with `issueTypeId`. Can't be provided with `issueId`.
schema:
type: string
- name: issueTypeId
in: query
description: >-
The ID of the issue type to filter results by. Must be provided with
`projectKeyOrId`. Can't be provided with `issueId`.
schema:
type: string
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 100
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanContextualConfiguration'
example: >-
{"maxResults":1000,"startAt":0,"total":2,"isLast":true,"values":[{"id":"10000","fieldContextId":"10010"},{"id":"10001","fieldContextId":"10011","configuration":{"minValue":0,"maxValue":10000},"schema":{"properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]}}]}
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user is not a Jira admin or the request is not
authenticated as from the app that provided the field.
'404':
description: Returned if the custom field is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:custom-field-contextual-configuration:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
put:
tags:
- Issue custom field configuration (apps)
summary: Update custom field configurations
description: >-
Update the configuration for contexts of a custom field created by a
[Forge app](https://developer.atlassian.com/platform/forge/).
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg). Jira permissions
are not required for the Forge app that created the custom field.
operationId: updateCustomFieldConfiguration
parameters:
- name: fieldIdOrKey
in: path
description: 'The ID or key of the custom field, for example `customfield_10000`.'
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldConfigurations'
example:
configurations:
- id: '10000'
- configuration:
maxValue: 10000
minValue: 0
id: '10001'
schema:
properties:
amount:
type: number
currency:
type: string
required:
- amount
- currency
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user is not a Jira admin or the request is not
authenticated as from the app that provided the field.
'404':
description: Returned if the custom field is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:custom-field-contextual-configuration:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/app/field/{fieldIdOrKey}/value':
put:
tags:
- Issue custom field values (apps)
summary: Update custom field value
description: >-
Updates the value of a custom field on one or more issues. Custom fields
can only be updated by the Forge app that created them.
**[Permissions](#permissions) required:** Only the app that created the
custom field can update its values with this operation.
operationId: updateCustomFieldValue
parameters:
- name: fieldIdOrKey
in: path
description: 'The ID or key of the custom field. For example, `customfield_10010`.'
required: true
schema:
type: string
- name: generateChangelog
in: query
description: Whether to generate a changelog for this update.
schema:
type: boolean
default: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldValueUpdateDetails'
example:
updates:
- issueIds:
- 10010
value: new value
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
'403':
description: >-
Returned if the request is not authenticated as the app that
provided the field.
'404':
description: Returned if the field is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes: []
- state: Beta
scheme: OAuth2
scopes: []
x-experimental: true
x-atlassian-connect-scope: INACCESSIBLE
/rest/api/3/application-properties:
get:
tags:
- Jira settings
summary: Get application property
description: >-
Returns all application properties or an application property.
If you specify a value for the `key` parameter, then an application
property is returned as an object (not in an array). Otherwise, an array
of all editable application properties is returned. See [Set application
property](#api-rest-api-3-application-properties-id-put) for
descriptions of editable properties.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getApplicationProperty
parameters:
- name: key
in: query
description: The key of the application property.
schema:
type: string
- name: permissionLevel
in: query
description: The permission level of all items being returned in the list.
schema:
type: string
- name: keyFilter
in: query
description: >-
When a `key` isn't provided, this filters the list of results by the
application property `key` using a regular expression. For example,
using `jira.lf.*` will return all application properties with keys
that start with *jira.lf.*.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApplicationProperty'
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 -"}]
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the application property is not found or the user does
not have permission to view it.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:instance-configuration:jira'
x-atlassian-connect-scope: ADMIN
/rest/api/3/application-properties/advanced-settings:
get:
tags:
- Jira settings
summary: Get advanced settings
description: >-
Returns the application properties that are accessible on the *Advanced
Settings* page. To navigate to the *Advanced Settings* page in Jira,
choose the Jira icon > **Jira settings** > **System**, **General
Configuration** and then click **Advanced Settings** (in the upper
right).
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getAdvancedSettings
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApplicationProperty'
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 -"}]
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user is not an administrator.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:instance-configuration:jira'
x-atlassian-connect-scope: ADMIN
'/rest/api/3/application-properties/{id}':
put:
tags:
- Jira settings
summary: Set application property
description: >-
Changes the value of an application property. For example, you can
change the value of the `jira.clone.prefix` from its default value of
*CLONE -* to *Clone -* if you prefer sentence case capitalization.
Editable properties are described below along with their default values.
#### Advanced settings ####
The advanced settings below are also accessible in
[Jira](https://confluence.atlassian.com/x/vYXKM).
| Key | Description | Default value |
| -- | -- | -- |
| `jira.clone.prefix` | The string of text prefixed to the title of a
cloned issue. | `CLONE -` |
| `jira.date.picker.java.format` | The date format for the Java
(server-side) generated dates. This must be the same as the
`jira.date.picker.javascript.format` format setting. | `d/MMM/yy` |
| `jira.date.picker.javascript.format` | The date format for the
JavaScript (client-side) generated dates. This must be the same as the
`jira.date.picker.java.format` format setting. | `%e/%b/%y` |
| `jira.date.time.picker.java.format` | The date format for the Java
(server-side) generated date times. This must be the same as the
`jira.date.time.picker.javascript.format` format setting. | `dd/MMM/yy
h:mm a` |
| `jira.date.time.picker.javascript.format` | The date format for the
JavaScript (client-side) generated date times. This must be the same as
the `jira.date.time.picker.java.format` format setting. | `%e/%b/%y
%I:%M %p` |
| `jira.issue.actions.order` | The default order of actions (such as
*Comments* or *Change history*) displayed on the issue view. | `asc` |
| `jira.table.cols.subtasks` | The columns to show while viewing subtask
issues in a table. For example, a list of subtasks on an issue. |
`issuetype, status, assignee, progress` |
| `jira.view.issue.links.sort.order` | The sort order of the list of
issue links on the issue view. | `type, status, priority` |
| `jira.comment.collapsing.minimum.hidden` | The minimum number of
comments required for comment collapsing to occur. A value of `0`
disables comment collapsing. | `4` |
| `jira.newsletter.tip.delay.days` | The number of days before a prompt
to sign up to the Jira Insiders newsletter is shown. A value of `-1`
disables this feature. | `7` |
#### Look and feel ####
The settings listed below adjust the [look and
feel](https://confluence.atlassian.com/x/VwCLLg).
| Key | Description | Default value |
| -- | -- | -- |
| `jira.lf.date.time` | The [ time
format](https://docs.oracle.com/javase/6/docs/api/index.html?java/text/SimpleDateFormat.html).
| `h:mm a` |
| `jira.lf.date.day` | The [ day
format](https://docs.oracle.com/javase/6/docs/api/index.html?java/text/SimpleDateFormat.html).
| `EEEE h:mm a` |
| `jira.lf.date.complete` | The [ date and time
format](https://docs.oracle.com/javase/6/docs/api/index.html?java/text/SimpleDateFormat.html).
| `dd/MMM/yy h:mm a` |
| `jira.lf.date.dmy` | The [ date
format](https://docs.oracle.com/javase/6/docs/api/index.html?java/text/SimpleDateFormat.html).
| `dd/MMM/yy` |
| `jira.date.time.picker.use.iso8061` | When enabled, sets Monday as the
first day of the week in the date picker, as specified by the ISO8601
standard. | `false` |
| `jira.lf.logo.url` | The URL of the logo image file. |
`/images/icon-jira-logo.png` |
| `jira.lf.logo.show.application.title` | Controls the visibility of the
application title on the sidebar. | `false` |
| `jira.lf.favicon.url` | The URL of the favicon. | `/favicon.ico` |
| `jira.lf.favicon.hires.url` | The URL of the high-resolution favicon.
| `/images/64jira.png` |
| `jira.lf.navigation.bgcolour` | The background color of the sidebar. |
`#0747A6` |
| `jira.lf.navigation.highlightcolour` | The color of the text and logo
of the sidebar. | `#DEEBFF` |
| `jira.lf.hero.button.base.bg.colour` | The background color of the
hero button. | `#3b7fc4` |
| `jira.title` | The text for the application title. The application
title can also be set in *General settings*. | `Jira` |
| `jira.option.globalsharing` | Whether filters and dashboards can be
shared with anyone signed into Jira. | `true` |
| `xflow.product.suggestions.enabled` | Whether to expose product
suggestions for other Atlassian products within Jira. | `true` |
#### Other settings ####
| Key | Description | Default value |
| -- | -- | -- |
| `jira.issuenav.criteria.autoupdate` | Whether instant updates to
search criteria is active. | `true` |
*Note: Be careful when changing [application properties and advanced
settings](https://confluence.atlassian.com/x/vYXKM).*
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: setApplicationProperty
parameters:
- name: id
in: path
description: The key of the application property to update.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleApplicationPropertyBean'
example:
id: jira.home
value: /var/jira/jira-home
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationProperty'
'400':
description: >-
Returned if the data type of the `value` does not match the
application property's data type. For example, a string is provided
instead of an integer.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have permission to edit the property.
'404':
description: >-
Returned if the property is not found or the user does not have
permission to view it.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:instance-configuration:jira'
- 'read:instance-configuration:jira'
x-atlassian-connect-scope: ADMIN
/rest/api/3/applicationrole:
get:
tags:
- Application roles
summary: Get all application roles
description: >-
Returns all application roles. In Jira, application roles are managed
using the [Application access
configuration](https://confluence.atlassian.com/x/3YxjL) page.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getAllApplicationRoles
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApplicationRole'
example: >-
[{"key":"jira-software","groups":["jira-software-users","jira-testers"],"groupDetails":[{"name":"jira-testers","groupId":"42c8955c-63d7-42c8-9520-63d7aca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=42c8955c-63d7-42c8-9520-63d7aca0625"},{"name":"jira-software-users","groupId":"276f955c-63d7-42c8-9520-92d01dca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"}],"name":"Jira
Software","defaultGroups":["jira-software-users"],"defaultGroupsDetails":[{"name":"jira-software-users","groupId":"276f955c-63d7-42c8-9520-92d01dca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"}],"selectedByDefault":false,"defined":false,"numberOfSeats":10,"remainingSeats":5,"userCount":5,"userCountDescription":"5
developers","hasUnlimitedSeats":false,"platform":false},{"key":"jira-core","groups":["jira-core-users"],"groupDetails":[{"name":"jira-core-users","groupId":"92d01dca0625-42c8-42c8-9520-276f955c","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=92d01dca0625-42c8-42c8-9520-276f955c"}],"name":"Jira
Core","defaultGroups":["jira-core-users"],"defaultGroupsDetails":[{"name":"jira-core-users","groupId":"92d01dca0625-42c8-42c8-9520-276f955c","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=92d01dca0625-42c8-42c8-9520-276f955c"}],"selectedByDefault":false,"defined":false,"numberOfSeats":1,"remainingSeats":1,"userCount":0,"userCountDescription":"0
users","hasUnlimitedSeats":false,"platform":true}]
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user is not an administrator.
deprecated: false
security:
- basicAuth: []
x-atlassian-connect-scope: INACCESSIBLE
'/rest/api/3/applicationrole/{key}':
get:
tags:
- Application roles
summary: Get application role
description: >-
Returns an application role.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getApplicationRole
parameters:
- name: key
in: path
description: >-
The key of the application role. Use the [Get all application
roles](#api-rest-api-3-applicationrole-get) operation to get the key
for each application role.
required: true
schema:
type: string
example: jira-software
x-showInExample: 'true'
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationRole'
example: >-
{"key":"jira-software","groups":["jira-software-users","jira-testers"],"groupDetails":[{"name":"jira-testers","groupId":"42c8955c-63d7-42c8-9520-63d7aca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=42c8955c-63d7-42c8-9520-63d7aca0625"},{"name":"jira-software-users","groupId":"276f955c-63d7-42c8-9520-92d01dca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"}],"name":"Jira
Software","defaultGroups":["jira-software-users"],"defaultGroupsDetails":[{"name":"jira-software-users","groupId":"276f955c-63d7-42c8-9520-92d01dca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"}],"selectedByDefault":false,"defined":false,"numberOfSeats":10,"remainingSeats":5,"userCount":5,"userCountDescription":"5
developers","hasUnlimitedSeats":false,"platform":false}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user is not an administrator.
'404':
description: Returned if the role is not found.
deprecated: false
security:
- basicAuth: []
x-atlassian-connect-scope: INACCESSIBLE
'/rest/api/3/attachment/content/{id}':
get:
tags:
- Issue attachments
summary: Get attachment content
description: >-
Returns the contents of an attachment. A `Range` header can be set to
define a range of bytes within the attachment to download. See the [HTTP
Range header
standard](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range)
for details.
To return a thumbnail of the attachment, use [Get attachment
thumbnail](#api-rest-api-3-attachment-thumbnail-id-get).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** For the issue containing the
attachment:
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: getAttachmentContent
parameters:
- name: id
in: path
description: The ID of the attachment.
required: true
schema:
type: string
- name: redirect
in: query
description: >-
Whether a redirect is provided for the attachment download. Clients
that do not automatically follow redirects can set this to `false`
to avoid making multiple requests to download the attachment.
schema:
type: boolean
default: true
responses:
'200':
description: >-
Returned if the request is successful when `redirect` is set to
`false`.
content:
application/json:
schema:
type: object
'206':
description: >-
Returned if the request is successful when a `Range` header is
provided and `redirect` is set to `false`.
'303':
description: >-
Returned if the request is successful. See the `Location` header for
the download URL.
'400':
description: Returned if the range supplied in the `Range` header is malformed.
'401':
description: Returned if the authentication credentials are incorrect.
'403':
description: The user does not have the necessary permission.
'404':
description: |-
Returned if:
* the attachment is not found.
* attachments are disabled in the Jira settings.
'416':
description: >-
Returned if the server is unable to satisfy the range of bytes
provided.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:attachment:jira'
x-atlassian-connect-scope: READ
/rest/api/3/attachment/meta:
get:
tags:
- Issue attachments
summary: Get Jira attachment settings
description: >-
Returns the attachment settings, that is, whether attachments are
enabled and the maximum attachment size allowed.
Note that there are also [project
permissions](https://confluence.atlassian.com/x/yodKLg) that restrict
whether users can create and delete attachments.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: getAttachmentMeta
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentSettings'
example: '{"enabled":true,"uploadLimit":1000000}'
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:instance-configuration:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/attachment/thumbnail/{id}':
get:
tags:
- Issue attachments
summary: Get attachment thumbnail
description: >-
Returns the thumbnail of an attachment.
To return the attachment contents, use [Get attachment
content](#api-rest-api-3-attachment-content-id-get).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** For the issue containing the
attachment:
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: getAttachmentThumbnail
parameters:
- name: id
in: path
description: The ID of the attachment.
required: true
schema:
type: string
- name: redirect
in: query
description: >-
Whether a redirect is provided for the attachment download. Clients
that do not automatically follow redirects can set this to `false`
to avoid making multiple requests to download the attachment.
schema:
type: boolean
default: true
- name: fallbackToDefault
in: query
description: >-
Whether a default thumbnail is returned when the requested thumbnail
is not found.
schema:
type: boolean
default: true
- name: width
in: query
description: The maximum width to scale the thumbnail to.
schema:
type: integer
format: int32
- name: height
in: query
description: The maximum height to scale the thumbnail to.
schema:
type: integer
format: int32
responses:
'200':
description: >-
Returned if the request is successful when `redirect` is set to
`false`.
content:
application/json:
schema:
type: object
'303':
description: >-
Returned if the request is successful. See the `Location` header for
the download URL.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect.
'403':
description: The user does not have the necessary permission.
'404':
description: |-
Returned if:
* the attachment is not found.
* attachments are disabled in the Jira settings.
* `fallbackToDefault` is `false` and the request thumbnail cannot be downloaded.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:attachment:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/attachment/{id}':
get:
tags:
- Issue attachments
summary: Get attachment metadata
description: >-
Returns the metadata for an attachment. Note that the attachment itself
is not returned.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: getAttachment
parameters:
- name: id
in: path
description: The ID of the attachment.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentMetadata'
example: >-
{"id":10000,"self":"https://your-domain.atlassian.net/rest/api/3/attachments/10000","filename":"picture.jpg","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"created":"2023-04-12T08:25:30.048+0000","size":23123,"mimeType":"image/jpeg","content":"https://your-domain.atlassian.net/jira/rest/api/3/attachment/content/10000","thumbnail":"https://your-domain.atlassian.net/jira/rest/api/3/attachment/thumbnail/10000"}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: |-
Returned if:
* the attachment is not found.
* attachments are disabled in the Jira settings.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:attachment:jira'
- 'read:user:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:group:jira'
x-atlassian-connect-scope: READ
delete:
tags:
- Issue attachments
summary: Delete attachment
description: >-
Deletes an attachment from an issue.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** For the project holding the
issue containing the attachment:
* *Delete own attachments* [project permission](https://confluence.atlassian.com/x/yodKLg) to delete an attachment created by the calling user.
* *Delete all attachments* [project permission](https://confluence.atlassian.com/x/yodKLg) to delete an attachment created by any user.
operationId: removeAttachment
parameters:
- name: id
in: path
description: The ID of the attachment.
required: true
schema:
type: string
responses:
'204':
description: Returned if the request is successful.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: |-
Returned if:
* the attachment is not found.
* attachments are disabled in the Jira settings.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:attachment:jira'
x-atlassian-connect-scope: DELETE
'/rest/api/3/attachment/{id}/expand/human':
get:
tags:
- Issue attachments
summary: Get all metadata for an expanded attachment
description: >-
Returns the metadata for the contents of an attachment, if it is an
archive, and metadata for the attachment itself. For example, if the
attachment is a ZIP archive, then information about the files in the
archive is returned and metadata for the ZIP archive. Currently, only
the ZIP archive format is supported.
Use this operation to retrieve data that is presented to the user, as
this operation returns the metadata for the attachment itself, such as
the attachment's ID and name. Otherwise, use [ Get contents metadata for
an expanded attachment](#api-rest-api-3-attachment-id-expand-raw-get),
which only returns the metadata for the attachment's contents.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** For the issue containing the
attachment:
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: expandAttachmentForHumans
parameters:
- name: id
in: path
description: The ID of the attachment.
required: true
schema:
type: string
responses:
'200':
description: >-
Returned if the request is successful. If an empty list is returned
in the response, the attachment is empty, corrupt, or not an
archive.
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentArchiveMetadataReadable'
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"}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: The user does not have the necessary permission.
'404':
description: |-
Returned if:
* the attachment is not found.
* attachments are disabled in the Jira settings.
'409':
description: >-
Returned if the attachment is an archive, but not a supported
archive format.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:attachment:jira'
x-experimental: true
x-atlassian-connect-scope: READ
'/rest/api/3/attachment/{id}/expand/raw':
get:
tags:
- Issue attachments
summary: Get contents metadata for an expanded attachment
description: >-
Returns the metadata for the contents of an attachment, if it is an
archive. For example, if the attachment is a ZIP archive, then
information about the files in the archive is returned. Currently, only
the ZIP archive format is supported.
Use this operation if you are processing the data without presenting it
to the user, as this operation only returns the metadata for the
contents of the attachment. Otherwise, to retrieve data to present to
the user, use [ Get all metadata for an expanded
attachment](#api-rest-api-3-attachment-id-expand-human-get) which also
returns the metadata for the attachment itself, such as the attachment's
ID and name.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** For the issue containing the
attachment:
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: expandAttachmentForMachines
parameters:
- name: id
in: path
description: The ID of the attachment.
required: true
schema:
type: string
responses:
'200':
description: >-
Returned if the request is successful. If an empty list is returned
in the response, the attachment is empty, corrupt, or not an
archive.
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentArchiveImpl'
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}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: The user does not have the necessary permission.
'404':
description: |-
Returned if:
* the attachment is not found.
* attachments are disabled in the Jira settings.
'409':
description: >-
Returned if the attachment is an archive, but not a supported
archive format.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:attachment:jira'
x-experimental: true
x-atlassian-connect-scope: READ
/rest/api/3/auditing/record:
get:
tags:
- Audit records
summary: Get audit records
description: >-
Returns a list of audit records. The list can be filtered to include
items:
* where each item in `filter` has at least one match in any of these fields:
* `summary`
* `category`
* `eventSource`
* `objectItem.name` If the object is a user, account ID is available to filter.
* `objectItem.parentName`
* `objectItem.typeName`
* `changedValues.changedFrom`
* `changedValues.changedTo`
* `remoteAddress`
For example, if `filter` contains *man ed*, an audit record containing `summary": "User added to group"` and `"category": "group management"` is returned.
* created on or after a date and time.
* created or or before a date and time.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getAuditRecords
parameters:
- name: offset
in: query
description: The number of records to skip before returning the first result.
schema:
type: integer
format: int32
default: 0
- name: limit
in: query
description: The maximum number of results to return.
schema:
type: integer
format: int32
default: 1000
- name: filter
in: query
description: 'The strings to match with audit field content, space separated.'
schema:
type: string
- name: from
in: query
description: >-
The date and time on or after which returned audit records must have
been created. If `to` is provided `from` must be before `to` or no
audit records are returned.
schema:
type: string
format: date-time
- name: to
in: query
description: >-
The date and time on or before which returned audit results must
have been created. If `from` is provided `to` must be after `from`
or no audit records are returned.
schema:
type: string
format: date-time
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/AuditRecords'
example: >-
{"offset":0,"limit":1000,"total":1,"records":[{"id":1,"summary":"User
created","remoteAddress":"192.168.1.1","authorKey":"administrator","authorAccountId":"5ab8f18d741e9c2c7e9d4538","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"}]}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: |-
Returned if:
* the user does not have the required permissions.
* all Jira products are on free plans. Audit logs are available when at least one Jira product is on a paid plan.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:audit-log:jira'
- 'read:user:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/avatar/{type}/system':
get:
tags:
- Avatars
summary: Get system avatars by type
description: >-
Returns a list of system avatar details by owner type, where the owner
types are issue type, project, or user.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: getAllSystemAvatars
parameters:
- name: type
in: path
description: The avatar type.
required: true
schema:
type: string
example: project
enum:
- issuetype
- project
- user
x-showInExample: 'true'
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/SystemAvatars'
example: >-
{"system":[{"id":"1000","isSystemAvatar":true,"isSelected":false,"isDeletable":false,"urls":{"16x16":"/secure/useravatar?size=xsmall&avatarId=10040&avatarType=project","24x24":"/secure/useravatar?size=small&avatarId=10040&avatarType=project","32x32":"/secure/useravatar?size=medium&avatarId=10040&avatarType=project","48x48":"/secure/useravatar?avatarId=10040&avatarType=project"}}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'500':
description: Returned if an error occurs while retrieving the list of avatars.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:avatar:jira'
x-atlassian-connect-scope: ADMIN
/rest/api/3/comment/list:
post:
tags:
- Issue comments
summary: Get comments by IDs
description: >-
Returns a [paginated](#pagination) list of comments specified by a list
of comment IDs.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** Comments are returned where
the user:
* has *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the comment.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* If the comment has visibility restrictions, belongs to the group or has the role visibility is restricted to.
operationId: getCommentsByIds
parameters:
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
comments in the response. This parameter accepts a comma-separated
list. Expand options include:
* `renderedBody` Returns the comment body rendered in HTML.
* `properties` Returns the comment's properties.
schema:
type: string
requestBody:
description: The list of comment IDs.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueCommentListRequestBean'
example:
ids:
- 1
- 2
- 5
- 10
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanComment'
example: >-
{"maxResults":1048576,"startAt":0,"total":1,"isLast":true,"values":[{"self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000","id":"10000","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"body":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"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":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"created":"2021-01-17T12:34:00.000+0000","updated":"2021-01-18T23:45:00.000+0000","visibility":{"type":"role","value":"Administrators","identifier":"Administrators"}}]}
'400':
description: Returned if the request contains more than 1000 IDs or is empty.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:comment.property:jira'
- 'read:avatar:jira'
- 'read:comment:jira'
- 'read:group:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:comment.property:jira'
- 'read:project:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/comment/{commentId}/properties':
get:
tags:
- Issue comment properties
summary: Get comment property keys
description: |-
Returns the keys of all the properties of a comment.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* If the comment has visibility restrictions, belongs to the group or has the role visibility is restricted to.
operationId: getCommentPropertyKeys
parameters:
- name: commentId
in: path
description: The ID of the comment.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PropertyKeys'
example: >-
{"keys":[{"self":"https://your-domain.atlassian.net/rest/api/3/issue/EX-2/properties/issue.support","key":"issue.support"}]}
'400':
description: Returned if the comment ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the comment is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:comment.property:jira'
- 'read:dashboard.property:jira'
- 'read:issue-type.property:jira'
- 'read:issue-worklog.property:jira'
- 'read:issue.property:jira'
- 'read:project.property:jira'
- 'read:user.property:jira'
- 'read:workflow.property:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/comment/{commentId}/properties/{propertyKey}':
get:
tags:
- Issue comment properties
summary: Get comment property
description: |-
Returns the value of a comment property.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* If the comment has visibility restrictions, belongs to the group or has the role visibility is restricted to.
operationId: getCommentProperty
parameters:
- name: commentId
in: path
description: The ID of the comment.
required: true
schema:
type: string
- name: propertyKey
in: path
description: The key of the property.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/EntityProperty'
example: >-
{"key":"issue.support","value":{"system.conversation.id":"b1bf38be-5e94-4b40-a3b8-9278735ee1e6","system.support.time":"1m"}}
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the comment or the property is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:comment.property:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Issue comment properties
summary: Set comment property
description: >-
Creates or updates the value of a property for a comment. Use this
resource to store custom data against a comment.
The value of the request body must be a
[valid](http://tools.ietf.org/html/rfc4627), non-empty JSON blob. The
maximum length is 32768 characters.
**[Permissions](#permissions) required:** either of:
* *Edit All Comments* [project permission](https://confluence.atlassian.com/x/yodKLg) to create or update the value of a property on any comment.
* *Edit Own Comments* [project permission](https://confluence.atlassian.com/x/yodKLg) to create or update the value of a property on a comment created by the user.
Also, when the visibility of a comment is restricted to a role or group
the user must be a member of that role or group.
operationId: setCommentProperty
parameters:
- name: commentId
in: path
description: The ID of the comment.
required: true
schema:
type: string
- name: propertyKey
in: path
description: The key of the property. The maximum length is 255 characters.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema: {}
required: true
responses:
'200':
description: Returned if the comment property is updated.
content:
application/json:
schema: {}
'201':
description: Returned if the comment property is created.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the comment is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:comment.property:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Issue comment properties
summary: Delete comment property
description: >-
Deletes a comment property.
**[Permissions](#permissions) required:** either of:
* *Edit All Comments* [project permission](https://confluence.atlassian.com/x/yodKLg) to delete a property from any comment.
* *Edit Own Comments* [project permission](https://confluence.atlassian.com/x/yodKLg) to delete a property from a comment created by the user.
Also, when the visibility of a comment is restricted to a role or group
the user must be a member of that role or group.
operationId: deleteCommentProperty
parameters:
- name: commentId
in: path
description: The ID of the comment.
required: true
schema:
type: string
- name: propertyKey
in: path
description: The key of the property.
required: true
schema:
type: string
responses:
'204':
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: >-
Returned if the comment or the property is not found or the user has
the necessary project permissions but isn't a member of the role or
group visibility of the comment is restricted to.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:comment.property:jira'
x-atlassian-connect-scope: DELETE
/rest/api/3/component:
post:
tags:
- Project components
summary: Create component
description: >-
Creates a component. Use components to provide containers for issues
within a project.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** *Administer projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for the project
in which the component is created or *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: createComponent
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectComponent'
example:
assigneeType: PROJECT_LEAD
description: This is a Jira component
isAssigneeTypeValid: false
leadAccountId: 5b10a2844c20165700ede21g
name: Component 1
project: HSP
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectComponent'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/component/10000","id":"10000","name":"Component
1","description":"This is a Jira
component","lead":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"isAssigneeTypeValid":false,"project":"HSP","projectId":10000}
'400':
description: |-
Returned if:
* the user is not found.
* `name` is not provided.
* `name` is over 255 characters in length.
* `projectId` is not provided.
* `assigneeType` is an invalid value.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user does not have permission to manage the project
containing the component or does not have permission to administer
Jira.
'404':
description: >-
Returned if the project is not found or the user does not have
permission to browse the project containing the component.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-project'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-project'
- state: Beta
scheme: OAuth2
scopes:
- 'read:project:jira'
- 'read:user:jira'
- 'write:project.component:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:group:jira'
- 'read:project.component:jira'
x-atlassian-connect-scope: PROJECT_ADMIN
'/rest/api/3/component/{id}':
get:
tags:
- Project components
summary: Get component
description: >-
Returns a component.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** *Browse projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for project
containing the component.
operationId: getComponent
parameters:
- name: id
in: path
description: The ID of the component.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectComponent'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/component/10000","id":"10000","name":"Component
1","description":"This is a Jira
component","lead":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"isAssigneeTypeValid":false,"project":"HSP","projectId":10000}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the component is not found or the user does not have
permission to browse the project containing the component.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:project:jira'
- 'read:project.component:jira'
- 'read:user:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:group:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Project components
summary: Update component
description: >-
Updates a component. Any fields included in the request are overwritten.
If `leadAccountId` is an empty string ("") the component lead is
removed.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** *Administer projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for the project
containing the component or *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateComponent
parameters:
- name: id
in: path
description: The ID of the component.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectComponent'
example:
assigneeType: PROJECT_LEAD
description: This is a Jira component
isAssigneeTypeValid: false
leadAccountId: 5b10a2844c20165700ede21g
name: Component 1
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectComponent'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/component/10000","id":"10000","name":"Component
1","description":"This is a Jira
component","lead":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"assigneeType":"PROJECT_LEAD","assignee":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"realAssigneeType":"PROJECT_LEAD","realAssignee":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"isAssigneeTypeValid":false,"project":"HSP","projectId":10000}
'400':
description: |-
Returned if:
* the user is not found.
* `assigneeType` is an invalid value.
* `name` is over 255 characters in length.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user does not have permission to manage the project
containing the component or does not have permission to administer
Jira.
'404':
description: >-
Returned if the component is not found or the user does not have
permission to browse the project containing the component.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-project'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-project'
- state: Beta
scheme: OAuth2
scopes:
- 'read:project:jira'
- 'read:user:jira'
- 'write:project.component:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:group:jira'
- 'read:project.component:jira'
x-atlassian-connect-scope: PROJECT_ADMIN
delete:
tags:
- Project components
summary: Delete component
description: >-
Deletes a component.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** *Administer projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for the project
containing the component or *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: deleteComponent
parameters:
- name: id
in: path
description: The ID of the component.
required: true
schema:
type: string
- name: moveIssuesTo
in: query
description: >-
The ID of the component to replace the deleted component. If this
value is null no replacement is made.
schema:
type: string
responses:
'204':
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user does not have permission to manage the project
containing the component or does not have permission to administer
Jira.
'404':
description: |-
Returned if:
* the component is not found.
* the replacement component is not found.
* the user does not have permission to browse the project containing the component.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-project'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-project'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:project.component:jira'
x-atlassian-connect-scope: PROJECT_ADMIN
'/rest/api/3/component/{id}/relatedIssueCounts':
get:
tags:
- Project components
summary: Get component issues count
description: |-
Returns the counts of issues assigned to the component.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: getComponentRelatedIssues
parameters:
- name: id
in: path
description: The ID of the component.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/ComponentIssuesCount'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/component/10000","issueCount":23}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: Returned if the component is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes: []
x-atlassian-connect-scope: READ
/rest/api/3/configuration:
get:
tags:
- Jira settings
summary: Get global settings
description: >-
Returns the [global settings](https://confluence.atlassian.com/x/qYXKM)
in Jira. These settings determine whether optional features (for
example, subtasks, time tracking, and others) are enabled. If time
tracking is enabled, this operation also returns the time tracking
configuration.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: getConfiguration
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Configuration'
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"}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-user'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-user'
- state: Beta
scheme: OAuth2
scopes:
- 'read:instance-configuration:jira'
- 'read:issue.time-tracking:jira'
x-atlassian-connect-scope: READ
/rest/api/3/configuration/timetracking:
get:
tags:
- Time tracking
summary: Get selected time tracking provider
description: >-
Returns the time tracking provider that is currently selected. Note that
if time tracking is disabled, then a successful but empty response is
returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getSelectedTimeTrackingImplementation
parameters: []
responses:
'200':
description: Returned if the request is successful and time tracking is enabled.
content:
application/json:
schema:
$ref: '#/components/schemas/TimeTrackingProvider'
example: >-
{"key":"Jira","name":"JIRA provided time
tracking","url":"/example/config/url"}
'204':
description: Returned if the request is successful but time tracking is disabled.
content:
application/json:
schema: {}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue.time-tracking:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Time tracking
summary: Select time tracking provider
description: >-
Selects a time tracking provider.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: selectTimeTrackingImplementation
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TimeTrackingProvider'
example:
key: Jira
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the time tracking provider is not found.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue.time-tracking:jira'
x-atlassian-connect-scope: ADMIN
/rest/api/3/configuration/timetracking/list:
get:
tags:
- Time tracking
summary: Get all time tracking providers
description: >-
Returns all time tracking providers. By default, Jira only has one time
tracking provider: *JIRA provided time tracking*. However, you can
install other time tracking providers via apps from the Atlassian
Marketplace. For more information on time tracking providers, see the
documentation for the [ Time Tracking
Provider](https://developer.atlassian.com/cloud/jira/platform/modules/time-tracking-provider/)
module.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getAvailableTimeTrackingImplementations
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/TimeTrackingProvider'
example: >-
[{"key":"Jira","name":"JIRA provided time
tracking","url":"/example/config/url"}]
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue.time-tracking:jira'
x-atlassian-connect-scope: READ
/rest/api/3/configuration/timetracking/options:
get:
tags:
- Time tracking
summary: Get time tracking settings
description: >-
Returns the time tracking settings. This includes settings such as the
time format, default time unit, and others. For more information, see
[Configuring time tracking](https://confluence.atlassian.com/x/qoXKM).
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getSharedTimeTrackingConfiguration
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/TimeTrackingConfiguration'
example: >-
{"workingHoursPerDay":7.6,"workingDaysPerWeek":5.5,"timeFormat":"pretty","defaultUnit":"hour"}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue.time-tracking:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Time tracking
summary: Set time tracking settings
description: >-
Sets the time tracking settings.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: setSharedTimeTrackingConfiguration
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TimeTrackingConfiguration'
example:
defaultUnit: hour
timeFormat: pretty
workingDaysPerWeek: 5.5
workingHoursPerDay: 7.6
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/TimeTrackingConfiguration'
example: >-
{"workingHoursPerDay":7.6,"workingDaysPerWeek":5.5,"timeFormat":"pretty","defaultUnit":"hour"}
'400':
description: Returned if the request object is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue.time-tracking:jira'
- 'read:issue.time-tracking:jira'
x-atlassian-connect-scope: ADMIN
'/rest/api/3/customFieldOption/{id}':
get:
tags:
- Issue custom field options
summary: Get custom field option
description: >-
Returns a custom field option. For example, an option in a select list.
Note that this operation **only works for issue field select list
options created in Jira or using operations from the [Issue custom field
options](#api-group-Issue-custom-field-options) resource**, it cannot be
used with issue field select list options created by Connect apps.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** The custom field option is
returned as follows:
* if the user has the *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
* if the user has the *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for at least one project the custom field is used in, and the field is visible in at least one layout the user has permission to view.
operationId: getCustomFieldOption
parameters:
- name: id
in: path
description: The ID of the custom field option.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldOption'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/customFieldOption/10000","value":"To
Do"}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* the custom field option is not found.
* the user does not have permission to view the custom field.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
- 'read:field.option:jira'
x-atlassian-connect-scope: READ
/rest/api/3/dashboard:
get:
tags:
- Dashboards
summary: Get all dashboards
description: >-
Returns a list of dashboards owned by or shared with the user. The list
may be filtered to include only favorite or owned dashboards.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: getAllDashboards
parameters:
- name: filter
in: query
description: |-
The filter applied to the list of dashboards. Valid values are:
* `favourite` Returns dashboards the user has marked as favorite.
* `my` Returns dashboards owned by the user.
schema:
type: string
enum:
- my
- favourite
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int32
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 20
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageOfDashboards'
example: >-
{"startAt":10,"maxResults":10,"total":143,"prev":"https://your-domain.atlassian.net/rest/api/3/dashboard?startAt=0","next":"https://your-domain.atlassian.net/rest/api/3/dashboard?startAt=10","dashboards":[{"id":"10000","isFavourite":false,"name":"System
Dashboard","popularity":1,"self":"https://your-domain.atlassian.net/rest/api/3/dashboard/10000","sharePermissions":[{"type":"global"}],"view":"https://your-domain.atlassian.net/secure/Dashboard.jspa?selectPageId=10000"},{"id":"20000","isFavourite":true,"name":"Build
Engineering","owner":{"key":"Mia","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","name":"mia","displayName":"Mia
Krystof","avatarUrls":{"16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32","48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"}},"popularity":1,"self":"https://your-domain.atlassian.net/rest/api/3/dashboard/20000","sharePermissions":[{"id":10105,"type":"group","group":{"name":"administrators","self":"https://your-domain.atlassian.net/rest/api/3/group?groupname=administrators"}}],"view":"https://your-domain.atlassian.net/secure/Dashboard.jspa?selectPageId=20000"}]}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:dashboard:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project-version:jira'
- 'read:project.component:jira'
x-atlassian-connect-scope: READ
post:
tags:
- Dashboards
summary: Create dashboard
description: |-
Creates a dashboard.
**[Permissions](#permissions) required:** None.
operationId: createDashboard
parameters: []
requestBody:
description: Dashboard details.
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardDetails'
example:
description: A dashboard to help auditors identify sample of issues to check.
editPermissions: []
name: Auditors dashboard
sharePermissions:
- type: global
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Dashboard'
example: >-
{"id":"10000","isFavourite":false,"name":"System
Dashboard","popularity":1,"self":"https://your-domain.atlassian.net/rest/api/3/dashboard/10000","sharePermissions":[{"type":"global"}],"view":"https://your-domain.atlassian.net/secure/Dashboard.jspa?selectPageId=10000"}
'400':
description: Returned if the request is not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:dashboard:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'write:dashboard:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project-version:jira'
- 'read:project.component:jira'
x-experimental: true
x-atlassian-connect-scope: WRITE
/rest/api/3/dashboard/gadgets:
get:
tags:
- Dashboards
summary: Get available gadgets
description: >-
Gets a list of all available gadgets that can be added to all
dashboards.
**[Permissions](#permissions) required:** None.
operationId: getAllAvailableDashboardGadgets
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/AvailableDashboardGadgetsResponse'
example: >-
{"gadgets":[{"moduleKey":"com.atlassian.plugins.atlassian-connect-plugin:com.atlassian.connect.node.sample-addon__sample-dashboard-item","title":"Issue
statistics"},{"uri":"rest/gadgets/1.0/g/com.atlassian.streams.streams-jira-plugin:activitystream-gadget/gadgets/activitystream-gadget.xml","title":"Activity
Stream"}]}
'400':
description: 400 response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:dashboard:jira'
x-experimental: true
x-atlassian-connect-scope: READ
/rest/api/3/dashboard/search:
get:
tags:
- Dashboards
summary: Search for dashboards
description: >-
Returns a [paginated](#pagination) list of dashboards. This operation is
similar to [Get dashboards](#api-rest-api-3-dashboard-get) except that
the results can be refined to include dashboards that have specific
attributes. For example, dashboards with a particular name. When
multiple attributes are specified only filters matching all attributes
are returned.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** The following dashboards that
match the query parameters are returned:
* Dashboards owned by the user. Not returned for anonymous users.
* Dashboards shared with a group that the user is a member of. Not returned for anonymous users.
* Dashboards shared with a private project that the user can browse. Not returned for anonymous users.
* Dashboards shared with a public project.
* Dashboards shared with the public.
operationId: getDashboardsPaginated
parameters:
- name: dashboardName
in: query
description: String used to perform a case-insensitive partial match with `name`.
schema:
type: string
- name: accountId
in: query
description: >-
User account ID used to return dashboards with the matching
`owner.accountId`. This parameter cannot be used with the `owner`
parameter.
schema:
maxLength: 128
type: string
- name: owner
in: query
description: >-
This parameter is deprecated because of privacy changes. Use
`accountId` instead. See the [migration
guide](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/)
for details. User name used to return dashboards with the matching
`owner.name`. This parameter cannot be used with the `accountId`
parameter.
schema:
type: string
- name: groupname
in: query
description: >-
As a group's name can change, use of `groupId` is recommended. Group
name used to return dashboards that are shared with a group that
matches `sharePermissions.group.name`. This parameter cannot be used
with the `groupId` parameter.
schema:
type: string
- name: groupId
in: query
description: >-
Group ID used to return dashboards that are shared with a group that
matches `sharePermissions.group.groupId`. This parameter cannot be
used with the `groupname` parameter.
schema:
type: string
- name: projectId
in: query
description: >-
Project ID used to returns dashboards that are shared with a project
that matches `sharePermissions.project.id`.
schema:
type: integer
format: int64
- name: orderBy
in: query
description: |-
[Order](#ordering) the results by a field:
* `description` Sorts by dashboard description. Note that this sort works independently of whether the expand to display the description field is in use.
* `favourite_count` Sorts by dashboard popularity.
* `id` Sorts by dashboard ID.
* `is_favourite` Sorts by whether the dashboard is marked as a favorite.
* `name` Sorts by dashboard name.
* `owner` Sorts by dashboard owner name.
schema:
type: string
default: name
enum:
- description
- '-description'
- +description
- favorite_count
- '-favorite_count'
- +favorite_count
- id
- '-id'
- +id
- is_favorite
- '-is_favorite'
- +is_favorite
- name
- '-name'
- +name
- owner
- '-owner'
- +owner
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: status
in: query
description: 'The status to filter by. It may be active, archived or deleted.'
schema:
type: string
default: active
enum:
- active
- archived
- deleted
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
dashboard in the response. This parameter accepts a comma-separated
list. Expand options include:
* `description` Returns the description of the dashboard.
* `owner` Returns the owner of the dashboard.
* `viewUrl` Returns the URL that is used to view the dashboard.
* `favourite` Returns `isFavourite`, an indicator of whether the user has set the dashboard as a favorite.
* `favouritedCount` Returns `popularity`, a count of how many users have set this dashboard as a favorite.
* `sharePermissions` Returns details of the share permissions defined for the dashboard.
* `editPermissions` Returns details of the edit permissions defined for the dashboard.
* `isWritable` Returns whether the current user has permission to edit the dashboard.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanDashboard'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/dashboard/search?expand=owner&maxResults=50&startAt=0","maxResults":100,"startAt":0,"total":2,"isLast":true,"values":[{"description":"Testing
program","id":"1","isFavourite":true,"name":"Testing","owner":{"self":"https://your-domain.atlassian.net/user?accountId=5b10a2844c20165700ede21g","displayName":"Mia","active":true,"accountId":"5b10a2844c20165700ede21g","avatarUrls":{"16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32","48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"}},"popularity":1,"self":"https://your-domain.atlassian.net/rest/api/3/dashboard/1","sharePermissions":[{"type":"global"}],"view":"https://your-domain.atlassian.net/Dashboard.jspa?selectPageId=1"},{"description":"Quantum
initiative","id":"2","isFavourite":false,"name":"Quantum
","owner":{"self":"https://your-domain.atlassian.net/user?accountId=5b10a2844c20165700ede21g","displayName":"Mia","active":true,"accountId":"5b10a2844c20165700ede21g","avatarUrls":{"16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32","48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"}},"popularity":0,"self":"https://your-domain.atlassian.net/rest/api/3/dashboard/2","sharePermissions":[{"type":"loggedin"}],"view":"https://your-domain.atlassian.net/Dashboard.jspa?selectPageId=2"}]}
'400':
description: |-
Returned if:
* `orderBy` is invalid.
* `expand` includes an invalid value.
* `accountId` and `owner` are provided.
* `groupname` and `groupId` are provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: 401 response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:dashboard:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project-version:jira'
- 'read:project.component:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/dashboard/{dashboardId}/gadget':
get:
tags:
- Dashboards
summary: Get gadgets
description: |-
Returns a list of dashboard gadgets on a dashboard.
This operation returns:
* Gadgets from a list of IDs, when `id` is set.
* Gadgets with a module key, when `moduleKey` is set.
* Gadgets from a list of URIs, when `uri` is set.
* All gadgets, when no other parameters are set.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: getAllGadgets
parameters:
- name: dashboardId
in: path
description: The ID of the dashboard.
required: true
schema:
type: integer
format: int64
- name: moduleKey
in: query
description: >-
The list of gadgets module keys. To include multiple module keys,
separate module keys with ampersand:
`moduleKey=key:one&moduleKey=key:two`.
schema:
type: array
items:
type: string
- name: uri
in: query
description: >-
The list of gadgets URIs. To include multiple URIs, separate URIs
with ampersand: `uri=/rest/example/uri/1&uri=/rest/example/uri/2`.
schema:
type: array
items:
type: string
- name: gadgetId
in: query
description: >-
The list of gadgets IDs. To include multiple IDs, separate IDs with
ampersand: `gadgetId=10000&gadgetId=10001`.
schema:
type: array
items:
type: integer
format: int64
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardGadgetResponse'
example: >-
{"gadgets":[{"id":10001,"moduleKey":"com.atlassian.plugins.atlassian-connect-plugin:com.atlassian.connect.node.sample-addon__sample-dashboard-item","color":"blue","position":{"row":0,"column":0},"title":"Issue
statistics"},{"id":10002,"moduleKey":"com.atlassian.plugins.atlassian-connect-plugin:com.atlassian.connect.node.sample-addon__sample-dashboard-graph","color":"red","position":{"row":1,"column":0},"title":"Activity
stream"},{"id":10003,"moduleKey":"com.atlassian.plugins.atlassian-connect-plugin:com.atlassian.connect.node.sample-addon__sample-dashboard-item","color":"yellow","position":{"row":0,"column":1},"title":"Bubble
chart"}]}
'401':
description: Returned if the authentication credentials are incorrect.
'404':
description: Returned if the dashboard is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["The dashboard you requested either does not
exist or you don't have the required permissions to perform this
action."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:dashboard:jira'
x-experimental: true
x-atlassian-connect-scope: READ
post:
tags:
- Dashboards
summary: Add gadget to dashboard
description: |-
Adds a gadget to a dashboard.
**[Permissions](#permissions) required:** None.
operationId: addGadget
parameters:
- name: dashboardId
in: path
description: The ID of the dashboard.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardGadgetSettings'
example:
color: blue
ignoreUriAndModuleKeyValidation: false
moduleKey: >-
com.atlassian.plugins.atlassian-connect-plugin:com.atlassian.connect.node.sample-addon__sample-dashboard-item
position:
column: 1
row: 0
title: Issue statistics
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardGadget'
example: >-
{"id":10001,"moduleKey":"com.atlassian.plugins.atlassian-connect-plugin:com.atlassian.connect.node.sample-addon__sample-dashboard-item","color":"blue","position":{"row":0,"column":1},"title":"Issue
statistics"}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["Cannot add another gadget. The maximum number
of gadgets the dashboard can hold has been
reached."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: Returned if the dashboard is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["The dashboard you requested either does not
exist or you don't have the required permissions to perform this
action."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- 'read:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:dashboard:jira'
- 'read:dashboard:jira'
x-experimental: true
x-atlassian-connect-scope: WRITE
'/rest/api/3/dashboard/{dashboardId}/gadget/{gadgetId}':
put:
tags:
- Dashboards
summary: Update gadget on dashboard
description: |-
Changes the title, position, and color of the gadget on a dashboard.
**[Permissions](#permissions) required:** None.
operationId: updateGadget
parameters:
- name: dashboardId
in: path
description: The ID of the dashboard.
required: true
schema:
type: integer
format: int64
- name: gadgetId
in: path
description: The ID of the gadget.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardGadgetUpdateRequest'
example:
color: red
position:
column: 1
row: 1
title: My new gadget title
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["The gadget cannot be placed in the selected
row. The selected row does not exist on the
dashboard."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect.
'404':
description: Returned if the gadget or the dashboard is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["The dashboard you requested either does not
exist or you don't have the required permissions to perform this
action."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:dashboard:jira'
x-experimental: true
x-atlassian-connect-scope: WRITE
delete:
tags:
- Dashboards
summary: Remove gadget from dashboard
description: >-
Removes a dashboard gadget from a dashboard.
When a gadget is removed from a dashboard, other gadgets in the same
column are moved up to fill the emptied position.
**[Permissions](#permissions) required:** None.
operationId: removeGadget
parameters:
- name: dashboardId
in: path
description: The ID of the dashboard.
required: true
schema:
type: integer
format: int64
- name: gadgetId
in: path
description: The ID of the gadget.
required: true
schema:
type: integer
format: int64
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: Returned if the gadget or the dashboard is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["The dashboard gadget was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:dashboard:jira'
x-experimental: true
x-atlassian-connect-scope: DELETE
'/rest/api/3/dashboard/{dashboardId}/items/{itemId}/properties':
get:
tags:
- Dashboards
summary: Get dashboard item property keys
description: >-
Returns the keys of all properties for a dashboard item.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** The user must be the owner of
the dashboard or have the dashboard shared with them. Note, users with
the *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) are considered
owners of the System dashboard. The System dashboard is considered to be
shared with all other users, and is accessible to anonymous users when
Jira’s anonymous access is permitted.
operationId: getDashboardItemPropertyKeys
parameters:
- name: dashboardId
in: path
description: The ID of the dashboard.
required: true
schema:
type: string
- name: itemId
in: path
description: The ID of the dashboard item.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PropertyKeys'
example: >-
{"keys":[{"self":"https://your-domain.atlassian.net/rest/api/3/issue/EX-2/properties/issue.support","key":"issue.support"}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the dashboard or dashboard item is not found, or the
dashboard is not owned by or shared with the user.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:dashboard.property:jira'
- 'read:comment.property:jira'
- 'read:issue-type.property:jira'
- 'read:issue-worklog.property:jira'
- 'read:issue.property:jira'
- 'read:project.property:jira'
- 'read:user.property:jira'
- 'read:workflow.property:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/dashboard/{dashboardId}/items/{itemId}/properties/{propertyKey}':
get:
tags:
- Dashboards
summary: Get dashboard item property
description: >-
Returns the key and value of a dashboard item property.
A dashboard item enables an app to add user-specific information to a
user dashboard. Dashboard items are exposed to users as gadgets that
users can add to their dashboards. For more information on how users do
this, see [Adding and customizing
gadgets](https://confluence.atlassian.com/x/7AeiLQ).
When an app creates a dashboard item it registers a callback to receive
the dashboard item ID. The callback fires whenever the item is rendered
or, where the item is configurable, the user edits the item. The app
then uses this resource to store the item's content or configuration
details. For more information on working with dashboard items, see [
Building a dashboard item for a JIRA Connect
add-on](https://developer.atlassian.com/server/jira/platform/guide-building-a-dashboard-item-for-a-jira-connect-add-on-33746254/)
and the [Dashboard
Item](https://developer.atlassian.com/cloud/jira/platform/modules/dashboard-item/)
documentation.
There is no resource to set or get dashboard items.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** The user must be the owner of
the dashboard or have the dashboard shared with them. Note, users with
the *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) are considered
owners of the System dashboard. The System dashboard is considered to be
shared with all other users, and is accessible to anonymous users when
Jira’s anonymous access is permitted.
operationId: getDashboardItemProperty
parameters:
- name: dashboardId
in: path
description: The ID of the dashboard.
required: true
schema:
type: string
- name: itemId
in: path
description: The ID of the dashboard item.
required: true
schema:
type: string
- name: propertyKey
in: path
description: The key of the dashboard item property.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/EntityProperty'
example: >-
{"key":"issue.support","value":{"system.conversation.id":"b1bf38be-5e94-4b40-a3b8-9278735ee1e6","system.support.time":"1m"}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the dashboard, the dashboard item, or dashboard item
property is not found, or the dashboard is not owned by or shared
with the user.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:dashboard.property:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Dashboards
summary: Set dashboard item property
description: >-
Sets the value of a dashboard item property. Use this resource in apps
to store custom data against a dashboard item.
A dashboard item enables an app to add user-specific information to a
user dashboard. Dashboard items are exposed to users as gadgets that
users can add to their dashboards. For more information on how users do
this, see [Adding and customizing
gadgets](https://confluence.atlassian.com/x/7AeiLQ).
When an app creates a dashboard item it registers a callback to receive
the dashboard item ID. The callback fires whenever the item is rendered
or, where the item is configurable, the user edits the item. The app
then uses this resource to store the item's content or configuration
details. For more information on working with dashboard items, see [
Building a dashboard item for a JIRA Connect
add-on](https://developer.atlassian.com/server/jira/platform/guide-building-a-dashboard-item-for-a-jira-connect-add-on-33746254/)
and the [Dashboard
Item](https://developer.atlassian.com/cloud/jira/platform/modules/dashboard-item/)
documentation.
There is no resource to set or get dashboard items.
The value of the request body must be a
[valid](http://tools.ietf.org/html/rfc4627), non-empty JSON blob. The
maximum length is 32768 characters.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** The user must be the owner of
the dashboard. Note, users with the *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) are considered
owners of the System dashboard.
operationId: setDashboardItemProperty
parameters:
- name: dashboardId
in: path
description: The ID of the dashboard.
required: true
schema:
type: string
- name: itemId
in: path
description: The ID of the dashboard item.
required: true
schema:
type: string
- name: propertyKey
in: path
description: >-
The key of the dashboard item property. The maximum length is 255
characters. For dashboard items with a spec URI and no complete
module key, if the provided propertyKey is equal to "config", the
request body's JSON must be an object with all keys and values as
strings.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema: {}
example:
number: 5
string: string-value
required: true
responses:
'200':
description: Returned if the dashboard item property is updated.
content:
application/json:
schema: {}
'201':
description: Returned if the dashboard item property is created.
content:
application/json:
schema: {}
'400':
description: |-
Returned if:
* Request is invalid
* Or if all of these conditions are met in the request:
* The dashboard item has a spec URI and no complete module key
* The value of propertyKey is equal to "config"
* The request body contains a JSON object whose keys and values are not strings.
content:
application/json:
example: >-
{"errorMessages":["The JSON data provided for the property has
too many levels. It must be an object with all keys and values
as strings."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user is not the owner of the dashboard.
'404':
description: >-
Returned if the dashboard item is not found or the dashboard is not
shared with the user.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:dashboard.property:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Dashboards
summary: Delete dashboard item property
description: >-
Deletes a dashboard item property.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** The user must be the owner of
the dashboard. Note, users with the *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) are considered
owners of the System dashboard.
operationId: deleteDashboardItemProperty
parameters:
- name: dashboardId
in: path
description: The ID of the dashboard.
required: true
schema:
type: string
- name: itemId
in: path
description: The ID of the dashboard item.
required: true
schema:
type: string
- name: propertyKey
in: path
description: The key of the dashboard item property.
required: true
schema:
type: string
responses:
'204':
description: Returned if the dashboard item property is deleted.
'400':
description: Returned if the dashboard or dashboard item ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user is not the owner of the dashboard.
'404':
description: >-
Returned if the dashboard item is not found or the dashboard is not
shared with the user.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:dashboard.property:jira'
x-atlassian-connect-scope: DELETE
'/rest/api/3/dashboard/{id}':
get:
tags:
- Dashboards
summary: Get dashboard
description: >-
Returns a dashboard.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
However, to get a dashboard, the dashboard must be shared with the user
or the user must own it. Note, users with the *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) are considered
owners of the System dashboard. The System dashboard is considered to be
shared with all other users.
operationId: getDashboard
parameters:
- name: id
in: path
description: The ID of the dashboard.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Dashboard'
example: >-
{"id":"10000","isFavourite":false,"name":"System
Dashboard","popularity":1,"self":"https://your-domain.atlassian.net/rest/api/3/dashboard/10000","sharePermissions":[{"type":"global"}],"view":"https://your-domain.atlassian.net/secure/Dashboard.jspa?selectPageId=10000"}
'400':
description: 400 response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'404':
description: >-
Returned if the dashboard is not found or the dashboard is not owned
by or shared with the user.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:dashboard:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project-version:jira'
- 'read:project.component:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Dashboards
summary: Update dashboard
description: >-
Updates a dashboard, replacing all the dashboard details with those
provided.
**[Permissions](#permissions) required:** None
The dashboard to be updated must be owned by the user.
operationId: updateDashboard
parameters:
- name: id
in: path
description: The ID of the dashboard to update.
required: true
schema:
type: string
requestBody:
description: Replacement dashboard details.
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardDetails'
example:
description: A dashboard to help auditors identify sample of issues to check.
editPermissions: []
name: Auditors dashboard
sharePermissions:
- type: global
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Dashboard'
example: >-
{"id":"10000","isFavourite":false,"name":"System
Dashboard","popularity":1,"self":"https://your-domain.atlassian.net/rest/api/3/dashboard/10000","sharePermissions":[{"type":"global"}],"view":"https://your-domain.atlassian.net/secure/Dashboard.jspa?selectPageId=10000"}
'400':
description: Returned if the request is not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'404':
description: >-
Returned if the dashboard is not found or the dashboard is not owned
by the user.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:dashboard:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'write:dashboard:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project-version:jira'
- 'read:project.component:jira'
x-experimental: true
x-atlassian-connect-scope: WRITE
delete:
tags:
- Dashboards
summary: Delete dashboard
description: |-
Deletes a dashboard.
**[Permissions](#permissions) required:** None
The dashboard to be deleted must be owned by the user.
operationId: deleteDashboard
parameters:
- name: id
in: path
description: The ID of the dashboard.
required: true
schema:
type: string
responses:
'204':
description: Returned if the dashboard is deleted.
'400':
description: 400 response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:dashboard:jira'
x-experimental: true
x-atlassian-connect-scope: DELETE
'/rest/api/3/dashboard/{id}/copy':
post:
tags:
- Dashboards
summary: Copy dashboard
description: >-
Copies a dashboard. Any values provided in the `dashboard` parameter
replace those in the copied dashboard.
**[Permissions](#permissions) required:** None
The dashboard to be copied must be owned by or shared with the user.
operationId: copyDashboard
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
description: Dashboard details.
content:
application/json:
schema:
$ref: '#/components/schemas/DashboardDetails'
example:
description: A dashboard to help auditors identify sample of issues to check.
editPermissions: []
name: Auditors dashboard
sharePermissions:
- type: global
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Dashboard'
example: >-
{"id":"10000","isFavourite":false,"name":"System
Dashboard","popularity":1,"self":"https://your-domain.atlassian.net/rest/api/3/dashboard/10000","sharePermissions":[{"type":"global"}],"view":"https://your-domain.atlassian.net/secure/Dashboard.jspa?selectPageId=10000"}
'400':
description: Returned if the request is not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'404':
description: >-
Returned if the dashboard is not found or the dashboard is not owned
by or shared with the user.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:dashboard:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'write:dashboard:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project-version:jira'
- 'read:project.component:jira'
x-experimental: true
x-atlassian-connect-scope: WRITE
/rest/api/3/events:
get:
tags:
- Issues
summary: Get events
description: >-
Returns all issue events.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getEvents
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IssueEvent'
example: >-
[{"id":1,"name":"Issue Created"},{"id":2,"name":"Issue
Updated"}]
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user does not have permission to complete this
request.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-event:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/expression/analyse:
post:
tags:
- Jira expressions
summary: Analyse Jira expression
description: >-
Analyses and validates Jira expressions.
As an experimental feature, this operation can also attempt to
type-check the expressions.
Learn more about Jira expressions in the
[documentation](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/).
**[Permissions](#permissions) required**: None.
operationId: analyseExpression
parameters:
- name: check
in: query
description: |-
The check to perform:
* `syntax` Each expression's syntax is checked to ensure the expression can be parsed. Also, syntactic limits are validated. For example, the expression's length.
* `type` EXPERIMENTAL. Each expression is type checked and the final type of the expression inferred. Any type errors that would result in the expression failure at runtime are reported. For example, accessing properties that don't exist or passing the wrong number of arguments to functions. Also performs the syntax check.
* `complexity` EXPERIMENTAL. Determines the formulae for how many [expensive operations](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/#expensive-operations) each expression may execute.
schema:
type: string
default: syntax
enum:
- syntax
- type
- complexity
requestBody:
description: The Jira expressions to analyse.
content:
application/json:
schema:
$ref: '#/components/schemas/JiraExpressionForAnalysis'
example:
contextVariables:
listOfStrings: List<String>
record: '{ a: Number, b: String }'
value: User
expressions:
- 'issues.map(issue => issue.properties[''property_key''])'
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/JiraExpressionsAnalysis'
example: >-
{"results":[{"expression":"analysed
expression","errors":[{"line":1,"column":4,"message":"!, -,
typeof, (, IDENTIFIER, null, true, false, NUMBER, STRING,
TEMPLATE_LITERAL, new, [ or { expected, >
encountered.","type":"syntax"},{"message":"Jira expression is
too long (1040), limit: 1000
characters","type":"other"},{"message":"Jira expression has too
many nodes (150), limit: 100
leaves","type":"other"}],"valid":false},{"expression":"issues.map(i
=> {idAndKey: [i.id, i.key], summary: i.summary, comments:
i.comments})","valid":true,"type":"List<{idAndKey: [Number,
String], summary: String, comments:
List<Comment>}>","complexity":{"expensiveOperations":"N","variables":{"N":"issues"}}},{"expression":"issues.map(i
=> i.id > '0')","errors":[{"expression":"i.id >
0","message":"Can't compare Number to
String.","type":"type"}],"valid":false,"type":"TypeError"}]}
'400':
description: 400 response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: 404 response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- 'read:jira-user'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- 'read:jira-user'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
- 'read:jira-expressions:jira'
x-atlassian-connect-scope: READ
/rest/api/3/expression/eval:
post:
tags:
- Jira expressions
summary: Evaluate Jira expression
description: >-
Evaluates a Jira expression and returns its value.
This resource can be used to test Jira expressions that you plan to use
elsewhere, or to fetch data in a flexible way. Consult the [Jira
expressions
documentation](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/)
for more details.
#### Context variables ####
The following context variables are available to Jira expressions
evaluated by this resource. Their presence depends on various factors;
usually you need to manually request them in the context object sent in
the payload, but some of them are added automatically under certain
conditions.
* `user` ([User](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#user)): The current user. Always available and equal to `null` if the request is anonymous.
* `app` ([App](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#app)): The [Connect app](https://developer.atlassian.com/cloud/jira/platform/index/#connect-apps) that made the request. Available only for authenticated requests made by Connect Apps (read more here: [Authentication for Connect apps](https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/)).
* `issue` ([Issue](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)): The current issue. Available only when the issue is provided in the request context object.
* `issues` ([List](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#list) of [Issues](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)): A collection of issues matching a JQL query. Available only when JQL is provided in the request context object.
* `project` ([Project](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#project)): The current project. Available only when the project is provided in the request context object.
* `sprint` ([Sprint](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#sprint)): The current sprint. Available only when the sprint is provided in the request context object.
* `board` ([Board](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#board)): The current board. Available only when the board is provided in the request context object.
* `serviceDesk` ([ServiceDesk](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#servicedesk)): The current service desk. Available only when the service desk is provided in the request context object.
* `customerRequest` ([CustomerRequest](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#customerrequest)): The current customer request. Available only when the customer request is provided in the request context object.
Also, custom context variables can be passed in the request with their
types. Those variables can be accessed by key in the Jira expression.
These variable types are available for use in a custom context:
* `user`: A [user](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#user) specified as an Atlassian account ID.
* `issue`: An [issue](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue) specified by ID or key. All the fields of the issue object are available in the Jira expression.
* `json`: A JSON object containing custom content.
* `list`: A JSON list of `user`, `issue`, or `json` variable types.
This operation can be accessed anonymously.
**[Permissions](#permissions) required**: None. However, an expression
may return different results for different users depending on their
permissions. For example, different users may see different comments on
the same issue.
Permission to access Jira Software is required to access Jira Software
context variables (`board` and `sprint`) or fields (for example,
`issue.sprint`).
operationId: evaluateJiraExpression
parameters:
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts `meta.complexity` that returns
information about the expression complexity. For example, the number
of expensive operations used by the expression and how close the
expression is to reaching the [complexity
limit](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/#restrictions).
Useful when designing and debugging your expressions.
schema:
type: string
requestBody:
description: The Jira expression and the evaluation context.
content:
application/json:
schema:
$ref: '#/components/schemas/JiraExpressionEvalRequestBean'
example:
context:
board: 10100
custom:
config:
type: json
value:
userId: '10002'
issuesList:
- key: ACJIRA-1471
type: issue
- id: 100001
type: issue
myUser:
accountId: '100001'
type: user
nullField:
type: json
customerRequest: 1450
issue:
key: ACJIRA-1470
issues:
jql:
maxResults: 100
query: project = HSP
startAt: 0
validation: strict
project:
key: ACJIRA
serviceDesk: 10023
sprint: 10001
expression: >-
{ key: issue.key, type: issue.issueType.name, links:
issue.links.map(link => link.linkedIssue.id),
listCustomVariable: issuesList.includes(issue), customVariables:
myUser.accountId == config.userId}
required: true
responses:
'200':
description: >-
Returned if the evaluation results in a value. The result is a JSON
primitive value, list, or object.
content:
application/json:
schema:
$ref: '#/components/schemas/JiraExpressionResult'
example: >-
{"value":"The expression's result. This value can be any JSON,
not necessarily a
String","meta":{"complexity":{"steps":{"value":1,"limit":10000},"expensiveOperations":{"value":3,"limit":10},"beans":{"value":0,"limit":1000},"primitiveValues":{"value":1,"limit":10000}},"issues":{"jql":{"startAt":0,"maxResults":1000,"count":140,"totalCount":140,"validationWarnings":["There
is a problem with the JQL query."]}}}}
'400':
description: |-
Returned if:
* the request is invalid, that is:
* invalid data is provided, such as a request including issue ID and key.
* the expression is invalid and can not be parsed.
* evaluation fails at runtime. This may happen for various reasons. For example, accessing a property on a null object (such as the expression `issue.id` where `issue` is `null`). In this case an error message is provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["Evaluation failed: \"issue['a' + 'b']\" -
Unrecognized property of `issue`: \"ab\" ('a' + 'b'). Available
properties of type 'Issue' are: 'assignee', 'comments',
'description', 'id', 'issueType', 'key', 'priority', 'project',
'properties', 'reporter', 'status', 'summary'"],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if any object provided in the request context is not found
or the user does not have permission to view it.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["Issue does not exist or you do not have
permission to see it."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- 'read:jira-user'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- 'read:jira-user'
- state: Beta
scheme: OAuth2
scopes:
- 'read:jira-expressions:jira'
x-atlassian-connect-scope: READ
/rest/api/3/field:
get:
tags:
- Issue fields
summary: Get fields
description: |-
Returns system and custom issue fields according to the following rules:
* Fields that cannot be added to the issue navigator are always returned.
* Fields that cannot be placed on an issue screen are always returned.
* Fields that depend on global Jira settings are only returned if the setting is enabled. That is, timetracking fields, subtasks, votes, and watches.
* For all other fields, this operation only returns the fields that the user has permission to view (that is, the field is used in at least one project that the user has *Browse Projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for.)
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: getFields
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FieldDetails'
example: >-
[{"id":"description","name":"Description","custom":false,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["description"],"schema":{"type":"string","system":"description"}},{"id":"summary","key":"summary","name":"Summary","custom":false,"orderable":true,"navigable":true,"searchable":true,"clauseNames":["summary"],"schema":{"type":"string","system":"summary"}}]
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
- 'read:avatar:jira'
- 'read:project-category:jira'
- 'read:project:jira'
- 'read:field-configuration:jira'
x-atlassian-connect-scope: READ
post:
tags:
- Issue fields
summary: Create custom field
description: >-
Creates a custom field.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: createCustomField
parameters: []
requestBody:
description: Definition of the custom field to be created
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldDefinitionJsonBean'
example:
description: Custom field for picking groups
name: New custom field
searcherKey: >-
com.atlassian.jira.plugin.system.customfieldtypes:grouppickersearcher
type: 'com.atlassian.jira.plugin.system.customfieldtypes:grouppicker'
required: true
responses:
'201':
description: Returned if the custom field is created.
content:
application/json:
schema:
$ref: '#/components/schemas/FieldDetails'
example: >-
{"id":"customfield_10101","key":"customfield_10101","name":"New
custom field","untranslatedName":"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}}
'400':
description: |-
Returned if:
* the user does not have permission to create custom fields.
* any of the request object properties have invalid or missing values.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field:jira'
- 'read:avatar:jira'
- 'read:field:jira'
- 'read:project-category:jira'
- 'read:project:jira'
- 'read:field-configuration:jira'
x-atlassian-connect-scope: ADMIN
/rest/api/3/field/search:
get:
tags:
- Issue fields
summary: Get fields paginated
description: >-
Returns a [paginated](#pagination) list of fields for Classic Jira
projects. The list can include:
* all fields
* specific fields, by defining `id`
* fields that contain a string in the field name or description, by defining `query`
* specific fields that contain a string in the field name or description, by defining `id` and `query`
Only custom fields can be queried, `type` must be set to `custom`.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getFieldsPaginated
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: type
in: query
description: The type of fields to search.
schema:
type: array
items:
type: string
enum:
- custom
- system
- name: id
in: query
description: >-
The IDs of the custom fields to return or, where `query` is
specified, filter.
schema:
uniqueItems: true
type: array
items:
type: string
- name: query
in: query
description: >-
String used to perform a case-insensitive partial match with field
names or descriptions.
schema:
type: string
- name: orderBy
in: query
description: |-
[Order](#ordering) the results by a field:
* `contextsCount` sorts by the number of contexts related to a field
* `lastUsed` sorts by the date when the value of the field last changed
* `name` sorts by the field name
* `screensCount` sorts by the number of screens related to a field
schema:
type: string
enum:
- contextsCount
- '-contextsCount'
- +contextsCount
- lastUsed
- '-lastUsed'
- +lastUsed
- name
- '-name'
- +name
- screensCount
- '-screensCount'
- +screensCount
- projectsCount
- '-projectsCount'
- +projectsCount
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts a comma-separated list. Expand
options include:
* `key` returns the key for each field
* `lastUsed` returns the date when the value of the field last changed
* `screensCount` returns the number of screens related to a field
* `contextsCount` returns the number of contexts related to a field
* `isLocked` returns information about whether the field is [locked](https://confluence.atlassian.com/x/ZSN7Og)
* `searcherKey` returns the searcher key for each custom field
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanField'
example: >-
{"maxResults":50,"startAt":0,"total":2,"isLast":false,"values":[{"id":"customfield_10000","name":"Approvers","schema":{"type":"array","items":"user","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker","customId":10000},"description":"Contains
users needed for approval. This custom field was created by Jira
Service
Desk.","key":"customfield_10000","isLocked":true,"searcherKey":"com.atlassian.jira.plugin.system.customfieldtypes:userpickergroupsearcher","screensCount":2,"contextsCount":2,"lastUsed":{"type":"TRACKED","value":"2019-09-12T10:10:00.956+0000"}},{"id":"customfield_10001","name":"Change
reason","schema":{"type":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:select","customId":10001},"description":"Choose
the reason for the change
request","key":"customfield_10001","isLocked":false,"searcherKey":"com.atlassian.jira.plugin.system.customfieldtypes:multiselectsearcher","screensCount":2,"contextsCount":2,"projectsCount":2,"lastUsed":{"type":"NOT_TRACKED"}}]}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["Only custom fields can be
queried."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["Only Jira administrators can access
fields."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
- 'read:field-configuration:jira'
x-experimental: true
x-atlassian-connect-scope: NONE
/rest/api/3/field/search/trashed:
get:
tags:
- Issue fields
summary: Get fields in trash paginated
description: >-
Returns a [paginated](#pagination) list of fields in the trash. The list
may be restricted to fields whose field name or description partially
match a string.
Only custom fields can be queried, `type` must be set to `custom`.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getTrashedFieldsPaginated
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: id
in: query
schema:
uniqueItems: true
type: array
items:
type: string
- name: query
in: query
description: >-
String used to perform a case-insensitive partial match with field
names or descriptions.
schema:
type: string
- name: expand
in: query
schema:
type: string
enum:
- name
- '-name'
- +name
- trashDate
- '-trashDate'
- +trashDate
- plannedDeletionDate
- '-plannedDeletionDate'
- +plannedDeletionDate
- projectsCount
- '-projectsCount'
- +projectsCount
- name: orderBy
in: query
description: |-
[Order](#ordering) the results by a field:
* `name` sorts by the field name
* `trashDate` sorts by the date the field was moved to the trash
* `plannedDeletionDate` sorts by the planned deletion date
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanField'
example: >-
{"maxResults":50,"startAt":0,"total":1,"isLast":false,"values":[{"id":"customfield_10000","name":"Approvers","schema":{"type":"array","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker","customId":10003},"description":"Contains
users needed for approval. This custom field was created by Jira
Service
Desk.","key":"customfield_10003","trashedDate":"2019-09-12T10:10:00.957+0000","trashedBy":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","emailAddress":"mia@example.com","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":true,"timeZone":"Australia/Sydney"},"plannedDeletionDate":"2019-09-30T10:10:00.957+0000"}]}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["Only custom fields can be
queried."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["Only Jira administrators can access
fields."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
- 'read:field-configuration:jira'
- 'read:user:jira'
x-experimental: true
x-atlassian-connect-scope: READ
'/rest/api/3/field/{fieldId}':
put:
tags:
- Issue fields
summary: Update custom field
description: >-
Updates a custom field.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateCustomField
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
requestBody:
description: The custom field update details.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCustomFieldDetails'
example:
description: Select the manager and the corresponding employee.
name: Managers and employees list
searcherKey: >-
com.atlassian.jira.plugin.system.customfieldtypes:cascadingselectsearcher
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["searcherKey is invalid for the field
type."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can edit custom
fields."],"errors":{}}
'404':
description: Returned if the custom field is not found.
content:
application/json:
example: >-
{"errorMessages":["The custom field was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{fieldId}/context':
get:
tags:
- Issue custom field contexts
summary: Get custom field contexts
description: >-
Returns a [paginated](#pagination) list of [
contexts](https://confluence.atlassian.com/adminjiracloud/what-are-custom-field-contexts-991923859.html)
for a custom field. Contexts can be returned as follows:
* With no other parameters set, all contexts.
* By defining `id` only, all contexts from the list of IDs.
* By defining `isAnyIssueType`, limit the list of contexts returned to either those that apply to all issue types (true) or those that apply to only a subset of issue types (false)
* By defining `isGlobalContext`, limit the list of contexts return to either those that apply to all projects (global contexts) (true) or those that apply to only a subset of projects (false).
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getContextsForField
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: isAnyIssueType
in: query
description: Whether to return contexts that apply to all issue types.
schema:
type: boolean
- name: isGlobalContext
in: query
description: Whether to return contexts that apply to all projects.
schema:
type: boolean
- name: contextId
in: query
description: >-
The list of context IDs. To include multiple contexts, separate IDs
with ampersand: `contextId=10000&contextId=10001`.
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanCustomFieldContext'
example: >-
{"maxResults":100,"startAt":0,"total":2,"isLast":true,"values":[{"id":"10025","name":"Bug
fields context","description":"A context used to define the
custom field options for
bugs.","isGlobalContext":true,"isAnyIssueType":false},{"id":"10026","name":"Task
fields context","description":"A context used to define the
custom field options for
tasks.","isGlobalContext":false,"isAnyIssueType":false}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access custom
field contexts."],"errors":{}}
'404':
description: Returned if the custom field was not found.
content:
application/json:
example: >-
{"errorMessages":["The custom field was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
- 'read:custom-field-contextual-configuration:jira'
x-experimental: true
x-atlassian-connect-scope: READ
post:
tags:
- Issue custom field contexts
summary: Create custom field context
description: >-
Creates a custom field context.
If `projectIds` is empty, a global context is created. A global context
is one that applies to all project. If `issueTypeIds` is empty, the
context applies to all issue types.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: createCustomFieldContext
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomFieldContext'
example:
description: A context used to define the custom field options for bugs.
issueTypeIds:
- '10010'
name: Bug fields context
projectIds: []
required: true
responses:
'201':
description: Returned if the custom field context is created.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomFieldContext'
example: >-
{"id":"10025","name":"Bug fields context","description":"A
context used to define the custom field options for
bugs.","projectIds":[],"issueTypeIds":["10010"]}
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: 'Returned if the field, project, or issue type is not found.'
'409':
description: >-
Returned if the issue type is a sub-task, but sub-tasks are disabled
in Jira settings.
content:
application/json:
example: >-
{"errorMessages":["Sub-tasks are disabled in Jira. At least one
of the issue types is a sub-task."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
- 'write:field:jira'
- 'read:custom-field-contextual-configuration:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{fieldId}/context/defaultValue':
get:
tags:
- Issue custom field contexts
summary: Get custom field contexts default values
description: >-
Returns a [paginated](#pagination) list of defaults for a custom field.
The results can be filtered by `contextId`, otherwise all values are
returned. If no defaults are set for a context, nothing is returned.
The returned object depends on type of the custom field:
* `CustomFieldContextDefaultValueDate` (type `datepicker`) for date fields.
* `CustomFieldContextDefaultValueDateTime` (type `datetimepicker`) for date-time fields.
* `CustomFieldContextDefaultValueSingleOption` (type `option.single`) for single choice select lists and radio buttons.
* `CustomFieldContextDefaultValueMultipleOption` (type `option.multiple`) for multiple choice select lists and checkboxes.
* `CustomFieldContextDefaultValueCascadingOption` (type `option.cascading`) for cascading select lists.
* `CustomFieldContextSingleUserPickerDefaults` (type `single.user.select`) for single users.
* `CustomFieldContextDefaultValueMultiUserPicker` (type `multi.user.select`) for user lists.
* `CustomFieldContextDefaultValueSingleGroupPicker` (type `grouppicker.single`) for single choice group pickers.
* `CustomFieldContextDefaultValueMultipleGroupPicker` (type `grouppicker.multiple`) for multiple choice group pickers.
* `CustomFieldContextDefaultValueURL` (type `url`) for URLs.
* `CustomFieldContextDefaultValueProject` (type `project`) for project pickers.
* `CustomFieldContextDefaultValueFloat` (type `float`) for floats (floating-point numbers).
* `CustomFieldContextDefaultValueLabels` (type `labels`) for labels.
* `CustomFieldContextDefaultValueTextField` (type `textfield`) for text fields.
* `CustomFieldContextDefaultValueTextArea` (type `textarea`) for text area fields.
* `CustomFieldContextDefaultValueReadOnly` (type `readonly`) for read only (text) fields.
* `CustomFieldContextDefaultValueMultipleVersion` (type `version.multiple`) for single choice version pickers.
* `CustomFieldContextDefaultValueSingleVersion` (type `version.single`) for multiple choice version pickers.
Forge custom fields
[types](https://developer.atlassian.com/platform/forge/manifest-reference/modules/jira-custom-field-type/#data-types)
are also supported, returning:
* `CustomFieldContextDefaultValueForgeStringFieldBean` (type `forge.string`) for Forge string fields.
* `CustomFieldContextDefaultValueForgeMultiStringFieldBean` (type `forge.string.list`) for Forge string collection fields.
* `CustomFieldContextDefaultValueForgeObjectFieldBean` (type `forge.object`) for Forge object fields.
* `CustomFieldContextDefaultValueForgeDateTimeFieldBean` (type `forge.datetime`) for Forge date-time fields.
* `CustomFieldContextDefaultValueForgeGroupFieldBean` (type `forge.group`) for Forge group fields.
* `CustomFieldContextDefaultValueForgeMultiGroupFieldBean` (type `forge.group.list`) for Forge group collection fields.
* `CustomFieldContextDefaultValueForgeNumberFieldBean` (type `forge.number`) for Forge number fields.
* `CustomFieldContextDefaultValueForgeUserFieldBean` (type `forge.user`) for Forge user fields.
* `CustomFieldContextDefaultValueForgeMultiUserFieldBean` (type `forge.user.list`) for Forge user collection fields.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getDefaultValues
parameters:
- name: fieldId
in: path
description: 'The ID of the custom field, for example `customfield\_10000`.'
required: true
schema:
type: string
- name: contextId
in: query
description: The IDs of the contexts.
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanCustomFieldContextDefaultValue'
example: >-
{"maxResults":50,"startAt":0,"total":3,"isLast":true,"values":[{"type":"option.single","contextId":"10100","optionId":"10001"},{"type":"option.single","contextId":"10101","optionId":"10003"},{"type":"option.single","contextId":"10103"}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access custom
field contexts."],"errors":{}}
'404':
description: Returned if the custom field is not found.
content:
application/json:
example: >-
{"errorMessages":["The custom field was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field.default-value:jira'
x-experimental: true
x-atlassian-connect-scope: READ
put:
tags:
- Issue custom field contexts
summary: Set custom field contexts default values
description: >-
Sets default for contexts of a custom field. Default are defined using
these objects:
* `CustomFieldContextDefaultValueDate` (type `datepicker`) for date fields.
* `CustomFieldContextDefaultValueDateTime` (type `datetimepicker`) for date-time fields.
* `CustomFieldContextDefaultValueSingleOption` (type `option.single`) for single choice select lists and radio buttons.
* `CustomFieldContextDefaultValueMultipleOption` (type `option.multiple`) for multiple choice select lists and checkboxes.
* `CustomFieldContextDefaultValueCascadingOption` (type `option.cascading`) for cascading select lists.
* `CustomFieldContextSingleUserPickerDefaults` (type `single.user.select`) for single users.
* `CustomFieldContextDefaultValueMultiUserPicker` (type `multi.user.select`) for user lists.
* `CustomFieldContextDefaultValueSingleGroupPicker` (type `grouppicker.single`) for single choice group pickers.
* `CustomFieldContextDefaultValueMultipleGroupPicker` (type `grouppicker.multiple`) for multiple choice group pickers.
* `CustomFieldContextDefaultValueURL` (type `url`) for URLs.
* `CustomFieldContextDefaultValueProject` (type `project`) for project pickers.
* `CustomFieldContextDefaultValueFloat` (type `float`) for floats (floating-point numbers).
* `CustomFieldContextDefaultValueLabels` (type `labels`) for labels.
* `CustomFieldContextDefaultValueTextField` (type `textfield`) for text fields.
* `CustomFieldContextDefaultValueTextArea` (type `textarea`) for text area fields.
* `CustomFieldContextDefaultValueReadOnly` (type `readonly`) for read only (text) fields.
* `CustomFieldContextDefaultValueMultipleVersion` (type `version.multiple`) for single choice version pickers.
* `CustomFieldContextDefaultValueSingleVersion` (type `version.single`) for multiple choice version pickers.
Forge custom fields
[types](https://developer.atlassian.com/platform/forge/manifest-reference/modules/jira-custom-field-type/#data-types)
are also supported, returning:
* `CustomFieldContextDefaultValueForgeStringFieldBean` (type `forge.string`) for Forge string fields.
* `CustomFieldContextDefaultValueForgeMultiStringFieldBean` (type `forge.string.list`) for Forge string collection fields.
* `CustomFieldContextDefaultValueForgeObjectFieldBean` (type `forge.object`) for Forge object fields.
* `CustomFieldContextDefaultValueForgeDateTimeFieldBean` (type `forge.datetime`) for Forge date-time fields.
* `CustomFieldContextDefaultValueForgeGroupFieldBean` (type `forge.group`) for Forge group fields.
* `CustomFieldContextDefaultValueForgeMultiGroupFieldBean` (type `forge.group.list`) for Forge group collection fields.
* `CustomFieldContextDefaultValueForgeNumberFieldBean` (type `forge.number`) for Forge number fields.
* `CustomFieldContextDefaultValueForgeUserFieldBean` (type `forge.user`) for Forge user fields.
* `CustomFieldContextDefaultValueForgeMultiUserFieldBean` (type `forge.user.list`) for Forge user collection fields.
Only one type of default object can be included in a request. To remove
a default for a context, set the default parameter to `null`.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: setDefaultValues
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldContextDefaultValueUpdate'
example:
defaultValues:
- contextId: '10100'
optionId: '10001'
type: option.single
- contextId: '10101'
optionId: '10003'
type: option.single
- contextId: '10103'
optionId: '10005'
type: option.single
required: true
responses:
'204':
description: Returned if operation is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["All default values in the request must have
the same type."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access custom
field contexts."],"errors":{}}
'404':
description: >-
Returned if the custom field, a context, an option, or a cascading
option is not found.
content:
application/json:
example: '{"errorMessages":["The context was not found."],"errors":{}}'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field.default-value:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{fieldId}/context/issuetypemapping':
get:
tags:
- Issue custom field contexts
summary: Get issue types for custom field context
description: >-
Returns a [paginated](#pagination) list of context to issue type
mappings for a custom field. Mappings are returned for all contexts or a
list of contexts. Mappings are ordered first by context ID and then by
issue type ID.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getIssueTypeMappingsForContexts
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: contextId
in: query
description: >-
The ID of the context. To include multiple contexts, provide an
ampersand-separated list. For example,
`contextId=10001&contextId=10002`.
schema:
type: array
items:
type: integer
format: int64
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
responses:
'200':
description: Returned if operation is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanIssueTypeToContextMapping'
example: >-
{"maxResults":100,"startAt":0,"total":3,"isLast":true,"values":[{"contextId":"10001","issueTypeId":"10010"},{"contextId":"10001","issueTypeId":"10011"},{"contextId":"10002","isAnyIssueType":true}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access custom
field contexts."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
x-experimental: true
x-atlassian-connect-scope: READ
'/rest/api/3/field/{fieldId}/context/mapping':
post:
tags:
- Issue custom field contexts
summary: Get custom field contexts for projects and issue types
description: >-
Returns a [paginated](#pagination) list of project and issue type
mappings and, for each mapping, the ID of a [custom field
context](https://confluence.atlassian.com/x/k44fOw) that applies to the
project and issue type.
If there is no custom field context assigned to the project then, if
present, the custom field context that applies to all projects is
returned if it also applies to the issue type or all issue types. If a
custom field context is not found, the returned custom field context ID
is `null`.
Duplicate project and issue type mappings cannot be provided in the
request.
The order of the returned values is the same as provided in the request.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getCustomFieldContextsForProjectsAndIssueTypes
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
requestBody:
description: The list of project and issue type mappings.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectIssueTypeMappings'
example:
mappings:
- issueTypeId: '10000'
projectId: '10000'
- issueTypeId: '10001'
projectId: '10000'
- issueTypeId: '10002'
projectId: '10001'
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanContextForProjectAndIssueType'
example: >-
{"maxResults":50,"startAt":0,"total":3,"isLast":true,"values":[{"projectId":"10000","issueTypeId":"10000","contextId":"10000"},{"projectId":"10000","issueTypeId":"10001","contextId":null},{"projectId":"10001","issueTypeId":"10002","contextId":"10003"}]}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["Duplicate project and issue type mappings
cannot be provided."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access custom
field contexts."],"errors":{}}
'404':
description: 'Returned if the custom field, project, or issue type is not found.'
content:
application/json:
example: >-
{"errorMessages":["These projects were not found:
10005."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{fieldId}/context/projectmapping':
get:
tags:
- Issue custom field contexts
summary: Get project mappings for custom field context
description: >-
Returns a [paginated](#pagination) list of context to project mappings
for a custom field. The result can be filtered by `contextId`.
Otherwise, all mappings are returned. Invalid IDs are ignored.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getProjectContextMapping
parameters:
- name: fieldId
in: path
description: 'The ID of the custom field, for example `customfield\_10000`.'
required: true
schema:
type: string
- name: contextId
in: query
description: >-
The list of context IDs. To include multiple context, separate IDs
with ampersand: `contextId=10000&contextId=10001`.
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanCustomFieldContextProjectMapping'
example: >-
{"maxResults":100,"startAt":0,"total":2,"isLast":true,"values":[{"contextId":"10025","projectId":"10001"},{"contextId":"10026","isGlobalContext":true}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access custom
field contexts."],"errors":{}}
'404':
description: Returned if the custom field is not found.
content:
application/json:
example: >-
{"errorMessages":["The custom field was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
x-experimental: true
x-atlassian-connect-scope: READ
'/rest/api/3/field/{fieldId}/context/{contextId}':
put:
tags:
- Issue custom field contexts
summary: Update custom field context
description: >-
Updates a [ custom field
context](https://confluence.atlassian.com/adminjiracloud/what-are-custom-field-contexts-991923859.html).
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateCustomFieldContext
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: contextId
in: path
description: The ID of the context.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldContextUpdateDetails'
example:
description: A context used to define the custom field options for bugs.
name: Bug fields context
required: true
responses:
'204':
description: Returned if the context is updated.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The contextId has to be
provided."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access custom
field contexts."],"errors":{}}
'404':
description: Returned if the custom field or the context is not found.
content:
application/json:
example: '{"errorMessages":["The context was not found."],"errors":{}}'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
delete:
tags:
- Issue custom field contexts
summary: Delete custom field context
description: >-
Deletes a [ custom field
context](https://confluence.atlassian.com/adminjiracloud/what-are-custom-field-contexts-991923859.html).
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: deleteCustomFieldContext
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: contextId
in: path
description: The ID of the context.
required: true
schema:
type: integer
format: int64
responses:
'204':
description: Returned if the context is deleted.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The contextId has to be
provided."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access custom
field contexts."],"errors":{}}
'404':
description: Returned if the custom field or the context is not found.
content:
application/json:
example: '{"errorMessages":["The context was not found."],"errors":{}}'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:field:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{fieldId}/context/{contextId}/issuetype':
put:
tags:
- Issue custom field contexts
summary: Add issue types to context
description: >-
Adds issue types to a custom field context, appending the issue types to
the issue types list.
A custom field context without any issue types applies to all issue
types. Adding issue types to such a custom field context would result in
it applying to only the listed issue types.
If any of the issue types exists in the custom field context, the
operation fails and no issue types are added.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: addIssueTypesToContext
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: contextId
in: path
description: The ID of the context.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeIds'
example:
issueTypeIds:
- '10001'
- '10005'
- '10006'
required: true
responses:
'204':
description: Returned if operation is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["These issue types are already associated with
the context: 10001."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access custom
field contexts."],"errors":{}}
'404':
description: >-
Returned if the custom field, context, or one or more issue types
are not found.
content:
application/json:
example: '{"errorMessages":["The context was not found."],"errors":{}}'
'409':
description: >-
Returned if the issue type is a sub-task, but sub-tasks are disabled
in Jira settings.
content:
application/json:
example: >-
{"errorMessages":["Sub-tasks are disabled in Jira. At least one
of the issue types is a sub-task."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{fieldId}/context/{contextId}/issuetype/remove':
post:
tags:
- Issue custom field contexts
summary: Remove issue types from context
description: >-
Removes issue types from a custom field context.
A custom field context without any issue types applies to all issue
types.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: removeIssueTypesFromContext
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: contextId
in: path
description: The ID of the context.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeIds'
example:
issueTypeIds:
- '10001'
- '10005'
- '10006'
required: true
responses:
'204':
description: Returned if operation is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["These issue types are not associated with the
context: 10002."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access custom
field contexts."],"errors":{}}
'404':
description: >-
Returned if the custom field, context, or one or more issue types
are not found.
content:
application/json:
example: '{"errorMessages":["The context was not found."],"errors":{}}'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{fieldId}/context/{contextId}/option':
get:
tags:
- Issue custom field options
summary: Get custom field options (context)
description: >-
Returns a [paginated](#pagination) list of all custom field option for a
context. Options are returned first then cascading options, in the order
they display in Jira.
This operation works for custom field options created in Jira or the
operations from this resource. **To work with issue field select list
options created for Connect apps use the [Issue custom field options
(apps)](#api-group-issue-custom-field-options--apps-) operations.**
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getOptionsForContext
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: contextId
in: path
description: The ID of the context.
required: true
schema:
type: integer
format: int64
- name: optionId
in: query
description: The ID of the option.
schema:
type: integer
format: int64
- name: onlyOptions
in: query
description: Whether only options are returned.
schema:
type: boolean
default: false
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 100
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanCustomFieldContextOption'
example: >-
{"maxResults":100,"startAt":0,"total":4,"isLast":true,"values":[{"id":"10001","value":"New
York"},{"id":"10002","value":"Boston","disabled":true},{"id":"10004","value":"Denver"},{"id":"10003","value":"Brooklyn","optionId":"10001"}]}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The custom field doesn't support
options."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can manage custom
field options."],"errors":{}}
'404':
description: >-
Returned if the custom field is not found or the context doesn't
match the custom field.
content:
application/json:
example: >-
{"errorMessages":["The custom field was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field.option:jira'
x-experimental: true
x-atlassian-connect-scope: READ
put:
tags:
- Issue custom field options
summary: Update custom field options (context)
description: >-
Updates the options of a custom field.
If any of the options are not found, no options are updated. Options
where the values in the request match the current values aren't updated
and aren't reported in the response.
Note that this operation **only works for issue field select list
options created in Jira or using operations from the [Issue custom field
options](#api-group-Issue-custom-field-options) resource**, it cannot be
used with issue field select list options created by Connect apps.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateCustomFieldOption
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: contextId
in: path
description: The ID of the context.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkCustomFieldOptionUpdateRequest'
example:
options:
- disabled: false
id: '10001'
value: Scranton
- disabled: true
id: '10002'
value: Manhattan
- disabled: false
id: '10003'
value: The Electric City
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldUpdatedContextOptionsList'
example: >-
{"options":[{"id":"10001","value":"Scranton","disabled":false},{"id":"10002","value":"Manhattan","disabled":true},{"id":"10003","value":"The
Electric City","disabled":false}]}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The custom field doesn't support
options."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can manage custom
field options."],"errors":{}}
'404':
description: 'Returned if the field, context, or one or more options is not found.'
content:
application/json:
example: >-
{"errorMessages":["The custom field was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field.option:jira'
- 'write:field.option:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
post:
tags:
- Issue custom field options
summary: Create custom field options (context)
description: >-
Creates options and, where the custom select field is of the type Select
List (cascading), cascading options for a custom select field. The
options are added to a context of the field.
The maximum number of options that can be created per request is 1000
and each field can have a maximum of 10000 options.
This operation works for custom field options created in Jira or the
operations from this resource. **To work with issue field select list
options created for Connect apps use the [Issue custom field options
(apps)](#api-group-issue-custom-field-options--apps-) operations.**
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: createCustomFieldOption
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: contextId
in: path
description: The ID of the context.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkCustomFieldOptionCreateRequest'
example:
options:
- disabled: false
value: Scranton
- disabled: true
optionId: '10000'
value: Manhattan
- disabled: false
value: The Electric City
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldCreatedContextOptionsList'
example: >-
{"options":[{"id":"10001","value":"Scranton","disabled":false},{"id":"10002","value":"Manhattan","optionId":"10000","disabled":true},{"id":"10003","value":"The
Electric City","disabled":false}]}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The custom field doesn't support
options."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can manage custom
field options."],"errors":{}}
'404':
description: >-
Returned if the custom field is not found or the context doesn't
match the custom field.
content:
application/json:
example: >-
{"errorMessages":["The custom field was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field.option:jira'
- 'write:field.option:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{fieldId}/context/{contextId}/option/move':
put:
tags:
- Issue custom field options
summary: Reorder custom field options (context)
description: >-
Changes the order of custom field options or cascading options in a
context.
This operation works for custom field options created in Jira or the
operations from this resource. **To work with issue field select list
options created for Connect apps use the [Issue custom field options
(apps)](#api-group-issue-custom-field-options--apps-) operations.**
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: reorderCustomFieldOptions
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: contextId
in: path
description: The ID of the context.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderOfCustomFieldOptions'
example:
customFieldOptionIds:
- '10001'
- '10002'
position: First
required: true
responses:
'204':
description: Returned if options are reordered.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["'after' and 'position' were provided. Only
'after' or 'position' can be specified."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can manage custom
field options."],"errors":{}}
'404':
description: >-
Returned if the field, the context, or one or more of the options is
not found..
content:
application/json:
example: >-
{"errorMessages":["The custom field was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field.option:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{fieldId}/context/{contextId}/option/{optionId}':
delete:
tags:
- Issue custom field options
summary: Delete custom field options (context)
description: >-
Deletes a custom field option.
Options with cascading options cannot be deleted without deleting the
cascading options first.
This operation works for custom field options created in Jira or the
operations from this resource. **To work with issue field select list
options created for Connect apps use the [Issue custom field options
(apps)](#api-group-issue-custom-field-options--apps-) operations.**
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: deleteCustomFieldOption
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: contextId
in: path
description: The ID of the context from which an option should be deleted.
required: true
schema:
type: integer
format: int64
- name: optionId
in: path
description: The ID of the option to delete.
required: true
schema:
type: integer
format: int64
responses:
'204':
description: Returned if the option is deleted.
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The custom field doesn't support
options."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can manage custom
field options."],"errors":{}}
'404':
description: 'Returned if the field, the context, or the option is not found.'
content:
application/json:
example: >-
{"errorMessages":["The custom field was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:field.option:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{fieldId}/context/{contextId}/project':
put:
tags:
- Issue custom field contexts
summary: Assign custom field context to projects
description: >-
Assigns a custom field context to projects.
If any project in the request is assigned to any context of the custom
field, the operation fails.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: assignProjectsToCustomFieldContext
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: contextId
in: path
description: The ID of the context.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectIds'
example:
projectIds:
- '10001'
- '10005'
- '10006'
required: true
responses:
'204':
description: Returned if operation is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The projectIds must not contain
duplicates."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access custom
field contexts."],"errors":{}}
'404':
description: 'Returned if the custom field, context, or project is not found.'
content:
application/json:
example: '{"errorMessages":["The context was not found."],"errors":{}}'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{fieldId}/context/{contextId}/project/remove':
post:
tags:
- Issue custom field contexts
summary: Remove custom field context from projects
description: >-
Removes a custom field context from projects.
A custom field context without any projects applies to all projects.
Removing all projects from a custom field context would result in it
applying to all projects.
If any project in the request is not assigned to the context, or the
operation would result in two global contexts for the field, the
operation fails.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: removeCustomFieldContextFromProjects
parameters:
- name: fieldId
in: path
description: The ID of the custom field.
required: true
schema:
type: string
- name: contextId
in: path
description: The ID of the context.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectIds'
example:
projectIds:
- '10001'
- '10005'
- '10006'
required: true
responses:
'204':
description: Returned if the custom field context is removed from the projects.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The projectIds must not contain
duplicates."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access custom
field contexts."],"errors":{}}
'404':
description: >-
Returned if the custom field, context, or one or more projects are
not found.
content:
application/json:
example: '{"errorMessages":["The context was not found."],"errors":{}}'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{fieldId}/contexts':
get:
tags:
- Issue fields
summary: Get contexts for a field
description: >-
Returns a [paginated](#pagination) list of the contexts a field is used
in. Deprecated, use [ Get custom field
contexts](#api-rest-api-3-field-fieldId-context-get).
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getContextsForFieldDeprecated
parameters:
- name: fieldId
in: path
description: The ID of the field to return contexts for.
required: true
schema:
type: string
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 20
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanContext'
example: >-
{"maxResults":1,"startAt":0,"total":5,"isLast":false,"values":[{"id":10001,"name":"Default
Context"}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
deprecated: true
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-project'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-project'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
- 'read:avatar:jira'
- 'read:project-category:jira'
- 'read:project:jira'
x-atlassian-connect-scope: NONE
'/rest/api/3/field/{fieldId}/screens':
get:
tags:
- Screens
summary: Get screens for a field
description: >-
Returns a [paginated](#pagination) list of the screens a field is used
in.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getScreensForField
parameters:
- name: fieldId
in: path
description: The ID of the field to return screens for.
required: true
schema:
type: string
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 100
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
screens in the response. This parameter accepts `tab` which returns
details about the screen tabs the field is used in.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanScreenWithTab'
example: >-
{"maxResults":1,"startAt":0,"total":5,"isLast":false,"values":[{"id":10001,"name":"Default
Screen","description":"Provides for the update of all system
fields.","tab":{"id":10000,"name":"Fields Tab"}}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-project'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-project'
- state: Beta
scheme: OAuth2
scopes:
- 'read:screen:jira'
- 'read:avatar:jira'
- 'read:project-category:jira'
- 'read:project:jira'
- 'read:screen-tab:jira'
x-atlassian-connect-scope: NONE
'/rest/api/3/field/{fieldKey}/option':
get:
tags:
- Issue custom field options (apps)
summary: Get all issue field options
description: >-
Returns a [paginated](#pagination) list of all the options of a select
list issue field. A select list issue field is a type of [issue
field](https://developer.atlassian.com/cloud/jira/platform/modules/issue-field/)
that enables a user to select a value from a list of options.
Note that this operation **only works for issue field select list
options added by Connect apps**, it cannot be used with issue field
select list options created in Jira or using operations from the [Issue
custom field options](#api-group-Issue-custom-field-options) resource.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg). Jira permissions
are not required for the app providing the field.
operationId: getAllIssueFieldOptions
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: fieldKey
in: path
description: >-
The field key is specified in the following format:
**$(app-key)\_\_$(field-key)**. For example,
*example-add-on\_\_example-issue-field*. To determine the `fieldKey`
value, do one of the following:
* open the app's plugin descriptor, then **app-key** is the key at the top and **field-key** is the key in the `jiraIssueFields` module. **app-key** can also be found in the app listing in the Atlassian Universal Plugin Manager.
* run [Get fields](#api-rest-api-3-field-get) and in the field details the value is returned in `key`. For example, `"key": "teams-add-on__team-issue-field"`
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanIssueFieldOption'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/field/fieldKey/option?startAt=0&maxResults=1","nextPage":"https://your-domain.atlassian.net/rest/api/3/field/fieldKey/option?startAt=1&maxResults=1","maxResults":1,"startAt":0,"total":10,"isLast":false,"values":[{"id":1,"value":"Team
1","properties":{"leader":{"name":"Leader
Name","email":"lname@example.com"},"members":42,"description":"The
team's
description","founded":"2016-06-06"},"config":{"scope":{"projects":[],"projects2":[{"id":1001,"attributes":["notSelectable"]},{"id":1002,"attributes":["notSelectable"]}],"global":{}},"attributes":[]}}]}
'400':
description: Returned if the field is not found or does not support options.
'403':
description: >-
Returned if the request is not authenticated as a Jira administrator
or the app that provided the field.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field.option:jira'
x-atlassian-connect-scope: NONE
post:
tags:
- Issue custom field options (apps)
summary: Create issue field option
description: >-
Creates an option for a select list issue field.
Note that this operation **only works for issue field select list
options added by Connect apps**, it cannot be used with issue field
select list options created in Jira or using operations from the [Issue
custom field options](#api-group-Issue-custom-field-options) resource.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg). Jira permissions
are not required for the app providing the field.
operationId: createIssueFieldOption
parameters:
- name: fieldKey
in: path
description: >-
The field key is specified in the following format:
**$(app-key)\_\_$(field-key)**. For example,
*example-add-on\_\_example-issue-field*. To determine the `fieldKey`
value, do one of the following:
* open the app's plugin descriptor, then **app-key** is the key at the top and **field-key** is the key in the `jiraIssueFields` module. **app-key** can also be found in the app listing in the Atlassian Universal Plugin Manager.
* run [Get fields](#api-rest-api-3-field-get) and in the field details the value is returned in `key`. For example, `"key": "teams-add-on__team-issue-field"`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueFieldOptionCreateBean'
example:
config:
attributes: []
scope:
global: {}
projects: []
projects2:
- attributes:
- notSelectable
id: 1001
- attributes:
- notSelectable
id: 1002
properties:
description: The team's description
founded: '2016-06-06'
leader:
email: lname@example.com
name: Leader Name
members: 42
value: Team 1
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueFieldOption'
example: >-
{"id":1,"value":"Team 1","properties":{"leader":{"name":"Leader
Name","email":"lname@example.com"},"members":42,"description":"The
team's
description","founded":"2016-06-06"},"config":{"scope":{"projects":[],"projects2":[{"id":1001,"attributes":["notSelectable"]},{"id":1002,"attributes":["notSelectable"]}],"global":{}},"attributes":[]}}
'400':
description: Returned if the option is invalid.
'403':
description: >-
Returned if the request is not authenticated as a Jira administrator
or the app that provided the field.
'404':
description: Returned if the field is not found or does not support options.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field.option:jira'
x-atlassian-connect-scope: NONE
'/rest/api/3/field/{fieldKey}/option/suggestions/edit':
get:
tags:
- Issue custom field options (apps)
summary: Get selectable issue field options
description: >-
Returns a [paginated](#pagination) list of options for a select list
issue field that can be viewed and selected by the user.
Note that this operation **only works for issue field select list
options added by Connect apps**, it cannot be used with issue field
select list options created in Jira or using operations from the [Issue
custom field options](#api-group-Issue-custom-field-options) resource.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: getSelectableIssueFieldOptions
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: projectId
in: query
description: >-
Filters the results to options that are only available in the
specified project.
schema:
type: integer
format: int64
- name: fieldKey
in: path
description: >-
The field key is specified in the following format:
**$(app-key)\_\_$(field-key)**. For example,
*example-add-on\_\_example-issue-field*. To determine the `fieldKey`
value, do one of the following:
* open the app's plugin descriptor, then **app-key** is the key at the top and **field-key** is the key in the `jiraIssueFields` module. **app-key** can also be found in the app listing in the Atlassian Universal Plugin Manager.
* run [Get fields](#api-rest-api-3-field-get) and in the field details the value is returned in `key`. For example, `"key": "teams-add-on__team-issue-field"`
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanIssueFieldOption'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/field/fieldKey/option/suggestions?startAt=0&maxResults=1","nextPage":"https://your-domain.atlassian.net/rest/api/3/field/fieldKey/option/suggestions?startAt=1&maxResults=1","maxResults":1,"startAt":0,"total":10,"isLast":false,"values":[{"id":1,"value":"Team
1","properties":{"leader":{"name":"Leader
Name","email":"lname@example.com"},"members":42,"description":"The
team's description","founded":"2016-06-06"}}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: Returned if the field is not found or does not support options.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field.option:jira'
x-atlassian-connect-scope: NONE
'/rest/api/3/field/{fieldKey}/option/suggestions/search':
get:
tags:
- Issue custom field options (apps)
summary: Get visible issue field options
description: >-
Returns a [paginated](#pagination) list of options for a select list
issue field that can be viewed by the user.
Note that this operation **only works for issue field select list
options added by Connect apps**, it cannot be used with issue field
select list options created in Jira or using operations from the [Issue
custom field options](#api-group-Issue-custom-field-options) resource.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: getVisibleIssueFieldOptions
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
- name: projectId
in: query
description: >-
Filters the results to options that are only available in the
specified project.
schema:
type: integer
format: int64
- name: fieldKey
in: path
description: >-
The field key is specified in the following format:
**$(app-key)\_\_$(field-key)**. For example,
*example-add-on\_\_example-issue-field*. To determine the `fieldKey`
value, do one of the following:
* open the app's plugin descriptor, then **app-key** is the key at the top and **field-key** is the key in the `jiraIssueFields` module. **app-key** can also be found in the app listing in the Atlassian Universal Plugin Manager.
* run [Get fields](#api-rest-api-3-field-get) and in the field details the value is returned in `key`. For example, `"key": "teams-add-on__team-issue-field"`
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanIssueFieldOption'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/field/fieldKey/option/suggestions?startAt=0&maxResults=1","nextPage":"https://your-domain.atlassian.net/rest/api/3/field/fieldKey/option/suggestions?startAt=1&maxResults=1","maxResults":1,"startAt":0,"total":10,"isLast":false,"values":[{"id":1,"value":"Team
1","properties":{"leader":{"name":"Leader
Name","email":"lname@example.com"},"members":42,"description":"The
team's description","founded":"2016-06-06"}}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: Returned if the field is not found or does not support options.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field.option:jira'
x-atlassian-connect-scope: NONE
'/rest/api/3/field/{fieldKey}/option/{optionId}':
get:
tags:
- Issue custom field options (apps)
summary: Get issue field option
description: >-
Returns an option from a select list issue field.
Note that this operation **only works for issue field select list
options added by Connect apps**, it cannot be used with issue field
select list options created in Jira or using operations from the [Issue
custom field options](#api-group-Issue-custom-field-options) resource.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg). Jira permissions
are not required for the app providing the field.
operationId: getIssueFieldOption
parameters:
- name: fieldKey
in: path
description: >-
The field key is specified in the following format:
**$(app-key)\_\_$(field-key)**. For example,
*example-add-on\_\_example-issue-field*. To determine the `fieldKey`
value, do one of the following:
* open the app's plugin descriptor, then **app-key** is the key at the top and **field-key** is the key in the `jiraIssueFields` module. **app-key** can also be found in the app listing in the Atlassian Universal Plugin Manager.
* run [Get fields](#api-rest-api-3-field-get) and in the field details the value is returned in `key`. For example, `"key": "teams-add-on__team-issue-field"`
required: true
schema:
type: string
- name: optionId
in: path
description: The ID of the option to be returned.
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Returned if the requested option is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueFieldOption'
example: >-
{"id":1,"value":"Team 1","properties":{"leader":{"name":"Leader
Name","email":"lname@example.com"},"members":42,"description":"The
team's
description","founded":"2016-06-06"},"config":{"scope":{"projects":[],"projects2":[{"id":1001,"attributes":["notSelectable"]},{"id":1002,"attributes":["notSelectable"]}],"global":{}},"attributes":[]}}
'400':
description: Returned if the field is not found or does not support options.
'403':
description: >-
Returned if the request is not authenticated as a Jira administrator
or the app that provided the field.
'404':
description: Returned if the option is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field.option:jira'
x-atlassian-connect-scope: NONE
put:
tags:
- Issue custom field options (apps)
summary: Update issue field option
description: >-
Updates or creates an option for a select list issue field. This
operation requires that the option ID is provided when creating an
option, therefore, the option ID needs to be specified as a path and
body parameter. The option ID provided in the path and body must be
identical.
Note that this operation **only works for issue field select list
options added by Connect apps**, it cannot be used with issue field
select list options created in Jira or using operations from the [Issue
custom field options](#api-group-Issue-custom-field-options) resource.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg). Jira permissions
are not required for the app providing the field.
operationId: updateIssueFieldOption
parameters:
- name: fieldKey
in: path
description: >-
The field key is specified in the following format:
**$(app-key)\_\_$(field-key)**. For example,
*example-add-on\_\_example-issue-field*. To determine the `fieldKey`
value, do one of the following:
* open the app's plugin descriptor, then **app-key** is the key at the top and **field-key** is the key in the `jiraIssueFields` module. **app-key** can also be found in the app listing in the Atlassian Universal Plugin Manager.
* run [Get fields](#api-rest-api-3-field-get) and in the field details the value is returned in `key`. For example, `"key": "teams-add-on__team-issue-field"`
required: true
schema:
type: string
- name: optionId
in: path
description: The ID of the option to be updated.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueFieldOption'
example:
config:
attributes: []
scope:
global: {}
projects: []
projects2:
- attributes:
- notSelectable
id: 1001
- attributes:
- notSelectable
id: 1002
id: 1
properties:
description: The team's description
founded: '2016-06-06'
leader:
email: lname@example.com
name: Leader Name
members: 42
value: Team 1
required: true
responses:
'200':
description: Returned if the option is updated or created.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueFieldOption'
example: >-
{"id":1,"value":"Team 1","properties":{"leader":{"name":"Leader
Name","email":"lname@example.com"},"members":42,"description":"The
team's
description","founded":"2016-06-06"},"config":{"scope":{"projects":[],"projects2":[{"id":1001,"attributes":["notSelectable"]},{"id":1002,"attributes":["notSelectable"]}],"global":{}},"attributes":[]}}
'400':
description: >-
Returned if the option is invalid, or the *ID* in the request object
does not match the *optionId* parameter.
'403':
description: >-
Returned if the request is not authenticated as a Jira administrator
or the app that provided the field.
'404':
description: Returned if field is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field.option:jira'
x-atlassian-connect-scope: NONE
delete:
tags:
- Issue custom field options (apps)
summary: Delete issue field option
description: >-
Deletes an option from a select list issue field.
Note that this operation **only works for issue field select list
options added by Connect apps**, it cannot be used with issue field
select list options created in Jira or using operations from the [Issue
custom field options](#api-group-Issue-custom-field-options) resource.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg). Jira permissions
are not required for the app providing the field.
operationId: deleteIssueFieldOption
parameters:
- name: fieldKey
in: path
description: >-
The field key is specified in the following format:
**$(app-key)\_\_$(field-key)**. For example,
*example-add-on\_\_example-issue-field*. To determine the `fieldKey`
value, do one of the following:
* open the app's plugin descriptor, then **app-key** is the key at the top and **field-key** is the key in the `jiraIssueFields` module. **app-key** can also be found in the app listing in the Atlassian Universal Plugin Manager.
* run [Get fields](#api-rest-api-3-field-get) and in the field details the value is returned in `key`. For example, `"key": "teams-add-on__team-issue-field"`
required: true
schema:
type: string
- name: optionId
in: path
description: The ID of the option to be deleted.
required: true
schema:
type: integer
format: int64
responses:
'204':
description: Returned if the field option is deleted.
content:
application/json:
schema: {}
'403':
description: >-
Returned if the request is not authenticated as a Jira administrator
or the app that provided the field.
'404':
description: Returned if the field or option is not found.
'409':
description: Returned if the option is selected for the field in any issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:field.option:jira'
x-atlassian-connect-scope: NONE
'/rest/api/3/field/{fieldKey}/option/{optionId}/issue':
delete:
tags:
- Issue custom field options (apps)
summary: Replace issue field option
description: >-
Deselects an issue-field select-list option from all issues where it is
selected. A different option can be selected to replace the deselected
option. The update can also be limited to a smaller set of issues by
using a JQL query.
Connect and Forge app users with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) can override the
screen security configuration using `overrideScreenSecurity` and
`overrideEditableFlag`.
This is an [asynchronous operation](#async). The response object
contains a link to the long-running task.
Note that this operation **only works for issue field select list
options added by Connect apps**, it cannot be used with issue field
select list options created in Jira or using operations from the [Issue
custom field options](#api-group-Issue-custom-field-options) resource.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg). Jira permissions
are not required for the app providing the field.
operationId: replaceIssueFieldOption
parameters:
- name: replaceWith
in: query
description: >-
The ID of the option that will replace the currently selected
option.
schema:
type: integer
format: int64
- name: jql
in: query
description: >-
A JQL query that specifies the issues to be updated. For example,
*project=10000*.
schema:
type: string
- name: overrideScreenSecurity
in: query
description: >-
Whether screen security is overridden to enable hidden fields to be
edited. Available to Connect and Forge app users with admin
permission.
schema:
type: boolean
default: false
- name: overrideEditableFlag
in: query
description: >-
Whether screen security is overridden to enable uneditable fields to
be edited. Available to Connect and Forge app users with *Administer
Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
schema:
type: boolean
default: false
- name: fieldKey
in: path
description: >-
The field key is specified in the following format:
**$(app-key)\_\_$(field-key)**. For example,
*example-add-on\_\_example-issue-field*. To determine the `fieldKey`
value, do one of the following:
* open the app's plugin descriptor, then **app-key** is the key at the top and **field-key** is the key in the `jiraIssueFields` module. **app-key** can also be found in the app listing in the Atlassian Universal Plugin Manager.
* run [Get fields](#api-rest-api-3-field-get) and in the field details the value is returned in `key`. For example, `"key": "teams-add-on__team-issue-field"`
required: true
schema:
type: string
- name: optionId
in: path
description: The ID of the option to be deselected.
required: true
schema:
type: integer
format: int64
responses:
'303':
description: Returned if the long-running task to deselect the option is started.
content:
application/json:
schema:
$ref: >-
#/components/schemas/TaskProgressBeanRemoveOptionFromIssuesResult
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/task/1","id":"1","description":"Remove
option 1 from issues matched by '*', and replace with option
3","status":"COMPLETE","result":{"modifiedIssues":[10001,10010],"unmodifiedIssues":[10005],"errors":{"errors":{},"errorMessages":["Option
2 cannot be set on issue MKY-5 as it is not in the correct
scope"],"httpStatusCode":{"empty":false,"present":true}}},"elapsedRuntime":42}
'400':
description: Returned if the request is not valid.
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
example: >-
{"errorMessages":["Connect and Forge app users with Administer
Jira global permission can override screen
security."],"errors":{}}
'404':
description: >-
Returned if the field is not found or does not support options, or
the options to be replaced are not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field.option:jira'
- 'delete:field.option:jira'
x-atlassian-connect-scope: NONE
'/rest/api/3/field/{id}':
delete:
tags:
- Issue fields
summary: Delete custom field
description: >-
Deletes a custom field. The custom field is deleted whether it is in the
trash or not. See [Edit or delete a custom
field](https://confluence.atlassian.com/x/Z44fOw) for more information
on trashing and deleting custom fields.
This operation is [asynchronous](#async). Follow the `location` link in
the response to determine the status of the task and use [Get
task](#api-rest-api-3-task-taskId-get) to obtain subsequent updates.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: deleteCustomField
parameters:
- name: id
in: path
description: The ID of a custom field.
required: true
schema:
type: string
responses:
'303':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskProgressBeanObject'
'400':
description: |-
Returned if any of these are true:
* The custom field is locked.
* The custom field is used in a issue security scheme or a permission scheme.
* The custom field ID format is incorrect.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'404':
description: Returned if the custom field is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'409':
description: Returned if a task to delete the custom field is running.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:field:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{id}/restore':
post:
tags:
- Issue fields
summary: Restore custom field from trash
description: >-
Restores a custom field from trash. See [Edit or delete a custom
field](https://confluence.atlassian.com/x/Z44fOw) for more information
on trashing and deleting custom fields.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: restoreCustomField
parameters:
- name: id
in: path
description: The ID of a custom field.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'404':
description: Returned if the custom field is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/field/{id}/trash':
post:
tags:
- Issue fields
summary: Move custom field to trash
description: >-
Moves a custom field to trash. See [Edit or delete a custom
field](https://confluence.atlassian.com/x/Z44fOw) for more information
on trashing and deleting custom fields.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: trashCustomField
parameters:
- name: id
in: path
description: The ID of a custom field.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'404':
description: Returned if the custom field is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:field:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/fieldconfiguration:
get:
tags:
- Issue field configurations
summary: Get all field configurations
description: >-
Returns a [paginated](#pagination) list of field configurations. The
list can be for all field configurations or a subset determined by any
combination of these criteria:
* a list of field configuration item IDs.
* whether the field configuration is a default.
* whether the field configuration name or description contains a query string.
Only field configurations used in company-managed (classic) projects are
returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getAllFieldConfigurations
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: id
in: query
description: >-
The list of field configuration IDs. To include multiple IDs,
provide an ampersand-separated list. For example,
`id=10000&id=10001`.
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
- name: isDefault
in: query
description: If *true* returns default field configurations only.
schema:
type: boolean
default: false
- name: query
in: query
description: >-
The query string used to match against field configuration names and
descriptions.
schema:
type: string
default: ''
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanFieldConfigurationDetails'
example: >-
{"maxResults":50,"startAt":0,"total":2,"isLast":true,"values":[{"id":10000,"name":"Default
Field Configuration","description":"The default field
configuration
description","isDefault":true},{"id":10001,"name":"My Field
Configuration","description":"My field configuration
description"}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field-configuration:jira'
x-atlassian-connect-scope: ADMIN
post:
tags:
- Issue field configurations
summary: Create field configuration
description: >-
Creates a field configuration. The field configuration is created with
the same field properties as the default configuration, with all the
fields being optional.
This operation can only create configurations for use in company-managed
(classic) projects.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: createFieldConfiguration
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FieldConfigurationDetails'
example:
description: My field configuration description
name: My Field Configuration
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/FieldConfiguration'
example: >-
{"id":10001,"name":"My Field Configuration","description":"My
field configuration description"}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field-configuration:jira'
- 'write:field-configuration:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/fieldconfiguration/{id}':
put:
tags:
- Issue field configurations
summary: Update field configuration
description: >-
Updates a field configuration. The name and the description provided in
the request override the existing values.
This operation can only update configurations used in company-managed
(classic) projects.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateFieldConfiguration
parameters:
- name: id
in: path
description: The ID of the field configuration.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FieldConfigurationDetails'
example:
description: A brand new description
name: My Modified Field Configuration
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the field configuration is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field-configuration:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
delete:
tags:
- Issue field configurations
summary: Delete field configuration
description: >-
Deletes a field configuration.
This operation can only delete configurations used in company-managed
(classic) projects.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: deleteFieldConfiguration
parameters:
- name: id
in: path
description: The ID of the field configuration.
required: true
schema:
type: integer
format: int64
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the field configuration is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:field-configuration:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/fieldconfiguration/{id}/fields':
get:
tags:
- Issue field configurations
summary: Get field configuration items
description: >-
Returns a [paginated](#pagination) list of all fields for a
configuration.
Only the fields from configurations used in company-managed (classic)
projects are returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getFieldConfigurationItems
parameters:
- name: id
in: path
description: The ID of the field configuration.
required: true
schema:
type: integer
format: int64
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanFieldConfigurationItem'
example: >-
{"maxResults":50,"startAt":0,"total":2,"isLast":true,"values":[{"id":"environment","description":"For
example operating system, software platform and/or hardware
specifications (include as appropriate for the
issue).","isHidden":false,"isRequired":false},{"id":"description","isHidden":false,"isRequired":false}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the field configuration is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field-configuration:jira'
x-atlassian-connect-scope: ADMIN
put:
tags:
- Issue field configurations
summary: Update field configuration items
description: >-
Updates fields in a field configuration. The properties of the field
configuration fields provided override the existing values.
This operation can only update field configurations used in
company-managed (classic) projects.
The operation can set the renderer for text fields to the default text
renderer (`text-renderer`) or wiki style renderer (`wiki-renderer`).
However, the renderer cannot be updated for fields using the
autocomplete renderer (`autocomplete-renderer`).
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateFieldConfigurationItems
parameters:
- name: id
in: path
description: The ID of the field configuration.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FieldConfigurationItemsDetails'
example:
fieldConfigurationItems:
- description: The new description of this item.
id: customfield_10012
isHidden: false
- id: customfield_10011
isRequired: true
- description: Another new description.
id: customfield_10010
isHidden: false
isRequired: false
renderer: wiki-renderer
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the field configuration is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field-configuration:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/fieldconfigurationscheme:
get:
tags:
- Issue field configurations
summary: Get all field configuration schemes
description: >-
Returns a [paginated](#pagination) list of field configuration schemes.
Only field configuration schemes used in classic projects are returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getAllFieldConfigurationSchemes
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: id
in: query
description: >-
The list of field configuration scheme IDs. To include multiple IDs,
provide an ampersand-separated list. For example,
`id=10000&id=10001`.
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanFieldConfigurationScheme'
example: >-
{"maxResults":10,"startAt":0,"total":3,"isLast":true,"values":[{"id":"10000","name":"Field
Configuration Scheme for Bugs","description":"This field
configuration scheme is for bugs
only."},{"id":"10001","name":"Field Configuration Scheme for
software related projects","description":"We can use this one
for software projects."},{"id":"10002","name":"Field
Configuration Scheme for Epics","description":"Use this one for
Epic issue type."}]}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field-configuration-scheme:jira'
x-atlassian-connect-scope: ADMIN
post:
tags:
- Issue field configurations
summary: Create field configuration scheme
description: >-
Creates a field configuration scheme.
This operation can only create field configuration schemes used in
company-managed (classic) projects.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: createFieldConfigurationScheme
parameters: []
requestBody:
description: The details of the field configuration scheme.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFieldConfigurationSchemeDetails'
example:
description: We can use this one for software projects.
name: Field Configuration Scheme for software related projects
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/FieldConfigurationScheme'
example: >-
{"id":"10002","name":"Field Configuration Scheme for software
related projects","description":"We can use this one for
software projects."}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["A field configuration scheme is using this
name."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access field
configurations."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field-configuration-scheme:jira'
- 'read:field-configuration-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/fieldconfigurationscheme/mapping:
get:
tags:
- Issue field configurations
summary: Get field configuration issue type items
description: >-
Returns a [paginated](#pagination) list of field configuration issue
type items.
Only items used in classic projects are returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getFieldConfigurationSchemeMappings
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: fieldConfigurationSchemeId
in: query
description: >-
The list of field configuration scheme IDs. To include multiple
field configuration schemes separate IDs with ampersand:
`fieldConfigurationSchemeId=10000&fieldConfigurationSchemeId=10001`.
schema:
maxItems: 50
minItems: 1
uniqueItems: true
type: array
items:
type: integer
format: int64
example: 10020
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanFieldConfigurationIssueTypeItem'
example: >-
{"maxResults":100,"startAt":0,"total":5,"isLast":true,"values":[{"fieldConfigurationSchemeId":"10020","issueTypeId":"10000","fieldConfigurationId":"10010"},{"fieldConfigurationSchemeId":"10020","issueTypeId":"10001","fieldConfigurationId":"10010"},{"fieldConfigurationSchemeId":"10021","issueTypeId":"10002","fieldConfigurationId":"10000"},{"fieldConfigurationSchemeId":"10022","issueTypeId":"default","fieldConfigurationId":"10011"},{"fieldConfigurationSchemeId":"10023","issueTypeId":"default","fieldConfigurationId":"10000"}]}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if no field configuration schemes are found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field-configuration-scheme:jira'
x-atlassian-connect-scope: ADMIN
/rest/api/3/fieldconfigurationscheme/project:
get:
tags:
- Issue field configurations
summary: Get field configuration schemes for projects
description: >-
Returns a [paginated](#pagination) list of field configuration schemes
and, for each scheme, a list of the projects that use it.
The list is sorted by field configuration scheme ID. The first item
contains the list of project IDs assigned to the default field
configuration scheme.
Only field configuration schemes used in classic projects are returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getFieldConfigurationSchemeProjectMapping
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: projectId
in: query
description: >-
The list of project IDs. To include multiple projects, separate IDs
with ampersand: `projectId=10000&projectId=10001`.
required: true
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanFieldConfigurationSchemeProjects'
example: >-
{"maxResults":50,"startAt":0,"total":5,"isLast":true,"values":[{"projectIds":["10","11"]},{"fieldConfigurationScheme":{"id":"10002","name":"Field
Configuration Scheme for software related
projects","description":"We can use this one for software
projects."},"projectIds":["12","13","14"]}]}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field-configuration-scheme:jira'
x-atlassian-connect-scope: ADMIN
put:
tags:
- Issue field configurations
summary: Assign field configuration scheme to project
description: >-
Assigns a field configuration scheme to a project. If the field
configuration scheme ID is `null`, the operation assigns the default
field configuration scheme.
Field configuration schemes can only be assigned to classic projects.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: assignFieldConfigurationSchemeToProject
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FieldConfigurationSchemeProjectAssociation'
example:
fieldConfigurationSchemeId: '10000'
projectId: '10000'
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the project is not a classic project.
content:
application/json:
example: >-
{"errorMessages":["Only classic projects can have field
configuration schemes assigned."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access field
configurations."],"errors":{}}
'404':
description: Returned if the project is missing.
content:
application/json:
example: '{"errorMessages":["The project was not found."],"errors":{}}'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field-configuration-scheme:jira'
x-atlassian-connect-scope: ADMIN
'/rest/api/3/fieldconfigurationscheme/{id}':
put:
tags:
- Issue field configurations
summary: Update field configuration scheme
description: >-
Updates a field configuration scheme.
This operation can only update field configuration schemes used in
company-managed (classic) projects.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateFieldConfigurationScheme
parameters:
- name: id
in: path
description: The ID of the field configuration scheme.
required: true
schema:
type: integer
format: int64
requestBody:
description: The details of the field configuration scheme.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFieldConfigurationSchemeDetails'
example:
description: We can use this one for software projects.
name: Field Configuration Scheme for software related projects
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["A field configuration scheme is using this
name."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access field
configurations."],"errors":{}}
'404':
description: Returned if the field configuration scheme is not found.
content:
application/json:
example: >-
{"errorMessages":["The field configuration scheme was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field-configuration-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
delete:
tags:
- Issue field configurations
summary: Delete field configuration scheme
description: >-
Deletes a field configuration scheme.
This operation can only delete field configuration schemes used in
company-managed (classic) projects.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: deleteFieldConfigurationScheme
parameters:
- name: id
in: path
description: The ID of the field configuration scheme.
required: true
schema:
type: integer
format: int64
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the field configuration scheme is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:field-configuration-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/fieldconfigurationscheme/{id}/mapping':
put:
tags:
- Issue field configurations
summary: Assign issue types to field configurations
description: >-
Assigns issue types to field configurations on field configuration
scheme.
This operation can only modify field configuration schemes used in
company-managed (classic) projects.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: setFieldConfigurationSchemeMapping
parameters:
- name: id
in: path
description: The ID of the field configuration scheme.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/AssociateFieldConfigurationsWithIssueTypesRequest
example:
mappings:
- fieldConfigurationId: '10000'
issueTypeId: default
- fieldConfigurationId: '10002'
issueTypeId: '10001'
- fieldConfigurationId: '10001'
issueTypeId: '10002'
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: >-
Returned if the field configuration scheme, the field configuration,
or the issue type is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field-configuration-scheme:jira'
- 'read:field-configuration-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/fieldconfigurationscheme/{id}/mapping/delete':
post:
tags:
- Issue field configurations
summary: Remove issue types from field configuration scheme
description: >-
Removes issue types from the field configuration scheme.
This operation can only modify field configuration schemes used in
company-managed (classic) projects.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: removeIssueTypesFromGlobalFieldConfigurationScheme
parameters:
- name: id
in: path
description: The ID of the field configuration scheme.
required: true
schema:
type: integer
format: int64
requestBody:
description: The issue type IDs to remove.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeIdsToRemove'
example:
issueTypeIds:
- '10000'
- '10001'
- '10002'
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["The issueTypeIds must not contain
duplicates."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["Only Jira administrators can access field
configurations."],"errors":{}}
'404':
description: >-
Returned if the field configuration scheme or the issue types are
not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["The field configuration scheme was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:field-configuration-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/filter:
post:
tags:
- Filters
summary: Create filter
description: >-
Creates a filter. The filter is shared according to the [default share
scope](#api-rest-api-3-filter-post). The filter is not selected as a
favorite.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: createFilter
parameters:
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
filter in the response. This parameter accepts a comma-separated
list. Expand options include:
* `sharedUsers` Returns the users that the filter is shared with. This includes users that can browse projects that the filter is shared with. If you don't specify `sharedUsers`, then the `sharedUsers` object is returned but it doesn't list any users. The list of users returned is limited to 1000, to access additional users append `[start-index:end-index]` to the expand request. For example, to access the next 1000 users, use `?expand=sharedUsers[1001:2000]`.
* `subscriptions` Returns the users that are subscribed to the filter. If you don't specify `subscriptions`, the `subscriptions` object is returned but it doesn't list any subscriptions. The list of subscriptions returned is limited to 1000, to access additional subscriptions append `[start-index:end-index]` to the expand request. For example, to access the next 1000 subscriptions, use `?expand=subscriptions[1001:2000]`.
schema:
type: string
- name: overrideSharePermissions
in: query
description: >-
EXPERIMENTAL: Whether share permissions are overridden to enable
filters with any share permissions to be created. Available to users
with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
schema:
type: boolean
default: false
requestBody:
description: The filter to create.
content:
application/json:
schema:
$ref: '#/components/schemas/Filter'
example:
description: Lists all open bugs
jql: type = Bug and resolution is empty
name: All Open Bugs
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Filter'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/filter/10000","id":"10000","name":"All
Open Bugs","description":"Lists all open
bugs","owner":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"jql":"type = Bug and resolution is
empty","viewUrl":"https://your-domain.atlassian.net/issues/?filter=10000","searchUrl":"https://your-domain.atlassian.net/rest/api/3/search?jql=type%20%3D%20Bug%20and%20resolutino%20is%20empty","favourite":true,"favouritedCount":0,"sharePermissions":[],"editPermissions":[],"subscriptions":{"size":0,"items":[],"max-results":0,"start-index":0,"end-index":0}}
'400':
description: >-
Returned if the request object is invalid. For example, the `name`
is not unique or the project ID is not specified for a project role
share permission.
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:filter:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'write:filter:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project-version:jira'
- 'read:project.component:jira'
x-atlassian-connect-scope: WRITE
/rest/api/3/filter/defaultShareScope:
get:
tags:
- Filter sharing
summary: Get default share scope
description: >-
Returns the default sharing settings for new filters and dashboards for
a user.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: getDefaultShareScope
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/DefaultShareScope'
example: '{"scope":"GLOBAL"}'
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:filter.default-share-scope:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Filter sharing
summary: Set default share scope
description: |-
Sets the default sharing for new filters and dashboards for a user.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: setDefaultShareScope
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DefaultShareScope'
example:
scope: GLOBAL
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/DefaultShareScope'
example: '{"scope":"GLOBAL"}'
'400':
description: Returned if an invalid scope is set.
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:filter.default-share-scope:jira'
- 'read:filter.default-share-scope:jira'
x-atlassian-connect-scope: WRITE
/rest/api/3/filter/favourite:
get:
tags:
- Filters
summary: Get favorite filters
description: >-
Returns the visible favorite filters of the user.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** A favorite filter is only
visible to the user where the filter is:
* owned by the user.
* shared with a group that the user is a member of.
* shared with a private project that the user has *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for.
* shared with a public project.
* shared with the public.
For example, if the user favorites a public filter that is subsequently
made private that filter is not returned by this operation.
operationId: getFavouriteFilters
parameters:
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
filter in the response. This parameter accepts a comma-separated
list. Expand options include:
* `sharedUsers` Returns the users that the filter is shared with. This includes users that can browse projects that the filter is shared with. If you don't specify `sharedUsers`, then the `sharedUsers` object is returned but it doesn't list any users. The list of users returned is limited to 1000, to access additional users append `[start-index:end-index]` to the expand request. For example, to access the next 1000 users, use `?expand=sharedUsers[1001:2000]`.
* `subscriptions` Returns the users that are subscribed to the filter. If you don't specify `subscriptions`, the `subscriptions` object is returned but it doesn't list any subscriptions. The list of subscriptions returned is limited to 1000, to access additional subscriptions append `[start-index:end-index]` to the expand request. For example, to access the next 1000 subscriptions, use `?expand=subscriptions[1001:2000]`.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Filter'
example: >-
[{"self":"https://your-domain.atlassian.net/rest/api/3/filter/10000","id":"10000","name":"All
Open Bugs","description":"Lists all open
bugs","owner":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"jql":"type = Bug and resolution is
empty","viewUrl":"https://your-domain.atlassian.net/issues/?filter=10000","searchUrl":"https://your-domain.atlassian.net/rest/api/3/search?jql=type%20%3D%20Bug%20and%20resolutino%20is%20empty","favourite":true,"favouritedCount":0,"sharePermissions":[],"editPermissions":[],"subscriptions":{"size":0,"items":[],"max-results":0,"start-index":0,"end-index":0}},{"self":"https://your-domain.atlassian.net/rest/api/3/filter/10010","id":"10010","name":"My
issues","description":"Issues assigned to
me","owner":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"jql":"assignee = currentUser() and
resolution is
empty","viewUrl":"https://your-domain.atlassian.net/issues/?filter=10010","searchUrl":"https://your-domain.atlassian.net/rest/api/3/search?jql=assignee+in+%28currentUser%28%29%29+and+resolution+is+empty","favourite":true,"favouritedCount":0,"sharePermissions":[{"id":10000,"type":"global"},{"id":10010,"type":"project","project":{"self":"https://your-domain.atlassian.net/rest/api/3/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000","16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000","id":"10000","name":"FIRST","description":"First
Project
Category"},"simplified":false,"style":"classic","insight":{"totalIssueCount":100,"lastIssueUpdateTime":"2023-04-12T08:25:28.334+0000"}}}],"editPermissions":[],"subscriptions":{"size":0,"items":[],"max-results":0,"start-index":0,"end-index":0}}]
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:filter:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:jql:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
x-atlassian-connect-scope: READ
/rest/api/3/filter/my:
get:
tags:
- Filters
summary: Get my filters
description: >-
Returns the filters owned by the user. If `includeFavourites` is `true`,
the user's visible favorite filters are also returned.
**[Permissions](#permissions) required:** Permission to access Jira,
however, a favorite filters is only visible to the user where the filter
is:
* owned by the user.
* shared with a group that the user is a member of.
* shared with a private project that the user has *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for.
* shared with a public project.
* shared with the public.
For example, if the user favorites a public filter that is subsequently
made private that filter is not returned by this operation.
operationId: getMyFilters
parameters:
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
filter in the response. This parameter accepts a comma-separated
list. Expand options include:
* `sharedUsers` Returns the users that the filter is shared with. This includes users that can browse projects that the filter is shared with. If you don't specify `sharedUsers`, then the `sharedUsers` object is returned but it doesn't list any users. The list of users returned is limited to 1000, to access additional users append `[start-index:end-index]` to the expand request. For example, to access the next 1000 users, use `?expand=sharedUsers[1001:2000]`.
* `subscriptions` Returns the users that are subscribed to the filter. If you don't specify `subscriptions`, the `subscriptions` object is returned but it doesn't list any subscriptions. The list of subscriptions returned is limited to 1000, to access additional subscriptions append `[start-index:end-index]` to the expand request. For example, to access the next 1000 subscriptions, use `?expand=subscriptions[1001:2000]`.
schema:
type: string
- name: includeFavourites
in: query
description: Include the user's favorite filters in the response.
schema:
type: boolean
default: false
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Filter'
example: >-
[{"self":"https://your-domain.atlassian.net/rest/api/3/filter/10000","id":"10000","name":"All
Open Bugs","description":"Lists all open
bugs","owner":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"jql":"type = Bug and resolution is
empty","viewUrl":"https://your-domain.atlassian.net/issues/?filter=10000","searchUrl":"https://your-domain.atlassian.net/rest/api/3/search?jql=type%20%3D%20Bug%20and%20resolutino%20is%20empty","favourite":true,"favouritedCount":0,"sharePermissions":[],"editPermissions":[],"subscriptions":{"size":0,"items":[],"max-results":0,"start-index":0,"end-index":0}},{"self":"https://your-domain.atlassian.net/rest/api/3/filter/10010","id":"10010","name":"My
issues","description":"Issues assigned to
me","owner":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"jql":"assignee = currentUser() and
resolution is
empty","viewUrl":"https://your-domain.atlassian.net/issues/?filter=10010","searchUrl":"https://your-domain.atlassian.net/rest/api/3/search?jql=assignee+in+%28currentUser%28%29%29+and+resolution+is+empty","favourite":true,"favouritedCount":0,"sharePermissions":[{"id":10000,"type":"global"},{"id":10010,"type":"project","project":{"self":"https://your-domain.atlassian.net/rest/api/3/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000","16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000","id":"10000","name":"FIRST","description":"First
Project
Category"},"simplified":false,"style":"classic","insight":{"totalIssueCount":100,"lastIssueUpdateTime":"2023-04-12T08:25:28.334+0000"}}}],"editPermissions":[],"subscriptions":{"size":0,"items":[],"max-results":0,"start-index":0,"end-index":0}}]
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:filter:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:jql:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
x-atlassian-connect-scope: READ
/rest/api/3/filter/search:
get:
tags:
- Filters
summary: Search for filters
description: >-
Returns a [paginated](#pagination) list of filters. Use this operation
to get:
* specific filters, by defining `id` only.
* filters that match all of the specified attributes. For example, all filters for a user with a particular word in their name. When multiple attributes are specified only filters matching all attributes are returned.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None, however, only the
following filters that match the query parameters are returned:
* filters owned by the user.
* filters shared with a group that the user is a member of.
* filters shared with a private project that the user has *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for.
* filters shared with a public project.
* filters shared with the public.
operationId: getFiltersPaginated
parameters:
- name: filterName
in: query
description: String used to perform a case-insensitive partial match with `name`.
schema:
type: string
- name: accountId
in: query
description: >-
User account ID used to return filters with the matching
`owner.accountId`. This parameter cannot be used with `owner`.
schema:
maxLength: 128
type: string
- name: owner
in: query
description: >-
This parameter is deprecated because of privacy changes. Use
`accountId` instead. See the [migration
guide](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/)
for details. User name used to return filters with the matching
`owner.name`. This parameter cannot be used with `accountId`.
schema:
type: string
- name: groupname
in: query
description: >-
As a group's name can change, use of `groupId` is recommended to
identify a group. Group name used to returns filters that are shared
with a group that matches `sharePermissions.group.groupname`. This
parameter cannot be used with the `groupId` parameter.
schema:
type: string
- name: groupId
in: query
description: >-
Group ID used to returns filters that are shared with a group that
matches `sharePermissions.group.groupId`. This parameter cannot be
used with the `groupname` parameter.
schema:
type: string
- name: projectId
in: query
description: >-
Project ID used to returns filters that are shared with a project
that matches `sharePermissions.project.id`.
schema:
type: integer
format: int64
- name: id
in: query
description: >-
The list of filter IDs. To include multiple IDs, provide an
ampersand-separated list. For example, `id=10000&id=10001`. Do not
exceed 200 filter IDs.
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
- name: orderBy
in: query
description: |-
[Order](#ordering) the results by a field:
* `description` Sorts by filter description. Note that this sorting works independently of whether the expand to display the description field is in use.
* `favourite_count` Sorts by the count of how many users have this filter as a favorite.
* `is_favourite` Sorts by whether the filter is marked as a favorite.
* `id` Sorts by filter ID.
* `name` Sorts by filter name.
* `owner` Sorts by the ID of the filter owner.
* `is_shared` Sorts by whether the filter is shared.
schema:
type: string
default: name
enum:
- description
- '-description'
- +description
- favourite_count
- '-favourite_count'
- +favourite_count
- id
- '-id'
- +id
- is_favourite
- '-is_favourite'
- +is_favourite
- name
- '-name'
- +name
- owner
- '-owner'
- +owner
- is_shared
- '-is_shared'
- +is_shared
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
filter in the response. This parameter accepts a comma-separated
list. Expand options include:
* `description` Returns the description of the filter.
* `favourite` Returns an indicator of whether the user has set the filter as a favorite.
* `favouritedCount` Returns a count of how many users have set this filter as a favorite.
* `jql` Returns the JQL query that the filter uses.
* `owner` Returns the owner of the filter.
* `searchUrl` Returns a URL to perform the filter's JQL query.
* `sharePermissions` Returns the share permissions defined for the filter.
* `editPermissions` Returns the edit permissions defined for the filter.
* `isWritable` Returns whether the current user has permission to edit the filter.
* `subscriptions` Returns the users that are subscribed to the filter.
* `viewUrl` Returns a URL to view the filter.
schema:
type: string
- name: overrideSharePermissions
in: query
description: >-
EXPERIMENTAL: Whether share permissions are overridden to enable
filters with any share permissions to be returned. Available to
users with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
schema:
type: boolean
default: false
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanFilterDetails'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/filter/search?accountId=&maxResults=50&filterName=&orderBy=name&startAt=0&expand=description,owner,jql,searchUrl,viewUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,subscriptions","maxResults":100,"startAt":0,"total":2,"isLast":true,"values":[{"expand":"description,owner,jql,searchUrl,viewUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,subscriptions","self":"https://your-domain.atlassian.net/rest/api/3/filter/10000","id":"10000","name":"All
Open Bugs","description":"Lists all open
bugs","owner":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"jql":"type = Bug and resolution is
empty","viewUrl":"https://your-domain.atlassian.net/issues/?filter=10000","searchUrl":"https://your-domain.atlassian.net/rest/api/3/search?jql=type%20%3D%20Bug%20and%20resolutino%20is%20empty","favourite":false,"favouritedCount":0,"sharePermissions":[],"editPermissions":[],"subscriptions":[]},{"expand":"description,owner,jql,searchUrl,viewUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,subscriptions","self":"https://your-domain.atlassian.net/rest/api/3/filter/10010","id":"10010","name":"My
issues","description":"Issues assigned to
me","owner":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"jql":"assignee = currentUser() and
resolution is
empty","viewUrl":"https://your-domain.atlassian.net/issues/?filter=10010","searchUrl":"https://your-domain.atlassian.net/rest/api/3/search?jql=assignee+in+%28currentUser%28%29%29+and+resolution+is+empty","favourite":true,"favouritedCount":123,"sharePermissions":[{"id":10000,"type":"global"},{"id":10010,"type":"project","project":{"self":"https://your-domain.atlassian.net/rest/api/3/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000","16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000","id":"10000","name":"FIRST","description":"First
Project
Category"},"simplified":false,"style":"classic","insight":{"totalIssueCount":100,"lastIssueUpdateTime":"2023-04-12T08:25:28.334+0000"}}}],"editPermissions":[{"id":10010,"type":"project","project":{"self":"https://your-domain.atlassian.net/rest/api/3/project/MKY","id":"10002","key":"MKY","name":"Example","avatarUrls":{"48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10002","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10002","16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10002","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10002"},"projectCategory":{"self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000","id":"10000","name":"FIRST","description":"First
Project
Category"},"simplified":false,"style":"classic","insight":{"totalIssueCount":100,"lastIssueUpdateTime":"2023-04-12T08:25:28.334+0000"},"deleted":true,"retentionTillDate":"2023-06-11T08:25:28.334+0000","deletedDate":"2023-04-12T08:25:28.334+0000","deletedBy":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false}},"role":{"self":"https://your-domain.atlassian.net/rest/api/3/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","actorGroup":{"name":"jira-developers","displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2"}},{"id":10241,"displayName":"Mia
Krystof","type":"atlassian-user-role-actor","actorUser":{"accountId":"5b10a2844c20165700ede21g"}}],"scope":{"type":"PROJECT","project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"}}}},{"id":10010,"type":"group","group":{"name":"jira-administrators","groupId":"276f955c-63d7-42c8-9520-92d01dca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"}}],"subscriptions":[{"id":1,"user":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","emailAddress":"mia@example.com","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":true,"timeZone":"Australia/Sydney","groups":{"size":3,"items":[]},"applicationRoles":{"size":1,"items":[]}}}]}]}
'400':
description: |-
Returned if:
* `owner` and `accountId` are provided.
* `expand` includes an invalid value.
* `orderBy` is invalid.
* `id` identifies more than 200 filter IDs.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:filter:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:jql:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/filter/{id}':
get:
tags:
- Filters
summary: Get filter
description: >-
Returns a filter.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None, however, the filter is
only returned where it is:
* owned by the user.
* shared with a group that the user is a member of.
* shared with a private project that the user has *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for.
* shared with a public project.
* shared with the public.
operationId: getFilter
parameters:
- name: id
in: path
description: The ID of the filter to return.
required: true
schema:
type: integer
format: int64
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
filter in the response. This parameter accepts a comma-separated
list. Expand options include:
* `sharedUsers` Returns the users that the filter is shared with. This includes users that can browse projects that the filter is shared with. If you don't specify `sharedUsers`, then the `sharedUsers` object is returned but it doesn't list any users. The list of users returned is limited to 1000, to access additional users append `[start-index:end-index]` to the expand request. For example, to access the next 1000 users, use `?expand=sharedUsers[1001:2000]`.
* `subscriptions` Returns the users that are subscribed to the filter. If you don't specify `subscriptions`, the `subscriptions` object is returned but it doesn't list any subscriptions. The list of subscriptions returned is limited to 1000, to access additional subscriptions append `[start-index:end-index]` to the expand request. For example, to access the next 1000 subscriptions, use `?expand=subscriptions[1001:2000]`.
schema:
type: string
- name: overrideSharePermissions
in: query
description: >-
EXPERIMENTAL: Whether share permissions are overridden to enable
filters with any share permissions to be returned. Available to
users with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
schema:
type: boolean
default: false
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Filter'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/filter/10000","id":"10000","name":"All
Open Bugs","description":"Lists all open
bugs","owner":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"jql":"type = Bug and resolution is
empty","viewUrl":"https://your-domain.atlassian.net/issues/?filter=10000","searchUrl":"https://your-domain.atlassian.net/rest/api/3/search?jql=type%20%3D%20Bug%20and%20resolutino%20is%20empty","favourite":true,"favouritedCount":0,"sharePermissions":[],"editPermissions":[],"subscriptions":{"size":0,"items":[],"max-results":0,"start-index":0,"end-index":0}}
'400':
description: >-
Returned if the filter is not found or the user does not have
permission to view it.
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:filter:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:jql:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Filters
summary: Update filter
description: >-
Updates a filter. Use this operation to update a filter's name,
description, JQL, or sharing.
**[Permissions](#permissions) required:** Permission to access Jira,
however the user must own the filter.
operationId: updateFilter
parameters:
- name: id
in: path
description: The ID of the filter to update.
required: true
schema:
type: integer
format: int64
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
filter in the response. This parameter accepts a comma-separated
list. Expand options include:
* `sharedUsers` Returns the users that the filter is shared with. This includes users that can browse projects that the filter is shared with. If you don't specify `sharedUsers`, then the `sharedUsers` object is returned but it doesn't list any users. The list of users returned is limited to 1000, to access additional users append `[start-index:end-index]` to the expand request. For example, to access the next 1000 users, use `?expand=sharedUsers[1001:2000]`.
* `subscriptions` Returns the users that are subscribed to the filter. If you don't specify `subscriptions`, the `subscriptions` object is returned but it doesn't list any subscriptions. The list of subscriptions returned is limited to 1000, to access additional subscriptions append `[start-index:end-index]` to the expand request. For example, to access the next 1000 subscriptions, use `?expand=subscriptions[1001:2000]`.
schema:
type: string
- name: overrideSharePermissions
in: query
description: >-
EXPERIMENTAL: Whether share permissions are overridden to enable the
addition of any share permissions to filters. Available to users
with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
schema:
type: boolean
default: false
requestBody:
description: The filter to update.
content:
application/json:
schema:
$ref: '#/components/schemas/Filter'
example:
description: Lists all open bugs
jql: type = Bug and resolution is empty
name: All Open Bugs
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Filter'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/filter/10000","id":"10000","name":"All
Open Bugs","description":"Lists all open
bugs","owner":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"jql":"type = Bug and resolution is
empty","viewUrl":"https://your-domain.atlassian.net/issues/?filter=10000","searchUrl":"https://your-domain.atlassian.net/rest/api/3/search?jql=type%20%3D%20Bug%20and%20resolutino%20is%20empty","favourite":true,"favouritedCount":0,"sharePermissions":[],"editPermissions":[],"subscriptions":{"size":0,"items":[],"max-results":0,"start-index":0,"end-index":0}}
'400':
description: >-
Returned if the request object is invalid. For example, the `name`
is not unique or the project ID is not specified for a project role
share permission.
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:filter:jira'
- 'read:filter:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:jql:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Filters
summary: Delete filter
description: >-
Delete a filter.
**[Permissions](#permissions) required:** Permission to access Jira,
however filters can only be deleted by the creator of the filter or a
user with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: deleteFilter
parameters:
- name: id
in: path
description: The ID of the filter to delete.
required: true
schema:
type: integer
format: int64
responses:
'204':
description: Returned if the request is successful.
'400':
description: Returned if the filter is not found.
'401':
description: Returned if the user does not have permission to delete the filter.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:filter:jira'
x-atlassian-connect-scope: DELETE
'/rest/api/3/filter/{id}/columns':
get:
tags:
- Filters
summary: Get columns
description: >-
Returns the columns configured for a filter. The column configuration is
used when the filter's results are viewed in *List View* with the
*Columns* set to *Filter*.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None, however, column details
are only returned for:
* filters owned by the user.
* filters shared with a group that the user is a member of.
* filters shared with a private project that the user has *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for.
* filters shared with a public project.
* filters shared with the public.
operationId: getColumns
parameters:
- name: id
in: path
description: The ID of the filter.
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ColumnItem'
example: >-
[{"label":"Key","value":"issuekey"},{"label":"Summary","value":"summary"}]
'400':
description: Returned if the user does not have permission to view the filter.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: Returned if a column configuration is not set for the filter.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:filter.column:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Filters
summary: Set columns
description: >-
Sets the columns for a filter. Only navigable fields can be set as
columns. Use [Get fields](#api-rest-api-3-field-get) to get the list
fields in Jira. A navigable field has `navigable` set to `true`.
The parameters for this resource are expressed as HTML form data. For
example, in curl:
`curl -X PUT -d columns=summary -d columns=description
https://your-domain.atlassian.net/rest/api/3/filter/10000/columns`
**[Permissions](#permissions) required:** Permission to access Jira,
however, columns are only set for:
* filters owned by the user.
* filters shared with a group that the user is a member of.
* filters shared with a private project that the user has *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for.
* filters shared with a public project.
* filters shared with the public.
operationId: setColumns
parameters:
- name: id
in: path
description: The ID of the filter.
required: true
schema:
type: integer
format: int64
requestBody:
description: >-
The IDs of the fields to set as columns. In the form data, specify
each field as `columns=id`, where `id` is the *id* of a field (as seen
in the response for [Get fields](#api-rest-api-<ver>-field-get)). For
example, `columns=summary`.
content:
'*/*':
schema:
type: array
items:
type: string
multipart/form-data:
schema:
type: array
items:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: |-
Returned if:
* a non-navigable field is set as a column.
* the user does not have permission to view the filter.
'403':
description: Returned if the requesting user is not an owner of the filter.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:filter.column:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Filters
summary: Reset columns
description: >-
Reset the user's column configuration for the filter to the default.
**[Permissions](#permissions) required:** Permission to access Jira,
however, columns are only reset for:
* filters owned by the user.
* filters shared with a group that the user is a member of.
* filters shared with a private project that the user has *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for.
* filters shared with a public project.
* filters shared with the public.
operationId: resetColumns
parameters:
- name: id
in: path
description: The ID of the filter.
required: true
schema:
type: integer
format: int64
responses:
'204':
description: Returned if the request is successful.
'400':
description: |-
Returned if:
* the filter is not found.
* the user does not have permission to view the filter.
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Beta
scheme: OAuth2
scopes:
- 'delete:filter.column:jira'
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
x-atlassian-connect-scope: DELETE
'/rest/api/3/filter/{id}/favourite':
put:
tags:
- Filters
summary: Add filter as favorite
description: >-
Add a filter as a favorite for the user.
**[Permissions](#permissions) required:** Permission to access Jira,
however, the user can only favorite:
* filters owned by the user.
* filters shared with a group that the user is a member of.
* filters shared with a private project that the user has *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for.
* filters shared with a public project.
* filters shared with the public.
operationId: setFavouriteForFilter
parameters:
- name: id
in: path
description: The ID of the filter.
required: true
schema:
type: integer
format: int64
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
filter in the response. This parameter accepts a comma-separated
list. Expand options include:
* `sharedUsers` Returns the users that the filter is shared with. This includes users that can browse projects that the filter is shared with. If you don't specify `sharedUsers`, then the `sharedUsers` object is returned but it doesn't list any users. The list of users returned is limited to 1000, to access additional users append `[start-index:end-index]` to the expand request. For example, to access the next 1000 users, use `?expand=sharedUsers[1001:2000]`.
* `subscriptions` Returns the users that are subscribed to the filter. If you don't specify `subscriptions`, the `subscriptions` object is returned but it doesn't list any subscriptions. The list of subscriptions returned is limited to 1000, to access additional subscriptions append `[start-index:end-index]` to the expand request. For example, to access the next 1000 subscriptions, use `?expand=subscriptions[1001:2000]`.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Filter'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/filter/10000","id":"10000","name":"All
Open Bugs","description":"Lists all open
bugs","owner":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"jql":"type = Bug and resolution is
empty","viewUrl":"https://your-domain.atlassian.net/issues/?filter=10000","searchUrl":"https://your-domain.atlassian.net/rest/api/3/search?jql=type%20%3D%20Bug%20and%20resolutino%20is%20empty","favourite":true,"favouritedCount":0,"sharePermissions":[],"editPermissions":[],"subscriptions":{"size":0,"items":[],"max-results":0,"start-index":0,"end-index":0}}
'400':
description: |-
Returned if:
* the filter is not found.
* the user does not have permission to favorite the filter.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:filter:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'write:filter:jira'
- 'read:jql:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Filters
summary: Remove filter as favorite
description: >-
Removes a filter as a favorite for the user. Note that this operation
only removes filters visible to the user from the user's favorites list.
For example, if the user favorites a public filter that is subsequently
made private (and is therefore no longer visible on their favorites
list) they cannot remove it from their favorites list.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: deleteFavouriteForFilter
parameters:
- name: id
in: path
description: The ID of the filter.
required: true
schema:
type: integer
format: int64
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
filter in the response. This parameter accepts a comma-separated
list. Expand options include:
* `sharedUsers` Returns the users that the filter is shared with. This includes users that can browse projects that the filter is shared with. If you don't specify `sharedUsers`, then the `sharedUsers` object is returned but it doesn't list any users. The list of users returned is limited to 1000, to access additional users append `[start-index:end-index]` to the expand request. For example, to access the next 1000 users, use `?expand=sharedUsers[1001:2000]`.
* `subscriptions` Returns the users that are subscribed to the filter. If you don't specify `subscriptions`, the `subscriptions` object is returned but it doesn't list any subscriptions. The list of subscriptions returned is limited to 1000, to access additional subscriptions append `[start-index:end-index]` to the expand request. For example, to access the next 1000 subscriptions, use `?expand=subscriptions[1001:2000]`.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Filter'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/filter/10000","id":"10000","name":"All
Open Bugs","description":"Lists all open
bugs","owner":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"jql":"type = Bug and resolution is
empty","viewUrl":"https://your-domain.atlassian.net/issues/?filter=10000","searchUrl":"https://your-domain.atlassian.net/rest/api/3/search?jql=type%20%3D%20Bug%20and%20resolutino%20is%20empty","favourite":true,"favouritedCount":0,"sharePermissions":[],"editPermissions":[],"subscriptions":{"size":0,"items":[],"max-results":0,"start-index":0,"end-index":0}}
'400':
description: |-
Returned if:
* the filter is not found.
* the user does not have permission to view the filter.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:filter:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:filter:jira'
- 'read:group:jira'
- 'read:issue-type-hierarchy:jira'
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project-role:jira'
- 'read:project-version:jira'
- 'read:project.component:jira'
- 'read:project:jira'
- 'read:user:jira'
x-atlassian-connect-scope: DELETE
'/rest/api/3/filter/{id}/owner':
put:
tags:
- Filters
summary: Change filter owner
description: >-
Changes the owner of the filter.
**[Permissions](#permissions) required:** Permission to access Jira.
However, the user must own the filter or have the *Administer Jira*
[global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: changeFilterOwner
parameters:
- name: id
in: path
description: The ID of the filter to update.
required: true
schema:
type: integer
format: int64
requestBody:
description: The account ID of the new owner of the filter.
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeFilterOwner'
example:
accountId: 0000-0000-0000-0000
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: |-
Returned when:
* The new owner of the filter owns a filter with the same name.
* An attempt is made to change owner of the default filter.
'403':
description: >-
Returned if the requesting user is not an owner of the filter or
does not have *Administer Jira* global permission.
'404':
description: Returned if the filter or the new owner of the filter is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Beta
scheme: OAuth2
scopes:
- 'read:filter:jira'
- 'write:filter:jira'
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
x-experimental: true
x-atlassian-connect-scope: WRITE
'/rest/api/3/filter/{id}/permission':
get:
tags:
- Filter sharing
summary: Get share permissions
description: >-
Returns the share permissions for a filter. A filter can be shared with
groups, projects, all logged-in users, or the public. Sharing with all
logged-in users or the public is known as a global share permission.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None, however, share
permissions are only returned for:
* filters owned by the user.
* filters shared with a group that the user is a member of.
* filters shared with a private project that the user has *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for.
* filters shared with a public project.
* filters shared with the public.
operationId: getSharePermissions
parameters:
- name: id
in: path
description: The ID of the filter.
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SharePermission'
example: >-
[{"id":10000,"type":"global"},{"id":10010,"type":"project","project":{"self":"https://your-domain.atlassian.net/rest/api/3/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000","16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000","id":"10000","name":"FIRST","description":"First
Project
Category"},"simplified":false,"style":"classic","insight":{"totalIssueCount":100,"lastIssueUpdateTime":"2023-04-12T08:25:28.334+0000"}}},{"id":10010,"type":"project","project":{"self":"https://your-domain.atlassian.net/rest/api/3/project/MKY","id":"10002","key":"MKY","name":"Example","avatarUrls":{"48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10002","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10002","16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10002","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10002"},"projectCategory":{"self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000","id":"10000","name":"FIRST","description":"First
Project
Category"},"simplified":false,"style":"classic","insight":{"totalIssueCount":100,"lastIssueUpdateTime":"2023-04-12T08:25:28.334+0000"},"deleted":true,"retentionTillDate":"2023-06-11T08:25:28.334+0000","deletedDate":"2023-04-12T08:25:28.334+0000","deletedBy":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false}},"role":{"self":"https://your-domain.atlassian.net/rest/api/3/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","actorGroup":{"name":"jira-developers","displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2"}},{"id":10241,"displayName":"Mia
Krystof","type":"atlassian-user-role-actor","actorUser":{"accountId":"5b10a2844c20165700ede21g"}}],"scope":{"type":"PROJECT","project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"}}}},{"id":10010,"type":"group","group":{"name":"jira-administrators","groupId":"276f955c-63d7-42c8-9520-92d01dca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"}}]
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* the filter is not found.
* the user does not have permission to view the filter.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:filter:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:user:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project-role:jira'
- 'read:project-version:jira'
- 'read:project.component:jira'
x-atlassian-connect-scope: READ
post:
tags:
- Filter sharing
summary: Add share permission
description: >-
Add a share permissions to a filter. If you add a global share
permission (one for all logged-in users or the public) it will overwrite
all share permissions for the filter.
Be aware that this operation uses different objects for updating share
permissions compared to [Update filter](#api-rest-api-3-filter-id-put).
**[Permissions](#permissions) required:** *Share dashboards and filters*
[global permission](https://confluence.atlassian.com/x/x4dKLg) and the
user must own the filter.
operationId: addSharePermission
parameters:
- name: id
in: path
description: The ID of the filter.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SharePermissionInputBean'
example:
groupname: jira-administrators
rights: 1
type: group
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SharePermission'
example: >-
[{"id":10000,"type":"global"},{"id":10010,"type":"project","project":{"self":"https://your-domain.atlassian.net/rest/api/3/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000","16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000","id":"10000","name":"FIRST","description":"First
Project
Category"},"simplified":false,"style":"classic","insight":{"totalIssueCount":100,"lastIssueUpdateTime":"2023-04-12T08:25:28.334+0000"}}},{"id":10010,"type":"project","project":{"self":"https://your-domain.atlassian.net/rest/api/3/project/MKY","id":"10002","key":"MKY","name":"Example","avatarUrls":{"48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10002","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10002","16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10002","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10002"},"projectCategory":{"self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000","id":"10000","name":"FIRST","description":"First
Project
Category"},"simplified":false,"style":"classic","insight":{"totalIssueCount":100,"lastIssueUpdateTime":"2023-04-12T08:25:28.334+0000"},"deleted":true,"retentionTillDate":"2023-06-11T08:25:28.334+0000","deletedDate":"2023-04-12T08:25:28.334+0000","deletedBy":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false}},"role":{"self":"https://your-domain.atlassian.net/rest/api/3/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","actorGroup":{"name":"jira-developers","displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2"}},{"id":10241,"displayName":"Mia
Krystof","type":"atlassian-user-role-actor","actorUser":{"accountId":"5b10a2844c20165700ede21g"}}],"scope":{"type":"PROJECT","project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"}}}},{"id":10010,"type":"group","group":{"name":"jira-administrators","groupId":"276f955c-63d7-42c8-9520-92d01dca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"}}]
'400':
description: |-
Returned if:
* the request object is invalid. For example, it contains an invalid type, the ID does not match the type, or the project or group is not found.
* the user does not own the filter.
* the user does not have the required permissions.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* the filter is not found.
* the user does not have permission to view the filter.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:filter:jira'
- 'read:filter:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:user:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project-role:jira'
- 'read:project-version:jira'
- 'read:project.component:jira'
x-atlassian-connect-scope: WRITE
'/rest/api/3/filter/{id}/permission/{permissionId}':
get:
tags:
- Filter sharing
summary: Get share permission
description: >-
Returns a share permission for a filter. A filter can be shared with
groups, projects, all logged-in users, or the public. Sharing with all
logged-in users or the public is known as a global share permission.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None, however, a share
permission is only returned for:
* filters owned by the user.
* filters shared with a group that the user is a member of.
* filters shared with a private project that the user has *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for.
* filters shared with a public project.
* filters shared with the public.
operationId: getSharePermission
parameters:
- name: id
in: path
description: The ID of the filter.
required: true
schema:
type: integer
format: int64
- name: permissionId
in: path
description: The ID of the share permission.
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/SharePermission'
example: '{"id":10000,"type":"global"}'
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* the filter is not found.
* the permission is not found.
* the user does not have permission to view the filter.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:filter:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:issue-type-hierarchy:jira'
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project-version:jira'
- 'read:project.component:jira'
x-atlassian-connect-scope: READ
delete:
tags:
- Filter sharing
summary: Delete share permission
description: >-
Deletes a share permission from a filter.
**[Permissions](#permissions) required:** Permission to access Jira and
the user must own the filter.
operationId: deleteSharePermission
parameters:
- name: id
in: path
description: The ID of the filter.
required: true
schema:
type: integer
format: int64
- name: permissionId
in: path
description: The ID of the share permission.
required: true
schema:
type: integer
format: int64
responses:
'204':
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* the filter is not found.
* the user does not own the filter.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:filter:jira'
x-atlassian-connect-scope: DELETE
/rest/api/3/group:
get:
tags:
- Groups
summary: Get group
description: >-
This operation is deprecated, use
[`group/member`](#api-rest-api-3-group-member-get).
Returns all users in a group.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getGroup
parameters:
- name: groupname
in: query
description: >-
As a group's name can change, use of `groupId` is recommended to
identify a group.
The name of the group. This parameter cannot be used with the
`groupId` parameter.
schema:
type: string
- name: groupId
in: query
description: >-
The ID of the group. This parameter cannot be used with the
`groupName` parameter.
schema:
type: string
x-showInExample: 'true'
- name: expand
in: query
description: List of fields to expand.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'400':
description: Returned if the group name is not specified.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the calling user does not have the Administer Jira
global permission.
'404':
description: Returned if the group is not found.
deprecated: true
security:
- basicAuth: []
- OAuth2:
- 'read:jira-user'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-user'
- state: Beta
scheme: OAuth2
scopes:
- 'read:group:jira'
- 'read:user:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: ADMIN
post:
tags:
- Groups
summary: Create group
description: >-
Creates a group.
**[Permissions](#permissions) required:** Site administration (that is,
member of the *site-admin*
[group](https://confluence.atlassian.com/x/24xjL)).
operationId: createGroup
parameters: []
requestBody:
description: The name of the group.
content:
application/json:
schema:
$ref: '#/components/schemas/AddGroupBean'
example:
name: power-users
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
example: >-
{"name":"power-users","groupId":"276f955c-63d7-42c8-9520-92d01dca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625","users":{"size":1,"items":[{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false}],"max-results":50,"start-index":0,"end-index":0},"expand":"users"}
'400':
description: Returned if group name is not specified or the group name is in use.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:group:jira'
- 'read:user:jira'
- 'write:group:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: INACCESSIBLE
delete:
tags:
- Groups
summary: Remove group
description: >-
Deletes a group.
**[Permissions](#permissions) required:** Site administration (that is,
member of the *site-admin* strategic
[group](https://confluence.atlassian.com/x/24xjL)).
operationId: removeGroup
parameters:
- name: groupname
in: query
schema:
type: string
- name: groupId
in: query
description: >-
The ID of the group. This parameter cannot be used with the
`groupname` parameter.
schema:
type: string
x-showInExample: 'true'
- name: swapGroup
in: query
description: >-
As a group's name can change, use of `swapGroupId` is recommended to
identify a group.
The group to transfer restrictions to. Only comments and worklogs
are transferred. If restrictions are not transferred, comments and
worklogs are inaccessible after the deletion. This parameter cannot
be used with the `swapGroupId` parameter.
schema:
type: string
- name: swapGroupId
in: query
description: >-
The ID of the group to transfer restrictions to. Only comments and
worklogs are transferred. If restrictions are not transferred,
comments and worklogs are inaccessible after the deletion. This
parameter cannot be used with the `swapGroup` parameter.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
'400':
description: Returned if the group name is not specified.
'401':
description: >-
Returned if the authentication credentials are incorrect or missing
from the request.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the group is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:group:jira'
x-atlassian-connect-scope: INACCESSIBLE
/rest/api/3/group/bulk:
get:
tags:
- Groups
summary: Bulk get groups
description: >-
Returns a [paginated](#pagination) list of groups.
**[Permissions](#permissions) required:** *Browse users and groups*
[global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: bulkGetGroups
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: groupId
in: query
description: >-
The ID of a group. To specify multiple IDs, pass multiple `groupId`
parameters. For example,
`groupId=5b10a2844c20165700ede21g&groupId=5b10ac8d82e05b22cc7d4ef5`.
schema:
uniqueItems: true
type: array
example: 3571b9a7-348f-414a-9087-8e1ea03a7df8
items:
type: string
example: 3571b9a7-348f-414a-9087-8e1ea03a7df8
x-showInExample: 'true'
- name: groupName
in: query
description: >-
The name of a group. To specify multiple names, pass multiple
`groupName` parameters. For example,
`groupName=administrators&groupName=jira-software-users`.
schema:
uniqueItems: true
type: array
items:
type: string
- name: accessType
in: query
description: >-
The access level of a group. Valid values: 'site-admin', 'admin',
'user'.
schema:
type: string
- name: applicationKey
in: query
description: >-
The application key of the product user groups to search for. Valid
values: 'jira-servicedesk', 'jira-software',
'jira-product-discovery', 'jira-core'.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanGroupDetails'
example: >-
{"maxResults":10,"startAt":0,"total":2,"isLast":true,"values":[{"name":"jdog-developers","groupId":"276f955c-63d7-42c8-9520-92d01dca0625"},{"name":"juvenal-bot","groupId":"6e87dc72-4f1f-421f-9382-2fee8b652487"}]}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
example: >-
{"errorMessages":["Browse users and groups permission is
required to view groups."],"errors":{}}
'500':
description: >-
Returned if the group with the given access level can't be
retrieved.
content:
application/json:
example: >-
{"errorMessages":["Couldn't retrieve groups with the site-admin
accessType."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-user'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-user'
- state: Beta
scheme: OAuth2
scopes:
- 'read:group:jira'
x-experimental: true
x-atlassian-connect-scope: READ
/rest/api/3/group/member:
get:
tags:
- Groups
summary: Get users from group
description: >-
Returns a [paginated](#pagination) list of all users in a group.
Note that users are ordered by username, however the username is not
returned in the results due to privacy reasons.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getUsersFromGroup
parameters:
- name: groupname
in: query
description: >-
As a group's name can change, use of `groupId` is recommended to
identify a group.
The name of the group. This parameter cannot be used with the
`groupId` parameter.
schema:
type: string
- name: groupId
in: query
description: >-
The ID of the group. This parameter cannot be used with the
`groupName` parameter.
schema:
type: string
x-showInExample: 'true'
- name: includeInactiveUsers
in: query
description: Include inactive users.
schema:
type: boolean
default: false
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanUserDetails'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/group/member?groupname=jira-administrators&includeInactiveUsers=false&startAt=2&maxResults=2","nextPage":"https://your-domain.atlassian.net/rest/api/3/group/member?groupname=jira-administrators&includeInactiveUsers=false&startAt=4&maxResults=2","maxResults":2,"startAt":3,"total":5,"isLast":false,"values":[{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","name":"","key":"","accountId":"5b10a2844c20165700ede21g","emailAddress":"mia@example.com","avatarUrls":{},"displayName":"Mia","active":true,"timeZone":"Australia/Sydney","accountType":"atlassian"},{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a0effa615349cb016cd8","name":"","key":"","accountId":"5b10a0effa615349cb016cd8","emailAddress":"will@example.com","avatarUrls":{},"displayName":"Will","active":false,"timeZone":"Australia/Sydney","accountType":"atlassian"}]}
'400':
description: Returned if the group name is not specified.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the calling user does not have the Administer Jira
global permission.
'404':
description: Returned if the group is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:group:jira'
- 'read:user:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: ADMIN
/rest/api/3/group/user:
post:
tags:
- Groups
summary: Add user to group
description: >-
Adds a user to a group.
**[Permissions](#permissions) required:** Site administration (that is,
member of the *site-admin*
[group](https://confluence.atlassian.com/x/24xjL)).
operationId: addUserToGroup
parameters:
- name: groupname
in: query
description: >-
As a group's name can change, use of `groupId` is recommended to
identify a group.
The name of the group. This parameter cannot be used with the
`groupId` parameter.
schema:
type: string
- name: groupId
in: query
description: >-
The ID of the group. This parameter cannot be used with the
`groupName` parameter.
schema:
type: string
x-showInExample: 'true'
requestBody:
description: The user to add to the group.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserToGroupBean'
example:
accountId: 5b10ac8d82e05b22cc7d4ef5
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'400':
description: |-
Returned if:
* `groupname` is not provided.
* `accountId` is missing.
'401':
description: >-
Returned if the authentication credentials are incorrect or missing
from the request.
'403':
description: Returned if the calling user does not have the necessary permission.
'404':
description: Returned if the group or user are not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:group:jira'
- 'read:avatar:jira'
- 'read:group:jira'
- 'read:user:jira'
x-atlassian-connect-scope: INACCESSIBLE
delete:
tags:
- Groups
summary: Remove user from group
description: >-
Removes a user from a group.
**[Permissions](#permissions) required:** Site administration (that is,
member of the *site-admin*
[group](https://confluence.atlassian.com/x/24xjL)).
operationId: removeUserFromGroup
parameters:
- name: groupname
in: query
description: >-
As a group's name can change, use of `groupId` is recommended to
identify a group.
The name of the group. This parameter cannot be used with the
`groupId` parameter.
schema:
type: string
- name: groupId
in: query
description: >-
The ID of the group. This parameter cannot be used with the
`groupName` parameter.
schema:
type: string
x-showInExample: 'true'
- name: username
in: query
description: >-
This parameter is no longer available. See the [deprecation
notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/)
for details.
schema:
type: string
- name: accountId
in: query
description: >-
The account ID of the user, which uniquely identifies the user
across all Atlassian products. For example,
*5b10ac8d82e05b22cc7d4ef5*.
required: true
schema:
maxLength: 128
type: string
example: 5b10ac8d82e05b22cc7d4ef5
x-showInExample: 'true'
responses:
'200':
description: Returned if the request is successful.
'400':
description: |-
Returned if:
* `groupName` is missing.
* `accountId` is missing.
'401':
description: >-
Returned if the authentication credentials are incorrect or missing
from the request.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the group or user are not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:group:jira'
x-atlassian-connect-scope: INACCESSIBLE
/rest/api/3/groups/picker:
get:
tags:
- Groups
summary: Find groups
description: >-
Returns a list of groups whose names contain a query string. A list of
group names can be provided to exclude groups from the results.
The primary use case for this resource is to populate a group picker
suggestions list. To this end, the returned object includes the `html`
field where the matched query term is highlighted in the group name with
the HTML strong tag. Also, the groups list is wrapped in a response
object that contains a header for use in the picker, specifically
*Showing X of Y matching groups*.
The list returns with the groups sorted. If no groups match the list
criteria, an empty list is returned.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** *Browse projects* [project
permission](https://confluence.atlassian.com/x/yodKLg). Anonymous calls
and calls by users without the required permission return an empty list.
*Browse users and groups* [global
permission](https://confluence.atlassian.com/x/x4dKLg). Without this
permission, calls where query is not an exact match to an existing group
will return an empty list.
operationId: findGroups
parameters:
- name: accountId
in: query
description: >-
This parameter is deprecated, setting it does not affect the
results. To find groups containing a particular user, use [Get user
groups](#api-rest-api-3-user-groups-get).
schema:
type: string
- name: query
in: query
description: The string to find in group names.
schema:
type: string
example: query
- name: exclude
in: query
description: >-
As a group's name can change, use of `excludeGroupIds` is
recommended to identify a group.
A group to exclude from the result. To exclude multiple groups,
provide an ampersand-separated list. For example,
`exclude=group1&exclude=group2`. This parameter cannot be used with
the `excludeGroupIds` parameter.
schema:
type: array
items:
type: string
- name: excludeId
in: query
description: >-
A group ID to exclude from the result. To exclude multiple groups,
provide an ampersand-separated list. For example,
`excludeId=group1-id&excludeId=group2-id`. This parameter cannot be
used with the `excludeGroups` parameter.
schema:
type: array
items:
type: string
- name: maxResults
in: query
description: >-
The maximum number of groups to return. The maximum number of groups
that can be returned is limited by the system property
`jira.ajax.autocomplete.limit`.
schema:
type: integer
format: int32
- name: caseInsensitive
in: query
description: Whether the search for groups should be case insensitive.
schema:
type: boolean
default: false
- name: userName
in: query
description: >-
This parameter is no longer available. See the [deprecation
notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/)
for details.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/FoundGroups'
example: >-
{"header":"Showing 20 of 25 matching
groups","total":25,"groups":[{"name":"jdog-developers","html":"<b>j</b>dog-developers","groupId":"276f955c-63d7-42c8-9520-92d01dca0625"},{"name":"juvenal-bot","html":"<b>j</b>uvenal-bot","groupId":"6e87dc72-4f1f-421f-9382-2fee8b652487"}]}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-user'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-user'
- state: Beta
scheme: OAuth2
scopes:
- 'read:group:jira'
x-atlassian-connect-scope: READ
/rest/api/3/groupuserpicker:
get:
tags:
- Group and user picker
summary: Find users and groups
description: >-
Returns a list of users and groups matching a string. The string is
used:
* for users, to find a case-insensitive match with display name and e-mail address. Note that if a user has hidden their email address in their user profile, partial matches of the email address will not find the user. An exact match is required.
* for groups, to find a case-sensitive match with group name.
For example, if the string *tin* is used, records with the display name
*Tina*, email address *sarah@tinplatetraining.com*, and the group
*accounting* would be returned.
Optionally, the search can be refined to:
* the projects and issue types associated with a custom field, such as a user picker. The search can then be further refined to return only users and groups that have permission to view specific:
* projects.
* issue types.
If multiple projects or issue types are specified, they must be a subset of those enabled for the custom field or no results are returned. For example, if a field is enabled for projects A, B, and C then the search could be limited to projects B and C. However, if the search is limited to projects B and D, nothing is returned.
* not return Connect app users and groups.
* return groups that have a case-insensitive match with the query.
The primary use case for this resource is to populate a picker field
suggestion list with users or groups. To this end, the returned object
includes an `html` field for each list. This field highlights the
matched query term in the item name with the HTML strong tag. Also, each
list is wrapped in a response object that contains a header for use in a
picker, specifically *Showing X of Y matching groups*.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** *Browse users and groups*
[global permission](https://confluence.atlassian.com/x/yodKLg).
operationId: findUsersAndGroups
parameters:
- name: query
in: query
description: The search string.
required: true
schema:
type: string
- name: maxResults
in: query
description: The maximum number of items to return in each list.
schema:
type: integer
format: int32
default: 50
- name: showAvatar
in: query
description: >-
Whether the user avatar should be returned. If an invalid value is
provided, the default value is used.
schema:
type: boolean
default: false
- name: fieldId
in: query
description: The custom field ID of the field this request is for.
schema:
type: string
- name: projectId
in: query
description: >-
The ID of a project that returned users and groups must have
permission to view. To include multiple projects, provide an
ampersand-separated list. For example,
`projectId=10000&projectId=10001`. This parameter is only used when
`fieldId` is present.
schema:
type: array
items:
type: string
- name: issueTypeId
in: query
description: >-
The ID of an issue type that returned users and groups must have
permission to view. To include multiple issue types, provide an
ampersand-separated list. For example,
`issueTypeId=10000&issueTypeId=10001`. Special values, such as `-1`
(all standard issue types) and `-2` (all subtask issue types), are
supported. This parameter is only used when `fieldId` is present.
schema:
type: array
items:
type: string
- name: avatarSize
in: query
description: >-
The size of the avatar to return. If an invalid value is provided,
the default value is used.
schema:
type: string
default: xsmall
enum:
- xsmall
- xsmall@2x
- xsmall@3x
- small
- small@2x
- small@3x
- medium
- medium@2x
- medium@3x
- large
- large@2x
- large@3x
- xlarge
- xlarge@2x
- xlarge@3x
- xxlarge
- xxlarge@2x
- xxlarge@3x
- xxxlarge
- xxxlarge@2x
- xxxlarge@3x
- name: caseInsensitive
in: query
description: Whether the search for groups should be case insensitive.
schema:
type: boolean
default: false
- name: excludeConnectAddons
in: query
description: >-
Whether Connect app users and groups should be excluded from the
search results. If an invalid value is provided, the default value
is used.
schema:
type: boolean
default: false
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/FoundUsersAndGroups'
example: >-
{"users":{"users":[{"accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"mia","key":"mia","html":"<strong>Mi</strong>a
Krystof - <strong>mi</strong>a@example.com
(<strong>mi</strong>a)","displayName":"Mia
Krystof","avatarUrl":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16"}],"total":25,"header":"Showing
20 of 25 matching groups"},"groups":{"header":"Showing 20 of 25
matching
groups","total":25,"groups":[{"name":"jdog-developers","html":"<b>j</b>dog-developers","groupId":"276f955c-63d7-42c8-9520-92d01dca0625"},{"name":"juvenal-bot","html":"<b>j</b>uvenal-bot","groupId":"6e87dc72-4f1f-421f-9382-2fee8b652487"}]}}
'400':
description: Returned if the query parameter is not provided.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'429':
description: >-
Returned if the rate limit is exceeded. User search endpoints share
a collective rate limit for the tenant, in addition to Jira's normal
rate limiting you may receive a rate limit for user search. Please
respect the Retry-After header.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:group:jira'
- 'read:user:jira'
x-atlassian-connect-scope: READ
/rest/api/3/instance/license:
get:
tags:
- Instance information
summary: Get license
description: |-
Returns licensing information about the Jira instance.
**[Permissions](#permissions) required:** None.
operationId: getLicense
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/License'
example: >-
{"applications":[{"id":"jira-core","plan":"PAID"},{"id":"jira-servicedesk","plan":"FREE"},{"id":"jira-software","plan":"PAID"},{"id":"jira-product-discovery","plan":"FREE"}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:license:jira'
x-experimental: true
x-atlassian-connect-scope: READ
/rest/api/3/issue:
post:
tags:
- Issues
summary: Create issue
description: >-
Creates an issue or, where the option to create subtasks is enabled in
Jira, a subtask. A transition may be applied, to move the issue or
subtask to a workflow step other than the default start step, and issue
properties set.
The content of the issue or subtask is defined using `update` and
`fields`. The fields that can be set in the issue or subtask are
determined using the [ Get create issue
metadata](#api-rest-api-3-issue-createmeta-get). These are the same
fields that appear on the issue's create screen. Note that the
`description`, `environment`, and any `textarea` type custom fields
(multi-line text fields) take Atlassian Document Format content. Single
line custom fields (`textfield`) accept a string and don't handle
Atlassian Document Format content.
Creating a subtask differs from creating an issue as follows:
* `issueType` must be set to a subtask issue type (use [ Get create issue metadata](#api-rest-api-3-issue-createmeta-get) to find subtask issue types).
* `parent` must contain the ID or key of the parent issue.
In a next-gen project any issue may be made a child providing that the
parent and child are members of the same project.
**[Permissions](#permissions) required:** *Browse projects* and *Create
issues* [project permissions](https://confluence.atlassian.com/x/yodKLg)
for the project in which the issue or subtask is created.
operationId: createIssue
parameters:
- name: updateHistory
in: query
description: >-
Whether the project in which the issue is created is added to the
user's **Recently viewed** project list, as shown under **Projects**
in Jira. When provided, the issue type and request type are added to
the user's history for a project. These values are then used to
provide defaults on the issue create screen.
schema:
type: boolean
default: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueUpdateDetails'
example:
fields:
assignee:
id: 5b109f2e9729b51b54dc274d
components:
- id: '10000'
customfield_10000: 09/Jun/19
customfield_20000: '06/Jul/19 3:25 PM'
customfield_30000:
- '10000'
- '10002'
customfield_40000:
content:
- content:
- text: Occurs on all orders
type: text
type: paragraph
type: doc
version: 1
customfield_50000:
content:
- content:
- text: Could impact day-to-day work.
type: text
type: paragraph
type: doc
version: 1
customfield_60000: jira-software-users
customfield_70000:
- jira-administrators
- jira-software-users
customfield_80000:
value: red
description:
content:
- content:
- text: Order entry fails when selecting supplier.
type: text
type: paragraph
type: doc
version: 1
duedate: '2019-05-11'
environment:
content:
- content:
- text: UAT
type: text
type: paragraph
type: doc
version: 1
fixVersions:
- id: '10001'
issuetype:
id: '10000'
labels:
- bugfix
- blitz_test
parent:
key: PROJ-123
priority:
id: '20000'
project:
id: '10000'
reporter:
id: 5b10a2844c20165700ede21g
security:
id: '10000'
summary: Main order flow broken
timetracking:
originalEstimate: '10'
remainingEstimate: '5'
versions:
- id: '10000'
update: {}
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/CreatedIssue'
example: >-
{"id":"10000","key":"ED-24","self":"https://your-domain.atlassian.net/rest/api/3/issue/10000","transition":{"status":200,"errorCollection":{"errorMessages":[],"errors":{}}}}
'400':
description: |-
Returned if the request:
* is missing required fields.
* contains invalid field values.
* contains fields that cannot be set for the issue type.
* is by a user who does not have the necessary permission.
* is to create a subtype in a project different that of the parent issue.
* is for a subtask when the option to create subtasks is disabled.
* is invalid for any other reason.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: '{"errorMessages":["Field ''priority'' is required"],"errors":{}}'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue:jira'
- 'write:comment:jira'
- 'write:comment.property:jira'
- 'write:attachment:jira'
- 'read:issue:jira'
x-atlassian-connect-scope: WRITE
/rest/api/3/issue/bulk:
post:
tags:
- Issues
summary: Bulk create issue
description: >-
Creates upto **50** issues and, where the option to create subtasks is
enabled in Jira, subtasks. Transitions may be applied, to move the
issues or subtasks to a workflow step other than the default start step,
and issue properties set.
The content of each issue or subtask is defined using `update` and
`fields`. The fields that can be set in the issue or subtask are
determined using the [ Get create issue
metadata](#api-rest-api-3-issue-createmeta-get). These are the same
fields that appear on the issues' create screens. Note that the
`description`, `environment`, and any `textarea` type custom fields
(multi-line text fields) take Atlassian Document Format content. Single
line custom fields (`textfield`) accept a string and don't handle
Atlassian Document Format content.
Creating a subtask differs from creating an issue as follows:
* `issueType` must be set to a subtask issue type (use [ Get create issue metadata](#api-rest-api-3-issue-createmeta-get) to find subtask issue types).
* `parent` the must contain the ID or key of the parent issue.
**[Permissions](#permissions) required:** *Browse projects* and *Create
issues* [project permissions](https://confluence.atlassian.com/x/yodKLg)
for the project in which each issue or subtask is created.
operationId: createIssues
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssuesUpdateBean'
example:
issueUpdates:
- fields:
assignee:
id: 5b109f2e9729b51b54dc274d
components:
- id: '10000'
customfield_10000: 09/Jun/19
customfield_20000: '06/Jul/19 3:25 PM'
customfield_30000:
- '10000'
- '10002'
customfield_40000:
content:
- content:
- text: Occurs on all orders
type: text
type: paragraph
type: doc
version: 1
customfield_50000:
content:
- content:
- text: Could impact day-to-day work.
type: text
type: paragraph
type: doc
version: 1
customfield_60000: jira-software-users
customfield_70000:
- jira-administrators
- jira-software-users
customfield_80000:
value: red
description:
content:
- content:
- text: Order entry fails when selecting supplier.
type: text
type: paragraph
type: doc
version: 1
duedate: '2011-03-11'
environment:
content:
- content:
- text: UAT
type: text
type: paragraph
type: doc
version: 1
fixVersions:
- id: '10001'
issuetype:
id: '10000'
labels:
- bugfix
- blitz_test
priority:
id: '20000'
project:
id: '10000'
reporter:
id: 5b10a2844c20165700ede21g
security:
id: '10000'
summary: Main order flow broken
timetracking:
originalEstimate: '10'
remainingEstimate: '5'
versions:
- id: '10000'
update:
worklog:
- add:
started: '2019-07-05T11:05:00.000+0000'
timeSpent: 60m
- fields:
assignee:
id: 5b109f2e9729b51b54dc274d
components:
- id: '10000'
customfield_10000: 09/Jun/19
customfield_20000: '06/Jul/19 3:25 PM'
customfield_30000:
- '10000'
- '10002'
customfield_40000:
content:
- content:
- text: Occurs on all orders
type: text
type: paragraph
type: doc
version: 1
customfield_50000:
content:
- content:
- text: Could impact day-to-day work.
type: text
type: paragraph
type: doc
version: 1
customfield_60000: jira-software-users
customfield_70000:
- jira-administrators
- jira-software-users
customfield_80000:
value: red
description:
content:
- content:
- text: Order remains pending after approved.
type: text
type: paragraph
type: doc
version: 1
duedate: '2019-04-16'
environment:
content:
- content:
- text: UAT
type: text
type: paragraph
type: doc
version: 1
fixVersions:
- id: '10001'
issuetype:
id: '10000'
labels:
- new_release
priority:
id: '20000'
project:
id: '1000'
reporter:
id: 5b10a2844c20165700ede21g
security:
id: '10000'
summary: Order stuck in pending
timetracking:
originalEstimate: '15'
remainingEstimate: '5'
versions:
- id: '10000'
update: {}
required: true
responses:
'201':
description: >-
Returned if any of the issue or subtask creation requests were
successful. A request may be unsuccessful when it:
* is missing required fields.
* contains invalid field values.
* contains fields that cannot be set for the issue type.
* is by a user who does not have the necessary permission.
* is to create a subtype in a project different that of the parent issue.
* is for a subtask when the option to create subtasks is disabled.
* is invalid for any other reason.
content:
application/json:
schema:
$ref: '#/components/schemas/CreatedIssues'
example: >-
{"issues":[{"id":"10000","key":"ED-24","self":"https://your-domain.atlassian.net/rest/api/3/issue/10000","transition":{"status":200,"errorCollection":{"errorMessages":[],"errors":{}}}},{"id":"10001","key":"ED-25","self":"https://your-domain.atlassian.net/rest/api/3/issue/10001"}],"errors":[]}
'400':
description: >-
Returned if all requests are invalid. Requests may be unsuccessful
when they:
* are missing required fields.
* contain invalid field values.
* contain fields that cannot be set for the issue type.
* are by a user who does not have the necessary permission.
* are to create a subtype in a project different that of the parent issue.
* is for a subtask when the option to create subtasks is disabled.
* are invalid for any other reason.
content:
application/json:
schema:
$ref: '#/components/schemas/CreatedIssues'
example: >-
{"issues":[],"errors":[{"status":400,"elementErrors":{"errorMessages":[],"errors":{"issuetype":"The
issue type selected is invalid.","project":"Sub-tasks must be
created in the same project as the
parent."}},"failedElementNumber":0},{"status":400,"elementErrors":{"errorMessages":[],"errors":{"issuetype":"The
issue type selected is invalid.","project":"Sub-tasks must be
created in the same project as the
parent."}},"failedElementNumber":1}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue:jira'
- 'write:comment:jira'
- 'write:comment.property:jira'
- 'write:attachment:jira'
- 'read:issue:jira'
x-atlassian-connect-scope: WRITE
/rest/api/3/issue/createmeta:
get:
tags:
- Issues
summary: Get create issue metadata
description: >-
Returns details of projects, issue types within projects, and, when
requested, the create screen fields for each issue type for the user.
Use the information to populate the requests in [ Create
issue](#api-rest-api-3-issue-post) and [Create
issues](#api-rest-api-3-issue-bulk-post).
The request can be restricted to specific projects or issue types using
the query parameters. The response will contain information for the
valid projects, issue types, or project and issue type combinations
requested. Note that invalid project, issue type, or project and issue
type combinations do not generate errors.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** *Create issues* [project
permission](https://confluence.atlassian.com/x/yodKLg) in the requested
projects.
operationId: getCreateIssueMeta
parameters:
- name: projectIds
in: query
description: >-
List of project IDs. This parameter accepts a comma-separated list.
Multiple project IDs can also be provided using an
ampersand-separated list. For example,
`projectIds=10000,10001&projectIds=10020,10021`. This parameter may
be provided with `projectKeys`.
schema:
type: array
items:
type: string
- name: projectKeys
in: query
description: >-
List of project keys. This parameter accepts a comma-separated list.
Multiple project keys can also be provided using an
ampersand-separated list. For example,
`projectKeys=proj1,proj2&projectKeys=proj3`. This parameter may be
provided with `projectIds`.
schema:
type: array
items:
type: string
- name: issuetypeIds
in: query
description: >-
List of issue type IDs. This parameter accepts a comma-separated
list. Multiple issue type IDs can also be provided using an
ampersand-separated list. For example,
`issuetypeIds=10000,10001&issuetypeIds=10020,10021`. This parameter
may be provided with `issuetypeNames`.
schema:
type: array
items:
type: string
- name: issuetypeNames
in: query
description: >-
List of issue type names. This parameter accepts a comma-separated
list. Multiple issue type names can also be provided using an
ampersand-separated list. For example,
`issuetypeNames=name1,name2&issuetypeNames=name3`. This parameter
may be provided with `issuetypeIds`.
schema:
type: array
items:
type: string
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
issue metadata in the response. This parameter accepts
`projects.issuetypes.fields`, which returns information about the
fields in the issue creation screen for each issue type. Fields
hidden from the screen are not returned. Use the information to
populate the `fields` and `update` fields in [Create
issue](#api-rest-api-3-issue-post) and [Create
issues](#api-rest-api-3-issue-bulk-post).
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueCreateMetadata'
example: >-
{"projects":[{"self":"https://your-domain.atlassian.net/rest/api/3/project/ED","id":"10000","key":"ED","name":"Edison
Project","avatarUrls":{"16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000&avatarId=10011","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000&avatarId=10011","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000&avatarId=10011","48x48":"https://your-domain.atlassian.net/secure/projectavatar?pid=10000&avatarId=10011"},"issuetypes":[{"self":"https://your-domain.atlassian.net/rest/api/3/issueType/1","id":"1","description":"An
error in the
code","iconUrl":"https://your-domain.atlassian.net/images/icons/issuetypes/bug.png","name":"Bug","subtask":false,"fields":{"issuetype":{"required":true,"name":"Issue
Type","key":"issuetype","hasDefaultValue":false,"operations":["set"]}}}]}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-meta:jira'
- 'read:avatar:jira'
- 'read:field-configuration:jira'
x-atlassian-connect-scope: READ
/rest/api/3/issue/picker:
get:
tags:
- Issue search
summary: Get issue picker suggestions
description: >-
Returns lists of issues matching a query string. Use this resource to
provide auto-completion suggestions when the user is looking for an
issue using a word or string.
This operation returns two lists:
* `History Search` which includes issues from the user's history of created, edited, or viewed issues that contain the string in the `query` parameter.
* `Current Search` which includes issues that match the JQL expression in `currentJQL` and contain the string in the `query` parameter.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: getIssuePickerResource
parameters:
- name: query
in: query
description: >-
A string to match against text fields in the issue such as title,
description, or comments.
schema:
type: string
example: query
x-showInExample: 'true'
- name: currentJQL
in: query
description: >-
A JQL query defining a list of issues to search for the query term.
Note that `username` and `userkey` cannot be used as search terms
for this parameter, due to privacy reasons. Use `accountId` instead.
schema:
type: string
- name: currentIssueKey
in: query
description: >-
The key of an issue to exclude from search results. For example, the
issue the user is viewing when they perform this query.
schema:
type: string
- name: currentProjectId
in: query
description: The ID of a project that suggested issues must belong to.
schema:
type: string
- name: showSubTasks
in: query
description: Indicate whether to include subtasks in the suggestions list.
schema:
type: boolean
- name: showSubTaskParent
in: query
description: >-
When `currentIssueKey` is a subtask, whether to include the parent
issue in the suggestions if it matches the query.
schema:
type: boolean
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssuePickerSuggestions'
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-details:jira'
x-atlassian-connect-scope: READ
/rest/api/3/issue/properties:
post:
tags:
- Issue properties
summary: Bulk set issues properties by list
description: >-
Sets or updates a list of entity property values on issues. A list of up
to 10 entity properties can be specified along with up to 10,000 issues
on which to set or update that list of entity properties.
The value of the request body must be a
[valid](http://tools.ietf.org/html/rfc4627), non-empty JSON. The maximum
length of single issue property value is 32768 characters. This
operation can be accessed anonymously.
This operation is:
* transactional, either all properties are updated in all eligible issues or, when errors occur, no properties are updated.
* [asynchronous](#async). Follow the `location` link in the response to determine the status of the task and use [Get task](#api-rest-api-3-task-taskId-get) to obtain subsequent updates.
**[Permissions](#permissions) required:**
* *Browse projects* and *Edit issues* [project permissions](https://confluence.atlassian.com/x/yodKLg) for the project containing the issue.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: bulkSetIssuesPropertiesList
parameters: []
requestBody:
description: Issue properties to be set or updated with values.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueEntityProperties'
required: true
responses:
'303':
description: Returned if the operation is successful.
'400':
description: >-
Return if the request is invalid or the user does not have the
necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue.property:jira'
x-experimental: true
x-atlassian-connect-scope: WRITE
/rest/api/3/issue/properties/multi:
post:
tags:
- Issue properties
summary: Bulk set issue properties by issue
description: >-
Sets or updates entity property values on issues. Up to 10 entity
properties can be specified for each issue and up to 100 issues included
in the request.
The value of the request body must be a
[valid](http://tools.ietf.org/html/rfc4627), non-empty JSON.
This operation is:
* [asynchronous](#async). Follow the `location` link in the response to determine the status of the task and use [Get task](#api-rest-api-3-task-taskId-get) to obtain subsequent updates.
* non-transactional. Updating some entities may fail. Such information will available in the task result.
**[Permissions](#permissions) required:**
* *Browse projects* and *Edit issues* [project permissions](https://confluence.atlassian.com/x/yodKLg) for the project containing the issue.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: bulkSetIssuePropertiesByIssue
parameters: []
requestBody:
description: >-
Details of the issue properties to be set or updated. Note that if an
issue is not found, it is ignored.
content:
application/json:
schema:
$ref: '#/components/schemas/MultiIssueEntityProperties'
example:
issues:
- issueID: 1000
properties:
myProperty:
owner: admin
weight: 100
- issueID: 1001
properties:
myOtherProperty:
cost: 150
transportation: car
required: true
responses:
'303':
description: Returned if the operation is successful.
'400':
description: Return if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Return if the user does not have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue.property:jira'
x-experimental: true
x-atlassian-connect-scope: WRITE
'/rest/api/3/issue/properties/{propertyKey}':
put:
tags:
- Issue properties
summary: Bulk set issue property
description: >-
Sets a property value on multiple issues.
The value set can be a constant or determined by a [Jira
expression](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/).
Expressions must be computable with constant complexity when applied to
a set of issues. Expressions must also comply with the
[restrictions](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/#restrictions)
that apply to all Jira expressions.
The issues to be updated can be specified by a filter.
The filter identifies issues eligible for update using these criteria:
* `entityIds` Only issues from this list are eligible.
* `currentValue` Only issues with the property set to this value are eligible.
* `hasProperty`:
* If *true*, only issues with the property are eligible.
* If *false*, only issues without the property are eligible.
If more than one criteria is specified, they are joined with the logical
*AND*: only issues that satisfy all criteria are eligible.
If an invalid combination of criteria is provided, an error is returned.
For example, specifying a `currentValue` and `hasProperty` as *false*
would not match any issues (because without the property the property
cannot have a value).
The filter is optional. Without the filter all the issues visible to the
user and where the user has the EDIT\_ISSUES permission for the issue
are considered eligible.
This operation is:
* transactional, either all eligible issues are updated or, when errors occur, none are updated.
* [asynchronous](#async). Follow the `location` link in the response to determine the status of the task and use [Get task](#api-rest-api-3-task-taskId-get) to obtain subsequent updates.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for each project containing issues.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* *Edit issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for each issue.
operationId: bulkSetIssueProperty
parameters:
- name: propertyKey
in: path
description: The key of the property. The maximum length is 255 characters.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkIssuePropertyUpdateRequest'
example:
filter:
currentValue:
owner: admin
weight: 50
entityIds:
- 10100
- 100010
hasProperty: true
value:
owner: admin
weight: 100
required: true
responses:
'303':
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:jira-expressions:jira'
- 'write:issue.property:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Issue properties
summary: Bulk delete issue property
description: >-
Deletes a property value from multiple issues. The issues to be updated
can be specified by filter criteria.
The criteria the filter used to identify eligible issues are:
* `entityIds` Only issues from this list are eligible.
* `currentValue` Only issues with the property set to this value are eligible.
If both criteria is specified, they are joined with the logical *AND*:
only issues that satisfy both criteria are considered eligible.
If no filter criteria are specified, all the issues visible to the user
and where the user has the EDIT\_ISSUES permission for the issue are
considered eligible.
This operation is:
* transactional, either the property is deleted from all eligible issues or, when errors occur, no properties are deleted.
* [asynchronous](#async). Follow the `location` link in the response to determine the status of the task and use [Get task](#api-rest-api-3-task-taskId-get) to obtain subsequent updates.
**[Permissions](#permissions) required:**
* *Browse projects* [ project permission](https://confluence.atlassian.com/x/yodKLg) for each project containing issues.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* *Edit issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for each issue.
operationId: bulkDeleteIssueProperty
parameters:
- name: propertyKey
in: path
description: The key of the property.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueFilterForBulkPropertyDelete'
example:
currentValue: deprecated value
entityIds:
- 10100
- 100010
required: true
responses:
'303':
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:issue.property:jira'
x-atlassian-connect-scope: DELETE
/rest/api/3/issue/watching:
post:
tags:
- Issue watchers
summary: Get is watching issue bulk
description: >-
Returns, for the user, details of the watched status of issues from a
list. If an issue ID is invalid, the returned watched status is `false`.
This operation requires the **Allow users to watch issues** option to be
*ON*. This option is set in General configuration for Jira. See
[Configuring Jira application
options](https://confluence.atlassian.com/x/uYXKM) for details.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: getIsWatchingIssueBulk
parameters: []
requestBody:
description: A list of issue IDs.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueList'
example:
issueIds:
- '10001'
- '10002'
- '10005'
required: true
responses:
'200':
description: Returned if the request is successful
content:
application/json:
schema:
$ref: '#/components/schemas/BulkIssueIsWatching'
example: '{"issuesIsWatching":{"10001":true,"10002":false,"10005":true}}'
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue.watcher:jira'
- 'read:user:jira'
x-atlassian-connect-scope: WRITE
'/rest/api/3/issue/{issueIdOrKey}':
get:
tags:
- Issues
summary: Get issue
description: >-
Returns the details for an issue.
The issue is identified by its ID or key, however, if the identifier
doesn't match an issue, a case-insensitive search and check for moved
issues is performed. If a matching issue is found its details are
returned, a 302 or other redirect is **not** returned. The issue key
returned in the response is the key of the issue found.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: getIssue
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: fields
in: query
description: >-
A list of fields to return for the issue. This parameter accepts a
comma-separated list. Use it to retrieve a subset of fields. Allowed
values:
* `*all` Returns all fields.
* `*navigable` Returns navigable fields.
* Any issue field, prefixed with a minus to exclude.
Examples:
* `summary,comment` Returns only the summary and comments fields.
* `-description` Returns all (default) fields except description.
* `*navigable,-comment` Returns all navigable fields except comment.
This parameter may be specified multiple times. For example,
`fields=field1,field2& fields=field3`.
Note: All fields are returned by default. This differs from [Search
for issues using JQL (GET)](#api-rest-api-3-search-get) and [Search
for issues using JQL (POST)](#api-rest-api-3-search-post) where the
default is all navigable fields.
schema:
type: array
items:
type: string
default: '*all'
- name: fieldsByKeys
in: query
description: >-
Whether fields in `fields` are referenced by keys rather than IDs.
This parameter is useful where fields have been added by a connect
app and a field's key may differ from its ID.
schema:
type: boolean
default: false
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about the
issues in the response. This parameter accepts a comma-separated
list. Expand options include:
* `renderedFields` Returns field values rendered in HTML format.
* `names` Returns the display name of each field.
* `schema` Returns the schema describing a field type.
* `transitions` Returns all possible transitions for the issue.
* `editmeta` Returns information about how each field can be edited.
* `changelog` Returns a list of recent updates to an issue, sorted by date, starting from the most recent.
* `versionedRepresentations` Returns a JSON array for each version of a field's value, with the highest number representing the most recent version. Note: When included in the request, the `fields` parameter is ignored.
schema:
type: string
- name: properties
in: query
description: >-
A list of issue properties to return for the issue. This parameter
accepts a comma-separated list. Allowed values:
* `*all` Returns all issue properties.
* Any issue property key, prefixed with a minus to exclude.
Examples:
* `*all` Returns all properties.
* `*all,-prop1` Returns all properties except `prop1`.
* `prop1,prop2` Returns `prop1` and `prop2` properties.
This parameter may be specified multiple times. For example,
`properties=prop1,prop2& properties=prop3`.
schema:
type: array
items:
type: string
default: 'null'
- name: updateHistory
in: query
description: >-
Whether the project in which the issue is created is added to the
user's **Recently viewed** project list, as shown under **Projects**
in Jira. This also populates the [JQL issues
search](#api-rest-api-3-search-get) `lastViewed` field.
schema:
type: boolean
default: false
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueBean'
example: >-
{"id":"10002","self":"https://your-domain.atlassian.net/rest/api/3/issue/10002","key":"ED-1","fields":{"watcher":{"self":"https://your-domain.atlassian.net/rest/api/3/issue/EX-1/watchers","isWatching":false,"watchCount":1,"watchers":[{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false}]},"attachment":[{"id":10000,"self":"https://your-domain.atlassian.net/rest/api/3/attachments/10000","filename":"picture.jpg","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false},"created":"2023-04-12T08:25:30.048+0000","size":23123,"mimeType":"image/jpeg","content":"https://your-domain.atlassian.net/jira/rest/api/3/attachment/content/10000","thumbnail":"https://your-domain.atlassian.net/jira/rest/api/3/attachment/thumbnail/10000"}],"sub-tasks":[{"id":"10000","type":{"id":"10000","name":"","inward":"Parent","outward":"Sub-task"},"outwardIssue":{"id":"10003","key":"ED-2","self":"https://your-domain.atlassian.net/rest/api/3/issue/ED-2","fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}}}}],"description":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"Main
order flow
broken"}]}]},"project":{"self":"https://your-domain.atlassian.net/rest/api/3/project/EX","id":"10000","key":"EX","name":"Example","avatarUrls":{"48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000","16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000","id":"10000","name":"FIRST","description":"First
Project
Category"},"simplified":false,"style":"classic","insight":{"totalIssueCount":100,"lastIssueUpdateTime":"2023-04-12T08:25:28.334+0000"}},"comment":[{"self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000","id":"10000","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"body":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"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":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"created":"2021-01-17T12:34:00.000+0000","updated":"2021-01-18T23:45:00.000+0000","visibility":{"type":"role","value":"Administrators","identifier":"Administrators"}}],"issuelinks":[{"id":"10001","type":{"id":"10000","name":"Dependent","inward":"depends
on","outward":"is depended
by"},"outwardIssue":{"id":"10004L","key":"PR-2","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-2","fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/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":"PR-3","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-3","fields":{"status":{"iconUrl":"https://your-domain.atlassian.net/images/icons/statuses/open.png","name":"Open"}}}}],"worklog":[{"self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/worklog/10000","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"updateAuthor":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"comment":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"I
did some work
here."}]}]},"updated":"2021-01-18T23:45:00.000+0000","visibility":{"type":"group","value":"jira-developers","identifier":"276f955c-63d7-42c8-9520-92d01dca0625"},"started":"2021-01-17T12:34:00.000+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}}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the issue is not found or the user does not have
permission to view it.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-meta:jira'
- 'read:issue-security-level:jira'
- 'read:issue.vote:jira'
- 'read:issue.changelog:jira'
- 'read:avatar:jira'
- 'read:issue:jira'
- 'read:status:jira'
- 'read:user:jira'
- 'read:field-configuration:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Issues
summary: Edit issue
description: >-
Edits an issue. A transition may be applied and issue properties updated
as part of the edit.
The edits to the issue's fields are defined using `update` and `fields`.
The fields that can be edited are determined using [ Get edit issue
metadata](#api-rest-api-3-issue-issueIdOrKey-editmeta-get).
The parent field may be set by key or ID. For standard issue types, the
parent may be removed by setting `update.parent.set.none` to *true*.
Note that the `description`, `environment`, and any `textarea` type
custom fields (multi-line text fields) take Atlassian Document Format
content. Single line custom fields (`textfield`) accept a string and
don't handle Atlassian Document Format content.
Connect apps having an app user with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg), and Forge apps
acting on behalf of users with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg), can override the
screen security configuration using `overrideScreenSecurity` and
`overrideEditableFlag`.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* and *Edit issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: editIssue
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: notifyUsers
in: query
description: >-
Whether a notification email about the issue update is sent to all
watchers. To disable the notification, administer Jira or administer
project permissions are required. If the user doesn't have the
necessary permission the request is ignored.
schema:
type: boolean
default: true
- name: overrideScreenSecurity
in: query
description: >-
Whether screen security is overridden to enable hidden fields to be
edited. Available to Connect app users with *Administer Jira*
[global permission](https://confluence.atlassian.com/x/x4dKLg) and
Forge apps acting on behalf of users with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
schema:
type: boolean
default: false
- name: overrideEditableFlag
in: query
description: >-
Whether screen security is overridden to enable uneditable fields to
be edited. Available to Connect app users with *Administer Jira*
[global permission](https://confluence.atlassian.com/x/x4dKLg) and
Forge apps acting on behalf of users with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
schema:
type: boolean
default: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueUpdateDetails'
example:
fields:
customfield_10000:
content:
- content:
- text: Investigation underway
type: text
type: paragraph
type: doc
version: 1
customfield_10010: 1
summary: Completed orders still displaying in pending
historyMetadata:
activityDescription: Complete order processing
actor:
avatarUrl: 'http://mysystem/avatar/tony.jpg'
displayName: Tony
id: tony
type: mysystem-user
url: 'http://mysystem/users/tony'
cause:
id: myevent
type: mysystem-event
description: From the order testing process
extraData:
Iteration: 10a
Step: '4'
generator:
id: mysystem-1
type: mysystem-application
type: 'myplugin:type'
properties:
- key: key1
value: Order number 10784
- key: key2
value: Order number 10923
update:
components:
- set: ''
labels:
- add: triaged
- remove: blocker
summary:
- set: Bug in business logic
timetracking:
- edit:
originalEstimate: 1w 1d
remainingEstimate: 4d
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: |-
Returned if:
* the request body is missing.
* the user does not have the necessary permission to edit one or more fields.
* the request includes one or more fields that are not found or are not associated with the issue's edit screen.
* the request includes an invalid transition.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user uses `overrideScreenSecurity` or
`overrideEditableFlag` but doesn't have the necessary permission.
'404':
description: >-
Returned if the issue is not found or the user does not have
permission to view it.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Issues
summary: Delete issue
description: >-
Deletes an issue.
An issue cannot be deleted if it has one or more subtasks. To delete an
issue with subtasks, set `deleteSubtasks`. This causes the issue's
subtasks to be deleted with the issue.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* and *Delete issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the issue.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: deleteIssue
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: deleteSubtasks
in: query
description: Whether the issue's subtasks are deleted when the issue is deleted.
schema:
type: string
default: 'false'
enum:
- 'true'
- 'false'
responses:
'204':
description: Returned if the request is successful.
'400':
description: >-
Returned if the issue has subtasks and `deleteSubtasks` is not set
to *true*.
'401':
description: Returned if the authentication credentials are incorrect.
'403':
description: Returned if the user does not have permission to delete the issue.
'404':
description: >-
Returned if the issue is not found or the user does not have
permission to view the issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:issue:jira'
x-atlassian-connect-scope: DELETE
'/rest/api/3/issue/{issueIdOrKey}/assignee':
put:
tags:
- Issues
summary: Assign issue
description: >-
Assigns an issue to a user. Use this operation when the calling user
does not have the *Edit Issues* permission but has the *Assign issue*
permission for the project that the issue is in.
If `name` or `accountId` is set to:
* `"-1"`, the issue is assigned to the default assignee for the project.
* `null`, the issue is set to unassigned.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse Projects* and *Assign Issues* [ project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: assignIssue
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue to be assigned.
required: true
schema:
type: string
requestBody:
description: The request object with the user that the issue is assigned to.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
example:
accountId: 5b10ac8d82e05b22cc7d4ef5
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: |-
Returned if:
* the user is not found.
* `name`, `key`, or `accountId` is missing.
* more than one of `name`, `key`, and `accountId` are provided.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the issue is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue:jira'
x-atlassian-connect-scope: WRITE
'/rest/api/3/issue/{issueIdOrKey}/attachments':
post:
tags:
- Issue attachments
summary: Add attachment
description: >-
Adds one or more attachments to an issue. Attachments are posted as
multipart/form-data ([RFC 1867](https://www.ietf.org/rfc/rfc1867.txt)).
Note that:
* The request must have a `X-Atlassian-Token: no-check` header, if not it is blocked. See [Special headers](#special-request-headers) for more information.
* The name of the multipart/form-data parameter that contains the attachments must be `file`.
The following examples upload a file called *myfile.txt* to the issue
*TEST-123*:
#### curl ####
curl --location --request POST 'https://your-domain.atlassian.net/rest/api/3/issue/TEST-123/attachments'
-u 'email@example.com:<api_token>'
-H 'X-Atlassian-Token: no-check'
--form 'file=@"myfile.txt"'
#### Node.js ####
// This code sample uses the 'node-fetch' and 'form-data' libraries:
// https://www.npmjs.com/package/node-fetch
// https://www.npmjs.com/package/form-data
const fetch = require('node-fetch');
const FormData = require('form-data');
const fs = require('fs');
const filePath = 'myfile.txt';
const form = new FormData();
const stats = fs.statSync(filePath);
const fileSizeInBytes = stats.size;
const fileStream = fs.createReadStream(filePath);
form.append('file', fileStream, {knownLength: fileSizeInBytes});
fetch('https://your-domain.atlassian.net/rest/api/3/issue/TEST-123/attachments', {
method: 'POST',
body: form,
headers: {
'Authorization': `Basic ${Buffer.from(
'email@example.com:'
).toString('base64')}`,
'Accept': 'application/json',
'X-Atlassian-Token': 'no-check'
}
})
.then(response => {
console.log(
`Response: ${response.status} ${response.statusText}`
);
return response.text();
})
.then(text => console.log(text))
.catch(err => console.error(err));
#### Java ####
// This code sample uses the 'Unirest' library:
// http://unirest.io/java.html
HttpResponse response = Unirest.post("https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}/attachments")
.basicAuth("email@example.com", "")
.header("Accept", "application/json")
.header("X-Atlassian-Token", "no-check")
.field("file", new File("myfile.txt"))
.asJson();
System.out.println(response.getBody());
#### Python ####
# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
from requests.auth import HTTPBasicAuth
import json
url = "https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}/attachments"
auth = HTTPBasicAuth("email@example.com", "")
headers = {
"Accept": "application/json",
"X-Atlassian-Token": "no-check"
}
response = requests.request(
"POST",
url,
headers = headers,
auth = auth,
files = {
"file": ("myfile.txt", open("myfile.txt","rb"), "application-type")
}
)
print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))
#### PHP ####
// This code sample uses the 'Unirest' library:
// http://unirest.io/php.html
Unirest\Request::auth('email@example.com', '');
$headers = array(
'Accept' => 'application/json',
'X-Atlassian-Token' => 'no-check'
);
$parameters = array(
'file' => File::add('myfile.txt')
);
$response = Unirest\Request::post(
'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}/attachments',
$headers,
$parameters
);
var_dump($response)
#### Forge ####
// This sample uses Atlassian Forge and the `form-data` library.
// https://developer.atlassian.com/platform/forge/
// https://www.npmjs.com/package/form-data
import api from "@forge/api";
import FormData from "form-data";
const form = new FormData();
form.append('file', fileStream, {knownLength: fileSizeInBytes});
const response = await api.asApp().requestJira('/rest/api/2/issue/{issueIdOrKey}/attachments', {
method: 'POST',
body: form,
headers: {
'Accept': 'application/json',
'X-Atlassian-Token': 'no-check'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());
Tip: Use a client library. Many client libraries have classes for
handling multipart POST operations. For example, in Java, the Apache
HTTP Components library provides a
[MultiPartEntity](http://hc.apache.org/httpcomponents-client-ga/httpmime/apidocs/org/apache/http/entity/mime/MultipartEntity.html)
class for multipart POST operations.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse Projects* and *Create attachments* [ project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: addAttachment
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue that attachments are added to.
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
type: string
format: binary
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Attachment'
example: >-
[{"self":"https://your-domain.atlassian.net/rest/api/3/attachments/10000","id":"10001","filename":"picture.jpg","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","emailAddress":"mia@example.com","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":true,"timeZone":"Australia/Sydney"},"created":"2023-04-12T08:25:27.054+0000","size":23123,"mimeType":"image/jpeg","content":"https://your-domain.atlassian.net/rest/api/3/attachment/content/10000","thumbnail":"https://your-domain.atlassian.net/rest/api/3/attachment/thumbnail/10000"},{"self":"https://your-domain.atlassian.net/rest/api/3/attachments/10001","filename":"dbeuglog.txt","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","emailAddress":"mia@example.com","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":true,"timeZone":"Australia/Sydney"},"created":"2023-04-12T08:25:27.054+0000","size":2460,"mimeType":"text/plain","content":"https://your-domain.atlassian.net/rest/api/3/attachment/content/10001"}]
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: |-
Returned if any of the following is true:
* the issue is not found.
* the user does not have permission to view the issue.
'413':
description: >-
The attachments exceed the maximum attachment size for issues. See
[Configuring file
attachments](https://confluence.atlassian.com/x/wIXKM) for details.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:user:jira'
- 'write:attachment:jira'
- 'read:attachment:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: WRITE
'/rest/api/3/issue/{issueIdOrKey}/changelog':
get:
tags:
- Issues
summary: Get changelogs
description: >-
Returns a [paginated](#pagination) list of all changelogs for an issue
sorted by date, starting from the oldest.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: getChangeLogs
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int32
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 100
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanChangelog'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/issue/TT-1/changelog?startAt=2&maxResults=2","nextPage":"https://your-domain.atlassian.net/rest/api/3/issue/TT-1/changelog?&startAt=4&maxResults=2","maxResults":2,"startAt":2,"total":5,"isLast":false,"values":[{"id":"10001","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","emailAddress":"mia@example.com","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":true,"timeZone":"Australia/Sydney"},"created":"1970-01-18T06:27:50.429+0000","items":[{"field":"fields","fieldtype":"jira","fieldId":"fieldId","from":null,"fromString":"","to":null,"toString":"label-1"}]},{"id":"10002","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","emailAddress":"mia@example.com","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":true,"timeZone":"Australia/Sydney"},"created":"1970-01-18T06:27:51.429+0000","items":[{"field":"fields","fieldtype":"jira","fieldId":"fieldId","from":null,"fromString":"label-1","to":null,"toString":"label-1
label-2"}]}]}
'404':
description: >-
Returned if the issue is not found or the user does not have
permission to view it.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-meta:jira'
- 'read:avatar:jira'
- 'read:issue.changelog:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/issue/{issueIdOrKey}/changelog/list':
post:
tags:
- Issues
summary: Get changelogs by IDs
description: |-
Returns changelogs for an issue specified by a list of changelog IDs.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: getChangeLogsByIds
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueChangelogIds'
example:
changelogIds:
- 10001
- 10002
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageOfChangelogs'
example: >-
{"startAt":0,"maxResults":2,"total":2,"histories":[{"id":"10001","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","emailAddress":"mia@example.com","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":true,"timeZone":"Australia/Sydney"},"created":"1970-01-18T06:27:50.429+0000","items":[{"field":"fields","fieldtype":"jira","fieldId":"fieldId","from":null,"fromString":"","to":null,"toString":"label-1"}]},{"id":"10002","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","emailAddress":"mia@example.com","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":true,"timeZone":"Australia/Sydney"},"created":"1970-01-18T06:27:51.429+0000","items":[{"field":"fields","fieldtype":"jira","fieldId":"fieldId","from":null,"fromString":"label-1","to":null,"toString":"label-1
label-2"}]}]}
'400':
description: Returned if the request is not valid.
'404':
description: >-
Returned if the issue is not found or the user does not have the
necessary permission.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-meta:jira'
- 'read:avatar:jira'
- 'read:issue.changelog:jira'
x-atlassian-connect-scope: WRITE
'/rest/api/3/issue/{issueIdOrKey}/comment':
get:
tags:
- Issue comments
summary: Get comments
description: >-
Returns all comments for an issue.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** Comments are included in the
response where the user has:
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the comment.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* If the comment has visibility restrictions, belongs to the group or has the role visibility is role visibility is restricted to.
operationId: getComments
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 5000
- name: orderBy
in: query
description: >-
[Order](#ordering) the results by a field. Accepts *created* to sort
comments by their created date.
schema:
type: string
enum:
- created
- '-created'
- +created
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
comments in the response. This parameter accepts `renderedBody`,
which returns the comment body rendered in HTML.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageOfComments'
example: >-
{"startAt":0,"maxResults":1,"total":1,"comments":[{"self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000","id":"10000","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"body":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"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":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"created":"2021-01-17T12:34:00.000+0000","updated":"2021-01-18T23:45:00.000+0000","visibility":{"type":"role","value":"Administrators","identifier":"Administrators"}}]}
'400':
description: Returned if `orderBy` is set to a value other than *created*.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the issue is not found or the user does not have
permission to view it.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:comment:jira'
- 'read:comment.property:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: READ
post:
tags:
- Issue comments
summary: Add comment
description: |-
Adds a comment to an issue.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* and *Add comments* [ project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue containing the comment is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: addComment
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
comments in the response. This parameter accepts `renderedBody`,
which returns the comment body rendered in HTML.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
example:
body:
content:
- content:
- text: >-
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.
type: text
type: paragraph
type: doc
version: 1
visibility:
identifier: Administrators
type: role
value: Administrators
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000","id":"10000","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"body":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"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":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"created":"2021-01-17T12:34:00.000+0000","updated":"2021-01-18T23:45:00.000+0000","visibility":{"type":"role","value":"Administrators","identifier":"Administrators"}}
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect.
'404':
description: >-
Returned if the issue is not found or the user does not have
permission to view it.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:comment:jira'
- 'read:comment.property:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'write:comment:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: WRITE
'/rest/api/3/issue/{issueIdOrKey}/comment/{id}':
get:
tags:
- Issue comments
summary: Get comment
description: |-
Returns a comment.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the comment.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* If the comment has visibility restrictions, the user belongs to the group or has the role visibility is restricted to.
operationId: getComment
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: id
in: path
description: The ID of the comment.
required: true
schema:
type: string
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
comments in the response. This parameter accepts `renderedBody`,
which returns the comment body rendered in HTML.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000","id":"10000","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"body":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"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":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"created":"2021-01-17T12:34:00.000+0000","updated":"2021-01-18T23:45:00.000+0000","visibility":{"type":"role","value":"Administrators","identifier":"Administrators"}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the issue or comment is not found or the user does not
have permission to view the issue or comment.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:comment:jira'
- 'read:comment.property:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Issue comments
summary: Update comment
description: |-
Updates a comment.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue containing the comment is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* *Edit all comments*[ project permission](https://confluence.atlassian.com/x/yodKLg) to update any comment or *Edit own comments* to update comment created by the user.
* If the comment has visibility restrictions, the user belongs to the group or has the role visibility is restricted to.
operationId: updateComment
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: id
in: path
description: The ID of the comment.
required: true
schema:
type: string
- name: notifyUsers
in: query
description: Whether users are notified when a comment is updated.
schema:
type: boolean
default: true
- name: overrideEditableFlag
in: query
description: >-
Whether screen security is overridden to enable uneditable fields to
be edited. Available to Connect app users with the *Administer Jira*
[global permission](https://confluence.atlassian.com/x/x4dKLg) and
Forge apps acting on behalf of users with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
schema:
type: boolean
default: false
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
comments in the response. This parameter accepts `renderedBody`,
which returns the comment body rendered in HTML.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
example:
body:
content:
- content:
- text: >-
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.
type: text
type: paragraph
type: doc
version: 1
visibility:
identifier: Administrators
type: role
value: Administrators
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000","id":"10000","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"body":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"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":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"created":"2021-01-17T12:34:00.000+0000","updated":"2021-01-18T23:45:00.000+0000","visibility":{"type":"role","value":"Administrators","identifier":"Administrators"}}
'400':
description: >-
Returned if the user does not have permission to edit the comment or
the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the issue or comment is not found or the user does not
have permission to view the issue or comment.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:comment:jira'
- 'read:comment.property:jira'
- 'read:group:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'write:comment:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Issue comments
summary: Delete comment
description: |-
Deletes a comment.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue containing the comment is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* *Delete all comments*[ project permission](https://confluence.atlassian.com/x/yodKLg) to delete any comment or *Delete own comments* to delete comment created by the user,
* If the comment has visibility restrictions, the user belongs to the group or has the role visibility is restricted to.
operationId: deleteComment
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: id
in: path
description: The ID of the comment.
required: true
schema:
type: string
responses:
'204':
description: Returned if the request is successful.
'400':
description: Returned if the user does not have permission to delete the comment.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the issue or comment is not found or the user does not
have permission to view the issue or comment.
'405':
description: Returned if an anonymous call is made to the operation.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:comment:jira'
- 'delete:comment.property:jira'
x-atlassian-connect-scope: DELETE
'/rest/api/3/issue/{issueIdOrKey}/editmeta':
get:
tags:
- Issues
summary: Get edit issue metadata
description: >-
Returns the edit screen fields for an issue that are visible to and
editable by the user. Use the information to populate the requests in
[Edit issue](#api-rest-api-3-issue-issueIdOrKey-put).
This endpoint will check for these conditions:
1. Field is available on a field screen - through screen, screen
scheme, issue type screen scheme, and issue type scheme configuration.
`overrideScreenSecurity=true` skips this condition.
2. Field is visible in the [field
configuration](https://support.atlassian.com/jira-cloud-administration/docs/change-a-field-configuration/).
`overrideScreenSecurity=true` skips this condition.
3. Field is shown on the issue: each field has different conditions
here. For example: Attachment field only shows if attachments are
enabled. Assignee only shows if user has permissions to assign the
issue.
4. If a field is custom then it must have valid custom field context,
applicable for its project and issue type. All system fields are assumed
to have context in all projects and all issue types.
5. Issue has a project, issue type, and status defined.
6. Issue is assigned to a valid workflow, and the current status has
assigned a workflow step. `overrideEditableFlag=true` skips this
condition.
7. The current workflow step is editable. This is true by default, but
[can be disabled by
setting](https://support.atlassian.com/jira-cloud-administration/docs/use-workflow-properties/)
the `jira.issue.editable` property to `false`.
`overrideEditableFlag=true` skips this condition.
8. User has [Edit issues
permission](https://support.atlassian.com/jira-cloud-administration/docs/permissions-for-company-managed-projects/).
9. Workflow permissions allow editing a field. This is true by default
but [can be
modified](https://support.atlassian.com/jira-cloud-administration/docs/use-workflow-properties/)
using `jira.permission.*` workflow properties.
Fields hidden using [Issue layout settings
page](https://support.atlassian.com/jira-software-cloud/docs/configure-field-layout-in-the-issue-view/)
remain editable.
Connect apps having an app user with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg), and Forge apps
acting on behalf of users with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg), can return
additional details using:
* `overrideScreenSecurity` When this flag is `true`, then this endpoint skips checking if fields are available through screens, and field configuration (conditions 1. and 2. from the list above).
* `overrideEditableFlag` When this flag is `true`, then this endpoint skips checking if workflow is present and if the current step is editable (conditions 6. and 7. from the list above).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
Note: For any fields to be editable the user must have the *Edit issues*
[project permission](https://confluence.atlassian.com/x/yodKLg) for the
issue.
operationId: getEditIssueMeta
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: overrideScreenSecurity
in: query
description: >-
Whether hidden fields are returned. Available to Connect app users
with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) and Forge
apps acting on behalf of users with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
schema:
type: boolean
default: false
- name: overrideEditableFlag
in: query
description: >-
Whether non-editable fields are returned. Available to Connect app
users with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) and Forge
apps acting on behalf of users with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
schema:
type: boolean
default: false
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueUpdateMetadata'
example: >-
{"fields":{"summary":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My
Multi
Select","key":"field_key","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue"],"defaultValue":"red"}}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user uses an override parameter but doesn't have
permission to do so.
'404':
description: >-
Returned if the issue is not found or the user does not have
permission to view it.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-meta:jira'
- 'read:field-configuration:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/issue/{issueIdOrKey}/notify':
post:
tags:
- Issues
summary: Send notification for issue
description: >-
Creates an email notification for an issue and adds it to the mail
queue.
**[Permissions](#permissions) required:**
* *Browse Projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: notify
parameters:
- name: issueIdOrKey
in: path
description: ID or key of the issue that the notification is sent for.
required: true
schema:
type: string
requestBody:
description: The request object for the notification and recipients.
content:
application/json:
schema:
$ref: '#/components/schemas/Notification'
example:
htmlBody: >-
The <strong>latest</strong> test results for this ticket are now
available.
restrict:
groupIds: []
groups:
- name: notification-group
permissions:
- key: BROWSE
subject: Latest test results
textBody: The latest test results for this ticket are now available.
to:
assignee: false
groupIds: []
groups:
- name: notification-group
reporter: false
users:
- accountId: 5b10a2844c20165700ede21g
active: false
voters: true
watchers: true
required: true
responses:
'204':
description: Returned if the email is queued for sending.
content:
application/json:
schema: {}
'400':
description: |-
Returned if:
* the recipient is the same as the calling user.
* the recipient is invalid. For example, the recipient is set to the assignee, but the issue is unassigned.
* the request is invalid. For example, required fields are missing or have invalid values.
'403':
description: |-
Returned if:
* outgoing emails are disabled.
* no SMTP server is configured.
'404':
description: Returned if the issue is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'send:notification:jira'
x-atlassian-connect-scope: WRITE
'/rest/api/3/issue/{issueIdOrKey}/properties':
get:
tags:
- Issue properties
summary: Get issue property keys
description: >-
Returns the URLs and keys of an issue's properties.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** Property details are only
returned where the user has:
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the issue.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: getIssuePropertyKeys
parameters:
- name: issueIdOrKey
in: path
description: The key or ID of the issue.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PropertyKeys'
example: >-
{"keys":[{"self":"https://your-domain.atlassian.net/rest/api/3/issue/EX-2/properties/issue.support","key":"issue.support"}]}
'404':
description: >-
Returned if the issue is not found or the user does not have
permissions to view the issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue.property:jira'
- 'read:comment.property:jira'
- 'read:dashboard.property:jira'
- 'read:issue-type.property:jira'
- 'read:issue-worklog.property:jira'
- 'read:project.property:jira'
- 'read:user.property:jira'
- 'read:workflow.property:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/issue/{issueIdOrKey}/properties/{propertyKey}':
get:
tags:
- Issue properties
summary: Get issue property
description: |-
Returns the key and value of an issue's property.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the issue.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: getIssueProperty
parameters:
- name: issueIdOrKey
in: path
description: The key or ID of the issue.
required: true
schema:
type: string
- name: propertyKey
in: path
description: The key of the property.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/EntityProperty'
example: >-
{"key":"issue.support","value":{"system.conversation.id":"b1bf38be-5e94-4b40-a3b8-9278735ee1e6","system.support.time":"1m"}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the issue or property is not found or the user does not
have permission to see the issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue.property:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Issue properties
summary: Set issue property
description: >-
Sets the value of an issue's property. Use this resource to store custom
data against an issue.
The value of the request body must be a
[valid](http://tools.ietf.org/html/rfc4627), non-empty JSON blob. The
maximum length is 32768 characters.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* and *Edit issues* [project permissions](https://confluence.atlassian.com/x/yodKLg) for the project containing the issue.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: setIssueProperty
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: propertyKey
in: path
description: The key of the issue property. The maximum length is 255 characters.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema: {}
required: true
responses:
'200':
description: Returned if the issue property is updated.
content:
application/json:
schema: {}
'201':
description: Returned if the issue property is created.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have permission to edit the issue.
'404':
description: >-
Returned if the issue is not found or the user does not have
permission to view the issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue.property:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Issue properties
summary: Delete issue property
description: |-
Deletes an issue's property.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* and *Edit issues* [project permissions](https://confluence.atlassian.com/x/yodKLg) for the project containing the issue.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: deleteIssueProperty
parameters:
- name: issueIdOrKey
in: path
description: The key or ID of the issue.
required: true
schema:
type: string
- name: propertyKey
in: path
description: The key of the property.
required: true
schema:
type: string
responses:
'204':
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the issue or property is not found, or the user does not
have permission to edit the issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:issue.property:jira'
x-atlassian-connect-scope: DELETE
'/rest/api/3/issue/{issueIdOrKey}/remotelink':
get:
tags:
- Issue remote links
summary: Get remote issue links
description: >-
Returns the remote issue links for an issue. When a remote issue link
global ID is provided the record with that global ID is returned,
otherwise all remote issue links are returned. Where a global ID
includes reserved URL characters these must be escaped in the request.
For example, pass `system=http://www.mycompany.com/support&id=1` as
`system%3Dhttp%3A%2F%2Fwww.mycompany.com%2Fsupport%26id%3D1`.
This operation requires [issue linking to be
active](https://confluence.atlassian.com/x/yoXKM).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: getRemoteIssueLinks
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
example: '10000'
x-showInExample: 'true'
- name: globalId
in: query
description: The global ID of the remote issue link.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/RemoteIssueLink'
example: >-
[{"id":10000,"self":"https://your-domain.atlassian.net/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":"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":"https://your-domain.atlassian.net/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
item","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/mia.gif","title":"Tested
by Mia
Krystof","link":"http://www.anothercompany.com/tester/person?accountId=5b10a2844c20165700ede21g"}}}}]
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if issue linking is disabled.
'404':
description: >-
Returned if the issue or remote issue link is not found or the user
does not have permission to view the issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue.remote-link:jira'
- 'read:status:jira'
x-atlassian-connect-scope: READ
post:
tags:
- Issue remote links
summary: Create or update remote issue link
description: >-
Creates or updates a remote issue link for an issue.
If a `globalId` is provided and a remote issue link with that global ID
is found it is updated. Any fields without values in the request are set
to null. Otherwise, the remote issue link is created.
This operation requires [issue linking to be
active](https://confluence.atlassian.com/x/yoXKM).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* and *Link issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: createOrUpdateRemoteIssueLink
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RemoteIssueLinkRequest'
example:
application:
name: My Acme Tracker
type: com.acme.tracker
globalId: 'system=http://www.mycompany.com/support&id=1'
object:
icon:
title: Support Ticket
url16x16: 'http://www.mycompany.com/support/ticket.png'
status:
icon:
link: 'http://www.mycompany.com/support?id=1&details=closed'
title: Case Closed
url16x16: 'http://www.mycompany.com/support/resolved.png'
resolved: true
summary: Customer support issue
title: TSTSUP-111
url: 'http://www.mycompany.com/support?id=1'
relationship: causes
required: true
responses:
'200':
description: Returned if the remote issue link is updated.
content:
application/json:
schema:
$ref: '#/components/schemas/RemoteIssueLinkIdentifies'
example: >-
{"id":10000,"self":"https://your-domain.atlassian.net/rest/api/issue/MKY-1/remotelink/10000"}
'201':
description: Returned if the remote issue link is created.
content:
application/json:
schema:
$ref: '#/components/schemas/RemoteIssueLinkIdentifies'
example: >-
{"id":10000,"self":"https://your-domain.atlassian.net/rest/api/issue/MKY-1/remotelink/10000"}
'400':
description: Returned if the request is invalid.
content:
application/json:
example: '{"errorMessages":[],"errors":{"title":"''title'' is required."}}'
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have permission to link issues.
'404':
description: >-
Returned if the issue is not found or the user does not have
permission to view the issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue:jira'
- 'write:issue.remote-link:jira'
- 'read:issue.remote-link:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Issue remote links
summary: Delete remote issue link by global ID
description: >-
Deletes the remote issue link from the issue using the link's global ID.
Where the global ID includes reserved URL characters these must be
escaped in the request. For example, pass
`system=http://www.mycompany.com/support&id=1` as
`system%3Dhttp%3A%2F%2Fwww.mycompany.com%2Fsupport%26id%3D1`.
This operation requires [issue linking to be
active](https://confluence.atlassian.com/x/yoXKM).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* and *Link issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is implemented, issue-level security permission to view the issue.
operationId: deleteRemoteIssueLinkByGlobalId
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
example: '10000'
x-showInExample: 'true'
- name: globalId
in: query
description: The global ID of a remote issue link.
required: true
schema:
type: string
example: 'system=http://www.mycompany.com/support&id=1'
x-showInExample: 'true'
responses:
'204':
description: Returned if the request is successful.
'400':
description: Returned if a global ID isn't provided.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have permission to link issues.
'404':
description: >-
Returned if the issue or remote issue link is not found or the user
does not have permission to view the issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:issue.remote-link:jira'
- 'write:issue:jira'
x-atlassian-connect-scope: DELETE
'/rest/api/3/issue/{issueIdOrKey}/remotelink/{linkId}':
get:
tags:
- Issue remote links
summary: Get remote issue link by ID
description: >-
Returns a remote issue link for an issue.
This operation requires [issue linking to be
active](https://confluence.atlassian.com/x/yoXKM).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: getRemoteIssueLinkById
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: linkId
in: path
description: The ID of the remote issue link.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/RemoteIssueLink'
example: >-
{"id":10000,"self":"https://your-domain.atlassian.net/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":"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"}}}}
'400':
description: >-
Returned if the link ID is invalid or the remote issue link does not
belong to the issue.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if issue linking is disabled.
'404':
description: >-
Returned if the issue or remote issue link is not found or the user
does not have permission to view the issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue.remote-link:jira'
- 'read:status:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Issue remote links
summary: Update remote issue link by ID
description: >-
Updates a remote issue link for an issue.
Note: Fields without values in the request are set to null.
This operation requires [issue linking to be
active](https://confluence.atlassian.com/x/yoXKM).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* and *Link issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: updateRemoteIssueLink
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
example: '10000'
x-showInExample: 'true'
- name: linkId
in: path
description: The ID of the remote issue link.
required: true
schema:
type: string
example: '10000'
x-showInExample: 'true'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RemoteIssueLinkRequest'
example:
application:
name: My Acme Tracker
type: com.acme.tracker
globalId: 'system=http://www.mycompany.com/support&id=1'
object:
icon:
title: Support Ticket
url16x16: 'http://www.mycompany.com/support/ticket.png'
status:
icon:
link: 'http://www.mycompany.com/support?id=1&details=closed'
title: Case Closed
url16x16: 'http://www.mycompany.com/support/resolved.png'
resolved: true
summary: Customer support issue
title: TSTSUP-111
url: 'http://www.mycompany.com/support?id=1'
relationship: causes
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: |-
Returned if:
* the link ID is invalid.
* the remote issue link does not belong to the issue.
* the request body is invalid.
content:
application/json:
example: '{"errorMessages":[],"errors":{"title":"''title'' is required."}}'
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have permission to link issues.
'404':
description: >-
Returned if the issue or remote issue link is not found or the user
does not have permission to view the issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue:jira'
- 'write:issue.remote-link:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Issue remote links
summary: Delete remote issue link by ID
description: >-
Deletes a remote issue link from an issue.
This operation requires [issue linking to be
active](https://confluence.atlassian.com/x/yoXKM).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects*, *Edit issues*, and *Link issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: deleteRemoteIssueLinkById
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
example: '10000'
x-showInExample: 'true'
- name: linkId
in: path
description: The ID of a remote issue link.
required: true
schema:
type: string
example: '10000'
x-showInExample: 'true'
responses:
'204':
description: Returned if the request is successful.
'400':
description: >-
Returned if the link ID is invalid or the remote issue link does not
belong to the issue.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have permission to link issues.
'404':
description: >-
Returned if the issue or remote issue link is not found or the user
does not have permission to view the issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:issue.remote-link:jira'
- 'write:issue:jira'
x-atlassian-connect-scope: DELETE
'/rest/api/3/issue/{issueIdOrKey}/transitions':
get:
tags:
- Issues
summary: Get transitions
description: >-
Returns either all transitions or a transition that can be performed by
the user on an issue, based on the issue's status.
Note, if a request is made for a transition that does not exist or
cannot be performed on the issue, given its status, the response will
return any empty transitions list.
This operation can be accessed anonymously.
**[Permissions](#permissions) required: A list or transition is returned
only when the user has:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
However, if the user does not have the *Transition issues* [ project
permission](https://confluence.atlassian.com/x/yodKLg) the response will
not list any transitions.
operationId: getTransitions
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
transitions in the response. This parameter accepts
`transitions.fields`, which returns information about the fields in
the transition screen for each transition. Fields hidden from the
screen are not returned. Use this information to populate the
`fields` and `update` fields in [Transition
issue](#api-rest-api-3-issue-issueIdOrKey-transitions-post).
schema:
type: string
- name: transitionId
in: query
description: The ID of the transition.
schema:
type: string
- name: skipRemoteOnlyCondition
in: query
description: >-
Whether transitions with the condition *Hide From User Condition*
are included in the response.
schema:
type: boolean
default: false
- name: includeUnavailableTransitions
in: query
description: >-
Whether details of transitions that fail a condition are included in
the response
schema:
type: boolean
default: false
- name: sortByOpsBarAndStatus
in: query
description: >-
Whether the transitions are sorted by ops-bar sequence value first
then category order (Todo, In Progress, Done) or only by ops-bar
sequence value.
schema:
type: boolean
default: false
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Transitions'
example: >-
{"transitions":[{"id":"2","name":"Close
Issue","to":{"self":"https://your-domain.atlassian.net/rest/api/3/status/10000","description":"The
issue is currently being worked
on.","iconUrl":"https://your-domain.atlassian.net/images/icons/progress.gif","name":"In
Progress","id":"10000","statusCategory":{"self":"https://your-domain.atlassian.net/rest/api/3/statuscategory/1","id":1,"key":"in-flight","colorName":"yellow","name":"In
Progress"}},"hasScreen":false,"isGlobal":false,"isInitial":false,"isAvailable":true,"isConditional":false,"fields":{"summary":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My
Multi
Select","key":"field_key","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue"],"defaultValue":"red"}}},{"id":"711","name":"QA
Review","to":{"self":"https://your-domain.atlassian.net/rest/api/3/status/5","description":"The
issue is
closed.","iconUrl":"https://your-domain.atlassian.net/images/icons/closed.gif","name":"Closed","id":"5","statusCategory":{"self":"https://your-domain.atlassian.net/rest/api/3/statuscategory/9","id":9,"key":"completed","colorName":"green"}},"hasScreen":true,"fields":{"summary":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My
Multi
Select","key":"field_key","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue"],"defaultValue":"red"},"colour":{"required":false,"schema":{"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10001},"name":"My
Multi
Select","key":"field_key","hasDefaultValue":false,"operations":["set","add"],"allowedValues":["red","blue"],"defaultValue":"red"}}}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the issue is not found or the user does not have
permission to view it.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue.transition:jira'
- 'read:status:jira'
- 'read:field-configuration:jira'
x-atlassian-connect-scope: READ
post:
tags:
- Issues
summary: Transition issue
description: >-
Performs an issue transition and, if the transition has a screen,
updates the fields from the transition screen.
sortByCategory To update the fields on the transition screen, specify
the fields in the `fields` or `update` parameters in the request body.
Get details about the fields using [ Get
transitions](#api-rest-api-3-issue-issueIdOrKey-transitions-get) with
the `transitions.fields` expand.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* and *Transition issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: doTransition
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueUpdateDetails'
example:
fields:
assignee:
name: bob
resolution:
name: Fixed
historyMetadata:
activityDescription: Complete order processing
actor:
avatarUrl: 'http://mysystem/avatar/tony.jpg'
displayName: Tony
id: tony
type: mysystem-user
url: 'http://mysystem/users/tony'
cause:
id: myevent
type: mysystem-event
description: From the order testing process
extraData:
Iteration: 10a
Step: '4'
generator:
id: mysystem-1
type: mysystem-application
type: 'myplugin:type'
transition:
id: '5'
update:
comment:
- add:
body:
content:
- content:
- text: Bug has been fixed
type: text
type: paragraph
type: doc
version: 1
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: |-
Returned if:
* no transition is specified.
* the user does not have permission to transition the issue.
* a field that isn't included on the transition screen is defined in `fields` or `update`.
* a field is specified in both `fields` and `update`.
* the request is invalid for any other reason.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the issue is not found or the user does not have
permission to view it.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue:jira'
- 'write:issue.property:jira'
x-atlassian-connect-scope: WRITE
'/rest/api/3/issue/{issueIdOrKey}/votes':
get:
tags:
- Issue votes
summary: Get votes
description: >-
Returns details about the votes on an issue.
This operation requires the **Allow users to vote on issues** option to
be *ON*. This option is set in General configuration for Jira. See
[Configuring Jira application
options](https://confluence.atlassian.com/x/uYXKM) for details.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is ini
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
Note that users with the necessary permissions for this operation but
without the *View voters and watchers* project permissions are not
returned details in the `voters` field.
operationId: getVotes
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Votes'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/issue/MKY-1/votes","votes":24,"hasVoted":true,"voters":[{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":false}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* voting is disabled.
* the user does not have permission to view the issue.
* the issue is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue.vote:jira'
- 'read:user:jira'
- 'read:application-role:jira'
- 'read:avatar:jira'
- 'read:group:jira'
x-atlassian-connect-scope: READ
post:
tags:
- Issue votes
summary: Add vote
description: >-
Adds the user's vote to an issue. This is the equivalent of the user
clicking *Vote* on an issue in Jira.
This operation requires the **Allow users to vote on issues** option to
be *ON*. This option is set in General configuration for Jira. See
[Configuring Jira application
options](https://confluence.atlassian.com/x/uYXKM) for details.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: addVote
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* voting is disabled.
* the issue is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue.vote:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Issue votes
summary: Delete vote
description: >-
Deletes a user's vote from an issue. This is the equivalent of the user
clicking *Unvote* on an issue in Jira.
This operation requires the **Allow users to vote on issues** option to
be *ON*. This option is set in General configuration for Jira. See
[Configuring Jira application
options](https://confluence.atlassian.com/x/uYXKM) for details.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: removeVote
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
responses:
'204':
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* voting is disabled.
* the user has not voted on the issue.
* the issue is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue.vote:jira'
x-atlassian-connect-scope: DELETE
'/rest/api/3/issue/{issueIdOrKey}/watchers':
get:
tags:
- Issue watchers
summary: Get issue watchers
description: >-
Returns the watchers for an issue.
This operation requires the **Allow users to watch issues** option to be
*ON*. This option is set in General configuration for Jira. See
[Configuring Jira application
options](https://confluence.atlassian.com/x/uYXKM) for details.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is ini
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* To see details of users on the watchlist other than themselves, *View voters and watchers* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
operationId: getIssueWatchers
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful
content:
application/json:
schema:
$ref: '#/components/schemas/Watchers'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/issue/EX-1/watchers","isWatching":false,"watchCount":1,"watchers":[{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the issue is not found or the user does not have
permission to view it.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue.watcher:jira'
- 'read:user:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: READ
post:
tags:
- Issue watchers
summary: Add watcher
description: >-
Adds a user as a watcher of an issue by passing the account ID of the
user. For example, `"5b10ac8d82e05b22cc7d4ef5"`. If no user is specified
the calling user is added.
This operation requires the **Allow users to watch issues** option to be
*ON*. This option is set in General configuration for Jira. See
[Configuring Jira application
options](https://confluence.atlassian.com/x/uYXKM) for details.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* To add users other than themselves to the watchlist, *Manage watcher list* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
operationId: addWatcher
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
requestBody:
description: >-
The account ID of the user. Note that username cannot be used due to
privacy changes.
content:
application/json:
schema:
type: string
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user does not have the permission to manage the
watcher list.
'404':
description: >-
Returned if the issue or the user is not found or the user does not
have permission to view the issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue.watcher:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Issue watchers
summary: Delete watcher
description: >-
Deletes a user as a watcher of an issue.
This operation requires the **Allow users to watch issues** option to be
*ON*. This option is set in General configuration for Jira. See
[Configuring Jira application
options](https://confluence.atlassian.com/x/uYXKM) for details.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* To remove users other than themselves from the watchlist, *Manage watcher list* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
operationId: removeWatcher
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: username
in: query
description: >-
This parameter is no longer available. See the [deprecation
notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/)
for details.
schema:
type: string
- name: accountId
in: query
description: >-
The account ID of the user, which uniquely identifies the user
across all Atlassian products. For example,
*5b10ac8d82e05b22cc7d4ef5*. Required.
schema:
maxLength: 128
type: string
example: 5b10ac8d82e05b22cc7d4ef5
x-showInExample: 'true'
responses:
'204':
description: Returned if the request is successful.
'400':
description: Returned if `accountId` is not supplied.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user does not have the permission to manage the
watcher list.
'404':
description: >-
Returned if the issue or the user is not found or the user does not
have permission to view the issue.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue.watcher:jira'
x-atlassian-connect-scope: DELETE
'/rest/api/3/issue/{issueIdOrKey}/worklog':
get:
tags:
- Issue worklogs
summary: Get issue worklogs
description: >-
Returns worklogs for an issue, starting from the oldest worklog or from
the worklog started on or after a date and time.
Time tracking must be enabled in Jira, otherwise this operation returns
an error. For more information, see [Configuring time
tracking](https://confluence.atlassian.com/x/qoXKM).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** Workloads are only returned
where the user has:
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
operationId: getIssueWorklog
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 5000
- name: startedAfter
in: query
description: >-
The worklog start date and time, as a UNIX timestamp in
milliseconds, after which worklogs are returned.
schema:
type: integer
format: int64
- name: startedBefore
in: query
description: >-
The worklog start date and time, as a UNIX timestamp in
milliseconds, before which worklogs are returned.
schema:
type: integer
format: int64
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
worklogs in the response. This parameter accepts`properties`, which
returns worklog properties.
schema:
type: string
default: ''
responses:
'200':
description: Returned if the request is successful
content:
application/json:
schema:
$ref: '#/components/schemas/PageOfWorklogs'
example: >-
{"startAt":0,"maxResults":1,"total":1,"worklogs":[{"self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/worklog/10000","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"updateAuthor":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"comment":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"I
did some work
here."}]}]},"updated":"2021-01-18T23:45:00.000+0000","visibility":{"type":"group","value":"jira-developers","identifier":"276f955c-63d7-42c8-9520-92d01dca0625"},"started":"2021-01-17T12:34:00.000+0000","timeSpent":"3h
20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* the issue is not found or the user does not have permission to view the issue.
* `startAt` or `maxResults` has non-numeric values.
* time tracking is disabled.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:group:jira'
- 'read:issue-worklog:jira'
- 'read:issue-worklog.property:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: READ
post:
tags:
- Issue worklogs
summary: Add worklog
description: >-
Adds a worklog to an issue.
Time tracking must be enabled in Jira, otherwise this operation returns
an error. For more information, see [Configuring time
tracking](https://confluence.atlassian.com/x/qoXKM).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* and *Work on issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: addWorklog
parameters:
- name: issueIdOrKey
in: path
description: The ID or key the issue.
required: true
schema:
type: string
- name: notifyUsers
in: query
description: Whether users watching the issue are notified by email.
schema:
type: boolean
default: true
- name: adjustEstimate
in: query
description: |-
Defines how to update the issue's time estimate, the options are:
* `new` Sets the estimate to a specific value, defined in `newEstimate`.
* `leave` Leaves the estimate unchanged.
* `manual` Reduces the estimate by amount specified in `reduceBy`.
* `auto` Reduces the estimate by the value of `timeSpent` in the worklog.
schema:
type: string
default: auto
enum:
- new
- leave
- manual
- auto
- name: newEstimate
in: query
description: >-
The value to set as the issue's remaining time estimate, as days
(\#d), hours (\#h), or minutes (\#m or \#). For example, *2d*.
Required when `adjustEstimate` is `new`.
schema:
type: string
- name: reduceBy
in: query
description: >-
The amount to reduce the issue's remaining estimate by, as days
(\#d), hours (\#h), or minutes (\#m). For example, *2d*. Required
when `adjustEstimate` is `manual`.
schema:
type: string
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
work logs in the response. This parameter accepts `properties`,
which returns worklog properties.
schema:
type: string
default: ''
- name: overrideEditableFlag
in: query
description: >-
Whether the worklog entry should be added to the issue even if the
issue is not editable, because jira.issue.editable set to false or
missing. For example, the issue is closed. Connect and Forge app
users with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) can use this
flag.
schema:
type: boolean
default: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Worklog'
example:
comment:
content:
- content:
- text: I did some work here.
type: text
type: paragraph
type: doc
version: 1
started: '2021-01-17T12:34:00.000+0000'
timeSpentSeconds: 12000
visibility:
identifier: 276f955c-63d7-42c8-9520-92d01dca0625
type: group
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Worklog'
'400':
description: |-
Returned if:
* `adjustEstimate` is set to `new` but `newEstimate` is not provided or is invalid.
* `adjustEstimate` is set to `manual` but `reduceBy` is not provided or is invalid.
* the user does not have permission to add the worklog.
* the request JSON is malformed.
'401':
description: Returned if the authentication credentials are incorrect.
'404':
description: >-
Returned if the issue is not found or the user does not have
permission to view it.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-worklog:jira'
- 'write:issue-worklog.property:jira'
- 'read:avatar:jira'
- 'read:group:jira'
- 'read:issue-worklog:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:issue-worklog.property:jira'
x-atlassian-connect-scope: WRITE
'/rest/api/3/issue/{issueIdOrKey}/worklog/{id}':
get:
tags:
- Issue worklogs
summary: Get worklog
description: >-
Returns a worklog.
Time tracking must be enabled in Jira, otherwise this operation returns
an error. For more information, see [Configuring time
tracking](https://confluence.atlassian.com/x/qoXKM).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
operationId: getWorklog
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: id
in: path
description: The ID of the worklog.
required: true
schema:
type: string
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
work logs in the response. This parameter accepts
`properties`, which returns worklog properties.
schema:
type: string
default: ''
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Worklog'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/worklog/10000","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"updateAuthor":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"comment":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"I
did some work
here."}]}]},"updated":"2021-01-18T23:45:00.000+0000","visibility":{"type":"group","value":"jira-developers","identifier":"276f955c-63d7-42c8-9520-92d01dca0625"},"started":"2021-01-17T12:34:00.000+0000","timeSpent":"3h
20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}
'401':
description: Returned if the authentication credentials are incorrect.
'404':
description: |-
Returned if:
* the issue is not found or the user does not have permission to view it.
* the worklog is not found or the user does not have permission to view it.
* time tracking is disabled.
.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:comment:jira'
- 'read:group:jira'
- 'read:issue-worklog:jira'
- 'read:issue-worklog.property:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Issue worklogs
summary: Update worklog
description: >-
Updates a worklog.
Time tracking must be enabled in Jira, otherwise this operation returns
an error. For more information, see [Configuring time
tracking](https://confluence.atlassian.com/x/qoXKM).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* *Edit all worklogs*[ project permission](https://confluence.atlassian.com/x/yodKLg) to update any worklog or *Edit own worklogs* to update worklogs created by the user.
* If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
operationId: updateWorklog
parameters:
- name: issueIdOrKey
in: path
description: The ID or key the issue.
required: true
schema:
type: string
- name: id
in: path
description: The ID of the worklog.
required: true
schema:
type: string
- name: notifyUsers
in: query
description: Whether users watching the issue are notified by email.
schema:
type: boolean
default: true
- name: adjustEstimate
in: query
description: |-
Defines how to update the issue's time estimate, the options are:
* `new` Sets the estimate to a specific value, defined in `newEstimate`.
* `leave` Leaves the estimate unchanged.
* `auto` Updates the estimate by the difference between the original and updated value of `timeSpent` or `timeSpentSeconds`.
schema:
type: string
default: auto
enum:
- new
- leave
- manual
- auto
- name: newEstimate
in: query
description: >-
The value to set as the issue's remaining time estimate, as days
(\#d), hours (\#h), or minutes (\#m or \#). For example, *2d*.
Required when `adjustEstimate` is `new`.
schema:
type: string
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
worklogs in the response. This parameter accepts `properties`, which
returns worklog properties.
schema:
type: string
default: ''
- name: overrideEditableFlag
in: query
description: >-
Whether the worklog should be added to the issue even if the issue
is not editable. For example, because the issue is closed. Connect
and Forge app users with *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) can use this
flag.
schema:
type: boolean
default: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Worklog'
example:
comment:
content:
- content:
- text: I did some work here.
type: text
type: paragraph
type: doc
version: 1
started: '2021-01-17T12:34:00.000+0000'
timeSpentSeconds: 12000
visibility:
identifier: 276f955c-63d7-42c8-9520-92d01dca0625
type: group
required: true
responses:
'200':
description: Returned if the request is successful
content:
application/json:
schema:
$ref: '#/components/schemas/Worklog'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/issue/10010/worklog/10000","author":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"updateAuthor":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"comment":{"type":"doc","version":1,"content":[{"type":"paragraph","content":[{"type":"text","text":"I
did some work
here."}]}]},"updated":"2021-01-18T23:45:00.000+0000","visibility":{"type":"group","value":"jira-developers","identifier":"276f955c-63d7-42c8-9520-92d01dca0625"},"started":"2021-01-17T12:34:00.000+0000","timeSpent":"3h
20m","timeSpentSeconds":12000,"id":"100028","issueId":"10002"}
'400':
description: |-
Returned if:
* `adjustEstimate` is set to `new` but `newEstimate` is not provided or is invalid.
* the user does not have permission to update the worklog.
* the request JSON is malformed.
'401':
description: Returned if the authentication credentials are incorrect.
'404':
description: |-
Returned if:
* the issue is not found or user does not have permission to view the issue.
* the worklog is not found or the user does not have permission to view it.
* time tracking is disabled.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:comment:jira'
- 'read:group:jira'
- 'read:issue-worklog:jira'
- 'read:issue-worklog.property:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'write:comment:jira'
- 'write:issue-worklog:jira'
- 'write:issue-worklog.property:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Issue worklogs
summary: Delete worklog
description: >-
Deletes a worklog from an issue.
Time tracking must be enabled in Jira, otherwise this operation returns
an error. For more information, see [Configuring time
tracking](https://confluence.atlassian.com/x/qoXKM).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* *Delete all worklogs*[ project permission](https://confluence.atlassian.com/x/yodKLg) to delete any worklog or *Delete own worklogs* to delete worklogs created by the user,
* If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
operationId: deleteWorklog
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: id
in: path
description: The ID of the worklog.
required: true
schema:
type: string
- name: notifyUsers
in: query
description: Whether users watching the issue are notified by email.
schema:
type: boolean
default: true
- name: adjustEstimate
in: query
description: |-
Defines how to update the issue's time estimate, the options are:
* `new` Sets the estimate to a specific value, defined in `newEstimate`.
* `leave` Leaves the estimate unchanged.
* `manual` Increases the estimate by amount specified in `increaseBy`.
* `auto` Reduces the estimate by the value of `timeSpent` in the worklog.
schema:
type: string
default: auto
enum:
- new
- leave
- manual
- auto
- name: newEstimate
in: query
description: >-
The value to set as the issue's remaining time estimate, as days
(\#d), hours (\#h), or minutes (\#m or \#). For example, *2d*.
Required when `adjustEstimate` is `new`.
schema:
type: string
- name: increaseBy
in: query
description: >-
The amount to increase the issue's remaining estimate by, as days
(\#d), hours (\#h), or minutes (\#m or \#). For example, *2d*.
Required when `adjustEstimate` is `manual`.
schema:
type: string
- name: overrideEditableFlag
in: query
description: >-
Whether the work log entry should be added to the issue even if the
issue is not editable, because jira.issue.editable set to false or
missing. For example, the issue is closed. Connect and Forge app
users with admin permission can use this flag.
schema:
type: boolean
default: false
responses:
'204':
description: Returned if the request is successful.
'400':
description: |-
Returned if:
* `adjustEstimate` is set to `new` but `newEstimate` is not provided or is invalid.
* `adjustEstimate` is set to `manual` but `reduceBy` is not provided or is invalid.
* the user does not have permission to delete the worklog.
'401':
description: Returned if the authentication credentials are incorrect.
'404':
description: |-
Returned if:
* the issue is not found or user does not have permission to view the issue.
* the worklog is not found or the user does not have permission to view it.
* time tracking is disabled.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:issue-worklog:jira'
- 'delete:issue-worklog.property:jira'
- 'write:issue.time-tracking:jira'
x-atlassian-connect-scope: DELETE
'/rest/api/3/issue/{issueIdOrKey}/worklog/{worklogId}/properties':
get:
tags:
- Issue worklog properties
summary: Get worklog property keys
description: |-
Returns the keys of all properties for a worklog.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
operationId: getWorklogPropertyKeys
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: worklogId
in: path
description: The ID of the worklog.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PropertyKeys'
example: >-
{"keys":[{"self":"https://your-domain.atlassian.net/rest/api/3/issue/EX-2/properties/issue.support","key":"issue.support"}]}
'400':
description: Returned if the worklog ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* the issue or worklog is not found.
* the user does not have permission to view the issue or worklog.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-worklog.property:jira'
- 'read:comment.property:jira'
- 'read:dashboard.property:jira'
- 'read:issue-type.property:jira'
- 'read:issue.property:jira'
- 'read:project.property:jira'
- 'read:user.property:jira'
- 'read:workflow.property:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/issue/{issueIdOrKey}/worklog/{worklogId}/properties/{propertyKey}':
get:
tags:
- Issue worklog properties
summary: Get worklog property
description: |-
Returns the value of a worklog property.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
operationId: getWorklogProperty
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: worklogId
in: path
description: The ID of the worklog.
required: true
schema:
type: string
- name: propertyKey
in: path
description: The key of the property.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/EntityProperty'
example: >-
{"key":"issue.support","value":{"system.conversation.id":"b1bf38be-5e94-4b40-a3b8-9278735ee1e6","system.support.time":"1m"}}
'400':
description: Returned if the worklog ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* the issue, worklog, or property is not found.
* the user does not have permission to view the issue or worklog.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-worklog.property:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Issue worklog properties
summary: Set worklog property
description: >-
Sets the value of a worklog property. Use this operation to store custom
data against the worklog.
The value of the request body must be a
[valid](http://tools.ietf.org/html/rfc4627), non-empty JSON blob. The
maximum length is 32768 characters.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* *Edit all worklogs*[ project permission](https://confluence.atlassian.com/x/yodKLg) to update any worklog or *Edit own worklogs* to update worklogs created by the user.
* If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
operationId: setWorklogProperty
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: worklogId
in: path
description: The ID of the worklog.
required: true
schema:
type: string
- name: propertyKey
in: path
description: The key of the issue property. The maximum length is 255 characters.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema: {}
required: true
responses:
'200':
description: Returned if the worklog property is updated.
content:
application/json:
schema: {}
'201':
description: Returned if the worklog property is created.
content:
application/json:
schema: {}
'400':
description: Returned if the worklog ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have permission to edit the worklog.
'404':
description: |-
Returned if:
* the issue or worklog is not found.
* the user does not have permission to view the issue or worklog.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-worklog.property:jira'
x-atlassian-connect-scope: WRITE
delete:
tags:
- Issue worklog properties
summary: Delete worklog property
description: |-
Deletes a worklog property.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.
operationId: deleteWorklogProperty
parameters:
- name: issueIdOrKey
in: path
description: The ID or key of the issue.
required: true
schema:
type: string
- name: worklogId
in: path
description: The ID of the worklog.
required: true
schema:
type: string
- name: propertyKey
in: path
description: The key of the property.
required: true
schema:
type: string
responses:
'204':
description: Returned if the worklog property is removed.
'400':
description: Returned if the worklog key or id is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have permission to edit the worklog.
'404':
description: |-
Returned if:
* the issue, worklog, or property is not found.
* the user does not have permission to view the issue or worklog.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:issue-worklog.property:jira'
x-atlassian-connect-scope: DELETE
/rest/api/3/issueLink:
post:
tags:
- Issue links
summary: Create issue link
description: >-
Creates a link between two issues. Use this operation to indicate a
relationship between two issues and optionally add a comment to the from
(outward) issue. To use this resource the site must have [Issue
Linking](https://confluence.atlassian.com/x/yoXKM) enabled.
This resource returns nothing on the creation of an issue link. To
obtain the ID of the issue link, use
`https://your-domain.atlassian.net/rest/api/3/issue/[linked issue
key]?fields=issuelinks`.
If the link request duplicates a link, the response indicates that the
issue link was created. If the request included a comment, the comment
is added.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse project* [project permission](https://confluence.atlassian.com/x/yodKLg) for all the projects containing the issues to be linked,
* *Link issues* [project permission](https://confluence.atlassian.com/x/yodKLg) on the project containing the from (outward) issue,
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
* If the comment has visibility restrictions, belongs to the group or has the role visibility is restricted to.
operationId: linkIssues
parameters: []
requestBody:
description: The issue link request.
content:
application/json:
schema:
$ref: '#/components/schemas/LinkIssueRequestJsonBean'
example:
comment:
body:
content:
- content:
- text: Linked related issue!
type: text
type: paragraph
type: doc
version: 1
visibility:
identifier: 276f955c-63d7-42c8-9520-92d01dca0625
type: group
value: jira-software-users
inwardIssue:
key: HSP-1
outwardIssue:
key: MKY-1
type:
name: Duplicate
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: >-
Returned if the comment is not created. The response contains an
error message indicating why the comment wasn't created. The issue
link is also not created.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* issue linking is disabled.
* the user cannot view one or both of the issues. For example, the user doesn't have *Browse project* project permission for a project containing one of the issues.
* the user does not have *link issues* project permission.
* either of the link issues are not found.
* the issue link type is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'write:comment:jira'
- 'write:issue:jira'
- 'write:issue-link:jira'
x-atlassian-connect-scope: WRITE
'/rest/api/3/issueLink/{linkId}':
get:
tags:
- Issue links
summary: Get issue link
description: |-
Returns an issue link.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Browse project* [project permission](https://confluence.atlassian.com/x/yodKLg) for all the projects containing the linked issues.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, permission to view both of the issues.
operationId: getIssueLink
parameters:
- name: linkId
in: path
description: The ID of the issue link.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueLink'
example: >-
{"id":"10001","type":{"id":"1000","name":"Duplicate","inward":"Duplicated
by","outward":"Duplicates","self":"https://your-domain.atlassian.net/rest/api/3/issueLinkType/1000"},"inwardIssue":{"id":"10004","key":"PR-3","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-3","fields":{"status":{"self":"https://your-domain.atlassian.net/rest/api/3/status/5","description":"The
issue is
closed.","iconUrl":"https://your-domain.atlassian.net/images/icons/closed.gif","name":"Closed","id":"5","statusCategory":{"self":"https://your-domain.atlassian.net/rest/api/3/statuscategory/9","id":9,"key":"completed","colorName":"green"}},"priority":{"self":"https://your-domain.atlassian.net/rest/api/3/priority/5","statusColor":"#cfcfcf","description":"Very
little
impact.","iconUrl":"https://your-domain.atlassian.net/images/icons/priorities/trivial.png","name":"Trivial","id":"2"},"issuetype":{"self":"https://your-domain.atlassian.net/rest/api/3/issueType/1","id":"1","description":"A
problem with the
software.","iconUrl":"https://your-domain.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10316&avatarType=issuetype\",","name":"Bug","subtask":false,"avatarId":10002,"entityId":"9d7dd6f7-e8b6-4247-954b-7b2c9b2a5ba2","hierarchyLevel":0,"scope":{"type":"PROJECT","project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"}}}}},"outwardIssue":{"id":"10004L","key":"PR-2","self":"https://your-domain.atlassian.net/rest/api/3/issue/PR-2","fields":{"status":{"self":"https://your-domain.atlassian.net/rest/api/3/status/10000","description":"The
issue is currently being worked
on.","iconUrl":"https://your-domain.atlassian.net/images/icons/progress.gif","name":"In
Progress","id":"10000","statusCategory":{"self":"https://your-domain.atlassian.net/rest/api/3/statuscategory/1","id":1,"key":"in-flight","colorName":"yellow","name":"In
Progress"}},"priority":{"self":"https://your-domain.atlassian.net/rest/api/3/priority/3","statusColor":"#009900","description":"Major
loss of
function.","iconUrl":"https://your-domain.atlassian.net/images/icons/priorities/major.png","name":"Major","id":"1"},"issuetype":{"self":"https://your-domain.atlassian.net/rest/api/3/issueType/3","id":"3","description":"A
task that needs to be
done.","iconUrl":"https://your-domain.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10299&avatarType=issuetype\",","name":"Task","subtask":false,"avatarId":1,"hierarchyLevel":0}}}}
'400':
description: Returned if the issue link ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* issue linking is disabled.
* the issue link is not found.
* the user doesn't have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
- 'read:issue-link-type:jira'
- 'read:issue:jira'
- 'read:issue-type:jira'
- 'read:priority:jira'
- 'read:status:jira'
- 'read:avatar:jira'
- 'read:issue.time-tracking:jira'
- 'read:project-category:jira'
- 'read:project:jira'
- 'read:user:jira'
x-atlassian-connect-scope: READ
delete:
tags:
- Issue links
summary: Delete issue link
description: |-
Deletes an issue link.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* Browse project [project permission](https://confluence.atlassian.com/x/yodKLg) for all the projects containing the issues in the link.
* *Link issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for at least one of the projects containing issues in the link.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, permission to view both of the issues.
operationId: deleteIssueLink
parameters:
- name: linkId
in: path
description: The ID of the issue link.
required: true
schema:
type: string
responses:
'200':
description: 200 response
'204':
description: Returned if the request is successful.
'400':
description: Returned if the issue link ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* issue linking is disabled.
* the issue link is not found.
* the user doesn't have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'write:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'write:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:issue-link:jira'
x-atlassian-connect-scope: DELETE
/rest/api/3/issueLinkType:
get:
tags:
- Issue link types
summary: Get issue link types
description: >-
Returns a list of all issue link types.
To use this operation, the site must have [issue
linking](https://confluence.atlassian.com/x/yoXKM) enabled.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** *Browse projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for a project in
the site.
operationId: getIssueLinkTypes
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueLinkTypes'
example: >-
{"issueLinkTypes":[{"id":"1000","name":"Duplicate","inward":"Duplicated
by","outward":"Duplicates","self":"https://your-domain.atlassian.net/rest/api/3/issueLinkType/1000"},{"id":"1010","name":"Blocks","inward":"Blocked
by","outward":"Blocks","self":"https://your-domain.atlassian.net/rest/api/3/issueLinkType/1010"}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: Returned if issue linking is disabled.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-link-type:jira'
x-atlassian-connect-scope: READ
post:
tags:
- Issue link types
summary: Create issue link type
description: >-
Creates an issue link type. Use this operation to create descriptions of
the reasons why issues are linked. The issue link type consists of a
name and descriptions for a link's inward and outward relationships.
To use this operation, the site must have [issue
linking](https://confluence.atlassian.com/x/yoXKM) enabled.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: createIssueLinkType
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueLinkType'
example:
inward: Duplicated by
name: Duplicate
outward: Duplicates
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueLinkType'
example: >-
{"id":"1000","name":"Duplicate","inward":"Duplicated
by","outward":"Duplicates","self":"https://your-domain.atlassian.net/rest/api/3/issueLinkType/1000"}
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* issue linking is disabled.
* the issue link type name is in use.
* the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-link-type:jira'
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issueLinkType/{issueLinkTypeId}':
get:
tags:
- Issue link types
summary: Get issue link type
description: >-
Returns an issue link type.
To use this operation, the site must have [issue
linking](https://confluence.atlassian.com/x/yoXKM) enabled.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** *Browse projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for a project in
the site.
operationId: getIssueLinkType
parameters:
- name: issueLinkTypeId
in: path
description: The ID of the issue link type.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueLinkType'
example: >-
{"id":"1000","name":"Duplicate","inward":"Duplicated
by","outward":"Duplicates","self":"https://your-domain.atlassian.net/rest/api/3/issueLinkType/1000"}
'400':
description: Returned if the issue link type ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* issue linking is disabled.
* the issue link type is not found.
* the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-link-type:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Issue link types
summary: Update issue link type
description: >-
Updates an issue link type.
To use this operation, the site must have [issue
linking](https://confluence.atlassian.com/x/yoXKM) enabled.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateIssueLinkType
parameters:
- name: issueLinkTypeId
in: path
description: The ID of the issue link type.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueLinkType'
example:
inward: Duplicated by
name: Duplicate
outward: Duplicates
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueLinkType'
example: >-
{"id":"1000","name":"Duplicate","inward":"Duplicated
by","outward":"Duplicates","self":"https://your-domain.atlassian.net/rest/api/3/issueLinkType/1000"}
'400':
description: Returned if the issue link type ID or the request body are invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* issue linking is disabled.
* the issue link type is not found.
* the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-link-type:jira'
- 'write:issue-link-type:jira'
x-atlassian-connect-scope: ADMIN
delete:
tags:
- Issue link types
summary: Delete issue link type
description: >-
Deletes an issue link type.
To use this operation, the site must have [issue
linking](https://confluence.atlassian.com/x/yoXKM) enabled.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: deleteIssueLinkType
parameters:
- name: issueLinkTypeId
in: path
description: The ID of the issue link type.
required: true
schema:
type: string
responses:
'204':
description: Returned if the request is successful.
'400':
description: Returned if the issue link type ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* issue linking is disabled.
* the issue link type is not found.
* the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:issue-link-type:jira'
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuesecurityschemes:
get:
tags:
- Issue security schemes
summary: Get issue security schemes
description: >-
Returns all [issue security
schemes](https://confluence.atlassian.com/x/J4lKLg).
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getIssueSecuritySchemes
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/SecuritySchemes'
example: >-
{"issueSecuritySchemes":[{"self":"https://your-domain.atlassian.net/rest/api/3/issuesecurityschemes/10000","id":10000,"name":"Default
Issue Security Scheme","description":"Description for the
default issue security scheme","defaultSecurityLevelId":10021}]}
'401':
description: Returned if the authentication credentials are incorrect.
'403':
description: >-
Returned if the user does not have permission to administer issue
security schemes.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-project'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-project'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-security-level:jira'
- 'read:issue-security-scheme:jira'
x-atlassian-connect-scope: ADMIN
post:
tags:
- Issue security schemes
summary: Create issue security scheme
description: >-
Creates a security scheme with security scheme levels and levels'
members. You can create up to 100 security scheme levels and security
scheme levels' members per request.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: createIssueSecurityScheme
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateIssueSecuritySchemeDetails'
example:
description: Newly created issue security scheme
levels:
- description: Newly created level
isDefault: true
members:
- parameter: administrators
type: group
name: New level
name: New security scheme
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/SecuritySchemeId'
example: '{"id":"10001"}'
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["The length of the description must not exceed
4,000 characters."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuesecurityschemes/level:
get:
tags:
- Issue security schemes
summary: Get issue security levels
description: >-
Returns a [paginated](#pagination) list of issue security levels.
Only issue security levels in the context of classic projects are
returned.
Filtering using IDs is inclusive: if you specify both security scheme
IDs and level IDs, the result will include both specified issue security
levels and all issue security levels from the specified schemes.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getSecurityLevels
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: string
default: '0'
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: string
default: '50'
- name: id
in: query
description: >-
The list of issue security scheme level IDs. To include multiple
issue security levels, separate IDs with an ampersand:
`id=10000&id=10001`.
schema:
uniqueItems: true
type: array
items:
type: string
- name: schemeId
in: query
description: >-
The list of issue security scheme IDs. To include multiple issue
security schemes, separate IDs with an ampersand:
`schemeId=10000&schemeId=10001`.
schema:
uniqueItems: true
type: array
items:
type: string
- name: onlyDefault
in: query
description: >-
When set to true, returns multiple default levels for each security
scheme containing a default. If you provide scheme and level IDs not
associated with the default, returns an empty page. The default
value is false.
schema:
type: boolean
default: false
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanSecurityLevel'
example: >-
{"maxResults":50,"startAt":0,"total":1,"isLast":true,"values":[{"self":"https://your-domain.atlassian.net/rest/api/3/issuesecurityscheme/level?id=10021","id":"10021","description":"Only
the reporter and internal staff can see this
issue.","name":"Reporter
Only","isDefault":true,"issueSecuritySchemeId":"10001"}]}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["-1000 is not a valid value. id must be zero
or a positive integer."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-security-level:jira'
- 'read:issue-security-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuesecurityschemes/level/default:
put:
tags:
- Issue security schemes
summary: Set default issue security levels
description: >-
Sets default issue security levels for schemes.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: setDefaultLevels
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetDefaultLevelsRequest'
example:
defaultValues:
- defaultLevelId: '20000'
issueSecuritySchemeId: '10000'
- defaultLevelId: '30000'
issueSecuritySchemeId: '12000'
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["some-wrong-string is not a valid value. The
issue security scheme ID must be a positive
integer."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
'404':
description: Returned if the issue resolution isn't found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["Issue security scheme with ID 4364564 not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuesecurityschemes/level/member:
get:
tags:
- Issue security schemes
summary: Get issue security level members
description: >-
Returns a [paginated](#pagination) list of issue security level members.
Only issue security level members in the context of classic projects are
returned.
Filtering using parameters is inclusive: if you specify both security
scheme IDs and level IDs, the result will include all issue security
level members from the specified schemes and levels.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getSecurityLevelMembers
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: string
default: '0'
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: string
default: '50'
- name: id
in: query
description: >-
The list of issue security level member IDs. To include multiple
issue security level members separate IDs with an ampersand:
`id=10000&id=10001`.
schema:
uniqueItems: true
type: array
items:
type: string
- name: schemeId
in: query
description: >-
The list of issue security scheme IDs. To include multiple issue
security schemes separate IDs with an ampersand:
`schemeId=10000&schemeId=10001`.
schema:
uniqueItems: true
type: array
items:
type: string
- name: levelId
in: query
description: >-
The list of issue security level IDs. To include multiple issue
security levels separate IDs with an ampersand:
`levelId=10000&levelId=10001`.
schema:
uniqueItems: true
type: array
items:
type: string
- name: expand
in: query
description: >-
Use expand to include additional information in the response. This
parameter accepts a comma-separated list. Expand options include:
* `all` Returns all expandable information
* `field` Returns information about the custom field granted the permission
* `group` Returns information about the group that is granted the permission
* `projectRole` Returns information about the project role granted the permission
* `user` Returns information about the user who is granted the permission
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanSecurityLevelMember'
example: >-
{"maxResults":100,"startAt":0,"total":3,"isLast":true,"values":[{"id":"10000","issueSecurityLevelId":"20010","issueSecuritySchemeId":"10010","holder":{"type":"group","expand":"group"}}]}
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-security-level:jira'
- 'read:issue-security-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuesecurityschemes/project:
get:
tags:
- Issue security schemes
summary: Get projects using issue security schemes
description: >-
Returns a [paginated](#pagination) mapping of projects that are using
security schemes. You can provide either one or multiple security scheme
IDs or project IDs to filter by. If you don't provide any, this will
return a list of all mappings. Only issue security schemes in the
context of classic projects are supported. **[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: searchProjectsUsingSecuritySchemes
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: string
default: '0'
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: string
default: '50'
- name: issueSecuritySchemeId
in: query
description: The list of security scheme IDs to be filtered out.
schema:
uniqueItems: true
type: array
items:
type: string
- name: projectId
in: query
description: The list of project IDs to be filtered out.
schema:
uniqueItems: true
type: array
items:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: >-
#/components/schemas/PageBeanIssueSecuritySchemeToProjectMapping
example: '{"issueSecuritySchemeId":"10000","projectId":"10000"}'
'400':
description: >-
Returned if the search criteria is invalid.If you specify the
project ID parameter
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuesecurityschemes/search:
get:
tags:
- Issue security schemes
summary: Search issue security schemes
description: >-
Returns a [paginated](#pagination) list of issue security schemes.
If you specify the project ID parameter, the result will contain issue
security schemes and related project IDs you filter by. Use \{@link
IssueSecuritySchemeResource\#searchProjectsUsingSecuritySchemes(String,
String, Set, Set)\} to obtain all projects related to scheme.
Only issue security schemes in the context of classic projects are
returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: searchSecuritySchemes
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: string
default: '0'
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: string
default: '50'
- name: id
in: query
description: >-
The list of issue security scheme IDs. To include multiple issue
security scheme IDs, separate IDs with an ampersand:
`id=10000&id=10001`.
schema:
uniqueItems: true
type: array
items:
type: string
- name: projectId
in: query
description: >-
The list of project IDs. To include multiple project IDs, separate
IDs with an ampersand: `projectId=10000&projectId=10001`.
schema:
uniqueItems: true
type: array
items:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanSecuritySchemeWithProjects'
example: >-
{"id":10000,"self":"https://your-domain.atlassian.net/rest/api/3/issuesecurityscheme/10000","name":"Default
scheme","description":"Default scheme
description","defaultLevel":10001,"projectIds":[10002]}
'400':
description: Returned if the request is invalid.
content:
application/json:
example: >-
{"errorMessages":["-1000 is not a valid value. id must be zero
or a positive integer."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-security-level:jira'
- 'read:issue-security-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuesecurityschemes/{id}':
get:
tags:
- Issue security schemes
summary: Get issue security scheme
description: |-
Returns an issue security scheme along with its security levels.
**[Permissions](#permissions) required:**
* *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
* *Administer Projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for a project that uses the requested issue security scheme.
operationId: getIssueSecurityScheme
parameters:
- name: id
in: path
description: >-
The ID of the issue security scheme. Use the [Get issue security
schemes](#api-rest-api-3-issuesecurityschemes-get) operation to get
a list of issue security scheme IDs.
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityScheme'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/issuesecurityschemes/10000","id":10000,"name":"Default
Issue Security Scheme","description":"Description for the
default issue security
scheme","defaultSecurityLevelId":10021,"levels":[{"self":"https://your-domain.atlassian.net/rest/api/3/securitylevel/10021","id":"10021","description":"Only
the reporter and internal staff can see this
issue.","name":"Reporter Only"}]}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user does not have the administrator permission and
the scheme is not used in any project where the user has
administrative permission.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-project'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-project'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-security-level:jira'
- 'read:issue-security-scheme:jira'
x-atlassian-connect-scope: ADMIN
put:
tags:
- Issue security schemes
summary: Update issue security scheme
description: >-
Updates the issue security scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateIssueSecurityScheme
parameters:
- name: id
in: path
description: The ID of the issue security scheme.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateIssueSecuritySchemeRequestBean'
example:
description: My issue security scheme description
name: My issue security scheme name
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["The length of the description must not exceed
4,000 characters."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
'404':
description: Returned if the issue security scheme isn't found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["Issue security scheme with ID 10000 not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuesecurityschemes/{issueSecuritySchemeId}/members':
get:
tags:
- Issue security level
summary: Get issue security level members
description: >-
Returns issue security level members.
Only issue security level members in context of classic projects are
returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getIssueSecurityLevelMembers
parameters:
- name: issueSecuritySchemeId
in: path
description: >-
The ID of the issue security scheme. Use the [Get issue security
schemes](#api-rest-api-3-issuesecurityschemes-get) operation to get
a list of issue security scheme IDs.
required: true
schema:
type: integer
format: int64
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: issueSecurityLevelId
in: query
description: >-
The list of issue security level IDs. To include multiple issue
security levels separate IDs with ampersand:
`issueSecurityLevelId=10000&issueSecurityLevelId=10001`.
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
- name: expand
in: query
description: >-
Use expand to include additional information in the response. This
parameter accepts a comma-separated list. Expand options include:
* `all` Returns all expandable information.
* `field` Returns information about the custom field granted the permission.
* `group` Returns information about the group that is granted the permission.
* `projectRole` Returns information about the project role granted the permission.
* `user` Returns information about the user who is granted the permission.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanIssueSecurityLevelMember'
example: >-
{"maxResults":100,"startAt":0,"total":3,"isLast":true,"values":[{"id":10000,"issueSecurityLevelId":10020,"holder":{"type":"user","user":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","emailAddress":"mia@example.com","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":true,"timeZone":"Australia/Sydney"},"expand":"user"}},{"id":10001,"issueSecurityLevelId":10020,"holder":{"type":"group","parameter":"jira-core-users","value":"9c559b11-6c5d-4f96-992c-a746cabab28b","expand":"group"}},{"id":10002,"issueSecurityLevelId":10021,"holder":{"type":"assignee"}}]}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if no issue security level members are found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
- 'read:issue-security-level:jira'
- 'read:project-role:jira'
- 'read:user:jira'
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuesecurityschemes/{schemeId}':
delete:
tags:
- Issue security schemes
summary: Delete issue security scheme
description: >-
Deletes an issue security scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: deleteSecurityScheme
parameters:
- name: schemeId
in: path
description: The ID of the issue security scheme.
required: true
schema:
type: string
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
"You can't delete an issue security scheme if any projects are
associated with it."
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errors":{},"errorMessages":["You are not authorized to perform
this action. Administrator privileges are
required."],"httpStatusCode":{"empty":false,"present":true}}
'404':
description: Returned if the issue security scheme isn't found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errors":{},"errorMessages":["Issue security scheme with ID
10000 not
found."],"httpStatusCode":{"empty":false,"present":true}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuesecurityschemes/{schemeId}/level':
put:
tags:
- Issue security schemes
summary: Add issue security levels
description: >-
Adds levels and levels' members to the issue security scheme. You can
add up to 100 levels per request.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: addSecurityLevel
parameters:
- name: schemeId
in: path
description: The ID of the issue security scheme.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddSecuritySchemeLevelsRequestBean'
example:
levels:
- description: First Level Description
isDefault: true
members:
- type: reporter
- parameter: jira-administrators
type: group
name: First Level
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["some-wrong-string is not a valid value. The
issue security scheme ID must be a positive
integer."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errors":{},"errorMessages":["You are not authorized to perform
this action. Administrator privileges are
required."],"httpStatusCode":{"empty":false,"present":true}}
'404':
description: Returned if the security scheme isn't found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errors":{},"errorMessages":["Issue security scheme with ID
10000 not
found."],"httpStatusCode":{"empty":false,"present":true}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuesecurityschemes/{schemeId}/level/{levelId}':
put:
tags:
- Issue security schemes
summary: Update issue security level
description: >-
Updates the issue security level.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateSecurityLevel
parameters:
- name: schemeId
in: path
description: The ID of the issue security scheme level belongs to.
required: true
schema:
type: string
- name: levelId
in: path
description: The ID of the issue security level to update.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateIssueSecurityLevelDetails'
example:
description: New level description
name: New level name
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request isn't valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["The length of the description must not exceed
4,000 characters."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
'404':
description: Returned if the issue security level isn't found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["Issue security scheme with ID 10000 not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-experimental: true
x-atlassian-connect-scope: ADMIN
delete:
tags:
- Issue security schemes
summary: Remove issue security level
description: >-
Deletes an issue security level.
This operation is [asynchronous](#async). Follow the `location` link in
the response to determine the status of the task and use [Get
task](#api-rest-api-3-task-taskId-get) to obtain subsequent updates.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: removeLevel
parameters:
- name: schemeId
in: path
description: The ID of the issue security scheme.
required: true
schema:
type: string
- name: levelId
in: path
description: The ID of the issue security level to remove.
required: true
schema:
type: string
- name: replaceWith
in: query
description: >-
The ID of the issue security level that will replace the currently
selected level.
schema:
type: string
responses:
'303':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskProgressBeanObject'
'400':
description: Returned if the request isn't valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
"You can't delete an issue security scheme if any projects are
associated with it."
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errors":{},"errorMessages":["You are not authorized to perform
this action. Administrator privileges are
required."],"httpStatusCode":{"empty":false,"present":true}}
'404':
description: Returned if the issue security level isn't found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errors":{},"errorMessages":["Issue security scheme with ID
10000 not
found."],"httpStatusCode":{"empty":false,"present":true}}
'409':
description: >-
Returned if a task to remove the issue security level is already
running.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuesecurityschemes/{schemeId}/level/{levelId}/member':
put:
tags:
- Issue security schemes
summary: Add issue security level members
description: >-
Adds members to the issue security level. You can add up to 100 members
per request.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: addSecurityLevelMembers
parameters:
- name: schemeId
in: path
description: The ID of the issue security scheme.
required: true
schema:
type: string
- name: levelId
in: path
description: The ID of the issue security level.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SecuritySchemeMembersRequest'
example:
members:
- type: reporter
- parameter: jira-administrators
type: group
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["some-wrong-string is not a valid value. The
issue security scheme ID must be a positive
integer."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errors":{},"errorMessages":["You are not authorized to perform
this action. Administrator privileges are
required."],"httpStatusCode":{"empty":false,"present":true}}
'404':
description: Returned if the security scheme isn't found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errors":{},"errorMessages":["Issue security scheme with ID
10000 not
found."],"httpStatusCode":{"empty":false,"present":true}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuesecurityschemes/{schemeId}/level/{levelId}/member/{memberId}':
delete:
tags:
- Issue security schemes
summary: Remove member from issue security level
description: >-
Removes an issue security level member from an issue security scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: removeMemberFromSecurityLevel
parameters:
- name: schemeId
in: path
description: The ID of the issue security scheme.
required: true
schema:
type: string
- name: levelId
in: path
description: The ID of the issue security level.
required: true
schema:
type: string
- name: memberId
in: path
description: The ID of the issue security level member to be removed.
required: true
schema:
type: string
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errors":{},"errorMessages":["You are not authorized to perform
this action. Administrator privileges are
required."],"httpStatusCode":{"empty":false,"present":true}}
'404':
description: Returned if the security scheme isn't found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errors":{},"errorMessages":["Issue security scheme with ID
10000 not
found."],"httpStatusCode":{"empty":false,"present":true}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuetype:
get:
tags:
- Issue types
summary: Get all issue types for user
description: >-
Returns all issue types.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** Issue types are only returned
as follows:
* if the user has the *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg), all issue types are returned.
* if the user has the *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for one or more projects, the issue types associated with the projects the user has permission to browse are returned.
operationId: getIssueAllTypes
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IssueTypeDetails'
example: >-
[{"self":"https://your-domain.atlassian.net/rest/api/3/issueType/3","id":"3","description":"A
task that needs to be
done.","iconUrl":"https://your-domain.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10299&avatarType=issuetype\",","name":"Task","subtask":false,"avatarId":1,"hierarchyLevel":0},{"self":"https://your-domain.atlassian.net/rest/api/3/issueType/1","id":"1","description":"A
problem with the
software.","iconUrl":"https://your-domain.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10316&avatarType=issuetype\",","name":"Bug","subtask":false,"avatarId":10002,"entityId":"9d7dd6f7-e8b6-4247-954b-7b2c9b2a5ba2","hierarchyLevel":0,"scope":{"type":"PROJECT","project":{"id":"10000","key":"KEY","name":"Next
Gen Project"}}}]
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-type:jira'
- 'read:avatar:jira'
- 'read:project-category:jira'
- 'read:project:jira'
x-atlassian-connect-scope: READ
post:
tags:
- Issue types
summary: Create issue type
description: >-
Creates an issue type and adds it to the default issue type scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: createIssueType
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeCreateBean'
example:
description: description
name: name
type: standard
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeDetails'
'400':
description: |-
Returned if the request is invalid because:
* no content is sent.
* the issue type name exceeds 60 characters.
* a subtask issue type is requested on an instance where subtasks are disabled.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'409':
description: Returned if the issue type name is in use.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type:jira'
- 'read:avatar:jira'
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project:jira'
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuetype/project:
get:
tags:
- Issue types
summary: Get issue types for project
description: >-
Returns issue types for a project.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** *Browse projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) in the relevant
project or *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getIssueTypesForProject
parameters:
- name: projectId
in: query
description: The ID of the project.
required: true
schema:
type: integer
format: int64
- name: level
in: query
description: |-
The level of the issue type to filter by. Use:
* `-1` for Subtask.
* `0` for Base.
* `1` for Epic.
schema:
type: integer
format: int32
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IssueTypeDetails'
example: >-
[{"self":"https://your-domain.atlassian.net/rest/api/3/issueType/1","id":"1","description":"A
problem with the
software.","iconUrl":"https://your-domain.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10316&avatarType=issuetype\",","name":"Bug","subtask":false,"avatarId":10002,"entityId":"9d7dd6f7-e8b6-4247-954b-7b2c9b2a5ba2","hierarchyLevel":0,"scope":{"type":"PROJECT","project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"}}},{"self":"https://your-domain.atlassian.net/rest/api/3/issueType/3","id":"3","description":"A
task that needs to be
done.","iconUrl":"https://your-domain.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10299&avatarType=issuetype\",","name":"Task","subtask":false,"avatarId":1,"hierarchyLevel":0,"scope":{"type":"PROJECT","project":{"id":"10000","key":"KEY","name":"Next
Gen Project"}}}]
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* the project is not found.
* the user does not have the necessary permission.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-type:jira'
- 'read:avatar:jira'
- 'read:project-category:jira'
- 'read:project:jira'
x-experimental: true
x-atlassian-connect-scope: READ
'/rest/api/3/issuetype/{id}':
get:
tags:
- Issue types
summary: Get issue type
description: >-
Returns an issue type.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** *Browse projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) in a project the
issue type is associated with or *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getIssueType
parameters:
- name: id
in: path
description: The ID of the issue type.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeDetails'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/issueType/3","id":"3","description":"A
task that needs to be
done.","iconUrl":"https://your-domain.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10299&avatarType=issuetype\",","name":"Task","subtask":false,"avatarId":1,"hierarchyLevel":0}
'400':
description: Returned if the issue type ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* the issue type is not found.
* the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-type:jira'
- 'read:avatar:jira'
- 'read:project-category:jira'
- 'read:project:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Issue types
summary: Update issue type
description: >-
Updates the issue type.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateIssueType
parameters:
- name: id
in: path
description: The ID of the issue type.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeUpdateBean'
example:
avatarId: 1
description: description
name: name
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeDetails'
'400':
description: |-
Returned if the request is invalid because:
* no content is sent.
* the issue type name exceeds 60 characters.
* the avatar is not associated with this issue type.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the issue type is not found.
'409':
description: Returned if the issue type name is in use.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type:jira'
- 'read:avatar:jira'
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project:jira'
x-atlassian-connect-scope: ADMIN
delete:
tags:
- Issue types
summary: Delete issue type
description: >-
Deletes the issue type. If the issue type is in use, all uses are
updated with the alternative issue type (`alternativeIssueTypeId`). A
list of alternative issue types are obtained from the [Get alternative
issue types](#api-rest-api-3-issuetype-id-alternatives-get) resource.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: deleteIssueType
parameters:
- name: id
in: path
description: The ID of the issue type.
required: true
schema:
type: string
- name: alternativeIssueTypeId
in: query
description: The ID of the replacement issue type.
schema:
type: string
responses:
'204':
description: Returned if the request is successful.
'400':
description: >-
Returned if any issues cannot be updated with the alternative issue
type.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: |-
Returned if:
* the issue type is in use and an alternative issue type is not specified.
* the issue type or alternative issue type is not found.
'409':
description: |-
Returned if the issue type is in use and:
* also specified as the alternative issue type.
* is a *standard* issue type and the alternative issue type is a *subtask*.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:issue-type:jira'
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuetype/{id}/alternatives':
get:
tags:
- Issue types
summary: Get alternative issue types
description: >-
Returns a list of issue types that can be used to replace the issue
type. The alternative issue types are those assigned to the same
workflow scheme, field configuration scheme, and screen scheme.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: getAlternativeIssueTypes
parameters:
- name: id
in: path
description: The ID of the issue type.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IssueTypeDetails'
example: >-
[{"self":"https://your-domain.atlassian.net/rest/api/3/issueType/3","id":"3","description":"A
task that needs to be
done.","iconUrl":"https://your-domain.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10299&avatarType=issuetype\",","name":"Task","subtask":false,"avatarId":1,"hierarchyLevel":0},{"self":"https://your-domain.atlassian.net/rest/api/3/issueType/1","id":"1","description":"A
problem with the
software.","iconUrl":"https://your-domain.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10316&avatarType=issuetype\",","name":"Bug","subtask":false,"avatarId":10002,"entityId":"9d7dd6f7-e8b6-4247-954b-7b2c9b2a5ba2","hierarchyLevel":0,"scope":{"type":"PROJECT","project":{"id":"10000","key":"KEY","name":"Next
Gen Project"}}}]
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: |-
Returned if:
* the issue type is not found.
* the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-type:jira'
- 'read:project-category:jira'
- 'read:project:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/issuetype/{id}/avatar2':
post:
tags:
- Issue types
summary: Load issue type avatar
description: >-
Loads an avatar for the issue type.
Specify the avatar's local file location in the body of the request.
Also, include the following headers:
* `X-Atlassian-Token: no-check` To prevent XSRF protection blocking the request, for more information see [Special Headers](#special-request-headers).
* `Content-Type: image/image type` Valid image types are JPEG, GIF, or PNG.
For example:
`curl --request POST \ --user email@example.com:<api_token> \ --header
'X-Atlassian-Token: no-check' \ --header 'Content-Type: image/<
image_type>' \ --data-binary "<@/path/to/file/with/your/avatar>" \ --url
'https://your-domain.atlassian.net/rest/api/3/issuetype/{issueTypeId}'This`
The avatar is cropped to a square. If no crop parameters are specified,
the square originates at the top left of the image. The length of the
square's sides is set to the smaller of the height or width of the
image.
The cropped image is then used to create avatars of 16x16, 24x24, 32x32,
and 48x48 in size.
After creating the avatar, use [ Update issue
type](#api-rest-api-3-issuetype-id-put) to set it as the issue type's
displayed avatar.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: createIssueTypeAvatar
parameters:
- name: id
in: path
description: The ID of the issue type.
required: true
schema:
type: string
- name: x
in: query
description: The X coordinate of the top-left corner of the crop region.
schema:
type: integer
format: int32
default: 0
- name: 'y'
in: query
description: The Y coordinate of the top-left corner of the crop region.
schema:
type: integer
format: int32
default: 0
- name: size
in: query
description: The length of each side of the crop region.
required: true
schema:
type: integer
format: int32
requestBody:
content:
'*/*':
schema: {}
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Avatar'
example: >-
{"id":"1000","isSystemAvatar":true,"isSelected":false,"isDeletable":false,"urls":{"16x16":"/secure/useravatar?size=xsmall&avatarId=10040&avatarType=project","24x24":"/secure/useravatar?size=small&avatarId=10040&avatarType=project","32x32":"/secure/useravatar?size=medium&avatarId=10040&avatarType=project","48x48":"/secure/useravatar?avatarId=10040&avatarType=project"}}
'400':
description: |-
Returned if:
* an image isn't included in the request.
* the image type is unsupported.
* the crop parameters extend the crop area beyond the edge of the image.
* `cropSize` is missing.
* the issue type ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the issue type is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:avatar:jira'
- 'write:issue-type:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuetype/{issueTypeId}/properties':
get:
tags:
- Issue type properties
summary: Get issue type property keys
description: >-
Returns all the [issue type
property](https://developer.atlassian.com/cloud/jira/platform/storing-data-without-a-database/#a-id-jira-entity-properties-a-jira-entity-properties)
keys of the issue type.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg) to get the property keys of any issue type.
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) to get the property keys of any issue types associated with the projects the user has permission to browse.
operationId: getIssueTypePropertyKeys
parameters:
- name: issueTypeId
in: path
description: The ID of the issue type.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PropertyKeys'
example: >-
{"keys":[{"self":"https://your-domain.atlassian.net/rest/api/3/issue/EX-2/properties/issue.support","key":"issue.support"}]}
'400':
description: Returned if the issue type ID is invalid.
'404':
description: |-
Returned if:
* the issue type is not found.
* the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-type.property:jira'
- 'read:comment.property:jira'
- 'read:dashboard.property:jira'
- 'read:issue-worklog.property:jira'
- 'read:issue.property:jira'
- 'read:project.property:jira'
- 'read:user.property:jira'
- 'read:workflow.property:jira'
x-atlassian-connect-scope: READ
'/rest/api/3/issuetype/{issueTypeId}/properties/{propertyKey}':
get:
tags:
- Issue type properties
summary: Get issue type property
description: >-
Returns the key and value of the [issue type
property](https://developer.atlassian.com/cloud/jira/platform/storing-data-without-a-database/#a-id-jira-entity-properties-a-jira-entity-properties).
This operation can be accessed anonymously.
**[Permissions](#permissions) required:**
* *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg) to get the details of any issue type.
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) to get the details of any issue types associated with the projects the user has permission to browse.
operationId: getIssueTypeProperty
parameters:
- name: issueTypeId
in: path
description: The ID of the issue type.
required: true
schema:
type: string
- name: propertyKey
in: path
description: >-
The key of the property. Use [Get issue type property
keys](#api-rest-api-3-issuetype-issueTypeId-properties-get) to get a
list of all issue type property keys.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/EntityProperty'
example: >-
{"key":"issue.support","value":{"system.conversation.id":"b1bf38be-5e94-4b40-a3b8-9278735ee1e6","system.support.time":"1m"}}
'400':
description: Returned if the issue type ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the issue type or property is not found or the user does
not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-type.property:jira'
x-atlassian-connect-scope: READ
put:
tags:
- Issue type properties
summary: Set issue type property
description: >-
Creates or updates the value of the [issue type
property](https://developer.atlassian.com/cloud/jira/platform/storing-data-without-a-database/#a-id-jira-entity-properties-a-jira-entity-properties).
Use this resource to store and update data against an issue type.
The value of the request body must be a
[valid](http://tools.ietf.org/html/rfc4627), non-empty JSON blob. The
maximum length is 32768 characters.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: setIssueTypeProperty
parameters:
- name: issueTypeId
in: path
description: The ID of the issue type.
required: true
schema:
type: string
- name: propertyKey
in: path
description: >-
The key of the issue type property. The maximum length is 255
characters.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema: {}
example:
number: 5
string: string-value
required: true
responses:
'200':
description: Returned if the issue type property is updated.
content:
application/json:
schema: {}
'201':
description: Returned if the issue type property is created.
content:
application/json:
schema: {}
'400':
description: |-
Returned if:
* the issue type ID is invalid.
* a property value is not provided.
* the property value JSON content is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user does not have permission to modify the issue
type.
'404':
description: |-
Returned if:
* the issue type is not found.
* the user does not have the permission view the issue type.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type.property:jira'
x-atlassian-connect-scope: ADMIN
delete:
tags:
- Issue type properties
summary: Delete issue type property
description: >-
Deletes the [issue type
property](https://developer.atlassian.com/cloud/jira/platform/storing-data-without-a-database/#a-id-jira-entity-properties-a-jira-entity-properties).
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: deleteIssueTypeProperty
parameters:
- name: issueTypeId
in: path
description: The ID of the issue type.
required: true
schema:
type: string
- name: propertyKey
in: path
description: >-
The key of the property. Use [Get issue type property
keys](#api-rest-api-3-issuetype-issueTypeId-properties-get) to get a
list of all issue type property keys.
required: true
schema:
type: string
responses:
'204':
description: Returned if the issue type property is deleted.
'400':
description: Returned if the issue type ID is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the issue type or property is not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:issue-type.property:jira'
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuetypescheme:
get:
tags:
- Issue type schemes
summary: Get all issue type schemes
description: >-
Returns a [paginated](#pagination) list of issue type schemes.
Only issue type schemes used in classic projects are returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getAllIssueTypeSchemes
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: id
in: query
description: >-
The list of issue type schemes IDs. To include multiple IDs, provide
an ampersand-separated list. For example, `id=10000&id=10001`.
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
- name: orderBy
in: query
description: |-
[Order](#ordering) the results by a field:
* `name` Sorts by issue type scheme name.
* `id` Sorts by issue type scheme ID.
schema:
type: string
default: id
enum:
- name
- '-name'
- +name
- id
- '-id'
- +id
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts a comma-separated list. Expand
options include:
* `projects` For each issue type schemes, returns information about the projects the issue type scheme is assigned to.
* `issueTypes` For each issue type schemes, returns information about the issueTypes the issue type scheme have.
schema:
type: string
default: ''
- name: queryString
in: query
description: >-
String used to perform a case-insensitive partial match with issue
type scheme name.
schema:
type: string
default: ''
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanIssueTypeScheme'
example: >-
{"maxResults":100,"startAt":0,"total":3,"isLast":true,"values":[{"id":"10000","name":"Default
Issue Type Scheme","description":"Default issue type scheme is
the list of global issue types. All newly created issue types
will automatically be added to this
scheme.","defaultIssueTypeId":"10003","isDefault":true},{"id":"10001","name":"SUP:
Kanban Issue Type Scheme","description":"A collection of issue
types suited to use in a kanban style
project.","projects":{"maxResults":100,"startAt":0,"total":1,"isLast":true,"values":[{"self":"project/EX","id":"10000","key":"EX","name":"Example","projectTypeKey":"ProjectTypeKey{key='software'}","simplified":false,"avatarUrls":{"48x48":"secure/projectavatar?size=large&pid=10000","24x24":"secure/projectavatar?size=small&pid=10000","16x16":"secure/projectavatar?size=xsmall&pid=10000","32x32":"secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"id":"10000","description":"Project
category description","name":"A project
category"}}]}},{"id":"10002","name":"HR: Scrum issue type
scheme","description":"","defaultIssueTypeId":"10004","issueTypes":{"maxResults":100,"startAt":0,"total":1,"isLast":true,"values":[{"id":"1000L","description":"Improvement
Issue
Type","iconUrl":"www.example.com","name":"Improvements","subtask":true,"hierarchyLevel":-1}]}}]}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-type-scheme:jira'
x-atlassian-connect-scope: ADMIN
post:
tags:
- Issue type schemes
summary: Create issue type scheme
description: >-
Creates an issue type scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: createIssueTypeScheme
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeSchemeDetails'
example:
defaultIssueTypeId: '10002'
description: >-
A collection of issue types suited to use in a kanban style
project.
issueTypeIds:
- '10001'
- '10002'
- '10003'
name: Kanban Issue Type Scheme
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeSchemeID'
example: '{"issueTypeSchemeId":"10010"}'
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The default issue type ID has to be present
in issue type IDs list."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access issue
type schemes."],"errors":{}}
'409':
description: Returned if the scheme name is used by another scheme.
content:
application/json:
example: >-
{"errorMessages":["The name is used by another
scheme."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuetypescheme/mapping:
get:
tags:
- Issue type schemes
summary: Get issue type scheme items
description: >-
Returns a [paginated](#pagination) list of issue type scheme items.
Only issue type scheme items used in classic projects are returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getIssueTypeSchemesMapping
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: issueTypeSchemeId
in: query
description: >-
The list of issue type scheme IDs. To include multiple IDs, provide
an ampersand-separated list. For example,
`issueTypeSchemeId=10000&issueTypeSchemeId=10001`.
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanIssueTypeSchemeMapping'
example: >-
{"maxResults":100,"startAt":0,"total":4,"isLast":true,"values":[{"issueTypeSchemeId":"10000","issueTypeId":"10000"},{"issueTypeSchemeId":"10000","issueTypeId":"10001"},{"issueTypeSchemeId":"10000","issueTypeId":"10002"},{"issueTypeSchemeId":"10001","issueTypeId":"10000"}]}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-type-scheme:jira'
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuetypescheme/project:
get:
tags:
- Issue type schemes
summary: Get issue type schemes for projects
description: >-
Returns a [paginated](#pagination) list of issue type schemes and, for
each issue type scheme, a list of the projects that use it.
Only issue type schemes used in classic projects are returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getIssueTypeSchemeForProjects
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: projectId
in: query
description: >-
The list of project IDs. To include multiple project IDs, provide an
ampersand-separated list. For example,
`projectId=10000&projectId=10001`.
required: true
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanIssueTypeSchemeProjects'
example: >-
{"maxResults":100,"startAt":0,"total":3,"isLast":true,"values":[{"issueTypeScheme":{"id":"10000","name":"Default
Issue Type Scheme","description":"Default issue type scheme is
the list of global issue types. All newly created issue types
will automatically be added to this
scheme.","defaultIssueTypeId":"10003","isDefault":true},"projectIds":["10000","10001"]},{"issueTypeScheme":{"id":"10001","name":"SUP:
Kanban Issue Type Scheme","description":"A collection of issue
types suited to use in a kanban style
project.","projects":{"maxResults":100,"startAt":0,"total":1,"isLast":true,"values":[{"self":"project/EX","id":"10000","key":"EX","name":"Example","projectTypeKey":"ProjectTypeKey{key='software'}","simplified":false,"avatarUrls":{"48x48":"secure/projectavatar?size=large&pid=10000","24x24":"secure/projectavatar?size=small&pid=10000","16x16":"secure/projectavatar?size=xsmall&pid=10000","32x32":"secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"id":"10000","description":"Project
category description","name":"A project
category"}}]}},"projectIds":["10002"]},{"issueTypeScheme":{"id":"10002","name":"HR:
Scrum issue type
scheme","description":"","defaultIssueTypeId":"10004","issueTypes":{"maxResults":100,"startAt":0,"total":1,"isLast":true,"values":[{"id":"1000L","description":"Improvement
Issue
Type","iconUrl":"www.example.com","name":"Improvements","subtask":true,"hierarchyLevel":-1}]}},"projectIds":["10003","10004","10005"]}]}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-type-scheme:jira'
x-atlassian-connect-scope: ADMIN
put:
tags:
- Issue type schemes
summary: Assign issue type scheme to project
description: >-
Assigns an issue type scheme to a project.
If any issues in the project are assigned issue types not present in the
new scheme, the operation will fail. To complete the assignment those
issues must be updated to use issue types in the new scheme.
Issue type schemes can only be assigned to classic projects.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: assignIssueTypeSchemeToProject
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeSchemeProjectAssociation'
example:
issueTypeSchemeId: '10000'
projectId: '10000'
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["This issue type scheme can't be assigned to
the project. This is because some issues in this project use
issue types not present in the scheme. Before assigning the
scheme to the project, update the issue types on these issues:
7"],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access issue
type schemes."],"errors":{}}
'404':
description: Returned if the issue type scheme or the project is not found.
content:
application/json:
example: >-
{"errorMessages":["The issue type scheme was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type-scheme:jira'
- 'write:project:jira'
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuetypescheme/{issueTypeSchemeId}':
put:
tags:
- Issue type schemes
summary: Update issue type scheme
description: >-
Updates an issue type scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateIssueTypeScheme
parameters:
- name: issueTypeSchemeId
in: path
description: The ID of the issue type scheme.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeSchemeUpdateDetails'
example:
defaultIssueTypeId: '10002'
description: >-
A collection of issue types suited to use in a kanban style
project.
name: Kanban Issue Type Scheme
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The default issue type has to be one of the
issue types of the scheme."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access issue
type schemes."],"errors":{}}
'404':
description: Returned if the issue type scheme is not found.
content:
application/json:
example: >-
{"errorMessages":["The issue type scheme was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
delete:
tags:
- Issue type schemes
summary: Delete issue type scheme
description: >-
Deletes an issue type scheme.
Only issue type schemes used in classic projects can be deleted.
Any projects assigned to the scheme are reassigned to the default issue
type scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: deleteIssueTypeScheme
parameters:
- name: issueTypeSchemeId
in: path
description: The ID of the issue type scheme.
required: true
schema:
type: integer
format: int64
responses:
'204':
description: Returned if the issue type scheme is deleted.
content:
application/json:
schema: {}
'400':
description: Returned if the request is to delete the default issue type scheme.
content:
application/json:
example: >-
{"errorMessages":["The default issue type scheme can't be
removed."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access issue
type schemes."],"errors":{}}
'404':
description: Returned if the issue type scheme is not found.
content:
application/json:
example: >-
{"errorMessages":["The issue type scheme was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:issue-type-scheme:jira'
- 'write:project:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuetypescheme/{issueTypeSchemeId}/issuetype':
put:
tags:
- Issue type schemes
summary: Add issue types to issue type scheme
description: >-
Adds issue types to an issue type scheme.
The added issue types are appended to the issue types list.
If any of the issue types exist in the issue type scheme, the operation
fails and no issue types are added.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: addIssueTypesToIssueTypeScheme
parameters:
- name: issueTypeSchemeId
in: path
description: The ID of the issue type scheme.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeIds'
example:
issueTypeIds:
- '10000'
- '10002'
- '10003'
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["These issue types were not added because they
are already present in the issue type scheme: 10002,
10003"],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access issue
type schemes."],"errors":{}}
'404':
description: Returned if the issue type or the issue type scheme is not found.
content:
application/json:
example: >-
{"errorMessages":["These issue types were not found: 10000,
10002"],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuetypescheme/{issueTypeSchemeId}/issuetype/move':
put:
tags:
- Issue type schemes
summary: Change order of issue types
description: >-
Changes the order of issue types in an issue type scheme.
The request body parameters must meet the following requirements:
* all of the issue types must belong to the issue type scheme.
* either `after` or `position` must be provided.
* the issue type in `after` must not be in the issue type list.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: reorderIssueTypesInIssueTypeScheme
parameters:
- name: issueTypeSchemeId
in: path
description: The ID of the issue type scheme.
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderOfIssueTypes'
example:
after: '10008'
issueTypeIds:
- '10001'
- '10004'
- '10002'
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The issue type scheme does not include some
of the specified issue types. Issue type IDs missing from the
scheme are: 10007, 10008"],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access issue
type schemes."],"errors":{}}
'404':
description: Returned if the issue type scheme is not found.
content:
application/json:
example: >-
{"errorMessages":["The issue type scheme was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuetypescheme/{issueTypeSchemeId}/issuetype/{issueTypeId}':
delete:
tags:
- Issue type schemes
summary: Remove issue type from issue type scheme
description: >-
Removes an issue type from an issue type scheme.
This operation cannot remove:
* any issue type used by issues.
* any issue types from the default issue type scheme.
* the last standard issue type from an issue type scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: removeIssueTypeFromIssueTypeScheme
parameters:
- name: issueTypeSchemeId
in: path
description: The ID of the issue type scheme.
required: true
schema:
type: integer
format: int64
- name: issueTypeId
in: path
description: The ID of the issue type.
required: true
schema:
type: integer
format: int64
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["Can't remove the last standard issue type
from the issue type scheme."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access issue
type schemes."],"errors":{}}
'404':
description: >-
Returned if the issue type scheme is missing or the issue type is
not found in the issue type scheme.
content:
application/json:
example: >-
{"errorMessages":["The issue type was not found in the issue
type scheme."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuetypescreenscheme:
get:
tags:
- Issue type screen schemes
summary: Get issue type screen schemes
description: >-
Returns a [paginated](#pagination) list of issue type screen schemes.
Only issue type screen schemes used in classic projects are returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getIssueTypeScreenSchemes
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: id
in: query
description: >-
The list of issue type screen scheme IDs. To include multiple IDs,
provide an ampersand-separated list. For example,
`id=10000&id=10001`.
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
- name: queryString
in: query
description: >-
String used to perform a case-insensitive partial match with issue
type screen scheme name.
schema:
type: string
default: ''
- name: orderBy
in: query
description: |-
[Order](#ordering) the results by a field:
* `name` Sorts by issue type screen scheme name.
* `id` Sorts by issue type screen scheme ID.
schema:
type: string
default: id
enum:
- name
- '-name'
- +name
- id
- '-id'
- +id
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts `projects` that, for each issue
type screen schemes, returns information about the projects the
issue type screen scheme is assigned to.
schema:
type: string
default: ''
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanIssueTypeScreenScheme'
example: >-
{"maxResults":100,"startAt":0,"total":2,"isLast":true,"values":[{"id":"1","name":"Default
Issue Type Screen Scheme","description":"The default issue type
screen scheme"},{"id":"10000","name":"Office issue type screen
scheme","description":"Managing office
projects","projects":{"maxResults":100,"startAt":0,"total":1,"isLast":true,"values":[{"self":"project/EX","id":"10000","key":"EX","name":"Example","projectTypeKey":"ProjectTypeKey{key='software'}","simplified":false,"avatarUrls":{"48x48":"secure/projectavatar?size=large&pid=10000","24x24":"secure/projectavatar?size=small&pid=10000","16x16":"secure/projectavatar?size=xsmall&pid=10000","32x32":"secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"id":"10000","description":"Project
category description","name":"A project category"}}]}}]}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-type-screen-scheme:jira'
x-atlassian-connect-scope: ADMIN
post:
tags:
- Issue type screen schemes
summary: Create issue type screen scheme
description: >-
Creates an issue type screen scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: createIssueTypeScreenScheme
parameters: []
requestBody:
description: An issue type screen scheme bean.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeScreenSchemeDetails'
example:
issueTypeMappings:
- issueTypeId: default
screenSchemeId: '10001'
- issueTypeId: '10001'
screenSchemeId: '10002'
- issueTypeId: '10002'
screenSchemeId: '10002'
name: Scrum issue type screen scheme
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeScreenSchemeId'
example: '{"id":"10001"}'
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["One or more issue type IDs are repeated, an
issue type ID can only be specified once."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access issue
type screen schemes."],"errors":{}}
'404':
description: Returned if the issue type or screen scheme is not found.
content:
application/json:
example: >-
{"errorMessages":["One or more issue type IDs were not
found."],"errors":{}}
'409':
description: >-
Returned if the issue type is a sub-task, but sub-tasks are disabled
in Jira settings.
content:
application/json:
example: >-
{"errorMessages":["Sub-tasks are disabled in Jira. At least one
of the issue types is a sub-task."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type-screen-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuetypescreenscheme/mapping:
get:
tags:
- Issue type screen schemes
summary: Get issue type screen scheme items
description: >-
Returns a [paginated](#pagination) list of issue type screen scheme
items.
Only issue type screen schemes used in classic projects are returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getIssueTypeScreenSchemeMappings
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: issueTypeScreenSchemeId
in: query
description: >-
The list of issue type screen scheme IDs. To include multiple issue
type screen schemes, separate IDs with ampersand:
`issueTypeScreenSchemeId=10000&issueTypeScreenSchemeId=10001`.
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanIssueTypeScreenSchemeItem'
example: >-
{"maxResults":100,"startAt":0,"total":4,"isLast":true,"values":[{"issueTypeScreenSchemeId":"10020","issueTypeId":"10000","screenSchemeId":"10010"},{"issueTypeScreenSchemeId":"10021","issueTypeId":"10001","screenSchemeId":"10010"},{"issueTypeScreenSchemeId":"10022","issueTypeId":"10002","screenSchemeId":"10010"},{"issueTypeScreenSchemeId":"10023","issueTypeId":"default","screenSchemeId":"10011"}]}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-type-screen-scheme:jira'
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuetypescreenscheme/project:
get:
tags:
- Issue type screen schemes
summary: Get issue type screen schemes for projects
description: >-
Returns a [paginated](#pagination) list of issue type screen schemes
and, for each issue type screen scheme, a list of the projects that use
it.
Only issue type screen schemes used in classic projects are returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getIssueTypeScreenSchemeProjectAssociations
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: projectId
in: query
description: >-
The list of project IDs. To include multiple projects, separate IDs
with ampersand: `projectId=10000&projectId=10001`.
required: true
schema:
uniqueItems: true
type: array
items:
type: integer
format: int64
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanIssueTypeScreenSchemesProjects'
example: >-
{"maxResults":100,"startAt":0,"total":1,"isLast":true,"values":[{"issueTypeScreenScheme":{"id":"1","name":"Default
Issue Type Screen Scheme","description":"The default issue type
screen scheme"},"projectIds":["10000","10001"]}]}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-type-screen-scheme:jira'
x-atlassian-connect-scope: ADMIN
put:
tags:
- Issue type screen schemes
summary: Assign issue type screen scheme to project
description: >-
Assigns an issue type screen scheme to a project.
Issue type screen schemes can only be assigned to classic projects.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: assignIssueTypeScreenSchemeToProject
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeScreenSchemeProjectAssociation'
example:
issueTypeScreenSchemeId: '10001'
projectId: '10002'
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: |-
Returned if:
* project is not found.
* issue type screen scheme is not found.
* the project is not a classic project.
content:
application/json:
example: >-
{"errorMessages":["Only classic projects can have issue type
screen schemes assigned."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access issue
type screen schemes."],"errors":{}}
'404':
description: Returned if the issue type screen scheme or the project are missing.
content:
application/json:
example: >-
{"errorMessages":["The issue type screen scheme was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type-screen-scheme:jira'
- 'write:project:jira'
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuetypescreenscheme/{issueTypeScreenSchemeId}':
put:
tags:
- Issue type screen schemes
summary: Update issue type screen scheme
description: >-
Updates an issue type screen scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateIssueTypeScreenScheme
parameters:
- name: issueTypeScreenSchemeId
in: path
description: The ID of the issue type screen scheme.
required: true
schema:
type: string
requestBody:
description: The issue type screen scheme update details.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeScreenSchemeUpdateDetails'
example:
description: Screens for scrum issue types.
name: Scrum scheme
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The issue type screen scheme name is in
use."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access issue
type screen schemes."],"errors":{}}
'404':
description: Returned if the issue type screen scheme is not found.
content:
application/json:
example: >-
{"errorMessages":["The issue type screen scheme was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type-screen-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
delete:
tags:
- Issue type screen schemes
summary: Delete issue type screen scheme
description: >-
Deletes an issue type screen scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: deleteIssueTypeScreenScheme
parameters:
- name: issueTypeScreenSchemeId
in: path
description: The ID of the issue type screen scheme.
required: true
schema:
type: string
responses:
'204':
description: Returned if the issue type screen scheme is deleted.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The issue type screen scheme cannot be
deleted because it is assigned to one or more
projects."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
'404':
description: Returned if the issue type screen scheme is not found.
content:
application/json:
example: >-
{"errorMessages":["The issue type screen scheme was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:issue-type-screen-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuetypescreenscheme/{issueTypeScreenSchemeId}/mapping':
put:
tags:
- Issue type screen schemes
summary: Append mappings to issue type screen scheme
description: >-
Appends issue type to screen scheme mappings to an issue type screen
scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: appendMappingsForIssueTypeScreenScheme
parameters:
- name: issueTypeScreenSchemeId
in: path
description: The ID of the issue type screen scheme.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeScreenSchemeMappingDetails'
example:
issueTypeMappings:
- issueTypeId: '10000'
screenSchemeId: '10001'
- issueTypeId: '10001'
screenSchemeId: '10002'
- issueTypeId: '10002'
screenSchemeId: '10002'
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["A default mapping cannot be
added."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
'404':
description: >-
Returned if the issue type screen scheme, issue type, or screen
scheme is not found.
content:
application/json:
example: >-
{"errorMessages":["The issue type screen scheme was not
found."],"errors":{}}
'409':
description: >-
Returned if the issue type is a sub-task, but sub-tasks are disabled
in Jira settings.
content:
application/json:
example: >-
{"errorMessages":["Sub-tasks are disabled in Jira. At least one
of the issue types is a sub-task."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type-screen-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuetypescreenscheme/{issueTypeScreenSchemeId}/mapping/default':
put:
tags:
- Issue type screen schemes
summary: Update issue type screen scheme default screen scheme
description: >-
Updates the default screen scheme of an issue type screen scheme. The
default screen scheme is used for all unmapped issue types.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: updateDefaultScreenScheme
parameters:
- name: issueTypeScreenSchemeId
in: path
description: The ID of the issue type screen scheme.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDefaultScreenScheme'
example:
screenSchemeId: '10010'
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The screenSchemeId has to be
provided."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access issue
type screen schemes."],"errors":{}}
'404':
description: >-
Returned if the issue type screen scheme or the screen screen is not
found, or the screen scheme isn't used in classic projects.
content:
application/json:
example: >-
{"errorMessages":["The issue type screen scheme was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type-screen-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuetypescreenscheme/{issueTypeScreenSchemeId}/mapping/remove':
post:
tags:
- Issue type screen schemes
summary: Remove mappings from issue type screen scheme
description: >-
Removes issue type to screen scheme mappings from an issue type screen
scheme.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: removeMappingsFromIssueTypeScreenScheme
parameters:
- name: issueTypeScreenSchemeId
in: path
description: The ID of the issue type screen scheme.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssueTypeIds'
example:
issueTypeIds:
- '10000'
- '10001'
- '10004'
required: true
responses:
'204':
description: >-
Returned if the screen scheme mappings are removed from the issue
type screen scheme.
content:
application/json:
schema: {}
'400':
description: Returned if the request is not valid.
content:
application/json:
example: >-
{"errorMessages":["The issueTypeIds must not contain
duplicates."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access issue
type screen schemes."],"errors":{}}
'404':
description: >-
Returned if the issue type screen scheme or one or more issue type
mappings are not found.
content:
application/json:
example: >-
{"errorMessages":["The issue type screen scheme was not
found."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:issue-type-screen-scheme:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/issuetypescreenscheme/{issueTypeScreenSchemeId}/project':
get:
tags:
- Issue type screen schemes
summary: Get issue type screen scheme projects
description: >-
Returns a [paginated](#pagination) list of projects associated with an
issue type screen scheme.
Only company-managed projects associated with an issue type screen
scheme are returned.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getProjectsForIssueTypeScreenScheme
parameters:
- name: issueTypeScreenSchemeId
in: path
description: The ID of the issue type screen scheme.
required: true
schema:
type: integer
format: int64
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 50
- name: query
in: query
schema:
type: string
default: ''
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanProjectDetails'
example: >-
{"maxResults":100,"startAt":0,"total":1,"isLast":true,"values":[{"self":"project/EX","id":"10000","key":"EX","name":"Example","projectTypeKey":"ProjectTypeKey{key='software'}","simplified":false,"avatarUrls":{"48x48":"secure/projectavatar?size=large&pid=10000","24x24":"secure/projectavatar?size=small&pid=10000","16x16":"secure/projectavatar?size=xsmall&pid=10000","32x32":"secure/projectavatar?size=medium&pid=10000"},"projectCategory":{"id":"10000","description":"Project
category description","name":"A project category"}}]}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:project:jira'
- 'read:avatar:jira'
- 'read:project-category:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/jql/autocompletedata:
get:
tags:
- JQL
summary: Get field reference data (GET)
description: >-
Returns reference data for JQL searches. This is a downloadable version
of the documentation provided in [Advanced searching - fields
reference](https://confluence.atlassian.com/x/gwORLQ) and [Advanced
searching - functions
reference](https://confluence.atlassian.com/x/hgORLQ), along with a list
of JQL-reserved words. Use this information to assist with the
programmatic creation of JQL queries or the validation of queries built
in a custom query builder.
To filter visible field details by project or collapse non-unique fields
by field type then [Get field reference data
(POST)](#api-rest-api-3-jql-autocompletedata-post) can be used.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: getAutoComplete
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/JQLReferenceData'
example: >-
{"visibleFieldNames":[{"value":"summary","displayName":"summary","orderable":"true","searchable":"true","operators":["~","!~","is","is
not"],"types":["java.lang.String"]},{"value":"Sprint","displayName":"Sprint
-
cf[10880]","orderable":"true","searchable":"true","auto":"true","cfid":"cf[10880]","operators":["=","!=","in","not
in","is","is
not"],"types":["com.atlassian.greenhopper.service.sprint.Sprint"]}],"visibleFunctionNames":[{"value":"standardIssueTypes()","displayName":"standardIssueTypes()","isList":"true","types":["com.atlassian.jira.issue.issuetype.IssueType"]}],"jqlReservedWords":["empty","and","or","in","distinct"]}
'401':
description: Returned if the authentication credentials are incorrect.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
x-atlassian-connect-scope: READ
post:
tags:
- JQL
summary: Get field reference data (POST)
description: >-
Returns reference data for JQL searches. This is a downloadable version
of the documentation provided in [Advanced searching - fields
reference](https://confluence.atlassian.com/x/gwORLQ) and [Advanced
searching - functions
reference](https://confluence.atlassian.com/x/hgORLQ), along with a list
of JQL-reserved words. Use this information to assist with the
programmatic creation of JQL queries or the validation of queries built
in a custom query builder.
This operation can filter the custom fields returned by project. Invalid
project IDs in `projectIds` are ignored. System fields are always
returned.
It can also return the collapsed field for custom fields. Collapsed
fields enable searches to be performed across all fields with the same
name and of the same field type. For example, the collapsed field
`Component - Component[Dropdown]` enables dropdown fields `Component -
cf[10061]` and `Component - cf[10062]` to be searched simultaneously.
**[Permissions](#permissions) required:** None.
operationId: getAutoCompletePost
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchAutoCompleteFilter'
example:
includeCollapsedFields: true
projectIds:
- 10000
- 10001
- 10002
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/JQLReferenceData'
example: >-
{"visibleFieldNames":[{"value":"summary","displayName":"summary","orderable":"true","searchable":"true","operators":["~","!~","is","is
not"],"types":["java.lang.String"]},{"value":"cf[10061]","displayName":"Component
-
cf[10061]","orderable":"true","auto":"true","cfid":"cf[10061]","operators":["=","!=","in","not
in","is","is
not"],"types":["com.atlassian.jira.issue.customfields.option.Option"]},{"value":"cf[10062]","displayName":"Component
-
cf[10062]","orderable":"true","auto":"true","cfid":"cf[10062]","operators":["=","!=","in","not
in","is","is
not"],"types":["com.atlassian.jira.issue.customfields.option.Option"]},{"value":"\"Component[Dropdown]\"","displayName":"Component
-
Component[Dropdown]","searchable":"true","auto":"true","operators":["=","!=","in","not
in","is","is
not"],"types":["com.atlassian.jira.issue.customfields.option.Option"]}],"visibleFunctionNames":[{"value":"standardIssueTypes()","displayName":"standardIssueTypes()","isList":"true","types":["com.atlassian.jira.issue.issuetype.IssueType"]}],"jqlReservedWords":["empty","and","or","in","distinct"]}
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
x-atlassian-connect-scope: READ
/rest/api/3/jql/autocompletedata/suggestions:
get:
tags:
- JQL
summary: Get field auto complete suggestions
description: |-
Returns the JQL search auto complete suggestions for a field.
Suggestions can be obtained by providing:
* `fieldName` to get a list of all values for the field.
* `fieldName` and `fieldValue` to get a list of values containing the text in `fieldValue`.
* `fieldName` and `predicateName` to get a list of all predicate values for the field.
* `fieldName`, `predicateName`, and `predicateValue` to get a list of predicate values containing the text in `predicateValue`.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: getFieldAutoCompleteForQueryString
parameters:
- name: fieldName
in: query
description: The name of the field.
schema:
type: string
example: reporter
x-showInExample: 'true'
- name: fieldValue
in: query
description: The partial field item name entered by the user.
schema:
type: string
- name: predicateName
in: query
description: >-
The name of the [ CHANGED operator
predicate](https://confluence.atlassian.com/x/hQORLQ#Advancedsearching-operatorsreference-CHANGEDCHANGED)
for which the suggestions are generated. The valid predicate
operators are *by*, *from*, and *to*.
schema:
type: string
- name: predicateValue
in: query
description: The partial predicate item name entered by the user.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/AutoCompleteSuggestions'
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)"}]}
'400':
description: Returned if an invalid combination of parameters is passed.
'401':
description: Returned if the authentication credentials are incorrect.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-details:jira'
x-atlassian-connect-scope: READ
/rest/api/3/jql/function/computation:
get:
summary: Get precomputation
description: ''
operationId: getPrecomputations
parameters:
- name: functionKey
in: query
schema:
type: array
items:
type: string
- name: startAt
in: query
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
schema:
type: integer
format: int32
default: 5000
- name: orderBy
in: query
schema:
type: string
- name: filter
in: query
schema:
type: string
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanJqlFunctionPrecomputationBean'
deprecated: false
security:
- basicAuth: []
- OAuth2: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes: []
- state: Beta
scheme: OAuth2
scopes: []
x-experimental: true
x-atlassian-connect-scope: READ
post:
summary: Update precomputations
description: ''
operationId: updatePrecomputations
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JqlFunctionPrecomputationUpdateRequestBean'
required: true
responses:
'200':
description: 200 response
content:
application/json:
schema: {}
deprecated: false
security:
- basicAuth: []
- OAuth2: []
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes: []
- state: Beta
scheme: OAuth2
scopes: []
x-experimental: true
x-atlassian-connect-scope: READ
/rest/api/3/jql/match:
post:
tags:
- Issue search
summary: Check issues against JQL
description: >-
Checks whether one or more issues would be returned by one or more JQL
queries.
**[Permissions](#permissions) required:** None, however, issues are only
matched against JQL queries where the user has:
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project that the issue is in.
* If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue.
operationId: matchIssues
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IssuesAndJQLQueries'
example:
issueIds:
- 10001
- 1000
- 10042
jqls:
- project = FOO
- issuetype = Bug
- 'summary ~ "some text" AND project in (FOO, BAR)'
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/IssueMatches'
example: >-
{"matches":[{"matchedIssues":[10000,10004],"errors":[]},{"matchedIssues":[100134,10025,10236],"errors":[]},{"matchedIssues":[],"errors":[]},{"matchedIssues":[],"errors":["Invalid
JQL: broken = value"]}]}
'400':
description: >-
Returned if `jqls` exceeds the maximum number of JQL queries or
`issueIds` exceeds the maximum number of issue IDs.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:issue-details:jira'
x-atlassian-connect-scope: READ
/rest/api/3/jql/parse:
post:
tags:
- JQL
summary: Parse JQL query
description: |-
Parses and validates JQL queries.
Validation is performed in context of the current user.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: parseJqlQueries
parameters:
- name: validation
in: query
description: >-
How to validate the JQL query and treat the validation results.
Validation options include:
* `strict` Returns all errors. If validation fails, the query structure is not returned.
* `warn` Returns all errors. If validation fails but the JQL query is correctly formed, the query structure is returned.
* `none` No validation is performed. If JQL query is correctly formed, the query structure is returned.
schema:
type: string
default: strict
enum:
- strict
- warn
- none
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JqlQueriesToParse'
example:
queries:
- >-
summary ~ test AND (labels in (urgent, blocker) OR
lastCommentedBy = currentUser()) AND status CHANGED AFTER
startOfMonth(-1M) ORDER BY updated DESC
- >-
issue.property["spaces here"].value in ("Service requests",
Incidents)
- invalid query
- summary = test
- summary in test
- project = INVALID
- universe = 42
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/ParsedJqlQueries'
example: >-
{"queries":[{"query":"summary ~ test AND (labels in (urgent,
blocker) OR lastCommentedBy = currentUser()) AND status CHANGED
AFTER -5d ORDER BY updated
DESC","structure":{"where":{"clauses":[{"field":{"name":"summary","encodedName":"summary"},"operator":"~","operand":{"value":"test","encodedValue":"test"}},{"clauses":[{"field":{"name":"labels","encodedName":"labels"},"operator":"in","operand":{"values":[{"value":"urgent","encodedValue":"urgent"},{"value":"blocker","encodedValue":"blocker"}],"encodedOperand":"urgent,
blocker)"}},{"field":{"name":"lastCommentedBy","encodedName":"lastCommentedBy","property":[{"entity":"issue","key":"propertyKey","path":"path.in.property","type":"user"}]},"operator":"=","operand":{"function":"currentUser","arguments":[],"encodedOperand":"currentUser()"}}],"operator":"or"},{"field":{"name":"status","encodedName":"status"},"operator":"changed","predicates":[{"operator":"after","operand":{"function":"startOfMonth","arguments":["-1M"],"encodedOperand":"startOfMonth(-1M)"}}]}],"operator":"and"},"orderBy":{"fields":[{"field":{"name":"updated","encodedName":"updated"},"direction":"desc"}]}}},{"query":"issue.property[\"spaces
here\"].value in (\"Service requests\",
Incidents)","structure":{"where":{"field":{"name":"issue.property[spaces
here].value","encodedName":"issue.property[\"spaces
here\"].value","property":[{"entity":"issue","key":"spaces
here","path":"value"}]},"operator":"in","operand":{"values":[{"value":"Service
requests","encodedValue":"\"Service
requests\""},{"value":"Incidents","encodedValue":"Incidents"}],"encodedOperand":"(\"Service
requests\", Incidents)"}}}},{"query":"invalid
query","errors":["Error in the JQL Query: Expecting operator but
got 'query'. The valid operators are '=', '!=', '<', '>', '<=',
'>=', '~', '!~', 'IN', 'NOT IN', 'IS' and 'IS NOT'. (line 1,
character 9)"]},{"query":"summary = test","errors":["The
operator '=' is not supported by the 'summary'
field."]},{"query":"summary in test","errors":["Operator 'in'
does not support the non-list value '\"test\"' for field
'summary'."]},{"query":"project = INVALID","errors":["The value
'INVALID' does not exist for the field
'project'."]},{"query":"universe = 42","errors":["Field
'universe' does not exist or you do not have permission to view
it."]}]}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
- 'validate:jql:jira'
- 'read:jql:jira'
x-experimental: true
x-atlassian-connect-scope: READ
/rest/api/3/jql/pdcleaner:
post:
tags:
- JQL
summary: Convert user identifiers to account IDs in JQL queries
description: >-
Converts one or more JQL queries with user identifiers (username or user
key) to equivalent JQL queries with account IDs.
You may wish to use this operation if your system stores JQL queries and
you want to make them GDPR-compliant. For more information about
GDPR-related changes, see the [migration
guide](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/).
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: migrateQueries
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JQLPersonalDataMigrationRequest'
example:
queryStrings:
- assignee = mia
- >-
issuetype = Bug AND assignee in (mia) AND reporter in (alana)
order by lastViewed DESC
required: true
responses:
'200':
description: >-
Returned if the request is successful. Note that the JQL queries are
returned in the same order that they were passed.
content:
application/json:
schema:
$ref: '#/components/schemas/ConvertedJQLQueries'
example: >-
{"queryStrings":["issuetype = Bug AND assignee in (abcde-12345)
AND reporter in (abc551-c4e99) order by lastViewed
DESC"],"queriesWithUnknownUsers":[{"originalQuery":"assignee =
mia","convertedQuery":"assignee = unknown"}]}
'400':
description: >-
Returned if at least one of the queries cannot be converted. For
example, the JQL has invalid operators or invalid keywords, or the
users in the query cannot be found.
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-user'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-user'
- state: Beta
scheme: OAuth2
scopes:
- 'read:user:jira'
- 'read:jql:jira'
- 'validate:jql:jira'
x-atlassian-connect-scope: READ
/rest/api/3/jql/sanitize:
post:
tags:
- JQL
summary: Sanitize JQL queries
description: >-
Sanitizes one or more JQL queries by converting readable details into
IDs where a user doesn't have permission to view the entity.
For example, if the query contains the clause *project = 'Secret
project'*, and a user does not have browse permission for the project
"Secret project", the sanitized query replaces the clause with *project
= 12345"* (where 12345 is the ID of the project). If a user has the
required permission, the clause is not sanitized. If the account ID is
null, sanitizing is performed for an anonymous user.
Note that sanitization doesn't make the queries GDPR-compliant, because
it doesn't remove user identifiers (username or user key). If you need
to make queries GDPR-compliant, use [Convert user identifiers to account
IDs in JQL
queries](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-jql/#api-rest-api-3-jql-sanitize-post).
Before sanitization each JQL query is parsed. The queries are returned
in the same order that they were passed.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: sanitiseJqlQueries
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JqlQueriesToSanitize'
example:
queries:
- query: project = 'Sample project'
- accountId: 5b10ac8d82e05b22cc7d4ef5
query: project = 'Sample project'
- accountId: cda2aa1395ac195d951b3387
query: project = 'Sample project'
- accountId: 5b10ac8d82e05b22cc7d4ef5
query: invalid query
required: true
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/SanitizedJqlQueries'
example: >-
{"queries":[{"initialQuery":"project = 'Sample
project'","sanitizedQuery":"project =
12345"},{"initialQuery":"project = 'Sample
project'","sanitizedQuery":"project = 'Sample
project'","accountId":"5b10ac8d82e05b22cc7d4ef5"},{"initialQuery":"project
= 'Sample project'","sanitizedQuery":"project =
12345","accountId":"cda2aa1395ac195d951b3387"},{"initialQuery":"non-parsable
query","errors":{"errorMessages":["Error in the JQL Query:
Expecting operator but got 'query'. The valid operators are '=',
'!=', '<', '>', '<=', '>=', '~', '!~', 'IN', 'NOT IN', 'IS' and
'IS NOT'. (line 1, character
9)"],"errors":{}},"accountId":"5b10ac8d82e05b22cc7d4ef5"}]}
'400':
description: Returned if the request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["The queries has to be
provided."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user does not have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:jql:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/label:
get:
tags:
- Labels
summary: Get all labels
description: 'Returns a [paginated](#pagination) list of labels.'
operationId: getAllLabels
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: integer
format: int64
default: 0
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: integer
format: int32
default: 1000
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanString'
example: >-
{"maxResults":2,"startAt":0,"total":100,"isLast":false,"values":["performance","security"]}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-work'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-work'
- state: Beta
scheme: OAuth2
scopes:
- 'read:label:jira'
x-atlassian-connect-scope: READ
/rest/api/3/license/approximateLicenseCount:
get:
tags:
- License metrics
summary: Get approximate license count
description: >-
Returns the total approximate user account across all jira licenced
application keys. Please note this information is cached with a 7-day
lifecycle and could be stale at the time of call.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getApproximateLicenseCount
parameters: []
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/LicenseMetric'
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user does not have permission to complete this
request.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:license:jira'
x-experimental: true
x-atlassian-connect-scope: READ
'/rest/api/3/license/approximateLicenseCount/product/{applicationKey}':
get:
tags:
- License metrics
summary: Get approximate application license count
description: >-
Returns the total approximate user account for a specific `jira licence
application key`. Please note this information is cached with a 7-day
lifecycle and could be stale at the time of call.
#### Application Key ####
An application key represents a specific version of Jira. See \{@link
ApplicationKey\} for details
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: getApproximateApplicationLicenseCount
parameters:
- name: applicationKey
in: path
required: true
schema:
type: string
responses:
'200':
description: 200 response
content:
application/json:
schema:
$ref: '#/components/schemas/LicenseMetric'
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: >-
Returned if the user does not have permission to complete this
request.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:license:jira'
x-experimental: true
x-atlassian-connect-scope: READ
/rest/api/3/mypermissions:
get:
tags:
- Permissions
summary: Get my permissions
description: >-
Returns a list of permissions indicating which permissions the user has.
Details of the user's permissions can be obtained in a global, project,
issue or comment context.
The user is reported as having a project permission:
* in the global context, if the user has the project permission in any project.
* for a project, where the project permission is determined using issue data, if the user meets the permission's criteria for any issue in the project. Otherwise, if the user has the project permission in the project.
* for an issue, where a project permission is determined using issue data, if the user has the permission in the issue. Otherwise, if the user has the project permission in the project containing the issue.
* for a comment, where the user has both the permission to browse the comment and the project permission for the comment's parent issue. Only the BROWSE\_PROJECTS permission is supported. If a `commentId` is provided whose `permissions` does not equal BROWSE\_PROJECTS, a 400 error will be returned.
This means that users may be shown as having an issue permission (such
as EDIT\_ISSUES) in the global context or a project context but may not
have the permission for any or all issues. For example, if Reporters
have the EDIT\_ISSUES permission a user would be shown as having this
permission in the global context or the context of a project, because
any user can be a reporter. However, if they are not the user who
reported the issue queried they would not have EDIT\_ISSUES permission
for that issue.
Global permissions are unaffected by context.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: getMyPermissions
parameters:
- name: projectKey
in: query
description: The key of project. Ignored if `projectId` is provided.
schema:
type: string
- name: projectId
in: query
description: The ID of project.
schema:
type: string
- name: issueKey
in: query
description: The key of the issue. Ignored if `issueId` is provided.
schema:
type: string
- name: issueId
in: query
description: The ID of the issue.
schema:
type: string
- name: permissions
in: query
description: >-
A list of permission keys. (Required) This parameter accepts a
comma-separated list. To get the list of available permissions, use
[Get all permissions](#api-rest-api-3-permissions-get).
schema:
type: string
example: 'BROWSE_PROJECTS,EDIT_ISSUES'
x-changes:
- announced: '2018-08-01'
details: >-
https://developer.atlassian.com/cloud/jira/platform/change-notice-get-my-permissions-requires-permissions-query-parameter/
effective: '2019-02-01'
type: required
x-showInExample: 'true'
- name: projectUuid
in: query
schema:
type: string
- name: projectConfigurationUuid
in: query
schema:
type: string
- name: commentId
in: query
description: The ID of the comment.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Permissions'
example: >-
{"permissions":{"EDIT_ISSUES":{"id":"12","key":"EDIT_ISSUES","name":"Edit
Issues","type":"PROJECT","description":"Ability to edit
issues.","havePermission":true}}}
'400':
description: >-
Returned if `permissions` is empty, contains an invalid key, or does
not equal BROWSE\_PROJECTS when commentId is provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'404':
description: >-
Returned if the project or issue is not found or the user does not
have permission to view the project or issue.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2: []
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes: []
- state: Beta
scheme: OAuth2
scopes:
- 'read:permission:jira'
x-atlassian-connect-scope: READ
/rest/api/3/mypreferences:
get:
tags:
- Myself
summary: Get preference
description: >-
Returns the value of a preference of the current user.
Note that these keys are deprecated:
* *jira.user.locale* The locale of the user. By default this is not set and the user takes the locale of the instance.
* *jira.user.timezone* The time zone of the user. By default this is not set and the user takes the timezone of the instance.
Use [ Update a user
profile](https://developer.atlassian.com/cloud/admin/user-management/rest/#api-users-account-id-manage-profile-patch)
from the user management REST API to manage timezone and locale instead.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: getPreference
parameters:
- name: key
in: query
description: The key of the preference.
required: true
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
type: string
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: Returned if the key is not provided or not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:user-configuration:jira'
x-atlassian-connect-scope: ACT_AS_USER
put:
tags:
- Myself
summary: Set preference
description: >-
Creates a preference for the user or updates a preference's value by
sending a plain text string. For example, `false`. An arbitrary
preference can be created with the value containing up to 255
characters. In addition, the following keys define system preferences
that can be set or created:
* *user.notifications.mimetype* The mime type used in notifications sent to the user. Defaults to `html`.
* *user.notify.own.changes* Whether the user gets notified of their own changes. Defaults to `false`.
* *user.default.share.private* Whether new [ filters](https://confluence.atlassian.com/x/eQiiLQ) are set to private. Defaults to `true`.
* *user.keyboard.shortcuts.disabled* Whether keyboard shortcuts are disabled. Defaults to `false`.
* *user.autowatch.disabled* Whether the user automatically watches issues they create or add a comment to. By default, not set: the user takes the instance autowatch setting.
Note that these keys are deprecated:
* *jira.user.locale* The locale of the user. By default, not set. The user takes the instance locale.
* *jira.user.timezone* The time zone of the user. By default, not set. The user takes the instance timezone.
Use [ Update a user
profile](https://developer.atlassian.com/cloud/admin/user-management/rest/#api-users-account-id-manage-profile-patch)
from the user management REST API to manage timezone and locale instead.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: setPreference
parameters:
- name: key
in: query
description: The key of the preference. The maximum length is 255 characters.
required: true
schema:
type: string
requestBody:
description: >-
The value of the preference as a plain text string. The maximum length
is 255 characters.
content:
application/json:
schema:
type: string
text/plain:
schema:
type: string
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: Returned if the key or value is not provided or invalid.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'write:user-configuration:jira'
x-atlassian-connect-scope: ACT_AS_USER
delete:
tags:
- Myself
summary: Delete preference
description: >-
Deletes a preference of the user, which restores the default value of
system defined settings.
Note that these keys are deprecated:
* *jira.user.locale* The locale of the user. By default, not set. The user takes the instance locale.
* *jira.user.timezone* The time zone of the user. By default, not set. The user takes the instance timezone.
Use [ Update a user
profile](https://developer.atlassian.com/cloud/admin/user-management/rest/#api-users-account-id-manage-profile-patch)
from the user management REST API to manage timezone and locale instead.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: removePreference
parameters:
- name: key
in: query
description: The key of the preference.
required: true
schema:
type: string
responses:
'204':
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: Returned if the key is not provided or not found.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'delete:user-configuration:jira'
x-atlassian-connect-scope: ACT_AS_USER
/rest/api/3/mypreferences/locale:
get:
tags:
- Myself
summary: Get locale
description: >-
Returns the locale for the user.
If the user has no language preference set (which is the default
setting) or this resource is accessed anonymous, the browser locale
detected by Jira is returned. Jira detects the browser locale using the
*Accept-Language* header in the request. However, if this doesn't match
a locale available Jira, the site default locale is returned.
This operation can be accessed anonymously.
**[Permissions](#permissions) required:** None.
operationId: getLocale
parameters: []
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Locale'
example: '{"locale":"en_US"}'
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
- {}
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:user-configuration:jira'
x-atlassian-connect-scope: ACT_AS_USER
put:
tags:
- Myself
summary: Set locale
description: >-
Deprecated, use [ Update a user
profile](https://developer.atlassian.com/cloud/admin/user-management/rest/#api-users-account-id-manage-profile-patch)
from the user management REST API instead.
Sets the locale of the user. The locale must be one supported by the
instance of Jira.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: setLocale
parameters: []
requestBody:
description: The locale defined in a LocaleBean.
content:
application/json:
schema:
$ref: '#/components/schemas/Locale'
example:
locale: en_US
required: true
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'400':
description: Returned if request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: true
security:
- basicAuth: []
x-atlassian-connect-scope: INACCESSIBLE
delete:
tags:
- Myself
summary: Delete locale
description: >-
Deprecated, use [ Update a user
profile](https://developer.atlassian.com/cloud/admin/user-management/rest/#api-users-account-id-manage-profile-patch)
from the user management REST API instead.
Deletes the locale of the user, which restores the default setting.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: deleteLocale
parameters: []
responses:
'204':
description: Returned if the request is successful.
content:
application/json:
schema: {}
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: true
security:
- basicAuth: []
x-atlassian-connect-scope: INACCESSIBLE
/rest/api/3/myself:
get:
tags:
- Myself
summary: Get current user
description: |-
Returns details for the current user.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: getCurrentUser
parameters:
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information about
user in the response. This parameter accepts a comma-separated list.
Expand options include:
* `groups` Returns all groups, including nested groups, the user belongs to.
* `applicationRoles` Returns the application roles the user is assigned to.
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
example: >-
{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","key":"","accountId":"5b10a2844c20165700ede21g","accountType":"atlassian","name":"","emailAddress":"mia@example.com","avatarUrls":{"48x48":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48","24x24":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24","16x16":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16","32x32":"https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"},"displayName":"Mia
Krystof","active":true,"timeZone":"Australia/Sydney","groups":{"size":3,"items":[]},"applicationRoles":{"size":1,"items":[]}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'read:jira-user'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'read:jira-user'
- state: Beta
scheme: OAuth2
scopes:
- 'read:application-role:jira'
- 'read:group:jira'
- 'read:user:jira'
- 'read:avatar:jira'
x-atlassian-connect-scope: READ
/rest/api/3/notificationscheme:
get:
tags:
- Issue notification schemes
summary: Get notification schemes paginated
description: >-
Returns a [paginated](#pagination) list of [notification
schemes](https://confluence.atlassian.com/x/8YdKLg) ordered by the
display name.
*Note that you should allow for events without recipients to appear in
responses.*
**[Permissions](#permissions) required:** Permission to access Jira,
however, the user must have permission to administer at least one
project associated with a notification scheme for it to be returned.
operationId: getNotificationSchemes
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: string
default: '0'
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: string
default: '50'
- name: id
in: query
description: The list of notification schemes IDs to be filtered by
schema:
uniqueItems: true
type: array
items:
type: string
- name: projectId
in: query
description: The list of projects IDs to be filtered by
schema:
uniqueItems: true
type: array
items:
type: string
- name: onlyDefault
in: query
description: >-
When set to true, returns only the default notification scheme. If
you provide project IDs not associated with the default, returns an
empty page. The default value is false.
schema:
type: boolean
default: false
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts a comma-separated list. Expand
options include:
* `all` Returns all expandable information
* `field` Returns information about any custom fields assigned to receive an event
* `group` Returns information about any groups assigned to receive an event
* `notificationSchemeEvents` Returns a list of event associations. This list is returned for all expandable information
* `projectRole` Returns information about any project roles assigned to receive an event
* `user` Returns information about any users assigned to receive an event
schema:
type: string
responses:
'200':
description: >-
Returned if the request is successful. Only returns notification
schemes that the user has permission to access. An empty list is
returned if the user lacks permission to access all notification
schemes.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanNotificationScheme'
example: >-
{"maxResults":6,"startAt":1,"total":5,"isLast":false,"values":[{"expand":"notificationSchemeEvents,user,group,projectRole,field,all","id":10100,"self":"https://your-domain.atlassian.net/rest/api/3/notificationscheme","name":"notification
scheme
name","description":"description","notificationSchemeEvents":[{"event":{"id":1,"name":"Issue
created","description":"Event published when an issue is
created"},"notifications":[{"id":1,"notificationType":"Group","parameter":"jira-administrators","recipient":"276f955c-63d7-42c8-9520-92d01dca0625","group":{"name":"jira-administrators","groupId":"276f955c-63d7-42c8-9520-92d01dca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"},"expand":"group"},{"id":2,"notificationType":"CurrentAssignee"},{"id":3,"notificationType":"ProjectRole","parameter":"10360","recipient":"10360","projectRole":{"self":"https://your-domain.atlassian.net/rest/api/3/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","actorGroup":{"name":"jira-developers","displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2"}},{"id":10241,"displayName":"Mia
Krystof","type":"atlassian-user-role-actor","actorUser":{"accountId":"5b10a2844c20165700ede21g"}}],"scope":{"type":"PROJECT","project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"}}},"expand":"projectRole"},{"id":4,"notificationType":"EmailAddress","parameter":"rest-developer@atlassian.com","recipient":"rest-developer@atlassian.com","emailAddress":"rest-developer@atlassian.com"},{"id":5,"notificationType":"User","parameter":"5b10a2844c20165700ede21g","recipient":"5b10a2844c20165700ede21g","user":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"expand":"user"},{"id":6,"notificationType":"GroupCustomField","parameter":"customfield_10101","recipient":"customfield_10101","field":{"id":"customfield_10101","key":"customfield_10101","name":"New
custom field","untranslatedName":"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 that is published together
with an issue created
event","templateEvent":{"id":1,"name":"Issue
created","description":"Event published when an issue is
created"}},"notifications":[{"id":1,"notificationType":"Group","parameter":"jira-administrators","recipient":"276f955c-63d7-42c8-9520-92d01dca0625","group":{"name":"jira-administrators","groupId":"276f955c-63d7-42c8-9520-92d01dca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"},"expand":"group"},{"id":2,"notificationType":"CurrentAssignee"},{"id":3,"notificationType":"ProjectRole","parameter":"10360","recipient":"10360","projectRole":{"self":"https://your-domain.atlassian.net/rest/api/3/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","actorGroup":{"name":"jira-developers","displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2"}},{"id":10241,"displayName":"Mia
Krystof","type":"atlassian-user-role-actor","actorUser":{"accountId":"5b10a2844c20165700ede21g"}}],"scope":{"type":"PROJECT","project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"}}},"expand":"projectRole"},{"id":4,"notificationType":"EmailAddress","parameter":"rest-developer@atlassian.com","recipient":"rest-developer@atlassian.com","emailAddress":"rest-developer@atlassian.com"},{"id":5,"notificationType":"User","parameter":"5b10a2844c20165700ede21g","recipient":"5b10a2844c20165700ede21g","user":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"expand":"user"},{"id":6,"notificationType":"GroupCustomField","parameter":"customfield_10101","recipient":"customfield_10101","field":{"id":"customfield_10101","key":"customfield_10101","name":"New
custom field","untranslatedName":"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"}]}],"projects":[10001,10002]}]}
'400':
description: Returned if the request isn't valid.
content:
application/json:
example: >-
{"errorMessages":["%20. is not a valid value. id must be zero or
a positive integer."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:field:jira'
- 'read:notification-scheme:jira'
- 'read:project:jira'
- 'read:project-role:jira'
- 'read:user:jira'
- 'read:avatar:jira'
- 'read:group:jira'
- 'read:project-category:jira'
- 'read:field-configuration:jira'
x-atlassian-connect-scope: ADMIN
post:
tags:
- Issue notification schemes
summary: Create notification scheme
description: >-
Creates a notification scheme with notifications. You can create up to
1000 notifications per request.
**[Permissions](#permissions) required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: createNotificationScheme
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNotificationSchemeDetails'
example:
description: My new scheme description
name: My new notification scheme
notificationSchemeEvents:
- event:
id: '1'
notifications:
- notificationType: Group
parameter: jira-administrators
required: true
responses:
'201':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationSchemeId'
example: '{"id":"10001"}'
'400':
description: Returned if the request isn't valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["The length of the description must not exceed
4000 characters."],"errors":{}}
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'403':
description: Returned if the user doesn't have the necessary permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/notificationscheme/project:
get:
tags:
- Issue notification schemes
summary: Get projects using notification schemes paginated
description: >-
Returns a [paginated](#pagination) mapping of project that have
notification scheme assigned. You can provide either one or multiple
notification scheme IDs or project IDs to filter by. If you don't
provide any, this will return a list of all mappings. Note that only
company-managed (classic) projects are supported. This is because
team-managed projects don't have a concept of a default notification
scheme. The mappings are ordered by projectId.
**[Permissions](#permissions) required:** Permission to access Jira.
operationId: getNotificationSchemeToProjectMappings
parameters:
- name: startAt
in: query
description: >-
The index of the first item to return in a page of results (page
offset).
schema:
type: string
default: '0'
- name: maxResults
in: query
description: The maximum number of items to return per page.
schema:
type: string
default: '50'
- name: notificationSchemeId
in: query
description: The list of notifications scheme IDs to be filtered out
schema:
uniqueItems: true
type: array
items:
type: string
- name: projectId
in: query
description: The list of project IDs to be filtered out
schema:
uniqueItems: true
type: array
items:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: >-
#/components/schemas/PageBeanNotificationSchemeAndProjectMappingJsonBean
example: >-
{"maxResults":50,"startAt":0,"total":4,"isLast":true,"values":[{"notificationSchemeId":"10001","projectId":"100001"}]}
'400':
description: >-
Returned if search criteria are invalid, strings vs numbers for
projectId, notificationSchemeId, startAt and maxResult
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
'401':
description: Returned if the authentication credentials are incorrect or missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
deprecated: false
security:
- basicAuth: []
- OAuth2:
- 'manage:jira-configuration'
x-atlassian-oauth2-scopes:
- state: Current
scheme: OAuth2
scopes:
- 'manage:jira-configuration'
- state: Beta
scheme: OAuth2
scopes:
- 'read:notification-scheme:jira'
- 'read:project:jira'
x-experimental: true
x-atlassian-connect-scope: ADMIN
'/rest/api/3/notificationscheme/{id}':
get:
tags:
- Issue notification schemes
summary: Get notification scheme
description: >-
Returns a [notification
scheme](https://confluence.atlassian.com/x/8YdKLg), including the list
of events and the recipients who will receive notifications for those
events.
**[Permissions](#permissions) required:** Permission to access Jira,
however, the user must have permission to administer at least one
project associated with the notification scheme.
operationId: getNotificationScheme
parameters:
- name: id
in: path
description: >-
The ID of the notification scheme. Use [Get notification schemes
paginated](#api-rest-api-3-notificationscheme-get) to get a list of
notification scheme IDs.
required: true
schema:
type: integer
format: int64
- name: expand
in: query
description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts a comma-separated list. Expand
options include:
* `all` Returns all expandable information
* `field` Returns information about any custom fields assigned to receive an event
* `group` Returns information about any groups assigned to receive an event
* `notificationSchemeEvents` Returns a list of event associations. This list is returned for all expandable information
* `projectRole` Returns information about any project roles assigned to receive an event
* `user` Returns information about any users assigned to receive an event
schema:
type: string
responses:
'200':
description: Returned if the request is successful.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationScheme'
example: >-
{"expand":"notificationSchemeEvents,user,group,projectRole,field,all","id":10100,"self":"https://your-domain.atlassian.net/rest/api/3/notificationscheme","name":"notification
scheme
name","description":"description","notificationSchemeEvents":[{"event":{"id":1,"name":"Issue
created","description":"Event published when an issue is
created"},"notifications":[{"id":1,"notificationType":"Group","parameter":"jira-administrators","recipient":"276f955c-63d7-42c8-9520-92d01dca0625","group":{"name":"jira-administrators","groupId":"276f955c-63d7-42c8-9520-92d01dca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"},"expand":"group"},{"id":2,"notificationType":"CurrentAssignee"},{"id":3,"notificationType":"ProjectRole","parameter":"10360","recipient":"10360","projectRole":{"self":"https://your-domain.atlassian.net/rest/api/3/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","actorGroup":{"name":"jira-developers","displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2"}},{"id":10241,"displayName":"Mia
Krystof","type":"atlassian-user-role-actor","actorUser":{"accountId":"5b10a2844c20165700ede21g"}}],"scope":{"type":"PROJECT","project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"}}},"expand":"projectRole"},{"id":4,"notificationType":"EmailAddress","parameter":"rest-developer@atlassian.com","recipient":"rest-developer@atlassian.com","emailAddress":"rest-developer@atlassian.com"},{"id":5,"notificationType":"User","parameter":"5b10a2844c20165700ede21g","recipient":"5b10a2844c20165700ede21g","user":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"expand":"user"},{"id":6,"notificationType":"GroupCustomField","parameter":"customfield_10101","recipient":"customfield_10101","field":{"id":"customfield_10101","key":"customfield_10101","name":"New
custom field","untranslatedName":"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 that is published together
with an issue created
event","templateEvent":{"id":1,"name":"Issue
created","description":"Event published when an issue is
created"}},"notifications":[{"id":1,"notificationType":"Group","parameter":"jira-administrators","recipient":"276f955c-63d7-42c8-9520-92d01dca0625","group":{"name":"jira-administrators","groupId":"276f955c-63d7-42c8-9520-92d01dca0625","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"},"expand":"group"},{"id":2,"notificationType":"CurrentAssignee"},{"id":3,"notificationType":"ProjectRole","parameter":"10360","recipient":"10360","projectRole":{"self":"https://your-domain.atlassian.net/rest/api/3/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","actorGroup":{"name":"jira-developers","displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2"}},{"id":10241,"displayName":"Mia
Krystof","type":"atlassian-user-role-actor","actorUser":{"accountId":"5b10a2844c20165700ede21g"}}],"scope":{"type":"PROJECT","project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"}}},"expand":"projectRole"},{"id":4,"notificationType":"EmailAddress","parameter":"rest-developer@atlassian.com","recipient":"rest-developer@atlassian.com","emailAddress":"rest-developer@atlassian.com"},{"id":5,"notificationType":"User","parameter":"5b10a2844c20165700ede21g","recipient":"5b10a2844c20165700ede21g","user":{"self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","accountId":"5b10a2844c20165700ede21g","displayName":"Mia
Krystof","active":false},"expand":"user"},{"id":6,"notificationType":"GroupCustomField","parameter":"customfield_10101","recipient":"customfield_10101","field":{"id":"customfield_10101","key":"customfield_10101","name":"New
custom field","untranslatedName":"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"}]}],"projects":[10001,10002]}
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authenticati
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment