Work with Watchers

Unlike most ScriptRunner operations, working with watchers is not supported by HAPI. Instead, you can manage watchers on existing work items using the native fetch API to call the Jira REST API directly. This page walks you through updating watchers using direct REST calls.

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.