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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.petabox.io/http-api-compatible-with-amazon-s3/api-reference/putobjecttagging.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.