> For the complete documentation index, see [llms.txt](https://docs.petabox.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.petabox.io/http-api-compatible-with-amazon-s3/api-reference/putobjecttagging.md).

# PutObjectTagging

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 [GetObjectTagging](/http-api-compatible-with-amazon-s3/api-reference/getobjecttagging.md).

Note that Petabox 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.

`PutObjectTagging` has the following special errors:

***Code**: InvalidTagError*

* *Cause: The tag provided was not a valid tag. This error can occur if the tag did not pass input validation.* 

***Code**: MalformedXMLError*

* *Cause: The XML provided does not match the schema.*

***Code**: OperationAbortedError*

* *Cause: A conflicting conditional action is currently in progress against this resource. Please try again.*

***Code**: InternalError*

* *Cause: The service was unable to apply the provided tag to the object.*

## Request Syntax <a href="#api_putobjecttagging_requestsyntax" id="api_putobjecttagging_requestsyntax"></a>

```http
PUT /{Key+}?tagging&versionId=VersionId HTTP/1.1
Host: Bucket.s3.petabox.io
Content-MD5: ContentMD5
x-amz-sdk-checksum-algorithm: ChecksumAlgorithm
x-amz-expected-bucket-owner: ExpectedBucketOwner
x-amz-request-payer: RequestPayer
<?xml version="1.0" encoding="UTF-8"?>
<Tagging xmlns="http://s3.petabox.io/doc/2006-03-01/">
   <TagSet>
      <Tag>
         <Key>string</Key>
         <Value>string</Value>
      </Tag>
   </TagSet>
</Tagging>
```

## URI Request Parameters <a href="#api_putobjecttagging_requestparameters" id="api_putobjecttagging_requestparameters"></a>

The request uses the following URI parameters.

#### Bucket

The bucket name containing the object.&#x20;

Required: Yes

#### Content-MD5

The MD5 hash for the request body.

#### Key

Name of the object key.

Length Constraints: Minimum length of 1.

Required: Yes

#### versionId

The versionId of the object that the tag-set will be added to.

#### x-amz-expected-bucket-owner

The account ID of the expected bucket owner. If the bucket is owned by a different account, the request fails with the HTTP status code `403 Forbidden` (access denied).

#### x-amz-request-payer

Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests.&#x20;

Valid Values: `requester`

## Request Body <a href="#api_putobjecttagging_requestbody" id="api_putobjecttagging_requestbody"></a>

The request accepts the following data in XML format.

#### Tagging

Root level tag for the Tagging parameters.

Required: Yes

#### TagSet

A collection for a set of tags

Type: Array of Tag data types

Required: Yes

## Response Syntax <a href="#api_putobjecttagging_responsesyntax" id="api_putobjecttagging_responsesyntax"></a>

```
HTTP/1.1 200
x-amz-version-id: VersionId
```

## Response Elements <a href="#api_putobjecttagging_responseelements" id="api_putobjecttagging_responseelements"></a>

If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

#### x-amz-version-id

The versionId of the object the tag-set was added to.

## Examples <a href="#api_putobjecttagging_examples" id="api_putobjecttagging_examples"></a>

### Sample Request: Add tag set to an object <a href="#api_putobjecttagging_example_1" id="api_putobjecttagging_example_1"></a>

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

```http
PUT object-key?tagging HTTP/1.1
Host: examplebucket.s3.<Region>.petabox.io
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 <a href="#api_putobjecttagging_example_2" id="api_putobjecttagging_example_2"></a>

This example illustrates one usage of PutObjectTagging.

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