PUT Object tagging

Last updated: 2020-07-07 11:59:41


    This API is used to set tags on an existing object. It can help you group and manage existing object resources by adding key-value pairs as object tags. For more information, see Object Tagging Overview.

    To call this API using a sub-account, please make sure that you have obtained permissions for this API from the root account.

    Currently, you can set up to 10 different tags on one object. If you set more, COS will replace the existing tags with new ones.


    When versioning is enabled for your bucket, you can include VersionId in your request to add object tags to the specified version of an object.


    Sample request

    PUT /<ObjectKey>tagging&VersionId=VersionId HTTP 1.1
    Date: GMT Date
    Authorization: Auth String

    Authorization: Auth String (see Request Signature for more information)

    Request parameters

    Name Description Type Required
    versionId Specifies the version ID of the object if versioning is enabled; if this parameter is not specified, the latest version will be added string No

    Request headers

    This API uses only common request headers. For more information, see Common Request Headers.

    Request body

    For this request, you need to configure the following set of tags:

    <?xml version="1.0" encoding="UTF-8" ?>

    The nodes are described in details below:

    Node Name (Keyword) Parent Node Description Type Required
    Tagging None Tag set Container Yes
    TagSet Tagging Tag set Container Yes
    Tag Tagging.TagSet Tag set, which can contain up to 10 tags Containers Yes
    Key Tagging.TagSet.Tag Tag key, which can contain up to 128 characters. A tag key can contain English letters, numbers, spaces, plus signs, minus signs, underscores, equals signs, dots, colons, and slashes String Yes
    Value Tagging.TagSet.Tag Tag value, which can contain up to 256 characters. A tag value can contain English letters, numbers, spaces, plus signs, minus signs, underscores, equals signs, dots, colons, and slashes String Yes


    Response headers

    This API returns common response headers. For more information, see Common Response Headers.

    Response body

    The response body is empty.

    Error codes

    This API returns uniform error responses and error codes. For more information, see Error Codes.



    The following request writes two tags {age:18} and {name:xiaoming} to the bucket examplebucket-1250000000. COS successfully configures the tags and returns 204 (success).

    PUT /exampleobject.txt?tagging HTTP/1.1
    User-Agent: curl/7.29.0
    Accept: */*
    Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
    Authorization: Auth String
    Content-Length: 127
    Content-MD5:MD5 String
    Content-Type: application/xml


    HTTP/1.1 204 No Content
    Content-Type: application/xml
    Content-Length: 0
    Connection: keep-alive
    Date: Fri, 19 Jan 2020 11:40:22 GMT
    Server: tencent-cos
    x-cos-request-id: NWE2MWQ5MjZfMTBhYzM1MGFfMTA5ODVfMTVj****