Updated on 2025-09-10 GMT+08:00

Favoriting a Work Item

Function

This API is used to favorite a work item.

Calling Method

For details, see Calling APIs.

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 the token by calling theObtaining a User TokenIAM API. In the returned response header, X-Subject-Token is the desired user token.

Constraints:

Mandatory.

Range:

Minimum length: 10 character. Maximum length: 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 Performing Advanced Query of Work Items API. The value of the id field in the response message body is the work item ID.

Constraints:

The value must contain 1 to 10 digits.

Value range:

Minimum length: 1 character. Maximum length: 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.

Value 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.

Value range:

N/A

user_id

Integer

Definition:

User ID of a favoriter.

Value range:

N/A

region

String

Definition:

Region where the current project is located.

Value range:

N/A

Example Requests

{endpoint}/v2/issues/watch?_=1754368218398

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

Example Responses

Status code: 200

Response body of the current request.

{
  "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.