Notifications and Tasks REST API documentation
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.
Structure of the REST URIs
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.
Index
This documents the current REST API provided by Notifications and Tasks.
Resources
/rest/action
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.
Methods
POST
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:
Example
{
"id": "1234",
"qualifiedAction": "comment",
"metadata": {}
}
available response representations:
200 - application/json
[
expand]
Example
{
"successful": true,
"resultUrl": "http://url/to/issue"
}
/rest/action/task
Methods
POST
acceptable request representations:
available response representations:
/rest/client
Stable endpoint for clients that need to register or ping the host.
Methods
POST
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:
200 - application/json
[
expand]
Example
"bf13be6c-926b-318e-95cc-99dc04f8597e"
Client was registered successfully.
/rest/client/pong
Methods
POST
/rest/client/pong?appId
Registers a successful round-trip for user authentication.
request query parameters
| parameter | value | description |
|---|
appId | string | The applicationLinkId of the connecting instance. |
available response representations:
Pong was received successfully.
/rest/configuration
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.
Methods
GET
Returns the list of registered application links and their corresponding registration details for the current locale.
available response representations:
200 - application/json
[
expand]
Example
[
{
"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}"
}
}
]
/rest/loggedInUser
Handlers host-agnostic user services. This is currently only used by the Chrome extension.
Methods
GET
Retrieves the currently logged in user.
available response representations:
200 - application/json
[
expand]
Example
{
"username": "joesmith123"
}
/rest/notification
This class provides a REST interface for NotificationService
Methods
GET
/rest/notification?after&before&limit&bypass
Retrieve a list of notifications as a flat list.
request query parameters
| parameter | value | description |
|---|
after | long | 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 | long | 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 | int | Number of results to return, defaults to {@link #DEFAULT_LIMIT}. |
bypass | string | Optional username for allowing administrators to find notifications on behalf of other users. |
available response representations:
200 - application/json
[
expand]
Example
[
{
"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
}
]
POST
/rest/notification?bypass
Creates or updates a notification.
request query parameters
| parameter | value | description |
|---|
bypass | string | Optional username for allowing administrators to create notifications on behalf of other users. |
acceptable request representations:
Example
{
"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:
200 - application/json
[
expand]
Example
{
"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
}
/rest/notification/lastreadid
Methods
PUT
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:
available response representations:
/rest/notification/metadata
Methods
POST
Updates the metadata for any notification with a given globalId (and matching the provided condition).
acceptable request representations:
Example
{
"globalId": "test",
"condition": {
"watching": "true"
},
"metadata": {
"user": "John Smith",
"watching": "false"
}
}
available response representations:
/rest/notification/nested
Methods
GET
/rest/notification/nested?after&before&limit
Retrieve a list of nested notifications, aggregated by their groupingId.
request query parameters
| parameter | value | description |
|---|
after | long | 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 | long | Optional notification id returning only notifications created before the specified notification.
This can be used to reduce both network traffic and seek time. |
limit | int | Number of results to return, defaults to {@link #DEFAULT_LIMIT}. |
available response representations:
200 - application/json
[
expand]
Example
[
{
"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
}
]
}
]
/rest/notification/read
Methods
PUT
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:
available response representations:
/rest/notification/{id}
resource-wide template parameters
| parameter | value | description |
|---|
id | long | Notification id |
Methods
DELETE
Deletes a notification permanently.
available response representations:
GET
Retrieve a specific notification.
available response representations:
200 - application/json
[
expand]
Example
{
"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
}
/rest/notification/{id}/status
resource-wide template parameters
| parameter | value | description |
|---|
id | long | Notification that is being updated. |
Methods
PUT
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:
available response representations:
200 - application/json
[
expand]
Example
{
"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"
}
}
/rest/status
This resource returns the status of a user's notifications.
Methods
GET
Retrieves the count of unseen notifications, as well as the current timeout which needs to be respected by polling clients.
available response representations:
200 - application/json
[
expand]
Example
{
"count": 7,
"timeout": 60,
"maxTimeout": 300
}
/rest/status/notification/count
Methods
GET
Retrieves the count of unseen notifications, as well as the current timeout which needs to be respected by polling clients.
available response representations:
200 - application/json
[
expand]
Example
{
"count": 7,
"timeout": 60,
"maxTimeout": 300
}
/rest/status/notification/new
Methods
GET
Retrieves just the count of unseen notifications.
available response representations:
/rest/task
This resource provides all the relevant endpoints for anything task-related.
Methods
DELETE
/rest/task?bypass&globalId
Deletes a single task.
request query parameters
| parameter | value | description |
|---|
bypass | string | Optional username for allowing administrators to delete tasks on behalf of other users. |
globalId | string | |
available response representations:
GET
/rest/task?bypass
Retrieve all the tasks for the current user.
request query parameters
| parameter | value | description |
|---|
bypass | string | Optional username for allowing administrators to find tasks on behalf of other users. |
available response representations:
200 - application/json
[
expand]
Example
[
{
"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"
}
}
]
POST
/rest/task?bypass
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.
request query parameters
| parameter | value | description |
|---|
bypass | string | Optional username for allowing administrators to create tasks on behalf of other users. |
acceptable request representations:
Example
[
{
"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:
200 - application/json
[
expand]
Example
[
{
"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"
}
}
]
/rest/task/count
Methods
GET
/rest/task/count?completed
Retrieve the number of currently assigned tasks.
request query parameters
| parameter | value | description |
|---|
completed | boolean | A flag to indicate whether to include completed tasks or incompleted tasks, defaulting to including all tasks. |
available response representations:
200 - application/json
[
expand]
/rest/task/globalId/{globalId}
resource-wide template parameters
| parameter | value | description |
|---|
globalId | string | of task |
Methods
GET
Retrieve a task by a specified globalId.
available response representations:
200 - application/json
[
expand]
Example
{
"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"
}
}
/rest/task/{id}
resource-wide template parameters
| parameter | value | description |
|---|
id | long | Task id |
Methods
DELETE
/rest/task/{id}?bypass
Deletes a single task.
request query parameters
| parameter | value | description |
|---|
bypass | string | Optional username for allowing administrators to delete tasks on behalf of other users. |
available response representations:
PUT
Update a single task.
acceptable request representations:
Example
{
"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:
200 - application/json
[
expand]
Example
{
"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"
}
}
/rest/task/{id}/notes
resource-wide template parameters
| parameter | value | description |
|---|
id | long | Task id |
Methods
PUT
Update notes for a single task.
acceptable request representations:
available response representations:
200 - application/json
[
expand]
/rest/task/{id}/position
resource-wide template parameters
| parameter | value | description |
|---|
id | long | Task id |
Methods
PUT
Re-order a task, inserting it just before another specified one, or at the end of the list if the other specified
task id is null.
acceptable request representations:
Example
{"before": 8} or {"before": null}
available response representations:
/rest/timeout
Methods
GET
available response representations:
PUT
available response representations: