S3 · Versioning & retention

PutObjectRetention

PUT/{bucket}/{key}?retention

Sets or extends the retention of one object version.

Storage keeps the version until the date that you send. You can add retention or move the date later. You cannot shorten it.

View as Markdown

Role: Editor or higher
Support: Partial
Auth: SigV4 with your API key

Needs versionId. COMPLIANCE only. Retention can be added or extended, never shortened.

Request

https://wspq7ws2np5l8z4.storage.beta.graphon.sh/support-tickets/a.json?retention&versionId=ver_5f0c8a8e3d2b4c1e9a7f6b5d4c3b2a19

PUT /support-tickets/a.json?retention&versionId=ver_5f0c8a8e3d2b4c1e9a7f6b5d4c3b2a19 HTTP/1.1
Host: wspq7ws2np5l8z4.storage.beta.graphon.sh
x-amz-date: 20261007T093000Z
x-amz-content-sha256: ec468f6091e11c1f437d9b2f410bc4e1d794693892d6c5e996accd210ff799d6
Authorization: AWS4-HMAC-SHA256 Credential=<ACCESS_KEY_ID>/20261007/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=<SIGNATURE>
Content-Length: 156

<Retention xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Mode>COMPLIANCE</Mode>
  <RetainUntilDate>2027-01-01T00:00:00Z</RetainUntilDate>
</Retention>

Replace wspq7ws2np5l8z4 with your workspace ID. HTTP shows the signed request on the wire. The aws CLI and the SDKs sign for you. The CLI uses the graphon profile, and the SDK samples read GRAPHON_API_KEY.

Response

200

Storage saved the retention.

HTTP/1.1 200 OK
x-amz-request-id: 4F8A2C7D1E6B4093A5C2D8E1F7B3A960

Path parameters

bucketstringrequired

The bucket name.

keystringrequired

The object key. Keep each / as it is. Percent-encode the other reserved characters.

Query parameters

retentionflagrequired

Selects this operation. Send it with no value.

versionIdstringrequired

The version to retain.

Headers

x-amz-expected-bucket-ownerstringoptional

The workspace ID that must own the bucket. Another owner returns 403 AccessDenied.

Request body

Retentionobjectrequired

The root element.

Modestringrequired

Send COMPLIANCE.

RetainUntilDatestringrequired

An ISO 8601 date in the future.

Responses

200OK

Storage saved the retention.

This response has no body.

Errors

Select an error in the response example to see its XML body. Any request can also get the common errors, such as SignatureDoesNotMatch.

400InvalidRequest

The request has no versionId, the mode is not COMPLIANCE, or the date is not in the future.

What to do: Send a versionId, COMPLIANCE mode, and a future RetainUntilDate.

403AccessDenied

The new date is earlier than the current one, or the key does not have the Editor role.

What to do: Send a date on or after the current RetainUntilDate.

404NoSuchKey

The bucket has no object at this key, or no version with this versionId.

What to do: Check the key and the versionId.

405MethodNotAllowed

The versionId names a delete marker, which has no bytes.

What to do: Use the versionId of a version that holds data. ListObjectVersions shows each one.

404NoSuchBucket

No bucket has this name, or the bucket was deleted.

What to do: Check the bucket name. ListBuckets shows the buckets of the workspace.

Was this page helpful?