Atlassian Jira Notification Scheme API
The Atlassian Jira Notification Scheme API enables managing notification schemes for Jira projects.
OpenAPI Specification
components:
schemas:
PageBeanNotificationSchemeAndProjectMappingJsonBean:
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/NotificationSchemeAndProjectMappingJsonBean'
readOnly: true
type: array
type: object
NotificationScheme:
additionalProperties: false
description: Details about a notification scheme.
properties:
description:
description: The description of the notification scheme.
type: string
expand:
description: >-
Expand options that include additional notification scheme details
in the response.
type: string
id:
description: The ID of the notification scheme.
format: int64
type: integer
name:
description: The name of the notification scheme.
type: string
notificationSchemeEvents:
description: The notification events and associated recipients.
items:
$ref: '#/components/schemas/NotificationSchemeEvent'
type: array
projects:
description: The list of project IDs associated with the notification scheme.
items:
format: int64
type: integer
type: array
scope:
allOf:
- $ref: '#/components/schemas/Scope'
description: The scope of the notification scheme.
self:
type: string
type: object
externalDocs:
description: Find out more about Atlassian products and services.
url: http://www.atlassian.com
info:
contact:
email: [email protected]
description: Needs description.
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: http://atlassian.com/terms/
title: 'Atlassian rest/api/3/notificationscheme/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/notificationscheme/project:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) mapping of project that have
notification scheme assigned. You can provide either one or multiple
notification scheme IDs or project IDs to filter by. If you don't
provide any, this will return a list of all mappings. Note that only
company-managed (classic) projects are supported. This is because
team-managed projects don't have a concept of a default notification
scheme. The mappings are ordered by
projectId.<br><br>**[Permissions](#permissions) required:** Permission
to access Jira.
operationId: atlassianGetnotificationschemetoprojectmappings
parameters:
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: '0'
type: string
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: '50'
type: string
- description: The list of notifications scheme IDs to be filtered out
in: query
name: notificationSchemeId
schema:
items:
default: ''
type: string
type: array
uniqueItems: true
- description: The list of project IDs to be filtered out
in: query
name: projectId
schema:
items:
default: ''
type: string
type: array
uniqueItems: true
responses:
'200':
content:
application/json:
example: >-
{"isLast":true,"maxResults":50,"startAt":0,"total":4,"values":[{"notificationSchemeId":"10001","projectId":"100001"}]}
schema:
$ref: >-
#/components/schemas/PageBeanNotificationSchemeAndProjectMappingJsonBean
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: >-
Returned if search criteria are invalid, strings vs numbers for
projectId, notificationSchemeId, startAt and maxResult
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Projects Using Notification Schemes Paginated
tags:
- Issue Notification Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- read:notification-scheme:jira
- read:project:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/notificationscheme/{id}:
get:
deprecated: false
description: >-
Returns a [notification
scheme](https://confluence.atlassian.com/x/8YdKLg), including the list
of events and the recipients who will receive notifications for those
events.<br><br>**[Permissions](#permissions) required:** Permission to
access Jira, however, the user must have permission to administer at
least one project associated with the notification scheme.
operationId: atlassianGetnotificationscheme
parameters:
- description: >-
The ID of the notification scheme. Use [Get notification schemes
paginated](#api-rest-api-3-notificationscheme-get) to get a list of
notification scheme IDs.
in: path
name: id
required: true
schema:
format: int64
type: integer
- description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts a comma-separated list. Expand
options include:
* `all` Returns all expandable information
* `field` Returns information about any custom fields assigned to receive an event
* `group` Returns information about any groups assigned to receive an event
* `notificationSchemeEvents` Returns a list of event associations. This list is returned for all expandable information
* `projectRole` Returns information about any project roles assigned to receive an event
* `user` Returns information about any users assigned to receive an event
in: query
name: expand
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"description":"description","expand":"notificationSchemeEvents,user,group,projectRole,field,all","id":10100,"name":"notification
scheme
name","notificationSchemeEvents":[{"event":{"description":"Event
published when an issue is created","id":1,"name":"Issue
created"},"notifications":[{"expand":"group","group":{"groupId":"276f955c-63d7-42c8-9520-92d01dca0625","name":"jira-administrators","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"},"id":1,"notificationType":"Group","parameter":"jira-administrators","recipient":"276f955c-63d7-42c8-9520-92d01dca0625"},{"id":2,"notificationType":"CurrentAssignee"},{"expand":"projectRole","id":3,"notificationType":"ProjectRole","parameter":"10360","projectRole":{"self":"https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360","name":"Developers","id":10360,"description":"A
project role that represents developers in a
project","actors":[{"actorGroup":{"name":"jira-developers","displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2"},"displayName":"jira-developers","id":10240,"name":"jira-developers","type":"atlassian-group-role-actor"},{"actorUser":{"accountId":"5b10a2844c20165700ede21g"},"displayName":"Mia
Krystof","id":10241,"type":"atlassian-user-role-actor"}],"scope":{"project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"},"type":"PROJECT"}},"recipient":"10360"},{"emailAddress":"[email protected]","id":4,"notificationType":"EmailAddress","parameter":"[email protected]","recipient":"[email protected]"},{"expand":"user","id":5,"notificationType":"User","parameter":"5b10a2844c20165700ede21g","recipient":"5b10a2844c20165700ede21g","user":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia
Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"}},{"expand":"field","field":{"clauseNames":["cf[10101]","New
custom
field"],"custom":true,"id":"customfield_10101","key":"customfield_10101","name":"New
custom
field","navigable":true,"orderable":true,"schema":{"custom":"com.atlassian.jira.plugin.system.customfieldtypes:project","customId":10101,"type":"project"},"searchable":true,"untranslatedName":"New
custom
field"},"id":6,"notificationType":"GroupCustomField","parameter":"customfield_10101","recipient":"customfield_10101"}]},{"event":{"description":"Custom
event that is published together with an issue created
event","id":20,"name":"Custom
event","templateEvent":{"description":"Event published when an
issue is created","id":1,"name":"Issue
created"}},"notifications":[{"expand":"group","group":{"groupId":"276f955c-63d7-42c8-9520-92d01dca0625","name":"jira-administrators","self":"https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"},"id":1,"notificationType":"Group","parameter":"jira-administrators","recipient":"276f955c-63d7-42c8-9520-92d01dca0625"},{"id":2,"notificationType":"CurrentAssignee"},{"expand":"projectRole","id":3,"notificationType":"ProjectRole","parameter":"10360","projectRole":{"self":"https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360","name":"Developers","id":10360,"description":"A
project role that represents developers in a
project","actors":[{"actorGroup":{"name":"jira-developers","displayName":"jira-developers","groupId":"952d12c3-5b5b-4d04-bb32-44d383afc4b2"},"displayName":"jira-developers","id":10240,"name":"jira-developers","type":"atlassian-group-role-actor"},{"actorUser":{"accountId":"5b10a2844c20165700ede21g"},"displayName":"Mia
Krystof","id":10241,"type":"atlassian-user-role-actor"}],"scope":{"project":{"id":"10000","key":"KEY","name":"Next
Gen
Project"},"type":"PROJECT"}},"recipient":"10360"},{"emailAddress":"[email protected]","id":4,"notificationType":"EmailAddress","parameter":"[email protected]","recipient":"[email protected]"},{"expand":"user","id":5,"notificationType":"User","parameter":"5b10a2844c20165700ede21g","recipient":"5b10a2844c20165700ede21g","user":{"accountId":"5b10a2844c20165700ede21g","active":false,"displayName":"Mia
Krystof","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"}},{"expand":"field","field":{"clauseNames":["cf[10101]","New
custom
field"],"custom":true,"id":"customfield_10101","key":"customfield_10101","name":"New
custom
field","navigable":true,"orderable":true,"schema":{"custom":"com.atlassian.jira.plugin.system.customfieldtypes:project","customId":10101,"type":"project"},"searchable":true,"untranslatedName":"New
custom
field"},"id":6,"notificationType":"GroupCustomField","parameter":"customfield_10101","recipient":"customfield_10101"}]}],"projects":[10001,10002],"self":"https://your-domain.atlassian.net/rest/api/3/notificationscheme"}
schema:
$ref: '#/components/schemas/NotificationScheme'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the notification scheme is not found or the user does
not have permission to view it.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Notification Scheme
tags:
- Issue Notification Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- read:field:jira
- read:notification-scheme:jira
- read:project:jira
- read:project-role:jira
- read:user:jira
- read:avatar:jira
- read:field-configuration:jira
- read:group:jira
- read:project-category:jira
state: Beta
x-atlassian-connect-scope: ADMIN
put:
deprecated: false
description: >-
Updates a notification scheme.<br><br>**[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianUpdatenotificationscheme
parameters:
- description: The ID of the notification scheme.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
description: My updated notification scheme description
name: My updated notification scheme
schema:
$ref: '#/components/schemas/UpdateNotificationSchemeDetails'
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["The length of the description must not exceed
4000 characters."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request isn't valid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user doesn't have the necessary permission.
'404':
content:
application/json:
example: >-
{"errorMessages":["Notification scheme with ID 10000 not
found."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the notification scheme isn't found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Update Notification Scheme
tags:
- Issue Notification Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/notificationscheme/{id}/notification:
put:
deprecated: false
description: >-
Adds notifications to a notification scheme. You can add up to 1000
notifications per request.<br><br>*Deprecated: The notification type
`EmailAddress` is no longer supported in Cloud. Refer to the
[changelog](https://developer.atlassian.com/cloud/jira/platform/changelog/#CHANGE-1031)
for more details.*<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianAddnotifications
parameters:
- description: The ID of the notification scheme.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
notificationSchemeEvents:
- event:
id: '1'
notifications:
- notificationType: Group
parameter: jira-administrators
schema:
$ref: '#/components/schemas/AddNotificationsDetails'
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["Event type with ID 2 not
found."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request isn't valid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user doesn't have the necessary permission.
'404':
content:
application/json:
example: >-
{"errorMessages":["Notification scheme with ID 10001 not
found."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the notification scheme isn't found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Add Notifications To Notification Scheme
tags:
- Issue Notification Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/notificationscheme/{notificationSchemeId}:
delete:
deprecated: false
description: >-
Deletes a notification scheme.<br><br>**[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianDeletenotificationscheme
parameters:
- description: The ID of the notification scheme.
in: path
name: notificationSchemeId
required: true
schema:
type: string
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["You can’t delete the default notification
scheme."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request isn't valid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user doesn't have the necessary permission.
'404':
content:
application/json:
example: >-
{"errorMessages":["Notification scheme with ID 10000 not
found."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the notification scheme isn't found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Delete Notification Scheme
tags:
- Issue Notification Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/notificationscheme/{notificationSchemeId}/notification/{notificationId}:
delete:
deprecated: false
description: >-
Removes a notification from a notification
scheme.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianRemovenotificationfromnotificationscheme
parameters:
- description: The ID of the notification scheme.
in: path
name: notificationSchemeId
required: true
schema:
type: string
- description: The ID of the notification.
in: path
name: notificationId
required: true
schema:
type: string
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request isn't valid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["You are not authorized to perform this
action. Administrator privileges are required."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user doesn't have the necessary permission.
'404':
content:
application/json:
example: >-
{"errorMessages":["Notification scheme with ID 10000 not
found."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: >-
Returned if either the notification scheme or notification isn't
found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Remove Notification From Notification Scheme
tags:
- Issue Notification Schemes
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: ADMIN
servers:
- url: https://your-domain.atlassian.net
tags:
- name: Issue Notification Schemes
x-atlassian-narrative:
documents:
- anchor: about
body: >-
The Jira REST API enables you to interact with Jira programmatically.
Use this API to
[build
apps](https://developer.atlassian.com/cloud/jira/platform/integrating-with-jira-cloud/),
script interactions with
Jira, or develop any other type of integration. This page documents the
REST resources available in Jira Cloud, including
the HTTP response codes and example requests and responses.
title: About
- anchor: version
body: >
This documentation is for **version 3** of the Jira Cloud platform REST
API, which is the latest version
but is in **beta**. [Version
2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/) and
version 3 of the API offer the same collection of operations. However,
version 3 provides support for
the [Atlassian Document
Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
(ADF) in:
- `body` in comments, including where comments are used in issue, issue
link, and transition resources.
- `comment` in worklogs.
- `description` and `environment` fields in issues.
- `textarea` type custom fields (multi-line text fields) in issues.
Single line custom fields
(`textfield`) accept a string and don't handle Atlassian Document Format content.
However, these new features are under development and may change.
title: Version
- anchor: authentication
body: >
### Forge apps
For Forge apps, [REST API
scopes](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/)
are used when authenticating with Jira Cloud platform. See [Add scopes
to call an Atlassian REST
API](https://developer.atlassian.com/platform/forge/add-scopes-to-call-an-atlassian-rest-api/)
for more details.
The URIs for Forge app REST API calls have this structure:
`/rest/api/3/<resource-name>`
For example, `/rest/api/3/issue/DEMO-1`
### Connect apps
For Connect apps, authentication (JWT-based) is built into the Connect
libraries. Authorization is implemented using either
scopes (shown as _App scope required_ for operations on this page) or
user impersonation. See
[Security for Connect
apps](https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/)
for details.
The URIs for Connect app REST API calls have this structure:
`https://<site-url>/rest/api/3/<resource-name>`
For example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`
### Other integrations
For integrations that are not Forge or Connect apps, use OAuth 2.0
authorization code grants (3LO) for security
(3LO scopes are shown as for operations _OAuth scopes required_). See
[OAuth 2.0 (3LO)
apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)
for details.
The URIs for OAuth 2.0 (3LO) app REST API calls have this structure:
`https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/<resource-name>`
For example,
`https://api.atlassian.com/ex/jira/35273b54-3f06-40d2-880f-dd28cf8daafa/rest/api/3/issue/DEMO-1`
### Ad-hoc API calls
For personal scripts, bots, and ad-hoc execution of the REST APIs use
basic authentication. See [Basic auth for REST
APIs](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/)
for details.
The URIs for basic authentication REST API calls have this structure:
`https://<site-url>/rest/api/3/<resource-name>`
For example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`
title: Authentication and authorization
- anchor: permissions
body: >
### Operation permissions
Most operations in this API require permissions. The calling user must
have the required permissions for an operation to
use it. Note that for Connect apps, the app user must have the required
permissions for the operation and the app must
have scopes that permit the operation.
A permission can be granted to a group, project role, or issue role that
the user is a member of, or granted directly to a user.
See [Permissions overview](https://confluence.atlassian.com/x/FQiiLQ)
for details. The most common permissions are:
- **Administer the Cloud site**: Users in the _site-admins_ group have
this
permission. See [Manage
groups](https://confluence.atlassian.com/x/24xjL) for details.
- **Administer Jira**: Granted by the _Jira Administrators_ global
permission. There is a default group for this permission.
See [Manage groups](https://confluence.atlassian.com/x/24xjL) and
[Managing global permissions](https://confluence.atlassian.com/x/x4dKLg)
for details.
- **Administer a project in Jira**: Granted by the _Administer projects_
project permission for a project. This can be
granted to a user, a group, a project role, and more.
See [Managing project
permissions](https://confluence.atlassian.com/x/yodKLg) for details.
- **Access a project in Jira**: Granted by the _Browse projects_ project
permission for a project. This can be
granted to a user, a group, a project role, and more.
See [Managing project
permissions](https://confluence.atlassian.com/x/yodKLg) for details.
- **Access Jira**: Granted by the _Jira Users_ global permission. Users
in the default product access group (for example,
_jira-software-users-acmesite_) have this permission.
See [Manage groups](https://confluence.atlassian.com/x/24xjL) and
[Managing global permissions](https://confluence.atlassian.com/x/x4dKLg)
for details.
### Anonymous access
Some operations provide support for anonymous access. However, anonymous
access is only available if
the Jira permission needed to access the object or records returned by
the operation is granted to
the _Public_ group. See [Allowing anonymous access to your
project](https://confluence.atlassian.com/x/GDxxLg)
for details.
If an operation is called anonymously and anonymous access is not
available, the operation will return
an error. Note that not all operations that correspond to objects that
can be given public access
provide for anonymous access.
title: P
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-notificationscheme--openapi-original.yml