PutObjectLegalHold
Places or removes a Legal Hold on an object.
Description
The PutObjectLegalHold operation places or removes a Legal Hold on an object. For this operation to succeed, the bucket must have object locking enabled.
Important
- To use this operation, you must have the
s3:PutObjectLegalHoldpermission. - The bucket must have object locking enabled.
- Legal Hold is independent from retention periods and retention modes.
- When an object has a Legal Hold placed on it:
- The object cannot be deleted
- The object's version cannot be overwritten
- The object's metadata cannot be modified
- Legal Hold remains in effect until explicitly removed, regardless of any retention settings.
Required Permissions
To successfully complete this operation, you must have:
s3:PutObjectLegalHoldpermission on the object- The bucket must have object locking enabled
Request Syntax
PUT /ObjectKey?legal-hold HTTP/1.1
Host: BucketName.qstorage.quilibrium.com
x-amz-legal-hold: ON
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<LegalHold>
<Status>ON</Status>
</LegalHold>
Values in italics indicate user input and should be replaced with actual values.
Request Parameters
URI Parameters
| Name | Description | Required |
|---|---|---|
| Bucket | The bucket name containing the object that you want to place a legal hold on. | Yes |
| Key | The key name for the object that you want to place a legal hold on. Minimum length of 1. | Yes |
| versionId | The version ID of the object that you want to place a legal hold on. | No |
Headers
| Name | Description | Required | Type |
|---|---|---|---|
| x-amz-legal-hold | Specifies whether you want to apply a Legal Hold to the object. Valid values: ON | OFF | Yes | text |
| Content-MD5 | The base64-encoded 128-bit MD5 digest of the Legal Hold configuration XML. This header is required by the API specification, but is calculated automatically with some CLI/SDK tooling. | Yes | text |
| x-amz-expected-bucket-owner | The account ID of the expected bucket owner. Request fails with 403 Forbidden if the account ID doesn't match the actual bucket owner | No | text |
| 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. If either the source or destination S3 bucket has Requester Pays enabled, the requester will pay for corresponding charges to copy the object. Valid values: requester | No | text |
| x-amz-sdk-checksum-algorithm | Indicates the algorithm used to create the checksum for the object when using the SDK. When you send this header, there must be a corresponding x-amz-checksum or x-amz-trailer header sent. Valid values: CRC32 | CRC32C | SHA1 | SHA256 | CRC64NVME | No | text |
Request Elements
| Name | Description | Required | Type |
|---|---|---|---|
| LegalHold | Root level tag for the Legal Hold parameters. | Yes | Container |
| Status | Specifies whether you want to apply a Legal Hold to the object. Valid values: ON | OFF | Yes | String |
Examples
Example 1: Place a Legal Hold on an object
PUT /document.txt?legal-hold HTTP/1.1
Host: my-bucket.qstorage.quilibrium.com
x-amz-legal-hold: ON
Content-MD5: NDM5MGY5YjhlODMzYjJhNzFmZjNkZGFlOTJhNzE4NDc=
<?xml version="1.0" encoding="UTF-8"?>
<LegalHold>
<Status>ON</Status>
</LegalHold>
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
x-amz-request-id: TX234S0F24A06C7
Values in italics indicate variable response values.
Example 2: Remove a Legal Hold from an object
PUT /document.txt?legal-hold HTTP/1.1
Host: my-bucket.qstorage.quilibrium.com
x-amz-legal-hold: OFF
Content-MD5: OWY5YjhlODMzYjJhNzFmZjNkZGFlOTJhNzE4NDc=
<?xml version="1.0" encoding="UTF-8"?>
<LegalHold>
<Status>OFF</Status>
</LegalHold>
Values in italics indicate user input and should be replaced with actual values.
HTTP/1.1 200 OK
x-amz-request-id: TX234S0F24A06C8
Values in italics indicate variable response values.
Response Syntax
HTTP/1.1 200 OK
x-amz-request-id: AmazonRequestId
Values in italics indicate variable response values.
Response Elements
Returns a HTTP 200 response if successful.
Response Headers
| Name | Description | Required | Type |
|---|---|---|---|
| x-amz-request-charged | If present, indicates that the requester was successfully charged for the request. Valid values: requester | No | String |
Special Errors
| Error Code | Description |
|---|---|
| InvalidRequest | The request was invalid. Check the error message for details. |
| NoSuchBucket | The specified bucket does not exist. |
| NoSuchKey | The specified key does not exist. |
| ObjectLockConfigurationNotFoundError | Object Lock configuration does not exist for this bucket. |
| 403 | Forbidden. Authentication failed or you do not have permission to perform this operation. |
Permissions
You must have the s3:PutObjectLegalHold permission on the object. The bucket must also have object locking enabled.
Try It Out
Test PutObjectLegalHold
Place or remove a Legal Hold on an object.
Coming Soon
This feature is currently under development and will be available soon.