Help Center/ CodeArts Repo/ API Reference/ APIs/ V4/ ProtectedRefs/ Obtaining the Protected Branch List
Updated on 2026-04-28 GMT+08:00
View PDF

Obtaining the Protected Branch List

Function

This API is used to obtain protected branch list of a repository.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

URI

GET https://{hostURL}/v4/repositories/{repository_id}/protected-branches

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

repository_id

Yes

Integer

Definition

You can query the project list to obtain the repository ID by calling the API used to query user's all repositories.

Constraints

N/A.

Value range:

1~2147483647
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

offset

No

Integer

Definition

Offset, which starts from 0.

Value range:

0~2147483647

Default value:

0

limit

No

Integer

Definition

Number of returned records.

Value range:

1~100

Default value:

20

search

No

String

Definition:

Query keyword, which can be used for fuzzy match of the protected branch name.

Constraints:

N/A.

Value range:

N/A.

Default value:

N/A.

Default value:

N/A

Request Parameters

Table 3 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

Mandatory.

Range

1–100,000 characters.

Default Value

N/A.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

[items]

Array of RepositoryProtectedBranchDto objects

List of protected branches in a repository.
Table 5 RepositoryProtectedBranchDto

Parameter

Type

Description

id

Integer

Definition:

ID of the protected branch.

Value range:

1–2147483647

Value range:

1~2147483647

name

String

Definition:

Branch name or wildcard.

Value range:

N/A.

actions

Array of RepositoryProtectedActionDto objects

Definition:

Event list.

Value range:

N/A.
Table 6 RepositoryProtectedActionDto

Parameter

Type

Description

action

String

Definition:

Event name.

Value range:

N/A.

enable

Boolean

Definition:

Whether to enable.

Value range:

  • true: Yes.

  • false: No.

users

Array of RepositoryUserDto objects

Definition:

Whitelisted user list.

Value range:

N/A.

user_teams

Array of UserTeamBasicDto objects

Definition:

Whitelisted user group list.

Value range:

N/A.

roles

Array of BasicRoleDto objects

Definition:

Whitelisted role list.

Value range:

N/A.
Table 7 RepositoryUserDto

Parameter

Type

Description

id

Integer

Definition

User ID.

Value range:

1~2147483647

name

String

Definition

Username.

username

String

Definition

Username.

state

String

Definition:

User status

Value range:

  • active: activated

  • blocked: disabled

Enumeration values:

  • active

  • blocked

avatar_url

String

Definition:

Profile picture URL.

Value range:

N/A.

nick_name

String

Definition:

User alias.

Value range:

N/A.

tenant_name

String

Definition:

Tenant name.

Value range:

N/A.
Table 8 UserTeamBasicDto

Parameter

Type

Description

id

Integer

Definition:

User group ID.

Value range:

1–2147483647

name

String

Definition:

User group name.

Value range:

N/A.
Table 9 BasicRoleDto

Parameter

Type

Description

id

Integer

Definition:

Role ID.

Value range:

1–2147483647

name

String

Definition:

Role name.

Value range:

N/A.

related_role_id

String

Definition:

Associated role ID.

Value range:

N/A.

chinese_name

String

Definition:

Role name in Chinese.

Value range:

N/A.

Example Requests

None

Example Responses

Status code: 200

List of protected branches in a repository.

[ {
  "id" : 2112012342,
  "name" : "t*",
  "actions" : [ {
    "action" : "push",
    "enable" : true,
    "users" : [ {
      "id" : 9124,
      "name" : "test_user",
      "username" : "c369c68f1ff84679b5a8ed904d8bff1c",
      "state" : "active",
      "avatar_url" : "",
      "nick_name" : "user",
      "tenant_name" : "tenant"
    } ],
    "user_teams" : [ {
      "id" : 247,
      "name" : "team-1"
    } ],
    "roles" : [ {
      "id" : 23836589,
      "name" : "Committer",
      "related_role_id" : "8425999e92974f2980b76b08ad423aa1",
      "chinese_name" : "Committer"
    }, {
      "id" : 23836590,
      "name" : "Developer",
      "related_role_id" : "f2464b129b064a6a988734a73c3f366b",
      "chinese_name" : "Developer"
    }, {
      "id" : 23836594,
      "name" : "Project manager",
      "related_role_id" : "6115a3ddd9044e288c558d1ae827a732",
      "chinese_name" : "Project manager"
    }, {
      "id" : 23836597,
      "name" : "Test manager",
      "related_role_id" : "24f72d0b611746c3a43da596ea5065f5",
      "chinese_name" : "Test manager"
    } ]
  }, {
    "action" : "merge",
    "enable" : true,
    "users" : [ {
      "id" : 9493,
      "name" : "user",
      "username" : "84280e40b7974b9eaff329f8e43a5080",
      "state" : "active",
      "avatar_url" : "",
      "nick_name" : "user",
      "tenant_name" : "tenantName"
    } ],
    "user_teams" : [ {
      "id" : 247,
      "name" : "team-1"
    } ],
    "roles" : [ {
      "id" : 23836589,
      "name" : "Committer",
      "related_role_id" : "8425999e92974f2980b76b08ad423aa1",
      "chinese_name" : "Committer"
    }, {
      "id" : 23836590,
      "name" : "Developer",
      "related_role_id" : "f2464b129b064a6a988734a73c3f366b",
      "chinese_name" : "Developer"
    }, {
      "id" : 23836595,
      "name" : "Administrator",
      "related_role_id" : "7a96af96176e4f728f571b8af8551dec",
      "chinese_name" : "Project administrator"
    }, {
      "id" : 23836597,
      "name" : "Test manager",
      "related_role_id" : "24f72d0b611746c3a43da596ea5065f5",
      "chinese_name" : "Test manager"
    } ]
  } ]
}, {
  "id" : 2112012343,
  "name" : "tt*",
  "actions" : [ {
    "action" : "push",
    "enable" : true,
    "users" : [ {
      "id" : 9493,
      "name" : "user",
      "username" : "84280e40b7974b9eaff329f8e43a5080",
      "state" : "active",
      "avatar_url" : "",
      "nick_name" : "user",
      "tenant_name" : "tenantName"
    } ],
    "user_teams" : [ {
      "id" : 247,
      "name" : "team-1"
    } ],
    "roles" : [ {
      "id" : 23836589,
      "name" : "Committer",
      "related_role_id" : "8425999e92974f2980b76b08ad423aa1",
      "chinese_name" : "Committer"
    }, {
      "id" : 23836590,
      "name" : "Developer",
      "related_role_id" : "f2464b129b064a6a988734a73c3f366b",
      "chinese_name" : "Developer"
    }, {
      "id" : 23836594,
      "name" : "Project manager",
      "related_role_id" : "6115a3ddd9044e288c558d1ae827a732",
      "chinese_name" : "Project manager"
    }, {
      "id" : 23836597,
      "name" : "Test manager",
      "related_role_id" : "24f72d0b611746c3a43da596ea5065f5",
      "chinese_name" : "Test manager"
    } ]
  }, {
    "action" : "merge",
    "enable" : true,
    "users" : [ {
      "id" : 9493,
      "name" : "user",
      "username" : "84280e40b7974b9eaff329f8e43a5080",
      "state" : "active",
      "avatar_url" : "",
      "nick_name" : "user",
      "tenant_name" : "tenantName"
    } ],
    "user_teams" : [ {
      "id" : 247,
      "name" : "team-1"
    } ],
    "roles" : [ {
      "id" : 23836589,
      "name" : "Committer",
      "related_role_id" : "8425999e92974f2980b76b08ad423aa1",
      "chinese_name" : "Committer"
    }, {
      "id" : 23836590,
      "name" : "Developer",
      "related_role_id" : "f2464b129b064a6a988734a73c3f366b",
      "chinese_name" : "Developer"
    }, {
      "id" : 23836595,
      "name" : "Administrator",
      "related_role_id" : "7a96af96176e4f728f571b8af8551dec",
      "chinese_name" : "Project administrator"
    }, {
      "id" : 23836597,
      "name" : "Test manager",
      "related_role_id" : "24f72d0b611746c3a43da596ea5065f5",
      "chinese_name" : "Test manager"
    } ]
  } ]
} ]

Status Codes

Status Code

Description

200

List of protected branches in a repository.

Error Codes

See Error Codes.

Parent topic: ProtectedRefs