• Announcement banner
  • App data policies (EAP)
  • Application roles
  • Audit records
  • Avatars
  • Classification levels
  • Dashboards
  • Filters
  • Filter sharing
  • Group and user picker
  • Groups
  • Issues
  • UI modifications (apps)
  • Issue attachments
  • Issue comments
  • Issue comment properties
  • Issue fields
  • Issue field configurations
  • Issue custom field contexts
  • Issue custom field options
  • Issue custom field options (apps)
  • Issue custom field values (apps)
  • Issue custom field configuration (apps)
  • Issue navigator settings
  • Issue notification schemes
  • Issue priorities
  • Issue properties
  • Issue resolutions
  • Issue security level
  • Issue security schemes
  • Issue types
  • Issue type schemes
  • Issue type screen schemes
  • Issue type properties
  • Issue votes
  • Issue watchers
  • Issue worklogs
  • Issue worklog properties
  • Jira expressions
  • Jira settings
  • JQL
  • JQL functions (apps)
  • Labels
  • License metrics
  • Myself
  • Permissions
  • Permission schemes
  • Projects
  • Project avatars
  • Project categories
  • Project classification levels
  • Project components
  • Project email
  • Project features
  • Project key and name validation
  • Project permission schemes
  • Project properties
  • Project roles
  • Project role actors
  • Project types
  • Project versions
  • Screens
  • Screen tabs
  • Screen tab fields
  • Screen schemes
  • Server info
  • Status
  • Tasks
  • Time tracking
  • Users
  • User properties
  • Webhooks
  • Workflows
  • Workflow transition rules
  • Workflow schemes
  • Workflow scheme project associations
  • Workflow scheme drafts
  • Workflow statuses
  • Workflow status categories
  • Workflow transition properties
  • App properties
  • Dynamic modules
  • App migration
  • Service Registry
Cloud
Jira Cloud platform / Reference / REST API v3 (beta)

Issue watchers

Postman Collection
OpenAPI

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.

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:

Data Security Policy: Not exempt from app access rules
Scopes

Connect app scope requiredWRITE

ClassicRECOMMENDED:read:jira-work
Granular:read:issue.watcher:jira, read:user:jira

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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 // 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
1 2 3 4 5 6 7 { "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:

Data Security Policy: Not exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:read:jira-work
Granular:read:issue.watcher:jira, read:user:jira, read:avatar:jira

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
1 2 3 4 5 6 7 8 9 10 11 12 // 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
1 2 3 4 5 6 7 8 9 10 11 12 13 { "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:

Data Security Policy: Not exempt from app access rules
Scopes

Connect app scope requiredWRITE

ClassicRECOMMENDED:write:jira-work
Granular:write:issue.watcher:jira

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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 // 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:

Data Security Policy: Not exempt from app access rules
Scopes

Connect app scope requiredDELETE

ClassicRECOMMENDED:write:jira-work
Granular:write:issue.watcher:jira

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
1 2 3 4 5 6 7 8 9 10 // 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());

Rate this page: