Workbox (Notifications and Tasks) REST API documentation

This is the reference document for the REST API and resources provided by Workbox. The REST APIs are developers who want to integrate Workbox with other standalone or web applications, and administrators who want to script interactions with the Workbox server.

Structure of the REST URIs

Workbox 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 Workbox 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 Workbox 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 Workbox REST API. It is available here.

Index

This documents the current REST API provided by Workbox (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":"Apples &amp; <strong>oranges</strong>","application":"com.atlassian.jira","entity":"issue","action":"comment","created":0,"updated":0,"status":"DONE","groupingId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","globalId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/images/icons/bug.gif","title":"JRA-1: Email addresses are case sensitive","url":"https://jira.atlassian.com/browse/JRA-1"},"read":false,"pinned":false}]

POST

/rest/notification?bypass

Creates or updates a notification.

URLs can be either absolute urls or a urls that start with '/' and are relative to the base url of the creating application. Relative urls are only supported for notifications that have a registration.

The only required field for a notification is 'title'.

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":"Apples &amp; <strong>oranges</strong>","application":"com.atlassian.jira","entity":"issue","action":"comment","created":0,"updated":0,"status":"DONE","groupingId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","globalId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/images/icons/bug.gif","title":"JRA-1: Email addresses are case sensitive","url":"https://jira.atlassian.com/browse/JRA-1"},"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":"Apples &amp; <strong>oranges</strong>","application":"com.atlassian.jira","entity":"issue","action":"comment","created":0,"updated":0,"status":"DONE","groupingId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","globalId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/images/icons/bug.gif","title":"JRA-1: Email addresses are case sensitive","url":"https://jira.atlassian.com/browse/JRA-1"},"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, with pre-rendered descriptions.

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/images/icons/bug.gif","title":"JRA-1: Email addresses are case sensitive","url":"https://jira.atlassian.com/browse/JRA-1","applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","application":"com.atlassian.jira","entity":"issue","action":"comment","groupingId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","aggregateKey":"key","pinned":false},"notifications":[{"id":0,"title":"John commented on an issue","description":"Apples &amp; <strong>oranges</strong>","globalId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","metadata":{"user":"John Smith"},"created":0,"updated":0,"status":"DONE","read":false,"pinned":false}]}]

/rest/notification/read

Methods

PUT

Marks a list of notifications as read.

acceptable request representations:

  • application/json [expand]

    Example
    [100, 101, 102]

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":"Apples &amp; <strong>oranges</strong>","application":"com.atlassian.jira","entity":"issue","action":"comment","created":0,"updated":0,"status":"DONE","groupingId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","globalId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/images/icons/bug.gif","title":"JRA-1: Email addresses are case sensitive","url":"https://jira.atlassian.com/browse/JRA-1"},"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":"Apples & oranges","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/images/icons/bug.gif","title":"JRA-1: Email addresses are case sensitive","url":"https://jira.atlassian.com/browse/JRA-1"}}

/rest/status

This resource returns the status of a user's notifications.

Methods

GET

/rest/status?pageid

Retrieves the count of unseen notifications, as well as the current timeout which needs to be respected by polling clients.

request query parameters
parametervaluedescription

pageid

long

optional pageId. If provided, will mark all notifications related to pageId as seen prior to returning the notification count

available response representations:

  • 200 - application/json [expand]

    Example
    {"count":7,"timeout":60,"maxTimeout":300}

/rest/status/notification/count

Methods

GET

/rest/status/notification/count?pageid

Retrieves the count of unseen notifications, as well as the current timeout which needs to be respected by polling clients.

request query parameters
parametervaluedescription

pageid

long

optional pageId. If provided, will mark all notifications related to pageId as seen prior to returning the notification count

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

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":"Apples & oranges","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/images/icons/bug.gif","title":"JRA-1: Email addresses are case sensitive","url":"https://jira.atlassian.com/browse/JRA-1"}}]

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.

URLs can be either absolute urls or a urls that start with '/' and are relative to the base url of the creating application. Relative urls are only supported for notifications that have a registration.

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":"Apples & oranges","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/images/icons/bug.gif","title":"JRA-1: Email addresses are case sensitive","url":"https://jira.atlassian.com/browse/JRA-1"}}]

available response representations:

  • 200 - application/json [expand]

    Example
    [{"id":0,"applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","title":"John commented on an issue","notes":"Apples & oranges","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/images/icons/bug.gif","title":"JRA-1: Email addresses are case sensitive","url":"https://jira.atlassian.com/browse/JRA-1"}}]

DELETE

/rest/task?bypass&globalId

Deletes a task with the matching globalId.

request query parameters
parametervaluedescription

bypass

string

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

globalId

string

of task to delete.

available response representations:

/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":"Apples & oranges","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/images/icons/bug.gif","title":"JRA-1: Email addresses are case sensitive","url":"https://jira.atlassian.com/browse/JRA-1"}}

/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":"Apples & oranges","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/images/icons/bug.gif","title":"JRA-1: Email addresses are case sensitive","url":"https://jira.atlassian.com/browse/JRA-1"}}

available response representations:

  • 200 - application/json [expand]

    Example
    {"id":0,"applicationLinkId":"bf13be6c-926b-318e-95cc-99dc04f8597e","title":"John commented on an issue","notes":"Apples & oranges","status":"TODO","application":"com.atlassian.jira","entity":"issue","created":0,"updated":0,"globalId":"appId=bf13be6c-926b-318e-95cc-99dc04f8597e&entity=issue&id=1234","metadata":{"user":"John Smith"},"item":{"iconUrl":"https://jira.atlassian.com/images/icons/bug.gif","title":"JRA-1: Email addresses are case sensitive","url":"https://jira.atlassian.com/browse/JRA-1"}}

/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
    "Apples &amp; <strong>oranges</strong>"

available response representations:

  • 200 - application/json [expand]

    Example
    "Apples &amp; <strong>oranges</strong>"

/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: