components:
schemas:
BulkEditShareableEntityResponse:
additionalProperties: false
description: Details of a request to bulk edit shareable entity.
properties:
action:
description: Allowed action for bulk edit shareable entity
enum:
- changeOwner
- changePermission
- addPermission
- removePermission
type: string
entityErrors:
additionalProperties:
$ref: '#/components/schemas/BulkEditActionError'
description: The mapping dashboard id to errors if any.
type: object
required:
- action
type: object
AvailableDashboardGadgetsResponse:
additionalProperties: false
description: The list of available gadgets.
properties:
gadgets:
description: The list of available gadgets.
items:
$ref: '#/components/schemas/AvailableDashboardGadget'
readOnly: true
type: array
required:
- gadgets
type: object
PageBeanDashboard:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/Dashboard'
readOnly: true
type: array
type: object
DashboardGadgetResponse:
additionalProperties: false
description: The list of gadgets on the dashboard.
properties:
gadgets:
description: The list of gadgets.
items:
$ref: '#/components/schemas/DashboardGadget'
readOnly: true
type: array
required:
- gadgets
type: object
DashboardGadget:
additionalProperties: false
description: Details of a gadget.
properties:
color:
description: >-
The color of the gadget. Should be one of `blue`, `red`, `yellow`,
`green`, `cyan`, `purple`, `gray`, or `white`.
enum:
- blue
- red
- yellow
- green
- cyan
- purple
- gray
- white
readOnly: true
type: string
id:
description: The ID of the gadget instance.
format: int64
readOnly: true
type: integer
moduleKey:
description: The module key of the gadget type.
readOnly: true
type: string
position:
allOf:
- $ref: '#/components/schemas/DashboardGadgetPosition'
description: The position of the gadget.
readOnly: true
title:
description: The title of the gadget.
readOnly: true
type: string
uri:
description: The URI of the gadget type.
readOnly: true
type: string
required:
- color
- id
- position
- title
type: object
PropertyKeys:
additionalProperties: false
description: List of property keys.
properties:
keys:
description: Property key details.
items:
$ref: '#/components/schemas/PropertyKey'
readOnly: true
type: array
type: object
EntityProperty:
additionalProperties: false
description: >-
An entity property, for more information see [Entity
properties](https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/).
properties:
key:
description: The key of the property. Required on create and update.
type: string
value:
description: The value of the property. Required on create and update.
type: object
Dashboard:
additionalProperties: false
description: Details of a dashboard.
properties:
automaticRefreshMs:
description: The automatic refresh interval for the dashboard in milliseconds.
format: int32
readOnly: true
type: integer
description:
type: string
editPermissions:
description: The details of any edit share permissions for the dashboard.
items:
$ref: '#/components/schemas/SharePermission'
readOnly: true
type: array
id:
description: The ID of the dashboard.
readOnly: true
type: string
isFavourite:
description: Whether the dashboard is selected as a favorite by the user.
readOnly: true
type: boolean
isWritable:
description: Whether the current user has permission to edit the dashboard.
readOnly: true
type: boolean
name:
description: The name of the dashboard.
readOnly: true
type: string
owner:
allOf:
- $ref: '#/components/schemas/UserBean'
description: The owner of the dashboard.
readOnly: true
popularity:
description: The number of users who have this dashboard as a favorite.
format: int64
readOnly: true
type: integer
rank:
description: The rank of this dashboard.
format: int32
readOnly: true
type: integer
self:
description: The URL of these dashboard details.
format: uri
readOnly: true
type: string
sharePermissions:
description: The details of any view share permissions for the dashboard.
items:
$ref: '#/components/schemas/SharePermission'
readOnly: true
type: array
systemDashboard:
description: Whether the current dashboard is system dashboard.
readOnly: true
type: boolean
view:
description: The URL of the dashboard.
readOnly: true
type: string
type: object
externalDocs:
description: Find out more about Atlassian products and services.
url: http://www.atlassian.com
info:
contact:
email: ecosystem@atlassian.com
description: Needs description.
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: http://atlassian.com/terms/
title: 'Atlassian rest/api/3/dashboard/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/dashboard/bulk/edit:
put:
deprecated: false
description: >-
Bulk edit dashboards. Maximum number of dashboards to be edited at the
same time is 100.
**[Permissions](#permissions) required:**
None
The dashboards to be updated must be owned by the user, or
the user must be an administrator.
operationId: atlassianBulkeditdashboards
parameters: []
requestBody:
content:
application/json:
example:
action: changePermission
entityIds:
- 10001
- 10002
extendAdminPermissions: true
permissionDetails:
editPermissions:
- group:
groupId: 276f955c-63d7-42c8-9520-92d01dca0625
name: jira-administrators
self: >-
https://your-domain.atlassian.net/rest/api/~ver~/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625
id: 10010
type: group
sharePermissions:
- id: 10000
type: global
schema:
$ref: '#/components/schemas/BulkEditShareableEntityRequest'
description: The details of dashboards being updated in bulk.
required: true
responses:
'200':
content:
application/json:
example: >-
{"action":"changePermission","entityErrors":{"10002":{"errorMessages":["Only
owner or editors of the dashboard can change
permissions."],"errors":{}}}}
schema:
$ref: '#/components/schemas/BulkEditShareableEntityResponse'
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is not valid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
security:
- basicAuth: []
- OAuth2:
- write:jira-work
summary: Atlassian Bulk Edit Dashboards
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- write:jira-work
state: Current
- 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
state: Beta
x-experimental: true
x-atlassian-connect-scope: WRITE
/rest/api/3/dashboard/gadgets:
get:
deprecated: false
description: >-
Gets a list of all available gadgets that can be added to all
dashboards.
**[Permissions](#permissions) required:** None.
operationId: atlassianGetallavailabledashboardgadgets
parameters: []
responses:
'200':
content:
application/json:
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"}]}
schema:
$ref: '#/components/schemas/AvailableDashboardGadgetsResponse'
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: 400 response
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
summary: Atlassian Get Available Gadgets
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:dashboard:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: READ
/rest/api/3/dashboard/search:
get:
deprecated: false
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: atlassianGetdashboardspaginated
parameters:
- description: String used to perform a case-insensitive partial match with `name`.
in: query
name: dashboardName
schema:
type: string
- description: >-
User account ID used to return dashboards with the matching
`owner.accountId`. This parameter cannot be used with the `owner`
parameter.
in: query
name: accountId
schema:
maxLength: 128
type: string
- 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.
in: query
name: owner
schema:
type: string
- 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.
in: query
name: groupname
schema:
type: string
- 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.
in: query
name: groupId
schema:
type: string
- description: >-
Project ID used to returns dashboards that are shared with a project
that matches `sharePermissions.project.id`.
in: query
name: projectId
schema:
format: int64
type: integer
- 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.
in: query
name: orderBy
schema:
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
type: string
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 50
format: int32
type: integer
- description: The status to filter by. It may be active, archived or deleted.
in: query
name: status
schema:
default: active
enum:
- active
- archived
- deleted
type: string
- 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.
in: query
name: expand
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"isLast":true,"maxResults":100,"self":"https://your-domain.atlassian.net/rest/api/3/dashboard/search?expand=owner&maxResults=50&startAt=0","startAt":0,"total":2,"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"}]}
schema:
$ref: '#/components/schemas/PageBeanDashboard'
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: |-
Returned if:
* `orderBy` is invalid.
* `expand` includes an invalid value.
* `accountId` and `owner` are provided.
* `groupname` and `groupId` are provided.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: 401 response
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Search For Dashboards
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- 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
state: Beta
x-atlassian-connect-scope: READ
/rest/api/3/dashboard/{dashboardId}/gadget:
get:
deprecated: false
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: atlassianGetallgadgets
parameters:
- description: The ID of the dashboard.
in: path
name: dashboardId
required: true
schema:
format: int64
type: integer
- description: >-
The list of gadgets module keys. To include multiple module keys,
separate module keys with ampersand:
`moduleKey=key:one&moduleKey=key:two`.
in: query
name: moduleKey
schema:
items:
default: ''
type: string
type: array
- description: >-
The list of gadgets URIs. To include multiple URIs, separate URIs
with ampersand: `uri=/rest/example/uri/1&uri=/rest/example/uri/2`.
in: query
name: uri
schema:
items:
default: ''
type: string
type: array
- description: >-
The list of gadgets IDs. To include multiple IDs, separate IDs with
ampersand: `gadgetId=10000&gadgetId=10001`.
in: query
name: gadgetId
schema:
items:
format: int64
type: integer
type: array
responses:
'200':
content:
application/json:
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"}]}
schema:
$ref: '#/components/schemas/DashboardGadgetResponse'
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect.
'404':
content:
application/json:
example: >-
{"errorMessages":["The dashboard you requested either does not
exist or you don't have the required permissions to perform this
action."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the dashboard is not found.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Get Gadgets
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:dashboard:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: READ
post:
deprecated: false
description: >-
Adds a gadget to a dashboard.
**[Permissions](#permissions)
required:** None.
operationId: atlassianAddgadget
parameters:
- description: The ID of the dashboard.
in: path
name: dashboardId
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
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
schema:
$ref: '#/components/schemas/DashboardGadgetSettings'
required: true
responses:
'200':
content:
application/json:
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"}
schema:
$ref: '#/components/schemas/DashboardGadget'
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["Cannot add another gadget. The maximum number
of gadgets the dashboard can hold has been
reached."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
content:
application/json:
example: >-
{"errorMessages":["The dashboard you requested either does not
exist or you don't have the required permissions to perform this
action."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the dashboard is not found.
security:
- basicAuth: []
- OAuth2:
- write:jira-work
- read:jira-work
summary: Atlassian Add Gadget To Dashboard
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- write:jira-work
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- write:dashboard:jira
- read:dashboard:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: WRITE
/rest/api/3/dashboard/{dashboardId}/gadget/{gadgetId}:
delete:
deprecated: false
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: atlassianRemovegadget
parameters:
- description: The ID of the dashboard.
in: path
name: dashboardId
required: true
schema:
format: int64
type: integer
- description: The ID of the gadget.
in: path
name: gadgetId
required: true
schema:
format: int64
type: integer
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
content:
application/json:
example: >-
{"errorMessages":["The dashboard gadget was not
found."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the gadget or the dashboard is not found.
security:
- basicAuth: []
- OAuth2:
- write:jira-work
summary: Atlassian Remove Gadget From Dashboard
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- write:jira-work
state: Current
- scheme: OAuth2
scopes:
- write:dashboard:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: DELETE
put:
deprecated: false
description: >-
Changes the title, position, and color of the gadget on a
dashboard.
**[Permissions](#permissions) required:** None.
operationId: atlassianUpdategadget
parameters:
- description: The ID of the dashboard.
in: path
name: dashboardId
required: true
schema:
format: int64
type: integer
- description: The ID of the gadget.
in: path
name: gadgetId
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
color: red
position:
column: 1
row: 1
title: My new gadget title
schema:
$ref: '#/components/schemas/DashboardGadgetUpdateRequest'
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["The gadget cannot be placed in the selected
row. The selected row does not exist on the
dashboard."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect.
'404':
content:
application/json:
example: >-
{"errorMessages":["The dashboard you requested either does not
exist or you don't have the required permissions to perform this
action."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the gadget or the dashboard is not found.
security:
- basicAuth: []
- OAuth2:
- write:jira-work
summary: Atlassian Update Gadget On Dashboard
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- write:jira-work
state: Current
- scheme: OAuth2
scopes:
- write:dashboard:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: WRITE
/rest/api/3/dashboard/{dashboardId}/items/{itemId}/properties:
get:
deprecated: false
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\\u2019s anonymous access is permitted.
operationId: atlassianGetdashboarditempropertykeys
parameters:
- description: The ID of the dashboard.
in: path
name: dashboardId
required: true
schema:
type: string
- description: The ID of the dashboard item.
in: path
name: itemId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"keys":[{"key":"issue.support","self":"https://your-domain.atlassian.net/rest/api/3/issue/EX-2/properties/issue.support"}]}
schema:
$ref: '#/components/schemas/PropertyKeys'
description: Returned if the request is successful.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: >-
Returned if the dashboard or dashboard item is not found, or the
dashboard is not owned by or shared with the user.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Get Dashboard Item Property Keys
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:dashboard.property:jira
state: Beta
x-atlassian-connect-scope: READ
/rest/api/3/dashboard/{dashboardId}/items/{itemId}/properties/{propertyKey}:
delete:
deprecated: false
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: atlassianDeletedashboarditemproperty
parameters:
- description: The ID of the dashboard.
in: path
name: dashboardId
required: true
schema:
type: string
- description: The ID of the dashboard item.
in: path
name: itemId
required: true
schema:
type: string
- description: The key of the dashboard item property.
in: path
name: propertyKey
required: true
schema:
type: string
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the dashboard item property is deleted.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the dashboard or dashboard item ID is invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user is not the owner of the dashboard.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: >-
Returned if the dashboard item is not found or the dashboard is not
shared with the user.
security:
- basicAuth: []
- OAuth2:
- write:jira-work
- {}
summary: Atlassian Delete Dashboard Item Property
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- write:jira-work
state: Current
- scheme: OAuth2
scopes:
- delete:dashboard.property:jira
state: Beta
x-atlassian-connect-scope: DELETE
get:
deprecated: false
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\\u2019s anonymous access is permitted.
operationId: atlassianGetdashboarditemproperty
parameters:
- description: The ID of the dashboard.
in: path
name: dashboardId
required: true
schema:
type: string
- description: The ID of the dashboard item.
in: path
name: itemId
required: true
schema:
type: string
- description: The key of the dashboard item property.
in: path
name: propertyKey
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"key":"issue.support","value":{"system.conversation.id":"b1bf38be-5e94-4b40-a3b8-9278735ee1e6","system.support.time":"1m"}}
schema:
$ref: '#/components/schemas/EntityProperty'
description: Returned if the request is successful.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
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.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Get Dashboard Item Property
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:dashboard.property:jira
state: Beta
x-atlassian-connect-scope: READ
put:
deprecated: false
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: atlassianSetdashboarditemproperty
parameters:
- description: The ID of the dashboard.
in: path
name: dashboardId
required: true
schema:
type: string
- description: The ID of the dashboard item.
in: path
name: itemId
required: true
schema:
type: string
- 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.
in: path
name: propertyKey
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
number: 5
string: string-value
schema: {}
description: >-
The value of the property. The value has to be a valid, non-empty
[JSON](https://tools.ietf.org/html/rfc4627) value. The maximum length
of the property value is 32768 bytes.
required: true
responses:
'200':
content:
application/json:
schema: {}
description: Returned if the dashboard item property is updated.
'201':
content:
application/json:
schema: {}
description: Returned if the dashboard item property is created.
'400':
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":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
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.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user is not the owner of the dashboard.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: >-
Returned if the dashboard item is not found or the dashboard is not
shared with the user.
security:
- basicAuth: []
- OAuth2:
- write:jira-work
- {}
summary: Atlassian Set Dashboard Item Property
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- write:jira-work
state: Current
- scheme: OAuth2
scopes:
- write:dashboard.property:jira
state: Beta
x-atlassian-connect-scope: WRITE
/rest/api/3/dashboard/{id}:
delete:
deprecated: false
description: >-
Deletes a dashboard.
**[Permissions](#permissions) required:**
None
The dashboard to be deleted must be owned by the user.
operationId: atlassianDeletedashboard
parameters:
- description: The ID of the dashboard.
in: path
name: id
required: true
schema:
type: string
responses:
'204':
description: Returned if the dashboard is deleted.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: 400 response
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
security:
- basicAuth: []
- OAuth2:
- write:jira-work
- {}
summary: Atlassian Delete Dashboard
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- write:jira-work
state: Current
- scheme: OAuth2
scopes:
- delete:dashboard:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: DELETE
get:
deprecated: false
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: atlassianGetdashboard
parameters:
- description: The ID of the dashboard.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
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"}
schema:
$ref: '#/components/schemas/Dashboard'
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: 400 response
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the dashboard is not found or the dashboard is not owned
by or shared with the user.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Get Dashboard
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- 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
state: Beta
x-atlassian-connect-scope: READ
put:
deprecated: false
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: atlassianUpdatedashboard
parameters:
- description: The ID of the dashboard to update.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
description: A dashboard to help auditors identify sample of issues to check.
editPermissions: []
name: Auditors dashboard
sharePermissions:
- type: global
schema:
$ref: '#/components/schemas/DashboardDetails'
description: Replacement dashboard details.
required: true
responses:
'200':
content:
application/json:
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"}
schema:
$ref: '#/components/schemas/Dashboard'
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is not valid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: >-
Returned if the dashboard is not found or the dashboard is not owned
by the user.
security:
- basicAuth: []
- OAuth2:
- write:jira-work
- {}
summary: Atlassian Update Dashboard
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- write:jira-work
state: Current
- 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
state: Beta
x-experimental: true
x-atlassian-connect-scope: WRITE
/rest/api/3/dashboard/{id}/copy:
post:
deprecated: false
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: atlassianCopydashboard
parameters:
- in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
description: A dashboard to help auditors identify sample of issues to check.
editPermissions: []
name: Auditors dashboard
sharePermissions:
- type: global
schema:
$ref: '#/components/schemas/DashboardDetails'
description: Dashboard details.
required: true
responses:
'200':
content:
application/json:
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"}
schema:
$ref: '#/components/schemas/Dashboard'
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is not valid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: >-
Returned if the dashboard is not found or the dashboard is not owned
by or shared with the user.
security:
- basicAuth: []
- OAuth2:
- write:jira-work
- {}
summary: Atlassian Copy Dashboard
tags:
- Dashboards
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- write:jira-work
state: Current
- 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
state: Beta
x-experimental: true
x-atlassian-connect-scope: WRITE
servers:
- url: https://your-domain.atlassian.net
tags:
- name: Dashboards
x-atlassian-narrative:
documents:
- anchor: about
body: >-
The Jira REST API enables you to interact with Jira programmatically.
Use this API to
[build
apps](https://developer.atlassian.com/cloud/jira/platform/integrating-with-jira-cloud/),
script interactions with
Jira, or develop any other type of integration. This page documents the
REST resources available in Jira Cloud, including
the HTTP response codes and example requests and responses.
title: About
- anchor: version
body: >
This documentation is for **version 3** of the Jira Cloud platform REST
API, which is the latest version
but is in **beta**. [Version
2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/) and
version 3 of the API offer the same collection of operations. However,
version 3 provides support for
the [Atlassian Document
Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
(ADF) in:
- `body` in comments, including where comments are used in issue, issue
link, and transition resources.
- `comment` in worklogs.
- `description` and `environment` fields in issues.
- `textarea` type custom fields (multi-line text fields) in issues.
Single line custom fields
(`textfield`) accept a string and don't handle Atlassian Document Format content.
However, these new features are under development and may change.
title: Version
- anchor: authentication
body: >
### Forge apps
For Forge apps, [REST API
scopes](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/)
are used when authenticating with Jira Cloud platform. See [Add scopes
to call an Atlassian REST
API](https://developer.atlassian.com/platform/forge/add-scopes-to-call-an-atlassian-rest-api/)
for more details.
The URIs for Forge app REST API calls have this structure:
`/rest/api/3/`
For example, `/rest/api/3/issue/DEMO-1`
### Connect apps
For Connect apps, authentication (JWT-based) is built into the Connect
libraries. Authorization is implemented using either
scopes (shown as _App scope required_ for operations on this page) or
user impersonation. See
[Security for Connect
apps](https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/)
for details.
The URIs for Connect app REST API calls have this structure:
`https:///rest/api/3/`
For example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`
### Other integrations
For integrations that are not Forge or Connect apps, use OAuth 2.0
authorization code grants (3LO) for security
(3LO scopes are shown as for operations _OAuth scopes required_). See
[OAuth 2.0 (3LO)
apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)
for details.
The URIs for OAuth 2.0 (3LO) app REST API calls have this structure:
`https://api.atlassian.com/ex/jira//rest/api/3/`
For example,
`https://api.atlassian.com/ex/jira/35273b54-3f06-40d2-880f-dd28cf8daafa/rest/api/3/issue/DEMO-1`
### Ad-hoc API calls
For personal scripts, bots, and ad-hoc execution of the REST APIs use
basic authentication. See [Basic auth for REST
APIs](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/)
for details.
The URIs for basic authentication REST API calls have this structure:
`https:///rest/api/3/`
For example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`
title: Authentication and authorization
- anchor: permissions
body: >
### Operation permissions
Most operations in this API require permissions. The calling user must
have the required permissions for an operation to
use it. Note that for Connect apps, the app user must have the required
permissions for the operation and the app must
have scopes that permit the operation.
A permission can be granted to a group, project role, or issue role that
the user is a member of, or granted directly to a user.
See [Permissions overview](https://confluence.atlassian.com/x/FQiiLQ)
for details. The most common permissions are:
- **Administer the Cloud site**: Users in the _site-admins_ group have
this
permission. See [Manage
groups](https://confluence.atlassian.com/x/24xjL) for details.
- **Administer Jira**: Granted by the _Jira Administrators_ global
permission. There is a default group for this permission.
See [Manage groups](https://confluence.atlassian.com/x/24xjL) and
[Managing global permissions](https://confluence.atlassian.com/x/x4dKLg)
for details.
- **Administer a project in Jira**: Granted by the _Administer projects_
project permission for a project. This can be
granted to a user, a group, a project role, and more.
See [Managing project
permissions](https://confluence.atlassian.com/x/yodKLg) for details.
- **Access a project in Jira**: Granted by the _Browse projects_ project
permission for a project. This can be
granted to a user, a group, a project role, and more.
See [Managing project
permissions](https://confluence.atlassian.com/x/yodKLg) for details.
- **Access Jira**: Granted by the _Jira Users_ global permission. Users
in the default product access group (for example,
_jira-software-users-acmesite_) have this permission.
See [Manage groups](https://confluence.atlassian.com/x/24xjL) and
[Managing global permissions](https://confluence.atlassian.com/x/x4dKLg)
for details.
### Anonymous access
Some operations provide support for anonymous access. However, anonymous
access is only available if
the Jira permission needed to access the object or records returned by
the operation is granted to
the _Public_ group. See [Allowing anonymous access to your
project](https://confluence.atlassian.com/x/GDxxLg)
for details.
If an operation is called anonymously and anonymous access is not
available, the operation will return
an error. Note that not all operations that correspond to objects that
can be given public access
provide for anonymous access.
title: Permissions
- anchor: expansion
body: >+
### Expansion
The Jira REST API uses resource expansion, which means that some parts
of a resource are not returned unless specified
in the request. This simplifies responses and minimizes network traffic.
To expand part of a resource in a request, use the expand query
parameter and specify the object(s) to be expanded.
If you need to expand nested objects, use the `.` dot notation. If you
need to expand multiple objects, use a
comma-separated list.
For example, the following request expands the `names` and
`renderedFields` properties for the _JRACLOUD-34423_ issue:
`GET issue/JRACLOUD-34423?expand=names,renderedFields`
To discover which object can be expanded, refer to the `expand` property
in the object.
In the JSON example below, the resource declares `widgets` as
expandable.
```json
{
"expand": "widgets",
"self": "https://your-domain.atlassian.net/rest/api/3/resource/KEY-1",
"widgets": {
"widgets": [],
"size": 5
}
}
```
### Pagination
The Jira REST API uses pagination to improve performance. Pagination is
enforced for operations that could return a large
collection of items. When you make a request to a paginated resource,
the response wraps the returned array of values in
a JSON object with paging metadata. For example:
```json
{
"startAt" : 0,
"maxResults" : 10,
"total": 200,
"isLast": false,
"values": [
{ /* result 0 */ },
{ /* result 1 */ },
{ /* result 2 */ }
]
}
```
* `startAt` is the index of the first item returned in the page.
* `maxResults` is the maximum number of items that a page can return.
Each operation can have a different limit for
the number of items returned, and these limits may change without notice. To find the maximum number of items
that an operation could return, set `maxResults` to a large number—for example, over 1000—and if the returned value of `maxResults` is less than the requested value, the returned value is the maximum.
* `total` is the total number of items contained in all pages. This
number **_may change_** as the client
requests the subsequent pages, therefore the client should always assume
that the requested page can be empty. Note
that this property is not returned for all operations.
* `isLast` indicates whether the page returned is the last one. Note
that this property is not returned for all operations.
### Ordering
Some operations support ordering the elements of a response by a field.
Check the documentation for the operation to
confirm whether ordering of a response is supported and which fields can
be used. Responses are listed in ascending order
by default. You can change the order using the `orderby` query parameter
with a `-` or `+` symbol. For example:
* `?orderBy=name` to order by `name` field ascending.
* `?orderBy=+name` to order by `name` field ascending.
* `?orderBy=-name` to order by `name` field descending.
title: Expansion, pagination, and ordering
- anchor: timestamps
body: >
By default, top-level timestamps (e.g. updated and created) are returned
in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format, in the system
default user time zone.
To return date time data in the logged in user's timezone, please refer
to `renderedFields` property under the `expand` query parameter in
relevant APIs.
title: Timestamps
- anchor: special-request-headers
body: >-
The following request and response headers define important metadata for
the Jira Cloud REST API resources.
- `X-Atlassian-Token` (request): Operations that accept
multipart/form-data must include the `X-Atlassian-Token: no-check`
header in requests. Otherwise the request is blocked by cross-site
request forgery (CSRF/XSRF) protection.
- `X-Force-Accept-Language` (request): controls how the standard HTTP
`Accept-Language` header is processed.
By default `Accept-Language` is ignored and the response is in the
language configured in the user's profile or,
when no language is configured for the user, the default Jira instance
language. For the response to recognize
`Accept-Language` send `X-Force-Accept-Language = true` as well. If
`Accept-Language` requests a language that Jira
can return the response is in that language, otherwise Jira returns the
response in the default language. If
`Accept-Language` is not specified the response is in the default
language.
- `X-AAccountId` (response): This response header contains the
Atlassian account ID of the authenticated user.
title: Special headers
- anchor: anonymous-operations
body: |2-
Jira provides for all permissions, except the [global permission](https://confluence.atlassian.com/x/x4dKLg) Administer Jira, to be assigned to *Anyone*. Once a permission is assigned to *Anyone*, anyone knowing a project's URL is able to use the features in Jira enabled by the permission. However, the Jira REST API does not enable anonymous access for operations by default. This means that an anonymous user who may be able to perform an action through Jira, may not be able to perform the same action where it's enabled by the REST API.
The operations that provide anonymous access are annotated "This operation can be accessed anonymously."
title: Anonymous operations
- anchor: async-operations
body: >-
Some Jira REST API operations may trigger long-running or
computationally expensive tasks. In these cases, the operation
will schedule an asynchronous task and return a `303 (See Other)`
response, indicating the location of the queued task
in the `Location` header. You can query this task to get progress
updates.
When the task finishes, the response object will contain the `result`
field. The content of the field is specific to the
operation that created the task. Refer to the operation’s documentation
for more information.
Note that asynchronous tasks are not guaranteed to be run in order. In
other words, if you need your tasks to execute
in a certain order, you should start a task only after the prerequisite
task(s) have finished.
title: Asynchronous operations
- anchor: experimental
body: >
Features and methods marked as experimental may change without notice.
Feedback on experimental functionality is welcome.
Report your suggestions and bugs in the [ACJIRA
project](https://ecosystem.atlassian.net/projects/ACJIRA) (preferred) or
use the
**Give docs feedback** link at the top of this page.
title: Experimental features
- anchor: status-codes
body: >-
The Jira Cloud platform REST API uses the [standard HTTP status
codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).
Operations that return an error status code may also return a response
body containing details of the error or errors.
The schema for the response body is shown below:
```json
{
"id": "https://docs.atlassian.com/jira/REST/schema/error-collection#",
"title": "Error Collection",
"type": "object",
"properties": {
"errorMessages": {
"type": "array",
"items": {
"type": "string"
}
},
"errors": {
"type": "object",
"patternProperties": {
".+": {
"type": "string"
}
},
"additionalProperties": false
},
"status": {
"type": "integer"
}
},
"additionalProperties": false
}
```
title: Status codes