Help Center/ CodeArts Repo/ API Reference/ APIs/ V4/ Refs/ Creating a Tag
Updated on 2026-04-28 GMT+08:00
View PDF

Creating a Tag

Function

This API is used to create a tag.

Debugging

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

URI

POST https://{hostURL}/v4/repositories/{repository_id}/repository/tags

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

Request Parameters

Table 2 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.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

tag_name

Yes

String

New label name

ref

Yes

String

Created based on ref (branch or commit ID)

message

No

String

Label description

Response Parameters

Status code: 201

Table 4 Response body parameters

Parameter

Type

Description

name

String

Label name

message

String

Label description

target

String

Commit ID-based

commit

CommitDto object

Commit information
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

Status code: 401

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Definition

Error code.

error_msg

String

Definition

Error message.

Status code: 403

Table 8 Response body parameters

Parameter

Type

Description

error_code

String

Definition

Error code.

error_msg

String

Definition

Error message.

Status code: 404

Table 9 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/tags

{
  "message" : "***",
  "ref" : "****",
  "tag_name" : "***"
}

Example Responses

Status code: 201

OK

{
  "name" : "11123s4",
  "message" : "",
  "target" : "a16f289be46*****0c4718c93ba18f478f8",
  "commit" : {
    "id" : "****",
    "message" : "*****",
    "parent_ids" : [ "***" ],
    "authored_date" : "2025-02-21T03:33:04.000Z",
    "author_name" : "****",
    "author_email" : "****",
    "committed_date" : "2025-02-21T03:33:04.000Z",
    "committer_name" : "****",
    "committer_email" : "****",
    "short_id" : "****",
    "created_at" : "2025-02-21T03:33:04.000Z",
    "title" : "****",
    "author_avatar_url" : "",
    "committer_avatar_url" : "",
    "nick_name" : "dev",
    "tenant_name" : "****",
    "user_name" : "****"
  }
}

Status code: 401

Unauthorized

{
  "error_code" : "CH.00000001",
  "error_msg" : "User authentication info not found."
}

Status code: 403

Bad Request

{
  "error_code" : "CH.00401008",
  "error_msg" : "Insufficient permissions. Apply for the required permissions and try again."
}

Status code: 404

Not Found

{
  "error_code" : "CH.00402000",
  "error_msg" : "The repository does not exist. Check and try again."
}

Status Codes

Status Code

Description

201

OK

401

Unauthorized

403

Bad Request

404

Not Found

Error Codes

See Error Codes.

Parent topic: Refs