# PutBucketTagging

Use tags to organize your Petabox bill to reflect your own cost structure. To do this, sign up to get your Petabox account bill with tag key values included. Then, to see the cost of combined resources, organize your billing information according to resources with the same tag key values. For example, you can tag several resources with a specific application name, and then organize your billing information to see the total cost of that application across several services.

{% hint style="info" %}
**Note**

When this operation sets the tags for a bucket, it will overwrite any current tags the bucket already has. You cannot use this operation to add tags to an existing list of tags.
{% endhint %}

To use this operation, you must have permissions to perform the `s3:PutBucketTagging` action. The bucket owner has this permission by default and can grant this permission to others.

`PutBucketTagging` has the following special ***errors***:

Error code: `InvalidTagError`

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

Error code: `MalformedXMLError`

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

Error code: `OperationAbortedError`

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

Error code: `InternalError`

* Description: The service was unable to apply the provided tag to the bucket.

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

```http
PUT /?tagging HTTP/1.1
Host: Bucket.s3.petabox.io
Content-MD5: ContentMD5
x-amz-sdk-checksum-algorithm: ChecksumAlgorithm
x-amz-expected-bucket-owner: ExpectedBucketOwner
<?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_putbuckettagging_requestparameters" id="api_putbuckettagging_requestparameters"></a>

The request uses the following URI parameters.

#### Bucket

The bucket name.

Required: Yes

#### Content-MD5

The base64-encoded 128-bit MD5 digest of the data. You must use this header as a message integrity check to verify that the request body was not corrupted in transit. For more information, see [RFC 1864](http://www.ietf.org/rfc/rfc1864.txt).

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

## Request Body <a href="#api_putbuckettagging_requestbody" id="api_putbuckettagging_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_putbuckettagging_responsesyntax" id="api_putbuckettagging_responsesyntax"></a>

```
HTTP/1.1 200
```

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

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

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

### Sample Request: Add tag set to a bucket <a href="#api_putbuckettagging_example_1" id="api_putbuckettagging_example_1"></a>

The following request adds a tag set to the existing `examplebucket` bucket.

```http
PUT ?tagging HTTP/1.1
Host: examplebucket.s3.<Region>.petabox.io
Content-Length: 1660
x-amz-date: Thu, 12 Apr 2012 20:04:21 GMT
Authorization: authorization string

<Tagging>
  <TagSet>
    <Tag>
      <Key>Project</Key>
      <Value>Project One</Value>
    </Tag>
    <Tag>
      <Key>User</Key>
      <Value>jsmith</Value>
    </Tag>
  </TagSet>
</Tagging>
```

### Sample Response <a href="#api_putbuckettagging_example_2" id="api_putbuckettagging_example_2"></a>

This example illustrates one usage of PutBucketTagging.

```http
HTTP/1.1 204 No Content
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Oct  2012 12:00:00 GMT
```


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.