Set object retention

To add or modify the retention configuration for an existing object, you make a PUT request that is scoped to the object, and you use the retention query string parameter. You must also include an XML document in the request body that contains the retention configuration that you want to apply. A retention configuration cannot be removed or shortened if its mode is set to COMPLIANCE.

You can also specify a retention configuration at the time you upload an object.

You must have FULL_CONTROL permission to apply a retention configuration to an existing object.

Query string parameters

Parameter Description Required
retention Scopes the request to add or modify the retention configuration for an object. You must specify the retention configuration in an XML document in the request body. No
generation Specifies the generation on which to set the retention configuration. No

See signed URL query string parameters for information on the parameters you include when creating and using signed URLs.

Request headers

In addition to common request headers, the following can be used.

Header Description Required
x-goog-bypass-governance-retention Must be set to true in order to remove an existing retention configuration, make an existing retention configuration shorter, or set the mode of an existing retention configuration to COMPLIANCE. No

Request body elements

The following request body elements are applicable only if you use the retention query string parameter to add or modify a retention configuration for an existing object. All elements are required.

Element Description
Retention Container for object's retention configuration.
Mode Mode of the object retention configuration. GOVERNANCE corresponds to unlocked mode, and COMPLIANCE corresponds to locked mode.
RetainUntilDate A date and time represented in RFC 3339 UTC format that determines the time until which the object is retained as immutable.

Request syntax

The following syntax applies to PUT Object requests that use the retention query string parameter and that scope the request to a specific object generation.

Date: DATE
Content-Type: MIME_TYPE


Response headers

The request can return a variety of response headers depending on the request headers you use.

Response body elements

The response does not include an XML document in the response body.


The following sample applies a retention configuration to the london.jpg object, which is stored in the travel-maps bucket. The configuration sets the Mode to be GOVERNANCE and the RetainUntilDate to be 2028-02-15T05:30:00Z.


PUT /london.jpg?retention HTTP/1.1
Date: Mon, 16 Oct 2023 17:08:44 GMT
Content-Length: 138
Content-Type=application/xml; charset=UTF-8
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

<?xml version="1.0" encoding="UTF-8"?>


HTTP/1.1 200 OK
Date: Mon, 16 Oct 2023 17:08:45 GMT
Content-Length: 0
Content-Type: text/html