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

PUT Object tagging

Description

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 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 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.

Requests

Syntax

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

Copy to clipboard
PUT /ObjectName?tagging HTTP/1.1 Host: BucketName.s3.amazonaws.com 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 will be a required header for this operation.

Request Elements

Name Description Required
Tagging

Container for the TagSet and Tag elements.

Type: String

Ancestors: None

Yes
TagSet

Container for a set of tags

Type: Container

Ancestors: Tagging

Yes
Tag

Container for tag information.

Type: Container

Ancestors: TagSet

No
Key

Name of the tag.

Type: String

Ancestors: Tag

Yes, if Tag is specified
Value

Value of the tag.

Type: String

Ancestors: Tag

No

Responses

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.

Examples

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.

Copy to clipboard
PUT object-key?tagging HTTP/1.1 Host: examplebucket.s3.amazonaws.com 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

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