Amazon Simple Storage Service
API Reference (API Version 2006-03-01)

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

PUT Object tagging


This implementation of the PUT operation uses the tagging subresource to add a set of tags to an existing object.

A tag is a key-value pair. You can associate tags with an object by sending a PUT request against the tagging subresource that is associated with the object. You can retrieve tags by sending a GET request. For more information, see GET Object tagging.

For tagging-related restrictions related to characters and encodings, see Tag Restrictions in the AWS Billing and Cost Management User Guide. Note that Amazon S3 limits the maximum number of tags to 10 tags per object.

To use this operation, you must have permission to perform the s3:PutObjectTagging action. By default, the bucket owner has this permission and can grant this permission to others.

To put tags of any other version, use the versionId query parameter. You also need permission for the s3:PutObjectVersionTagging action.

For information about the Amazon S3 object tagging feature, see Object Tagging in the Amazon Simple Storage Service Developer Guide.



The following request shows the syntax for sending tagging information in the request body.

PUT /ObjectName?tagging HTTP/1.1 Host: Date: date Authorization: authorization string (see Authenticating Requests (AWS Signature Version 4)) <Tagging> <TagSet> <Tag> <Key>Tag Name</Key> <Value>Tag Value</Value> </Tag> </TagSet> </Tagging>

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Content-MD5 is a required header for this operation.

Request Elements

Name Description Required

Container for the TagSet and Tag elements.

Type: String

Ancestors: None


Container for a set of tags

Type: Container

Ancestors: Tagging


Container for tag information.

Type: Container

Ancestors: TagSet


Name of the tag.

Type: String

Ancestors: Tag

Yes, if Tag is specified.

Value of the tag.

Type: String

Ancestors: Tag

Yes, if Tag is specified.


Response Headers

The operation returns response headers that are common to most responses. For more information, see Common Response Headers.

Response Elements

This operation does not return response elements.

Special Errors

  • InvalidTagError - The tag provided was not a valid tag. This error can occur if the tag did not pass input validation. For more information, see Object Tagging in the Amazon Simple Storage Service Developer Guide.

  • MalformedXMLError - The XML provided does not match the schema.

  • OperationAbortedError - A conflicting conditional operation is currently in progress against this resource. Please try again.

  • InternalError - The service was unable to apply the provided tag to the object.


Sample Request: Add tag set to an object

The following request adds a tag set to the existing object object-key in the examplebucket bucket.

PUT object-key?tagging HTTP/1.1 Host: Content-Length: length Content-MD5: pUNXr/BjKK5G2UKExample== x-amz-date: 20160923T001956Z Authorization: authorization string <Tagging> <TagSet> <Tag> <Key>tag1</Key> <Value>val1</Value> </Tag> <Tag> <Key>tag2</Key> <Value>val2</Value> </Tag> </TagSet> </Tagging>

Sample Response

HTTP/1.1 200 OK x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo x-amz-request-id: 236A8905248E5A01 Date: Fri, 23 Sep 2016 00:20:19 GMT