> 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/putobjectretention.md).

# PutObjectRetention

Places an Object Retention configuration on an object

Users or accounts require the `s3:PutObjectRetention` permission in order to place an Object Retention configuration on objects. Bypassing a Governance Retention configuration requires the `s3:BypassGovernanceRetention` permission.

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

```http
PUT /{Key+}?retention&versionId=VersionId HTTP/1.1
Host: Bucket.s3.petabox.io
x-amz-request-payer: RequestPayer
x-amz-bypass-governance-retention: BypassGovernanceRetention
Content-MD5: ContentMD5
x-amz-expected-bucket-owner: ExpectedBucketOwner
<?xml version="1.0" encoding="UTF-8"?>
<Retention xmlns="http://s3.petabox.io/doc/2006-03-01/">
   <Mode>string</Mode>
   <RetainUntilDate>timestamp</RetainUntilDate>
</Retention>
```

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

The request uses the following URI parameters.

#### Bucket

The bucket name that contains the object you want to apply this Object Retention configuration to.

Required: Yes

#### Content-MD5

The MD5 hash for the request body.

For requests made using the Command Line Interface (CLI) or SDKs, this field is calculated automatically.

#### Key

The key name for the object that you want to apply this Object Retention configuration to.

Length Constraints: Minimum length of 1.

Required: Yes

#### versionId

The version ID for the object that you want to apply this Object Retention configuration to.

#### x-amz-bypass-governance-retention

Indicates whether this action should bypass Governance-mode restrictions.

#### 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 he 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_putobjectretention_requestbody" id="api_putobjectretention_requestbody"></a>

The request accepts the following data in XML format.

#### Retention

Root level tag for the Retention parameters.

Required: Yes

#### Mode

Indicates the Retention mode for the specified object.

Type: String

Valid Values: `GOVERNANCE | COMPLIANCE`

Required: No

#### RetainUntilDate

The date on which this Object Lock Retention will expire.

Type: Timestamp

Required: No

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

```http
HTTP/1.1 200
x-amz-request-charged: RequestCharged
```

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

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

The response returns the following HTTP headers.

#### x-amz-request-charged

If present, indicates that the requester was successfully charged for the request.

Valid Values: `requester`