Help Center/ CodeArts Repo/ API Reference/ APIs/ V4/ Refs/ Creating a Branch

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

View PDF

Creating a Branch

Function

This API is used to create a branch.

Debugging

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

Authorization Information

Each account root user has all the permissions required to call all APIs, but IAM users must be assigned the following required identity policy-based permissions. For details about the required permissions, see Permissions Policies and Supported Actions.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
codeartsrepo:repository:createBranch	Write	-	-	-	-

URI

POST https://{hostURL}/v4/repositories/{repository_id}/repository/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 Default Value N/A Value range: 1~2147483647

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. Obtain one by calling the IAM API Obtaining a User Token. The value of X-Subject-Token in the response header is a token. Constraints N/A Range 1–100,000 characters. Default Value N/A

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
branch	Yes	String	Definition Branch name. Constraints Do not start with a hyphen (-), period (.) or refs/heads/refs/remotes/. Do not enter spaces or special characters such as [ \ < ~ ^ : ? * ! ( ) ' " \|. Do not end with / .lock. Range 1–200 characters. Default Value N/A.
ref	Yes	String	Definition Name of the branch to be based on. Constraints Do not start with a hyphen (-), period (.) or refs/heads/refs/remotes/. Do not enter spaces or special characters such as [ \ < ~ ^ : ? * ! ( ) ' " \|. Do not end with / .lock. Range 1–200 characters. Default Value N/A.
description	No	String	Definition Branch description. Constraints None. Range 1–2,000 characters. Default Value N/A.
related_ids	No	Array of strings	Definition Associated work item list. Constraints None. Range None. Default Value N/A.

Response Parameters

Status code: 201

**Table 4** Response body parameters
Parameter	Type	Description
name	String	Branch name Value range: 1~100000
default	Boolean	Default branch or not
can_delete	Boolean	Whether user's branch is the default branch
can_read	Boolean	Default branch or not
can_download	Boolean	Default branch or not
can_push	Boolean	Default branch or not
commit	CommitDto object	Commit information
merged	Boolean	Whether all commits are merged into the default branch
protected	Boolean	Protected branch or not
created_at	String	Creation time
creator	UserBasicDto object	User information
description	String	Branch description
create_source	String	Branch-based
create_source_exists	Boolean	Whether the branch to be based exists
latest_pipeline	PipelineBasicDto object	Pipeline basic information
opened_mr_count	Integer	Number of MRs that are being enabled of the branch Value range: 0~2147483647
diverging_commit_counts	DivergingCommitCounts object	Number of commit differences

**Table 5** CommitDto
Parameter	Type	Description
id	String	id
message	String	Message
parent_ids	Array of strings	Parent node commit ID
authored_date	String	Time when the branch was created.
author_name	String	Creator name
author_email	String	Creator's email.
committed_date	String	Code commit date and time
committer_name	String	Committer name
committer_email	String	Committer email
open_gpg_verified	Boolean	Whether to enable the GPG verification
verification_status	Integer	Verification status Value range: 0~1
gpg_primary_key_id	String	Identifier of the GPG public key
name	String	Username
gpg_nick_name	String	Alias
gpg_tenant_name	String	Tenant name
gpg_user_name	String	Information about a specific GPG user
short_id	String	Short ID
created_at	String	Creation time
title	String	Title
author_avatar_url	String	author_avatar_url
committer_avatar_url	String	committer_avatar_url
relate_url	Array of RelatedCommitSimpleDto objects	only for DevCloud
nick_name	String	Title
tenant_name	String	tenant_name
user_name	String	Username

**Table 6** RelatedCommitSimpleDto
Parameter	Type	Description
related_id	String	Associated work item ID
related_url	String	Associated work item URL

**Table 7** UserBasicDto
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: available account blocked: locked user error: The user is not found Enumeration values: active blocked error
service_license_status	Integer	Service-level permission status. 0: disabled; 1: enabled
avatar_url	String	User profile picture URL
avatar_path	String	User profile picture path
email	String	User email
name_cn	String	Username (CN)
web_url	String	User homepage
nick_name	String	User alias
tenant_name	String	Tenant name
error_message	String	Definition When some query APIs detect that the user permission in the transfer parameter is insufficient or the user does not exist, the user is returned but the field is not empty for information.

**Table 8** PipelineBasicDto
Parameter	Type	Description
id	Integer	Pipeline ID Value range: 1~2147483647
web_url	String	Pipeline link
sha	String	commit id
ref	String	Branch
status	String	Pipeline status. pending: queuing; running: running; success: successful; failed: failed; canceled: canceled; skipped: skipped; and timedout: timed out Enumeration values: pending running success failed canceled skipped timedout

**Table 9** DivergingCommitCounts
Parameter	Type	Description
behind	Integer	Number of commits that lag behind the default branch.
ahead	Integer	Number of commits ahead of the default branch.

Status code: 401

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	Definition Error code.
error_msg	String	Definition Error message.

Example Requests

POST https://{endpoint}/v4/repositories/2112015538/repository/branches

{
  "branch" : "main",
  "description" : "123",
  "ref" : "master"
}

Example Responses

Status code: 201

{
  "name" : "b6",
  "default" : false,
  "can_delete" : null,
  "can_read" : null,
  "can_download" : null,
  "can_push" : null,
  "commit" : {
    "id" : "****",
    "message" : "****",
    "parent_ids" : [ "6ac4a7f56d28c9b76d3a7210608f496c519058be" ],
    "authored_date" : "2025-06-27T01:52:33.000Z",
    "author_name" : "****",
    "author_email" : "****",
    "committed_date" : "2025-06-27T01:52:33.000Z",
    "committer_name" : "****",
    "committer_email" : "****",
    "open_gpg_verified" : null,
    "verification_status" : null,
    "gpg_primary_key_id" : null,
    "name" : null,
    "gpg_nick_name" : null,
    "gpg_tenant_name" : null,
    "gpg_user_name" : null,
    "short_id" : "****",
    "created_at" : "2025-06-27T01:52:33.000Z",
    "title" : "Update ere",
    "author_avatar_url" : null,
    "committer_avatar_url" : null,
    "relate_url" : null,
    "nick_name" : null,
    "tenant_name" : null,
    "user_name" : null
  },
  "merged" : false,
  "protected" : false,
  "created_at" : "2025-07-18T11:24:46.000+08:00",
  "creator" : {
    "id" : "****",
    "name" : "****",
    "username" : "****",
    "state" : "active",
    "service_license_status" : null,
    "avatar_url" : "",
    "avatar_path" : null,
    "email" : "****",
    "name_cn" : "****",
    "web_url" : "https://example.com/****",
    "nick_name" : "****",
    "tenant_name" : "****",
    "error_message" : null
  },
  "description" : "****",
  "create_source" : "master",
  "create_source_exists" : true,
  "latest_pipeline" : null,
  "opened_mr_count" : 0,
  "diverging_commit_counts" : {
    "behind" : 0,
    "ahead" : 0
  }
}

Status code: 401

Unauthorized

{
  "error_code" : "DEV.00000003",
  "error_msg" : "Authentication information expired."
}

Status Codes

Status Code	Description
201	OK
401	Unauthorized

Error Codes

See Error Codes.

Parent topic: Refs

Previous topic: Obtaining the Branch List

Next topic: Obtaining the Tag List

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot