Atlassian Jira Dashboard API
The Atlassian Jira Dashboard API enables creating, customizing, and managing dashboards and gadgets within Jira.
OpenAPI Specification
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: [email protected]
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.<br><br>**[Permissions](#permissions) required:**
None<br><br>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.<br><br>**[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.<br><br>This operation can be accessed
anonymously.<br><br>**[Permissions](#permissions) required:** The
following dashboards that match the query parameters are
returned:<br><br> * Dashboards owned by the user. Not returned for
anonymous users.<br> * Dashboards shared with a group that the user is
a member of. Not returned for anonymous users.<br> * Dashboards shared
with a private project that the user can browse. Not returned for
anonymous users.<br> * Dashboards shared with a public project.<br> * 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.<br><br>This
operation returns:<br><br> * Gadgets from a list of IDs, when `id` is
set.<br> * Gadgets with a module key, when `moduleKey` is set.<br> * Gadgets from a list of URIs, when `uri` is set.<br> * All gadgets, when
no other parameters are set.<br><br>This operation can be accessed
anonymously.<br><br>**[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.<br><br>**[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.<br><br>When a gadget is
removed from a dashboard, other gadgets in the same column are moved up
to fill the emptied position.<br><br>**[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.<br><br>**[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: >-
{"errorMessa
# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-dashboard--openapi-original.yml