Cloud

Jira Cloud platform / Reference / REST API v3

Issue watchers

This resource represents users watching an issue. Use it to get details of users watching an issue as well as start and stop a user watching an issue.

Operations

POST/rest/api/3/issue/watching GET/rest/api/3/issue/{issueIdOrKey}/watchers POST/rest/api/3/issue/{issueIdOrKey}/watchers DEL/rest/api/3/issue/{issueIdOrKey}/watchers

POST

Get is watching issue bulk

Returns, for the user, details of the watched status of issues from a list. If an issue ID is invalid, the returned watched status is false.

This operation requires the Allow users to watch issues option to be ON. This option is set in General configuration for Jira. See Configuring Jira application options for details.

Permissions required:

Browse projects project permission for the project that the issue is in
If issue-level security is configured, issue-level security permission to view the issue.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:issue.watcher:jira, read:user:jira

Connect app scope required: WRITE

Request

Request bodyapplication/json

A list of issue IDs.

issueIds

array<string>

Required

Responses

Returned if the request is successful

application/json

BulkIssueIsWatching

A container for the watch status of a list of issues.

POST/rest/api/3/issue/watching

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "issueIds": [
    "10001",
    "10002",
    "10005"
  ]
}`;

const response = await api.asUser().requestJira(route`/rest/api/3/issue/watching`, {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "issuesIsWatching": {
    "10001": true,
    "10002": false,
    "10005": true
  }
}

GET

Get issue watchers

Returns the watchers for an issue.

This operation requires the Allow users to watch issues option to be ON. This option is set in General configuration for Jira. See Configuring Jira application options for details.

This operation can be accessed anonymously.

Permissions required:

Browse projects project permission for the project that the issue is ini
If issue-level security is configured, issue-level security permission to view the issue.
To see details of users on the watchlist other than themselves, View voters and watchers project permission for the project that the issue is in.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:issue.watcher:jira, read:user:jira, read:avatar:jira

Connect app scope required: READ

Request

Path parameters

issueIdOrKey

string

Required

Responses

Returned if the request is successful

application/json

Watchers

The details of watchers on an issue.

GET/rest/api/3/issue/{issueIdOrKey}/watchers

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/3/issue/{issueIdOrKey}/watchers`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "isWatching": false,
  "self": "https://your-domain.atlassian.net/rest/api/3/issue/EX-1/watchers",
  "watchCount": 1,
  "watchers": [
    {
      "accountId": "5b10a2844c20165700ede21g",
      "active": false,
      "displayName": "Mia Krystof",
      "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
    }
  ]
}

POST

Add watcher

Adds a user as a watcher of an issue by passing the account ID of the user. For example, "5b10ac8d82e05b22cc7d4ef5". If no user is specified the calling user is added.

This operation requires the Allow users to watch issues option to be ON. This option is set in General configuration for Jira. See Configuring Jira application options for details.

Permissions required:

Browse projects project permission for the project that the issue is in.
If issue-level security is configured, issue-level security permission to view the issue.
To add users other than themselves to the watchlist, Manage watcher list project permission for the project that the issue is in.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:jira-work

Granular:write:issue.watcher:jira

Connect app scope required: WRITE

Request

Path parameters

issueIdOrKey

string

Required

Request bodyapplication/json

The account ID of the user. Note that username cannot be used due to privacy changes.

string

Responses

Returned if the request is successful.

application/json

any

POST/rest/api/3/issue/{issueIdOrKey}/watchers

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `"<string>"`;

const response = await api.asUser().requestJira(route`/rest/api/3/issue/{issueIdOrKey}/watchers`, {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

DEL

Delete watcher

Deletes a user as a watcher of an issue.

This operation requires the Allow users to watch issues option to be ON. This option is set in General configuration for Jira. See Configuring Jira application options for details.

Permissions required:

Browse projects project permission for the project that the issue is in.
If issue-level security is configured, issue-level security permission to view the issue.
To remove users other than themselves from the watchlist, Manage watcher list project permission for the project that the issue is in.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:jira-work

Granular:write:issue.watcher:jira

Connect app scope required: DELETE

Request

Path parameters

issueIdOrKey

string

Required

Query parameters

username

string

accountId

string

Responses

Returned if the request is successful.

DEL/rest/api/3/issue/{issueIdOrKey}/watchers

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/3/issue/{issueIdOrKey}/watchers?accountId=5b10ac8d82e05b22cc7d4ef5`, {
  method: 'DELETE'
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.text());