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:

  • application/json [expand]

    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
parametervaluedescription

appId

string

The applicationLinkId of the connecting instance.

available response representations:

  • 204 [expand]

    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
parametervaluedescription

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
parametervaluedescription

bypass

string

Optional username for allowing administrators to create notifications on behalf of other users.

acceptable request representations:

  • 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}

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:

  • application/json [expand]

    Example
    104

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:

  • application/json [expand]

    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
parametervaluedescription

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:

  • application/json [expand]

    Example
    104

available response representations:

/rest/notification/{id}

resource-wide template parameters
parametervaluedescription

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
parametervaluedescription

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:

  • application/json [expand]

    Example
    "DONE"

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
parametervaluedescription

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
parametervaluedescription

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
parametervaluedescription

bypass

string

Optional username for allowing administrators to create tasks on behalf of other users.

acceptable request representations:

  • 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"}}]

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
parametervaluedescription

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]

    Example
    10

/rest/task/globalId/{globalId}

resource-wide template parameters
parametervaluedescription

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
parametervaluedescription

id

long

Task id

Methods

DELETE

/rest/task/{id}?bypass

Deletes a single task.

request query parameters
parametervaluedescription

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:

  • 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"}}

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
parametervaluedescription

id

long

Task id

Methods

PUT

Update notes for a single task.

acceptable request representations:

  • application/json [expand]

    Example
    "This looks good"

available response representations:

  • 200 - application/json [expand]

    Example
    "This looks good"

/rest/task/{id}/position

resource-wide template parameters
parametervaluedescription

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:

  • application/json [expand]

    Example
    {"before": 8} or {"before": null}

available response representations:

/rest/timeout

Methods

GET

available response representations:

PUT

available response representations: