Work with Watchers

Learn how to add, remove, and list work item watchers by calling the Jira REST API with fetch, since HAPI doesn't support watchers.

For details of each watcher endpoint, see Issue watchers in the Jira Cloud REST API documentation.

Pattern for working with watchers

When you work with watchers, you can follow this basic pattern:

Use fetch with the DELETE method to remove a user as a watcher.
Use fetch with the POST method to add a user as a watcher.
Use fetch with the GET method to retrieve the current list of watchers.

Provide the work item key (issueIdOrKey) and the user's accountId in each request.

The following example shows this general pattern:

export default async function () {
  const issueIdOrKey = 'JRA-1'
  const accountId = 'ACCOUNT_ID'
 
  // Remove the user as a watcher (if they are currently watching)
  const deleteResponse = await fetch(
    `/rest/api/3/issue/${issueIdOrKey}/watchers?accountId=${encodeURIComponent(accountId)}`,
    { method: 'DELETE' },
  )
  if (!deleteResponse.ok && deleteResponse.status !== 404) {
    throw new Error(`Failed to remove watcher: ${deleteResponse.status}`)
  }
 
  // Add the same user as a watcher
  const addResponse = await fetch(`/rest/api/3/issue/${issueIdOrKey}/watchers`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(accountId),
  })
  if (!addResponse.ok) {
    throw new Error(`Failed to add watcher: ${addResponse.status}`)
  }
 
  // Return the current list of watchers on the work item
  const getResponse = await fetch(`/rest/api/3/issue/${issueIdOrKey}/watchers`)
  if (!getResponse.ok) {
    throw new Error(`Failed to get watchers: ${getResponse.status}`)
  }
 
  return getResponse.json()
}

In‑app example scripts

The following example is available in‑app:

Work with watchers: Shows how to use fetch with the DELETE and POST methods to remove and then re‑add a user as a watcher on a work item, and how to use fetch with the GET method to return the updated watcher list.