Available in Classic and VPC
Set retention on an Ncloud Storage object. Objects subject to retention cannot be deleted or changed until the specified expiration date.
Request
This section describes the request format. The method and URI are as follows:
| Method | URI |
|---|---|
| PUT | /{Key} |
Request headers
The following describes the request headers.
For information about the headers common to all Ncloud Storage APIs, see Ncloud Storage request headers.
| Field | Required | Description |
|---|---|---|
Content-MD5 |
Conditional | Base64-encoded 128-bit MD5 hash of the request body
|
x-amz-checksum-* |
Conditional | Checksum hash value
|
x-amz-bypass-governance-retention |
Optional | Whether to bypass GOVERNANCE mode retention
|
Request path parameters
You can use the following path parameters with your request:
| Field | Type | Required | Description |
|---|---|---|---|
Key |
String | Required | Object name |
Request query parameters
You can use the following query parameters with your request:
| Field | Type | Required | Description |
|---|---|---|---|
versionId |
String | Optional | Version ID of the object to set the retention for
|
Request body
You can include the following data in the body of your request:
| Field | Type | Required | Description |
|---|---|---|---|
Retention |
Object | Required | Retention settings |
Retention.Mode |
String | Optional | Retention mode
|
Retention.RetainUntilDate |
String | Optional | Retention expiration date
|
If both Mode and RetainUntilDate are omitted, the object's retention settings are disabled.
Request example
The request example is as follows:
PUT /object.csv?retention HTTP/1.1
Host: {Bucket}.kr.ncloudstorage.com
Content-MD5: {MD5 hash value}
<?xml version="1.0" encoding="UTF-8"?>
<Retention>
<Mode>GOVERNANCE</Mode>
<RetainUntilDate>2025-12-31T00:00:00.000Z</RetainUntilDate>
</Retention>
Response
This section describes the response format.
Response headers
For information about the headers common to all Ncloud Storage APIs, see Ncloud Storage response headers.
Response status codes
The following describes the response status codes.
For information about the HTTP status codes common to all Ncloud Storage APIs, see Common Ncloud Storage response status codes.
| Error code | HTTP status code | Description |
|---|---|---|
InvalidRequest |
400 | No object lock settings exist in the bucket. |
InvalidArgument |
400 | The retention expiration date (RetainUntilDate) is not in the future. |
MalformedXML |
400 | The request body XML does not conform to the schema.
|
AccessDenied |
403 | The existing retention settings were relaxed or removed without bypass permissions. |
NoSuchKey |
404 | Specified object does not exist. |
NoSuchVersion |
404 | Specified version does not exist. |
MethodNotAllowed |
405 | Retention is set on a deletion marker. |
Response example
The response example is as follows:
HTTP/1.1 200 OK