Updated on 2026-10-27 GMT+08:00

Favoriting a Work Item

Function

This API is used to favorite a work item.

Calling Method

For details, see Calling APIs.

Authorization Information

No identity policy-based permission required for calling this API.

URI

POST /v2/issues/watch

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. Obtain a token by calling the IAM API for obtaining a user token. The value of X-Subject-Token in the response header is the user token. Constraints N/A Range The value contains 10 to 32,768 characters. Default Value N/A

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
type	Yes	String	Definition: Type of the current project. Constraints: N/A Value range: SCRUM Default value: N/A
issue_id	No	String	Definition Work item ID, which can be obtained from the API for performing advanced query of work items. The value of the id field in the response body is the work item ID. Constraints A string of 1 to 10 digits. Range 1 to 10 characters. Default Value N/A

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
result	result object	Definition: Returned result of favoriting a work item.
status	String	Definition: Status of the current request. Value range: success: successful error: failed

**Table 4** result
Parameter	Type	Description
watcher	watcher object	Definition: Structure of a favorited work item.

**Table 5** watcher
Parameter	Type	Description
id	Integer	Definition Unique ID of the current favoriting record. Range N/A
watchable_type	String	Definition: Type of a favorited work item. Value range: Issue (favorited work item) project (favorited project)
watchable_id	Integer	Definition ID of the favorited work item or project. Range N/A
user_id	Integer	Definition User ID of a favoriter. Range N/A
region	String	Definition: Region where the current project is located. Value range: N/A

Example Requests

POST https://{endpoint}/v2/issues/watch?_=1754368218398

{
  "issue_id" : 9192160,
  "type" : "scrum"
}

Example Responses

Status code: 200

{
  "result" : {
    "watcher" : {
      "id" : 226991,
      "watchable_type" : "Issue",
      "watchable_id" : 9192160,
      "user_id" : 4091,
      "region" : "example"
    }
  },
  "status" : "success"
}

Status Codes

Status Code	Description
200	Response body of the current request.

Error Codes

See Error Codes.

Parent topic: Work Items of a Scrum Project