openapi: 3.2.0 info: contact: email: ecosystem@atlassian.com description: Jira Cloud platform REST API documentation license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html termsOfService: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/ title: Jira Cloud platform REST Dashboards API version: 1001.0.0-SNAPSHOT-82b018affa468e58f284fbe4df33536469d757df servers: - url: https://your-domain.atlassian.net tags: - 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: Dashboards paths: /rest/api/3/dashboard: get: deprecated: false 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 required:** None.' operationId: getAllDashboards parameters: - description: "The filter applied to the list of dashboards. Valid values are:\n\n * `favourite` Returns dashboards the user has marked as favorite.\n * `my` Returns dashboards owned by the user." in: query name: filter schema: enum: - my - favourite 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: int32 type: integer - description: The maximum number of items to return per page. in: query name: maxResults schema: default: 20 format: int32 type: integer responses: '200': content: application/json: example: '{"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":[{"group":{"name":"administrators","self":"https://your-domain.atlassian.net/rest/api/3/group?groupname=administrators"},"id":10105,"type":"group"}],"view":"https://your-domain.atlassian.net/secure/Dashboard.jspa?selectPageId=20000"}],"maxResults":10,"next":"https://your-domain.atlassian.net/rest/api/3/dashboard?startAt=10","prev":"https://your-domain.atlassian.net/rest/api/3/dashboard?startAt=0","startAt":10,"total":143}' schema: $ref: '#/components/schemas/PageOfDashboards' description: Returned if the request is successful. '400': content: application/json: schema: $ref: '#/components/schemas/ErrorCollection' description: Returned if the request is invalid. '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: Get all 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 post: deprecated: false description: 'Creates a dashboard. **Permissions required:** None.' operationId: createDashboard parameters: - description: Whether admin level permissions are used. It should only be true if the user has *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg) in: query name: extendAdminPermissions schema: default: false type: boolean 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. security: - basicAuth: [] - OAuth2: - write:jira-work - {} summary: Create 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/bulk/edit: put: deprecated: false description: 'Bulk edit dashboards. Maximum number of dashboards to be edited at the same time is 100. **Permissions required:** None The dashboards to be updated must be owned by the user, or the user must be an administrator.' operationId: bulkEditDashboards 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: 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 required:** None.' operationId: getAllAvailableDashboardGadgets 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: 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 list of dashboards. This operation is similar to Get dashboards 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 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: - 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:\n\n * `description` Sorts by dashboard description. Note that this sort works independently of whether the expand to display the description field is in use.\n * `favourite_count` Sorts by dashboard popularity.\n * `id` Sorts by dashboard ID.\n * `is_favourite` Sorts by whether the dashboard is marked as a favorite.\n * `name` Sorts by dashboard name.\n * `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:\n\n * `description` Returns the description of the dashboard.\n * `owner` Returns the owner of the dashboard.\n * `viewUrl` Returns the URL that is used to view the dashboard.\n * `favourite` Returns `isFavourite`, an indicator of whether the user has set the dashboard as a favorite.\n * `favouritedCount` Returns `popularity`, a count of how many users have set this dashboard as a favorite.\n * `sharePermissions` Returns details of the share permissions defined for the dashboard.\n * `editPermissions` Returns details of the edit permissions defined for the dashboard.\n * `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:\n\n * `orderBy` is invalid.\n * `expand` includes an invalid value.\n * `accountId` and `owner` are provided.\n * `groupname` and `groupId` are provided." '401': content: application/json: schema: $ref: '#/components/schemas/ErrorCollection' description: 401 response security: - basicAuth: [] - OAuth2: - read:jira-work - {} summary: 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 required:** None.' operationId: getAllGadgets 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: 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 required:** None.' operationId: addGadget 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: '{"color":"blue","id":10001,"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/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: 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 required:** None.' operationId: removeGadget 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: 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 required:** None.' operationId: updateGadget 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: 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 required:** The user must have read permission of the dashboard or have the dashboard shared with them.' operationId: getDashboardItemPropertyKeys 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: 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 required:** The user must have edit permission of the dashboard.' operationId: deleteDashboardItemProperty 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: 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. 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 and the Dashboard Item documentation. There is no resource to set or get dashboard items. This operation can be accessed anonymously. **Permissions required:** The user must have read permission of the dashboard or have the dashboard shared with them.' operationId: getDashboardItemProperty 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: 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. 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 and the Dashboard Item documentation. There is no resource to set or get dashboard items. The value of the request body must be a valid, non-empty JSON blob. The maximum length is 32768 characters. This operation can be accessed anonymously. **Permissions required:** The user must have edit permisson of the dashboard.' operationId: setDashboardItemProperty 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:\n\n * Request is invalid\n * Or if all of these conditions are met in the request:\n \n * The dashboard item has a spec URI and no complete module key\n * The value of propertyKey is equal to \"config\"\n * 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: 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 required:** None The dashboard to be deleted must be owned by the user.' operationId: deleteDashboard 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: 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 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 are considered owners of the System dashboard. The System dashboard is considered to be shared with all other users.' operationId: getDashboard 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: 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 required:** None The dashboard to be updated must be owned by the user.' operationId: updateDashboard parameters: - description: The ID of the dashboard to update. in: path name: id required: true schema: type: string - description: Whether admin level permissions are used. It should only be true if the user has *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg) in: query name: extendAdminPermissions schema: default: false type: boolean 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: 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 required:** None The dashboard to be copied must be owned by or shared with the user.' operationId: copyDashboard parameters: - in: path name: id required: true schema: type: string - description: Whether admin level permissions are used. It should only be true if the user has *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg) in: query name: extendAdminPermissions schema: default: false type: boolean 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: 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 components: schemas: ProjectCategory: additionalProperties: false description: A project category. properties: description: description: The description of the project category. type: string id: description: The ID of the project category. readOnly: true type: string name: description: The name of the project category. Required on create, optional on update. type: string self: description: The URL of the project category. format: uri readOnly: true type: string type: object SimpleLink: additionalProperties: false description: Details about the operations available in this version. properties: href: type: string iconClass: type: string id: type: string label: type: string styleClass: type: string title: type: string weight: format: int32 type: integer type: object xml: name: link User: additionalProperties: false description: "A user with details as permitted by the user's Atlassian Account privacy settings. However, be aware of these exceptions:\n\n * User record deleted from Atlassian: This occurs as the result of a right to be forgotten request. In this case, `displayName` provides an indication and other parameters have default values or are blank (for example, email is blank).\n * User record corrupted: This occurs as a results of events such as a server import and can only happen to deleted users. In this case, `accountId` returns *unknown* and all other parameters have fallback values.\n * User record unavailable: This usually occurs due to an internal service outage. In this case, all parameters have fallback values." properties: accountId: description: The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*. Required in requests. maxLength: 128 type: string accountType: description: "The user account type. Can take the following values:\n\n * `atlassian` regular Atlassian user account\n * `app` system account used for Connect applications and OAuth to represent external systems\n * `customer` Jira Service Desk account representing an external service desk" enum: - atlassian - app - customer - unknown readOnly: true type: string active: description: Whether the user is active. readOnly: true type: boolean appType: description: "The app type of the user account when accountType is 'app'. Can take the following values:\n\n * `service` Service Account\n * `agent` Rovo Agent Account\n * `unknown` Unknown app type" readOnly: true type: string applicationRoles: allOf: - $ref: '#/components/schemas/SimpleListWrapperApplicationRole' description: The application roles the user is assigned to. readOnly: true avatarUrls: allOf: - $ref: '#/components/schemas/AvatarUrlsBean' description: The avatars of the user. readOnly: true displayName: description: The display name of the user. Depending on the user’s privacy setting, this may return an alternative value. readOnly: true type: string emailAddress: description: The email address of the user. Depending on the user’s privacy setting, this may be returned as null. readOnly: true type: string expand: description: Expand options that include additional user details in the response. readOnly: true type: string xml: attribute: true groups: allOf: - $ref: '#/components/schemas/SimpleListWrapperGroupName' description: The groups that the user belongs to. readOnly: true guest: description: Whether the user is a guest. readOnly: true type: boolean key: description: This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. type: string locale: description: The locale of the user. Depending on the user’s privacy setting, this may be returned as null. readOnly: true type: string name: description: This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. type: string self: description: The URL of the user. format: uri readOnly: true type: string timeZone: description: The time zone specified in the user's profile. If the user's time zone is not visible to the current user (due to user's profile setting), or if a time zone has not been set, the instance's default time zone will be returned. readOnly: true type: string type: object xml: name: user ListWrapperCallbackGroupName: additionalProperties: false type: object DashboardGadgetUpdateRequest: additionalProperties: false description: The details of the gadget to update. properties: color: description: The color of the gadget. Should be one of `blue`, `red`, `yellow`, `green`, `cyan`, `purple`, `gray`, or `white`. type: string writeOnly: true position: allOf: - $ref: '#/components/schemas/DashboardGadgetPosition' description: The position of the gadget. title: description: The title of the gadget. type: string writeOnly: true type: object SharePermission: additionalProperties: false description: Details of a share permission for the filter. properties: group: allOf: - $ref: '#/components/schemas/GroupName' description: The group that the filter is shared with. For a request, specify the `groupId` or `name` property for the group. As a group's name can change, use of `groupId` is recommended. id: description: The unique identifier of the share permission. format: int64 readOnly: true type: integer project: allOf: - $ref: '#/components/schemas/Project' description: "The project that the filter is shared with. This is similar to the project object returned by [Get project](#api-rest-api-3-project-projectIdOrKey-get) but it contains a subset of the properties, which are: `self`, `id`, `key`, `assigneeType`, `name`, `roles`, `avatarUrls`, `projectType`, `simplified`. \nFor a request, specify the `id` for the project." role: allOf: - $ref: '#/components/schemas/ProjectRole' description: "The project role that the filter is shared with. \nFor a request, specify the `id` for the role. You must also specify the `project` object and `id` for the project that the role is in." type: description: "The type of share permission:\n\n * `user` Shared with a user.\n * `group` Shared with a group. If set in a request, then specify `sharePermission.group` as well.\n * `project` Shared with a project. If set in a request, then specify `sharePermission.project` as well.\n * `projectRole` Share with a project role in a project. This value is not returned in responses. It is used in requests, where it needs to be specify with `projectId` and `projectRoleId`.\n * `global` Shared globally. If set in a request, no other `sharePermission` properties need to be specified.\n * `loggedin` Shared with all logged-in users. Note: This value is set in a request by specifying `authenticated` as the `type`.\n * `project-unknown` Shared with a project that the user does not have access to. Cannot be set in a request." enum: - user - group - project - projectRole - global - loggedin - authenticated - project-unknown type: string user: allOf: - $ref: '#/components/schemas/UserBean' description: The user account ID that the filter is shared with. For a request, specify the `accountId` property for the user. required: - type type: object Scope: additionalProperties: true description: The projects the item is associated with. Indicated for items associated with [next-gen projects](https://confluence.atlassian.com/x/loMyO). properties: project: allOf: - $ref: '#/components/schemas/ProjectDetails' description: The project the item has scope in. readOnly: true type: description: The type of scope. enum: - PROJECT - TEMPLATE readOnly: true type: string type: object ListWrapperCallbackApplicationRole: additionalProperties: false type: object AvatarUrlsBean: additionalProperties: false properties: 16x16: description: The URL of the item's 16x16 pixel avatar. format: uri type: string 24x24: description: The URL of the item's 24x24 pixel avatar. format: uri type: string 32x32: description: The URL of the item's 32x32 pixel avatar. format: uri type: string 48x48: description: The URL of the item's 48x48 pixel avatar. format: uri type: string type: object ProjectPermissions: additionalProperties: false description: Permissions which a user has on a project. properties: canEdit: description: Whether the logged user can edit the project. readOnly: true type: boolean type: object Project: additionalProperties: false description: Details about a project. properties: archived: description: Whether the project is archived. readOnly: true type: boolean archivedBy: allOf: - $ref: '#/components/schemas/User' description: The user who archived the project. readOnly: true archivedDate: description: The date when the project was archived. format: date-time readOnly: true type: string assigneeType: description: The default assignee when creating issues for this project. enum: - PROJECT_LEAD - UNASSIGNED readOnly: true type: string avatarUrls: allOf: - $ref: '#/components/schemas/AvatarUrlsBean' description: The URLs of the project's avatars. readOnly: true components: description: List of the components contained in the project. items: $ref: '#/components/schemas/ProjectComponent' readOnly: true type: array deleted: description: Whether the project is marked as deleted. readOnly: true type: boolean deletedBy: allOf: - $ref: '#/components/schemas/User' description: The user who marked the project as deleted. readOnly: true deletedDate: description: The date when the project was marked as deleted. format: date-time readOnly: true type: string description: description: A brief description of the project. readOnly: true type: string email: description: An email address associated with the project. type: string expand: description: Expand options that include additional project details in the response. readOnly: true type: string xml: attribute: true favourite: description: Whether the project is selected as a favorite. type: boolean id: description: The ID of the project. type: string insight: allOf: - $ref: '#/components/schemas/ProjectInsight' description: Insights about the project. readOnly: true isPrivate: description: Whether the project is private from the user's perspective. This means the user can't see the project or any associated issues. readOnly: true type: boolean issueTypeHierarchy: allOf: - $ref: '#/components/schemas/Hierarchy' description: The issue type hierarchy for the project. readOnly: true issueTypes: description: List of the issue types available in the project. items: $ref: '#/components/schemas/IssueTypeDetails' readOnly: true type: array key: description: The key of the project. readOnly: true type: string landingPageInfo: allOf: - $ref: '#/components/schemas/ProjectLandingPageInfo' description: The project landing page info. readOnly: true lead: allOf: - $ref: '#/components/schemas/User' description: The username of the project lead. readOnly: true name: description: The name of the project. readOnly: true type: string permissions: allOf: - $ref: '#/components/schemas/ProjectPermissions' description: User permissions on the project readOnly: true projectCategory: allOf: - $ref: '#/components/schemas/ProjectCategory' description: The category the project belongs to. readOnly: true projectTypeKey: description: The [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes) of the project. enum: - software - service_desk - business - product_discovery readOnly: true type: string properties: additionalProperties: readOnly: true description: Map of project properties readOnly: true type: object retentionTillDate: description: The date when the project is deleted permanently. format: date-time readOnly: true type: string roles: additionalProperties: format: uri readOnly: true type: string description: The name and self URL for each role defined in the project. For more information, see [Create project role](#api-rest-api-3-role-post). readOnly: true type: object self: description: The URL of the project details. format: uri readOnly: true type: string simplified: description: Whether the project is simplified. readOnly: true type: boolean style: description: The type of the project. enum: - classic - next-gen readOnly: true type: string url: description: A link to information about this project, such as project documentation. readOnly: true type: string uuid: description: Unique ID for next-gen projects. format: uuid readOnly: true type: string versions: description: The versions defined in the project. For more information, see [Create version](#api-rest-api-3-version-post). items: $ref: '#/components/schemas/Version' readOnly: true type: array type: object xml: name: project 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 IssueTypeDetails: additionalProperties: false description: Details about an issue type. properties: avatarId: description: The ID of the issue type's avatar. format: int64 readOnly: true type: integer description: description: The description of the issue type. readOnly: true type: string entityId: description: Unique ID for next-gen projects. format: uuid readOnly: true type: string hierarchyLevel: description: Hierarchy level of the issue type. format: int32 readOnly: true type: integer iconUrl: description: The URL of the issue type's avatar. readOnly: true type: string id: description: The ID of the issue type. readOnly: true type: string name: description: The name of the issue type. readOnly: true type: string scope: allOf: - $ref: '#/components/schemas/Scope' description: Details of the next-gen projects the issue type is available in. readOnly: true self: description: The URL of these issue type details. readOnly: true type: string subtask: description: Whether this issue type is used to create subtasks. readOnly: true type: boolean type: object ProjectComponent: additionalProperties: false description: Details about a project component. properties: ari: description: Compass component's ID. Can't be updated. Not required for creating a Project Component. readOnly: true type: string assignee: allOf: - $ref: '#/components/schemas/User' description: The details of the user associated with `assigneeType`, if any. See `realAssignee` for details of the user assigned to issues created with this component. readOnly: true assigneeType: description: "The nominal user type used to determine the assignee for issues created with this component. See `realAssigneeType` for details on how the type of the user, and hence the user, assigned to issues is determined. Can take the following values:\n\n * `PROJECT_LEAD` the assignee to any issues created with this component is nominally the lead for the project the component is in.\n * `COMPONENT_LEAD` the assignee to any issues created with this component is nominally the lead for the component.\n * `UNASSIGNED` an assignee is not set for issues created with this component.\n * `PROJECT_DEFAULT` the assignee to any issues created with this component is nominally the default assignee for the project that the component is in.\n\nDefault value: `PROJECT_DEFAULT`. \nOptional when creating or updating a component." enum: - PROJECT_DEFAULT - COMPONENT_LEAD - PROJECT_LEAD - UNASSIGNED type: string description: description: The description for the component. Optional when creating or updating a component. type: string id: description: The unique identifier for the component. readOnly: true type: string isAssigneeTypeValid: description: Whether a user is associated with `assigneeType`. For example, if the `assigneeType` is set to `COMPONENT_LEAD` but the component lead is not set, then `false` is returned. readOnly: true type: boolean lead: allOf: - $ref: '#/components/schemas/User' description: The user details for the component's lead user. readOnly: true leadAccountId: description: The accountId of the component's lead user. The accountId uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*. maxLength: 128 type: string writeOnly: true leadUserName: description: This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. type: string metadata: additionalProperties: readOnly: true type: string description: Compass component's metadata. Can't be updated. Not required for creating a Project Component. readOnly: true type: object name: description: The unique name for the component in the project. Required when creating a component. Optional when updating a component. The maximum length is 255 characters. type: string project: description: The key of the project the component is assigned to. Required when creating a component. Can't be updated. type: string projectId: description: The ID of the project the component is assigned to. format: int64 readOnly: true type: integer realAssignee: allOf: - $ref: '#/components/schemas/User' description: The user assigned to issues created with this component, when `assigneeType` does not identify a valid assignee. readOnly: true realAssigneeType: description: "The type of the assignee that is assigned to issues created with this component, when an assignee cannot be set from the `assigneeType`. For example, `assigneeType` is set to `COMPONENT_LEAD` but no component lead is set. This property is set to one of the following values:\n\n * `PROJECT_LEAD` when `assigneeType` is `PROJECT_LEAD` and the project lead has permission to be assigned issues in the project that the component is in.\n * `COMPONENT_LEAD` when `assignee`Type is `COMPONENT_LEAD` and the component lead has permission to be assigned issues in the project that the component is in.\n * `UNASSIGNED` when `assigneeType` is `UNASSIGNED` and Jira is configured to allow unassigned issues.\n * `PROJECT_DEFAULT` when none of the preceding cases are true." enum: - PROJECT_DEFAULT - COMPONENT_LEAD - PROJECT_LEAD - UNASSIGNED readOnly: true type: string self: description: The URL of the component. format: uri readOnly: true type: string type: object xml: name: component ApplicationRole: additionalProperties: false description: Details of an application role. properties: defaultGroups: description: The groups that are granted default access for this application role. As a group's name can change, use of `defaultGroupsDetails` is recommended to identify a groups. items: type: string type: array uniqueItems: true defaultGroupsDetails: description: The groups that are granted default access for this application role. items: $ref: '#/components/schemas/GroupName' type: array defined: description: Deprecated. type: boolean groupDetails: description: The groups associated with the application role. items: $ref: '#/components/schemas/GroupName' type: array groups: description: The groups associated with the application role. As a group's name can change, use of `groupDetails` is recommended to identify a groups. items: type: string type: array uniqueItems: true hasUnlimitedSeats: type: boolean key: description: The key of the application role. type: string name: description: The display name of the application role. type: string numberOfSeats: description: The maximum count of users on your license. format: int32 type: integer platform: description: Indicates if the application role belongs to Jira platform (`jira-core`). type: boolean remainingSeats: description: The count of users remaining on your license. format: int32 type: integer selectedByDefault: description: Determines whether this application role should be selected by default on user creation. type: boolean userCount: description: The number of users counting against your license. format: int32 type: integer userCountDescription: description: The [type of users](https://confluence.atlassian.com/x/lRW3Ng) being counted against your license. type: string type: object VersionApprover: additionalProperties: true description: Contains details about a version approver. properties: accountId: description: The Atlassian account ID of the approver. readOnly: true type: string declineReason: description: A description of why the user is declining the approval. readOnly: true type: string description: description: A description of what the user is approving within the specified version. readOnly: true type: string status: description: The status of the approval, which can be *PENDING*, *APPROVED*, or *DECLINED* readOnly: true type: string 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 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 ProjectRoleUser: additionalProperties: false description: Details of the user associated with the role. properties: accountId: description: The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*. Returns *unknown* if the record is deleted and corrupted, for example, as the result of a server import. maxLength: 128 readOnly: true type: string type: object ErrorCollection: additionalProperties: false description: Error messages from an operation. properties: errorMessages: description: The list of error messages produced by this operation. For example, "input parameter 'key' must be provided" items: type: string type: array errors: additionalProperties: type: string description: 'The list of errors by parameter returned by the operation. For example,"projectKey": "Project keys must start with an uppercase letter, followed by one or more uppercase alphanumeric characters."' type: object status: format: int32 type: integer type: object Version: additionalProperties: false description: Details about a project version. properties: approvers: description: If the expand option `approvers` is used, returns a list containing the approvers for this version. items: $ref: '#/components/schemas/VersionApprover' readOnly: true type: array archived: description: Indicates that the version is archived. Optional when creating or updating a version. type: boolean description: description: The description of the version. Optional when creating or updating a version. The maximum size is 16,384 bytes. type: string driver: description: The Atlassian account ID of the version driver. Optional when creating or updating a version. If the expand option `driver` is used, returns the Atlassian account ID of the driver. type: string expand: description: "Use [expand](em>#expansion) to include additional information about version in the response. This parameter accepts a comma-separated list. Expand options include:\n\n * `operations` Returns the list of operations available for this version.\n * `issuesstatus` Returns the count of issues in this version for each of the status categories *to do*, *in progress*, *done*, and *unmapped*. The *unmapped* property contains a count of issues with a status other than *to do*, *in progress*, and *done*.\n * `driver` Returns the Atlassian account ID of the version driver.\n * `approvers` Returns a list containing approvers for this version.\n\nOptional for create and update." type: string xml: attribute: true id: description: The ID of the version. readOnly: true type: string issuesStatusForFixVersion: allOf: - $ref: '#/components/schemas/VersionIssuesStatus' description: If the expand option `issuesstatus` is used, returns the count of issues in this version for each of the status categories *to do*, *in progress*, *done*, and *unmapped*. The *unmapped* property contains a count of issues with a status other than *to do*, *in progress*, and *done*. readOnly: true moveUnfixedIssuesTo: description: The URL of the self link to the version to which all unfixed issues are moved when a version is released. Not applicable when creating a version. Optional when updating a version. format: uri type: string name: description: The unique name of the version. Required when creating a version. Optional when updating a version. The maximum length is 255 characters. type: string operations: description: If the expand option `operations` is used, returns the list of operations available for this version. items: $ref: '#/components/schemas/SimpleLink' readOnly: true type: array overdue: description: Indicates that the version is overdue. readOnly: true type: boolean project: description: Deprecated. Use `projectId`. type: string projectId: description: The ID of the project to which this version is attached. Required when creating a version. Not applicable when updating a version. format: int64 type: integer releaseDate: description: The release date of the version. Expressed in ISO 8601 format (yyyy-mm-dd). Optional when creating or updating a version. format: date type: string released: description: Indicates that the version is released. If the version is released a request to release again is ignored. Not applicable when creating a version. Optional when updating a version. type: boolean self: description: The URL of the version. format: uri readOnly: true type: string startDate: description: The start date of the version. Expressed in ISO 8601 format (yyyy-mm-dd). Optional when creating or updating a version. format: date type: string userReleaseDate: description: The date on which work on this version is expected to finish, expressed in the instance's *Day/Month/Year Format* date format. readOnly: true type: string userStartDate: description: The date on which work on this version is expected to start, expressed in the instance's *Day/Month/Year Format* date format. readOnly: true type: string type: object xml: name: version VersionIssuesStatus: additionalProperties: true description: Counts of the number of issues in various statuses. properties: done: description: Count of issues with status *done*. format: int64 readOnly: true type: integer inProgress: description: Count of issues with status *in progress*. format: int64 readOnly: true type: integer toDo: description: Count of issues with status *to do*. format: int64 readOnly: true type: integer unmapped: description: Count of issues with a status other than *to do*, *in progress*, and *done*. format: int64 readOnly: true type: integer type: object ProjectRole: additionalProperties: false description: Details about the roles in a project. properties: actors: description: The list of users who act in this role. items: $ref: '#/components/schemas/RoleActor' readOnly: true type: array admin: description: Whether this role is the admin role for the project. readOnly: true type: boolean currentUserRole: description: Whether the calling user is part of this role. type: boolean default: description: Whether this role is the default role for the project readOnly: true type: boolean description: description: The description of the project role. readOnly: true type: string id: description: The ID of the project role. format: int64 readOnly: true type: integer name: description: The name of the project role. type: string roleConfigurable: description: Whether the roles are configurable for this project. readOnly: true type: boolean scope: allOf: - $ref: '#/components/schemas/Scope' description: The scope of the role. Indicated for roles associated with [next-gen projects](https://confluence.atlassian.com/x/loMyO). readOnly: true self: description: The URL the project role details. format: uri readOnly: true type: string translatedName: description: The translated name of the project role. type: string type: object ProjectDetails: additionalProperties: false description: Details about a project. properties: avatarUrls: allOf: - $ref: '#/components/schemas/AvatarUrlsBean' description: The URLs of the project's avatars. readOnly: true id: description: The ID of the project. type: string key: description: The key of the project. readOnly: true type: string name: description: The name of the project. readOnly: true type: string projectCategory: allOf: - $ref: '#/components/schemas/UpdatedProjectCategory' description: The category the project belongs to. readOnly: true projectTypeKey: description: The [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes) of the project. enum: - software - service_desk - business - product_discovery readOnly: true type: string self: description: The URL of the project details. readOnly: true type: string simplified: description: Whether or not the project is simplified. readOnly: true type: boolean type: object BulkEditShareableEntityRequest: 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 changeOwnerDetails: allOf: - $ref: '#/components/schemas/BulkChangeOwnerDetails' description: The details of change owner action. entityIds: description: The id list of shareable entities to be changed. items: format: int64 type: integer type: array uniqueItems: true extendAdminPermissions: description: Whether the actions are executed by users with Administer Jira global permission. type: boolean permissionDetails: allOf: - $ref: '#/components/schemas/PermissionDetails' description: The permission details to be changed. required: - action - entityIds type: object PageOfDashboards: additionalProperties: false description: A page containing dashboard details. properties: dashboards: description: List of dashboards. items: $ref: '#/components/schemas/Dashboard' readOnly: true type: array maxResults: description: The maximum number of results that could be on the page. format: int32 readOnly: true type: integer next: description: The URL of the next page of results, if any. readOnly: true type: string prev: description: The URL of the previous page of results, if any. readOnly: true type: string startAt: description: The index of the first item returned on the page. format: int32 readOnly: true type: integer total: description: The number of results on the page. format: int32 readOnly: true type: integer type: object BulkEditActionError: additionalProperties: false description: Errors of bulk edit action. properties: errorMessages: description: The error messages. items: type: string type: array errors: additionalProperties: type: string description: The errors. type: object required: - errorMessages - errors type: object PropertyKey: additionalProperties: false description: Property key details. properties: key: description: The key of the property. readOnly: true type: string self: description: The URL of the property. readOnly: true type: string type: object SimpleListWrapperApplicationRole: additionalProperties: false properties: callback: $ref: '#/components/schemas/ListWrapperCallbackApplicationRole' items: items: $ref: '#/components/schemas/ApplicationRole' type: array max-results: format: int32 type: integer xml: attribute: true name: max-results pagingCallback: $ref: '#/components/schemas/ListWrapperCallbackApplicationRole' size: format: int32 type: integer xml: attribute: true type: object xml: name: list ProjectLandingPageInfo: additionalProperties: false properties: attributes: additionalProperties: type: string type: object boardId: format: int64 type: integer boardName: type: string projectKey: type: string projectType: type: string queueCategory: type: string queueId: format: int64 type: integer queueName: type: string simpleBoard: type: boolean simplified: type: boolean url: type: string type: object ProjectInsight: additionalProperties: false description: Additional details about a project. properties: lastIssueUpdateTime: description: The last issue update time. format: date-time readOnly: true type: string totalIssueCount: description: Total issue count. format: int64 readOnly: true type: integer type: object BulkChangeOwnerDetails: additionalProperties: false description: Details for changing owners of shareable entities properties: autofixName: description: Whether the name is fixed automatically if it's duplicated after changing owner. type: boolean newOwner: description: The account id of the new owner. type: string required: - autofixName - newOwner type: object UpdatedProjectCategory: additionalProperties: false description: A project category. properties: description: description: The name of the project category. readOnly: true type: string id: description: The ID of the project category. readOnly: true type: string name: description: The description of the project category. readOnly: true type: string self: description: The URL of the project category. readOnly: true type: string type: object SimplifiedHierarchyLevel: additionalProperties: false properties: aboveLevelId: description: 'The ID of the level above this one in the hierarchy. This property is deprecated, see [Change notice: Removing hierarchy level IDs from next-gen APIs](https://developer.atlassian.com/cloud/jira/platform/change-notice-removing-hierarchy-level-ids-from-next-gen-apis/).' format: int64 type: integer belowLevelId: description: 'The ID of the level below this one in the hierarchy. This property is deprecated, see [Change notice: Removing hierarchy level IDs from next-gen APIs](https://developer.atlassian.com/cloud/jira/platform/change-notice-removing-hierarchy-level-ids-from-next-gen-apis/).' format: int64 type: integer externalUuid: description: 'The external UUID of the hierarchy level. This property is deprecated, see [Change notice: Removing hierarchy level IDs from next-gen APIs](https://developer.atlassian.com/cloud/jira/platform/change-notice-removing-hierarchy-level-ids-from-next-gen-apis/).' format: uuid type: string hierarchyLevelNumber: format: int32 type: integer id: description: 'The ID of the hierarchy level. This property is deprecated, see [Change notice: Removing hierarchy level IDs from next-gen APIs](https://developer.atlassian.com/cloud/jira/platform/change-notice-removing-hierarchy-level-ids-from-next-gen-apis/).' format: int64 type: integer issueTypeIds: description: The issue types available in this hierarchy level. items: format: int64 type: integer type: array level: description: The level of this item in the hierarchy. format: int32 type: integer name: description: The name of this hierarchy level. type: string projectConfigurationId: description: 'The ID of the project configuration. This property is deprecated, see [Change oticen: Removing hierarchy level IDs from next-gen APIs](https://developer.atlassian.com/cloud/jira/platform/change-notice-removing-hierarchy-level-ids-from-next-gen-apis/).' format: int64 type: integer type: object DashboardDetails: additionalProperties: false description: Details of a dashboard. properties: description: description: The description of the dashboard. type: string editPermissions: description: The edit permissions for the dashboard. items: $ref: '#/components/schemas/SharePermission' type: array name: description: The name of the dashboard. type: string sharePermissions: description: The share permissions for the dashboard. items: $ref: '#/components/schemas/SharePermission' type: array required: - editPermissions - name - sharePermissions type: object UserBean: additionalProperties: false properties: accountId: description: The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*. maxLength: 128 type: string active: description: Whether the user is active. type: boolean avatarUrls: allOf: - $ref: '#/components/schemas/UserBeanAvatarUrls' description: The avatars of the user. displayName: description: The display name of the user. Depending on the user’s privacy setting, this may return an alternative value. type: string key: description: "This property is deprecated in favor of `accountId` because of privacy changes. See the [migration guide](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. \nThe key of the user." type: string name: description: "This property is deprecated in favor of `accountId` because of privacy changes. See the [migration guide](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. \nThe username of the user." type: string self: description: The URL of the user. format: uri type: string type: object 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 ProjectRoleGroup: additionalProperties: false description: Details of the group associated with the role. properties: displayName: description: The display name of the group. type: string groupId: description: The ID of the group. type: string name: description: The name of the group. As a group's name can change, use of `groupId` is recommended to identify the group. type: string type: object GroupName: additionalProperties: false description: Details about a group. properties: groupId: description: The ID of the group, which uniquely identifies the group across all Atlassian products. For example, *952d12c3-5b5b-4d04-bb32-44d383afc4b2*. type: - string - 'null' name: description: The name of group. type: string self: description: The URL for these group details. format: uri readOnly: true type: string 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 RoleActor: additionalProperties: false description: Details about a user assigned to a project role. properties: actorGroup: allOf: - $ref: '#/components/schemas/ProjectRoleGroup' readOnly: true actorUser: allOf: - $ref: '#/components/schemas/ProjectRoleUser' readOnly: true avatarUrl: description: The avatar of the role actor. format: uri readOnly: true type: string displayName: description: The display name of the role actor. For users, depending on the user’s privacy setting, this may return an alternative value for the user's name. readOnly: true type: string id: description: The ID of the role actor. format: int64 readOnly: true type: integer name: description: This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. readOnly: true type: string type: description: The type of role actor. enum: - atlassian-group-role-actor - atlassian-user-role-actor readOnly: true type: string type: object xml: name: projectRoleActor 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 DashboardGadgetPosition: additionalProperties: false description: Details of a gadget position. properties: The column position of the gadget.: format: int32 type: integer The row position of the gadget.: format: int32 type: integer required: - The column position of the gadget. - The row position of the gadget. type: object writeOnly: true AvailableDashboardGadget: additionalProperties: false description: The details of the available dashboard gadget. properties: moduleKey: description: The module key of the gadget type. readOnly: true type: string title: description: The title of the gadget. readOnly: true type: string uri: description: The URI of the gadget type. readOnly: true type: string required: - title type: object SimpleListWrapperGroupName: additionalProperties: false properties: callback: $ref: '#/components/schemas/ListWrapperCallbackGroupName' items: items: $ref: '#/components/schemas/GroupName' type: array max-results: format: int32 type: integer xml: attribute: true name: max-results pagingCallback: $ref: '#/components/schemas/ListWrapperCallbackGroupName' size: format: int32 type: integer xml: attribute: true type: object xml: name: list 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 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 UserBeanAvatarUrls: additionalProperties: false properties: 16x16: description: The URL of the user's 16x16 pixel avatar. format: uri type: string 24x24: description: The URL of the user's 24x24 pixel avatar. format: uri type: string 32x32: description: The URL of the user's 32x32 pixel avatar. format: uri type: string 48x48: description: The URL of the user's 48x48 pixel avatar. format: uri type: string type: object PermissionDetails: additionalProperties: false description: Details for permissions of shareable entities properties: editPermissions: description: The edit permissions for the shareable entities. items: $ref: '#/components/schemas/SharePermission' type: array sharePermissions: description: The share permissions for the shareable entities. items: $ref: '#/components/schemas/SharePermission' type: array required: - editPermissions - sharePermissions type: object Hierarchy: additionalProperties: false description: The project issue type hierarchy. properties: baseLevelId: description: 'The ID of the base level. This property is deprecated, see [Change notice: Removing hierarchy level IDs from next-gen APIs](https://developer.atlassian.com/cloud/jira/platform/change-notice-removing-hierarchy-level-ids-from-next-gen-apis/).' format: int64 type: integer levels: description: Details about the hierarchy level. items: $ref: '#/components/schemas/SimplifiedHierarchyLevel' readOnly: true type: array type: object xml: name: hierarchy DashboardGadgetSettings: additionalProperties: false description: Details of the settings for a dashboard gadget. properties: color: description: The color of the gadget. Should be one of `blue`, `red`, `yellow`, `green`, `cyan`, `purple`, `gray`, or `white`. type: string writeOnly: true ignoreUriAndModuleKeyValidation: description: Whether to ignore the validation of module key and URI. For example, when a gadget is created that is a part of an application that isn't installed. type: boolean writeOnly: true moduleKey: description: The module key of the gadget type. Can't be provided with `uri`. type: string writeOnly: true position: allOf: - $ref: '#/components/schemas/DashboardGadgetPosition' description: The position of the gadget. When the gadget is placed into the position, other gadgets in the same column are moved down to accommodate it. title: description: The title of the gadget. type: string writeOnly: true uri: description: The URI of the gadget type. Can't be provided with `moduleKey`. type: string writeOnly: true type: object securitySchemes: OAuth2: description: OAuth2 scopes for Jira flows: authorizationCode: authorizationUrl: https://auth.atlassian.com/authorize scopes: delete:async-task:jira: Delete asynchronous task. delete:attachment:jira: Delete issue attachments. delete:avatar:jira: Delete system and custom avatars. delete:comment.property:jira: Delete issue comment properties. delete:comment:jira: Delete issue comments. delete:dashboard.property:jira: Delete dashboard properties. delete:dashboard:jira: Delete dashboards. delete:field-configuration-scheme:jira: Delete field configuration schemes. delete:field-configuration:jira: Delete field configurations. delete:field.option:jira: Delete field options. delete:field:jira: Delete fields. delete:filter.column:jira: Delete filter columns. delete:filter:jira: Delete filters. delete:group:jira: Delete user groups. delete:issue-link-type:jira: Delete issue link types. delete:issue-link:jira: Delete issue links. delete:issue-type-scheme:jira: Delete issue type schemes. delete:issue-type-screen-scheme:jira: Delete issue type screen schemes. delete:issue-type.property:jira: Delete issue type properties. delete:issue-type:jira: Delete issue types. delete:issue-worklog.property:jira: Delete issue worklog properties. delete:issue-worklog:jira: Delete issue worklogs. delete:issue.property:jira: Delete issue properties. delete:issue.remote-link:jira: Delete issue remote links. delete:issue:jira: Delete issues. delete:permission-scheme:jira: Delete permission schemes. delete:permission:jira: Delete permissions. delete:project-category:jira: Delete project categories. delete:project-role:jira: Delete project roles. delete:project-version:jira: Delete project versions. delete:project.avatar:jira: Delete project avatars. delete:project.component:jira: Delete project components. delete:project.property:jira: Delete project properties. delete:project:jira: Delete projects and their details, such as issue types, project lead, and avatars. delete:screen-scheme:jira: Delete screen schemes. delete:screen-tab:jira: Delete screen tabs. delete:screen:jira: Delete screens. delete:screenable-field:jira: Delete screenable fields. delete:user-configuration:jira: Delete user configurations. delete:user.property:jira: Delete user properties. delete:webhook:jira: Delete webhooks. delete:workflow-scheme:jira: Delete workflow schemes. delete:workflow.property:jira: Delete workflow properties. delete:workflow:jira: Delete workflows. manage:jira-configuration: Configure Jira settings that require the Jira administrators permission, for example, create projects and custom fields, view workflows, manage issue link types. manage:jira-project: Create and edit project settings and create new project-level objects, for example, versions, components. manage:jira-webhook: Manage Jira webhooks. Enables an OAuth app to register and unregister dynamic webhooks in Jira. It also provides for fetching of registered webhooks. read:app-data:jira: Read app data. read:application-role:jira: View application roles. read:attachment:jira: View issue attachments. read:audit-log:jira: View audit logs. read:avatar:jira: View system and custom avatars. read:comment.property:jira: View issue comment properties. read:comment:jira: View issue comments. read:custom-field-contextual-configuration:jira: Read custom field contextual configurations. read:dashboard.property:jira: View dashboard properties. read:dashboard:jira: View dashboards. read:email-address:jira: View email addresses of all users regardless of the user's profile visibility settings. read:field-configuration-scheme:jira: View field configuration schemes. read:field-configuration:jira: Read field configurations. read:field.default-value:jira: View field default values. read:field.option:jira: View field options. read:field.options:jira: Read field options. read:field:jira: View fields. read:filter.column:jira: View filter columns. read:filter.default-share-scope:jira: View filter default share scopes. read:filter:jira: View filters. read:group:jira: View user groups. read:instance-configuration:jira: View instance configurations. read:issue-details:jira: View issue details. read:issue-event:jira: Read issue events. read:issue-field-values:jira: View issue field valueses. read:issue-link-type:jira: View issue link types. read:issue-link:jira: View issue links. read:issue-meta:jira: View issue meta. read:issue-security-level:jira: View issue security levels. read:issue-security-scheme:jira: View issue security schemes. read:issue-status:jira: View issue statuses. read:issue-type-hierarchy:jira: Read issue type hierarchies. read:issue-type-scheme:jira: View issue type schemes. read:issue-type-screen-scheme:jira: View issue type screen schemes. read:issue-type.property:jira: View issue type properties. read:issue-type:jira: View issue types. read:issue-worklog.property:jira: View issue worklog properties. read:issue-worklog:jira: View issue worklogs. read:issue.changelog:jira: View issue changelogs. read:issue.property:jira: View issue properties. read:issue.remote-link:jira: View issue remote links. read:issue.time-tracking:jira: View issue time trackings. read:issue.transition:jira: View issue transitions. read:issue.vote:jira: View issue votes. read:issue.votes:jira: View issue voteses. read:issue.watcher:jira: View issue watchers. read:issue:jira: View issues. read:jira-expressions:jira: View jira expressions. read:jira-user: View user information in Jira that you have access to, including usernames, email addresses, and avatars. read:jira-work: Read project and issue data. Search for issues and objects associated with issues (such as attachments and worklogs). read:jql:jira: View JQL. read:label:jira: View labels. read:license:jira: View licenses. read:notification-scheme:jira: View notification schemes. read:permission-scheme:jira: View permission schemes. read:permission:jira: View permissions. read:priority:jira: View priorities. read:project-category:jira: View project categories. read:project-role:jira: View project roles. read:project-type:jira: View project types. read:project-version:jira: View project versions. read:project.avatar:jira: Read project avatars. read:project.component:jira: View project components. read:project.email:jira: View project emails. read:project.feature:jira: Read project features. read:project.property:jira: View project properties. read:project:jira: View projects. read:resolution:jira: View resolutions. read:role:jira: View roles. read:screen-field:jira: View screen fields. read:screen-scheme:jira: View screen schemes. read:screen-tab:jira: View screen tabs. read:screen:jira: View screens. read:screenable-field:jira: View screenable fields. read:status:jira: View statuses. read:user-configuration:jira: View user configurations. read:user.columns:jira: View user columnses. read:user.property:jira: View user properties. read:user:jira: View users. read:webhook:jira: View webhooks. read:workflow-scheme:jira: View workflow schemes. read:workflow.property:jira: View workflow properties. read:workflow:jira: View workflows. send:notification:jira: Send notifications. validate:jql:jira: Validate JQL. write:app-data:jira: Write app data. write:attachment:jira: Create and update issue attachments. write:avatar:jira: Create and update system and custom avatars. write:comment.property:jira: Create and update issue comment properties. write:comment:jira: Create and update issue comments. write:custom-field-contextual-configuration:jira: Save custom field contextual configurations. write:dashboard.property:jira: Create and update dashboard properties. write:dashboard:jira: Create and update dashboards. write:field-configuration-scheme:jira: Create and update field configuration schemes. write:field-configuration:jira: Save field configurations. write:field.default-value:jira: Create and update field default values. write:field.option:jira: Create and update field options. write:field:jira: Create and update fields. write:filter.column:jira: Create and update filter columns. write:filter.default-share-scope:jira: Create and update filter default share scopes. write:filter:jira: Create and update filters. write:group:jira: Create and update user groups. write:instance-configuration:jira: Create and update instance configurations. write:issue-link-type:jira: Create and update issue link types. write:issue-link:jira: Create and update issue links. write:issue-type-scheme:jira: Create and update issue type schemes. write:issue-type-screen-scheme:jira: Create and update issue type screen schemes. write:issue-type.property:jira: Create and update issue type properties. write:issue-type:jira: Create and update issue types. write:issue-worklog.property:jira: Create and update issue worklog properties. write:issue-worklog:jira: Create and update issue worklogs. write:issue.property:jira: Create and update issue properties. write:issue.remote-link:jira: Create and update issue remote links. write:issue.time-tracking:jira: Create and update issue time trackings. write:issue.vote:jira: Create and update issue votes. write:issue.watcher:jira: Create and update issue watchers. write:issue:jira: Create and update issues. write:jira-work: Create and edit issues in Jira, post comments, create worklogs, and delete issues. write:permission-scheme:jira: Create and update permission schemes. write:permission:jira: Create and update permissions. write:project-category:jira: Create and update project categories. write:project-role:jira: Create and update project roles. write:project-version:jira: Create and update project versions. write:project.avatar:jira: Create and update project avatars. write:project.component:jira: Create and update project components. write:project.email:jira: Create and update project emails. write:project.feature:jira: Save project features. write:project.property:jira: Create and update project properties. write:project:jira: Create and update projects. write:screen-scheme:jira: Create and update screen schemes. write:screen-tab:jira: Create and update screen tabs. write:screen:jira: Create and update screens. write:screenable-field:jira: Create and update screenable fields. write:user-configuration:jira: Create and update user configurations. write:user.property:jira: Create and update user properties. write:webhook:jira: Create and update webhooks. write:workflow-scheme:jira: Create and update workflow schemes. write:workflow.property:jira: Create and update workflow properties. write:workflow:jira: Create and update workflows. tokenUrl: https://auth.atlassian.com/oauth/token type: oauth2 basicAuth: description: You can access this resource via basic auth. scheme: basic type: http externalDocs: description: Find out more about Atlassian products and services. url: http://www.atlassian.com x-atlassian-narrative: documents: - anchor: about body: "The Jira REST API enables you to interact with Jira programmatically. Use this API to \n[build apps](https://developer.atlassian.com/cloud/jira/platform/integrating-with-jira-cloud/), script interactions with \nJira, or develop any other type of integration. This page documents the REST resources available in Jira Cloud, including \nthe 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\nversion. [Version 2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/) and\nversion 3 of the API offer the same collection of operations. However, version 3 provides support for\nthe [Atlassian Document Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)\n(ADF) in:\n- `body` in comments, including where comments are used in issue, issue link, and transition resources.\n- `comment` in worklogs.\n- `description` and `environment` fields in issues.\n- `textarea` type custom fields (multi-line text fields) in issues. Single line custom fields\n (`textfield`) accept a string and don't handle Atlassian Document Format content.\n" title: Version - anchor: authentication body: "### Forge apps\n\nFor Forge apps, [REST API scopes](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/) \nare 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.\n\nThe URIs for Forge app REST API calls have this structure:\n\n`/rest/api/3/`\n\nFor example, `/rest/api/3/issue/DEMO-1`\n\n### Connect apps\n\nFor Connect apps, authentication (JWT-based) is built into the Connect libraries. Authorization is implemented using either \nscopes (shown as _App scope required_ for operations on this page) or user impersonation. See \n[Security for Connect apps](https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/) \nfor details.\n\nThe URIs for Connect app REST API calls have this structure:\n\n`https:///rest/api/3/`\n\nFor example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`\n\n### Other integrations\n\nFor integrations that are not Forge or Connect apps, use OAuth 2.0 authorization code grants (3LO) for security \n(3LO scopes are shown as for operations _OAuth scopes required_). See \n[OAuth 2.0 (3LO) apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/) \nfor details.\n\nThe URIs for OAuth 2.0 (3LO) app REST API calls have this structure:\n\n`https://api.atlassian.com/ex/jira//rest/api/3/`\n\nFor example, `https://api.atlassian.com/ex/jira/35273b54-3f06-40d2-880f-dd28cf8daafa/rest/api/3/issue/DEMO-1`\n\n### Ad-hoc API calls\n\nFor 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. \n\nThe URIs for basic authentication REST API calls have this structure:\n\n`https:///rest/api/3/`\n\nFor example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`\n" title: Authentication and authorization - anchor: permissions body: "### Operation permissions\n\nMost operations in this API require permissions. The calling user must have the required permissions for an operation to \nuse it. Note that for Connect apps, the app user must have the required permissions for the operation and the app must \nhave scopes that permit the operation.\n\nA 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. \nSee [Permissions overview](https://confluence.atlassian.com/x/FQiiLQ) for details. The most common permissions are:\n\n- **Administer the Cloud site**: Users in the _site-admins_ group have this \npermission. See [Manage groups](https://confluence.atlassian.com/x/24xjL) for details.\n- **Administer Jira**: Granted by the _Jira Administrators_ global permission. There is a default group for this permission. \nSee [Manage groups](https://confluence.atlassian.com/x/24xjL) and [Managing global permissions](https://confluence.atlassian.com/x/x4dKLg) for details.\n- **Administer a project in Jira**: Granted by the _Administer projects_ project permission for a project. This can be \ngranted to a user, a group, a project role, and more. \nSee [Managing project permissions](https://confluence.atlassian.com/x/yodKLg) for details.\n- **Access a project in Jira**: Granted by the _Browse projects_ project permission for a project. This can be \ngranted to a user, a group, a project role, and more. \nSee [Managing project permissions](https://confluence.atlassian.com/x/yodKLg) for details.\n- **Access Jira**: Granted by the _Jira Users_ global permission. Users in the default product access group (for example, \n_jira-software-users-acmesite_) have this permission. \nSee [Manage groups](https://confluence.atlassian.com/x/24xjL) and \n[Managing global permissions](https://confluence.atlassian.com/x/x4dKLg) for details.\n\n### Anonymous access\n\nSome operations provide support for anonymous access. However, anonymous access is only available if \nthe Jira permission needed to access the object or records returned by the operation is granted to \nthe _Public_ group. See [Allowing anonymous access to your project](https://confluence.atlassian.com/x/GDxxLg) \nfor details.\n\nIf an operation is called anonymously and anonymous access is not available, the operation will return \nan error. Note that not all operations that correspond to objects that can be given public access \nprovide for anonymous access.\n" title: Permissions - anchor: expansion body: "### Expansion\n\nThe Jira REST API uses resource expansion, which means that some parts of a resource are not returned unless specified \nin the request. This simplifies responses and minimizes network traffic.\n\nTo expand part of a resource in a request, use the expand query parameter and specify the object(s) to be expanded. \nIf you need to expand nested objects, use the `.` dot notation. If you need to expand multiple objects, use a \ncomma-separated list. \n\nFor example, the following request expands the `names` and `renderedFields` properties for the _JRACLOUD-34423_ issue:\n\n`GET issue/JRACLOUD-34423?expand=names,renderedFields`\n\nTo discover which object can be expanded, refer to the `expand` property in the object. \nIn the JSON example below, the resource declares `widgets` as expandable.\n\n```json\n{\n \"expand\": \"widgets\", \n \"self\": \"https://your-domain.atlassian.net/rest/api/3/resource/KEY-1\", \n \"widgets\": {\n \"widgets\": [],\n \"size\": 5\n }\n}\n```\n\n### Pagination\n\nThe Jira REST API uses pagination to improve performance. Pagination is enforced for operations that could return a large \ncollection of items. When you make a request to a paginated resource, the response wraps the returned array of values in \na JSON object with paging metadata. For example:\n\n```json\n{\n \"startAt\" : 0,\n \"maxResults\" : 10,\n \"total\": 200,\n \"isLast\": false,\n \"values\": [\n { /* result 0 */ },\n { /* result 1 */ },\n { /* result 2 */ }\n ]\n}\n```\n\n* `startAt` is the index of the first item returned in the page.\n* `maxResults` is the maximum number of items that a page can return. Each operation can have a different limit for\n the number of items returned, and these limits may change without notice. To find the maximum number of items \n 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.\n* `total` is the total number of items contained in all pages. This number **_may change_** as the client \nrequests the subsequent pages, therefore the client should always assume that the requested page can be empty. Note \nthat this property is not returned for all operations.\n* `isLast` indicates whether the page returned is the last one. Note that this property is not returned for all operations.\n\n### Ordering\n\nSome operations support ordering the elements of a response by a field. Check the documentation for the operation to \nconfirm whether ordering of a response is supported and which fields can be used. Responses are listed in ascending order \nby default. You can change the order using the `orderby` query parameter with a `-` or `+` symbol. For example:\n\n* `?orderBy=name` to order by `name` field ascending.\n* `?orderBy=+name` to order by `name` field ascending.\n* `?orderBy=-name` to order by `name` field descending.\n\n\n" 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: " 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. \n\n 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 \nwill schedule an asynchronous task and return a `303 (See Other)` response, indicating the location of the queued task \nin the `Location` header. You can query this task to get progress updates.\n\nWhen the task finishes, the response object will contain the `result` field. The content of the field is specific to the \noperation that created the task. Refer to the operation’s documentation for more information.\n\nNote that asynchronous tasks are not guaranteed to be run in order. In other words, if you need your tasks to execute \nin 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. \nReport issues to [Developer and Marketplace support](https://developer.atlassian.com/support) (preferred) or use the \n**Give docs feedback** link at the top of this page. \n" 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).\n\nOperations that return an error status code may also return a response body containing details of the error or errors. \nThe schema for the response body is shown below:\n\n\n```json\n{\n \"id\": \"https://docs.atlassian.com/jira/REST/schema/error-collection#\",\n \"title\": \"Error Collection\",\n \"type\": \"object\",\n \"properties\": {\n \"errorMessages\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"errors\": {\n \"type\": \"object\",\n \"patternProperties\": {\n \".+\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"status\": { \n \"type\": \"integer\"\n }\n },\n \"additionalProperties\": false\n}\n```" title: Status codes