This is the reference document for the REST API and resources provided by Notifications and Tasks. The REST APIs are developers who want to integrate Notifications and Tasks with other standalone or web applications, and administrators who want to script interactions with the Notifications and Tasks server.
Notifications and Tasks REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will
make an HTTP request and parse the response. The Notifications and Tasks REST API uses
JSON as its communication format, and the standard HTTP methods like
GET, PUT, POST and DELETE (see API descriptions below for which
methods are available for each resource). URIs for Notifications and Tasks REST API resource have the following structure:
http://host:port/context/rest/api-name/api-version/resource-name
The current API version is 1. However, there is also a symbolic version, called latest,
which resolves to the latest version supported by the given instance.
There is a WADL document that contains the documentation for each resource in the Notifications and Tasks REST API. It is available here.
This documents the current REST API provided by Notifications and Tasks.
Direct endpoint for inline actions, will then forward to the correct client or run locally. Currently this relies on clients being registered as application links, and storing the ID on each notification.
Executes an inline action for a specific notification. Returning a resultUrl is optional, and will allow the action to link to object created by this action, such as a new comment.
acceptable request representations:
{"id": "1234", "qualifiedAction": "comment", "metadata": {}}available response representations:
{"successful": true, "resultUrl": "http://url/to/issue"}Stable endpoint for clients that need to register or ping the host.
Updates the registration of the given client id. This will trigger a call to the client registration endpoint which is then stored on the host.
acceptable request representations:
available response representations:
"bf13be6c-926b-318e-95cc-99dc04f8597e"Client was registered successfully.
Handles the configuration required for notifications which have been sent from various clients. Each client may register global configuration, which is then cached by the host. This include i18n values, actions and various URL paths.
Returns the list of registered application links and their corresponding registration details for the current locale.
available response representations:
[{"application":"bf13be6c-926b-318e-95cc-99dc04f8597e","appId":"com.atlassian.confluence","url":"https://jira.atlassian.com","i18n":{},"actions":{"openLink":{"name":"Open","type":"link","objectActions":["page","blog","comment"],"actions":["page.comment","blog.comment"]}},"properties":{"com.atlassian.confluence.blog.task.remove":"/images/icons/inline-tasks/inline-task.png","com.atlassian.confluence.user_url":"/users/viewuserprofile.action?username={username}"}}]Handlers host-agnostic user services. This is currently only used by the Chrome extension.
Retrieves the currently logged in user.
available response representations:
{"username": "joesmith123"}This class provides a REST interface for NotificationService
Retrieve a list of notifications as a flat list.
| parameter | value | description |
|---|---|---|
after | Optional notification id for returning only notifications created after the specified notification. This can be used to reduce both network traffic and seek time. | |
before | Optional notification id for returning only notifications created before the specified notification. This can be used to reduce both network traffic and seek time. | |
limit | Number of results to return, defaults to {@link #DEFAULT_LIMIT}. | |
bypass | Optional username for allowing administrators to find notifications on behalf of other users. |
available response representations:
[{"id":0,"applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","title":"John commented on an issue","description":"This looks good","application":"com.atlassian.jira","entity":"issue","action":"comment","created":0,"updated":0,"status":"DONE","groupingId":"1234","globalId":"1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/browse/","title":"WDAY-833: No description/sub-text in header","url":"https://jira.atlassian.com/browse/WDAY-833"},"read":false,"pinned":false}]Creates or updates a notification.
| parameter | value | description |
|---|---|---|
bypass | Optional username for allowing administrators to create notifications on behalf of other users. |
acceptable request representations:
{"id":0,"applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","title":"John commented on an issue","description":"This looks good","application":"com.atlassian.jira","entity":"issue","action":"comment","created":0,"updated":0,"status":"DONE","groupingId":"1234","globalId":"1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/browse/","title":"WDAY-833: No description/sub-text in header","url":"https://jira.atlassian.com/browse/WDAY-833"},"read":false,"pinned":false}available response representations:
{"id":0,"applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","title":"John commented on an issue","description":"This looks good","application":"com.atlassian.jira","entity":"issue","action":"comment","created":0,"updated":0,"status":"DONE","groupingId":"1234","globalId":"1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/browse/","title":"WDAY-833: No description/sub-text in header","url":"https://jira.atlassian.com/browse/WDAY-833"},"read":false,"pinned":false}Set the id of the last notification that has been seen. This determines the count of unread notifications that is shown.
Note that this distinct from the number of notifications that are "unread", which must be marked individually.
acceptable request representations:
104available response representations:
Updates the metadata for any notification with a given globalId (and matching the provided condition).
acceptable request representations:
{"globalId":"test","condition":{"watching":"true"},"metadata":{"user":"John Smith","watching":"false"}}available response representations:
Retrieve a list of nested notifications, aggregated by their groupingId.
| parameter | value | description |
|---|---|---|
after | Optional notification id for returning only notifications created after the specified notification. This can be used to reduce both network traffic and seek time. | |
before | Optional notification id returning only notifications created before the specified notification. This can be used to reduce both network traffic and seek time. | |
limit | Number of results to return, defaults to {@link #DEFAULT_LIMIT}. |
available response representations:
[{"item":{"iconUrl":"https://jira.atlassian.com/browse/","title":"WDAY-833: No description/sub-text in header","url":"https://jira.atlassian.com/browse/WDAY-833","applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","application":"com.atlassian.jira","entity":"issue","action":"comment","groupingId":"1234","aggregateKey":"key","pinned":false},"notifications":[{"id":0,"title":"John commented on an issue","description":"This looks good","url":"https://jira.atlassian.com/browse/WDAY-833","globalId":"1234","metadata":{"user":"John Smith"},"created":0,"updated":0,"status":"DONE","read":false,"pinned":false}]}]Set the id of the last notification that has been seen. This determines the count of unread notifications that is shown.
Note that this distinct from the number of notifications that are "unread", which must be marked individually.
acceptable request representations:
104available response representations:
| parameter | value | description |
|---|---|---|
id | Notification id |
Deletes a notification permanently.
available response representations:
Retrieve a specific notification.
available response representations:
{"id":0,"applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","title":"John commented on an issue","description":"This looks good","application":"com.atlassian.jira","entity":"issue","action":"comment","created":0,"updated":0,"status":"DONE","groupingId":"1234","globalId":"1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/browse/","title":"WDAY-833: No description/sub-text in header","url":"https://jira.atlassian.com/browse/WDAY-833"},"read":false,"pinned":false}| parameter | value | description |
|---|---|---|
id | Notification that is being updated. |
Changes the status of a notification. If the status is being changed to {@link Status#TODO} this will result in a new task being created.
acceptable request representations:
"DONE"available response representations:
{"id":0,"applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","title":"John commented on an issue","notes":"This looks good","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"1234","metadata":{"user":"John Smith"},"item":{"title":"WDAY-833: No description/sub-text in header"}}This resource returns the status of a user's notifications.
Retrieves the count of unseen notifications, as well as the current timeout which needs to be respected by polling clients.
available response representations:
{"count":7,"timeout":60,"maxTimeout":300}Retrieves the count of unseen notifications, as well as the current timeout which needs to be respected by polling clients.
available response representations:
{"count":7,"timeout":60,"maxTimeout":300}Retrieves just the count of unseen notifications.
available response representations:
7This resource provides all the relevant endpoints for anything task-related.
Deletes a single task.
| parameter | value | description |
|---|---|---|
bypass | Optional username for allowing administrators to delete tasks on behalf of other users. | |
globalId |
available response representations:
Retrieve all the tasks for the current user.
| parameter | value | description |
|---|---|---|
bypass | Optional username for allowing administrators to find tasks on behalf of other users. |
available response representations:
[{"id":0,"applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","title":"John commented on an issue","notes":"This looks good","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"1234","metadata":{"user":"John Smith"},"item":{"title":"WDAY-833: No description/sub-text in header"}}]Create or update an individual task or a list of tasks.
If there exists a task with the same globalId, the existing task will be updated. Otherwise a new task is created.
| parameter | value | description |
|---|---|---|
bypass | Optional username for allowing administrators to create tasks on behalf of other users. |
acceptable request representations:
[{"id":0,"applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","title":"John commented on an issue","notes":"This looks good","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"1234","metadata":{"user":"John Smith"},"item":{"title":"WDAY-833: No description/sub-text in header"}}]available response representations:
[{"id":0,"applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","title":"John commented on an issue","notes":"This looks good","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"1234","metadata":{"user":"John Smith"},"item":{"title":"WDAY-833: No description/sub-text in header"}}]Retrieve the number of currently assigned tasks.
| parameter | value | description |
|---|---|---|
completed | A flag to indicate whether to include completed tasks or incompleted tasks, defaulting to including all tasks. |
available response representations:
10| parameter | value | description |
|---|---|---|
globalId | of task |
Retrieve a task by a specified globalId.
available response representations:
{"id":0,"applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","title":"John commented on an issue","notes":"This looks good","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"1234","metadata":{"user":"John Smith"},"item":{"title":"WDAY-833: No description/sub-text in header"}}| parameter | value | description |
|---|---|---|
id | Task id |
Deletes a single task.
| parameter | value | description |
|---|---|---|
bypass | Optional username for allowing administrators to delete tasks on behalf of other users. |
available response representations:
Update a single task.
acceptable request representations:
{"id":0,"applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","title":"John commented on an issue","notes":"This looks good","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"1234","metadata":{"user":"John Smith"},"item":{"title":"WDAY-833: No description/sub-text in header"}}available response representations:
{"id":0,"applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","title":"John commented on an issue","notes":"This looks good","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"1234","metadata":{"user":"John Smith"},"item":{"title":"WDAY-833: No description/sub-text in header"}}| parameter | value | description |
|---|---|---|
id | Task id |
| parameter | value | description |
|---|---|---|
id | Task id |