Bucket

You can use the Object Storage bucket API to manage bucket creation, properties, and policies.

Prerequisite

• For prerequisites to call the API, refer to Prepare to use api.
• For a description of the Object Storage API model, refer to API model.

API endpoint URL

The Object Storage API endpoint URL for the kr-central-2 region is:

Object Storage API endpoint URL format

https://objectstorage.kr-central-2.kakaocloud.com

Create bucket

Creates a bucket.

Permission

According to IAM roles, the project admin or project member role is required to create a bucket.

Request syntax

Create bucket request syntax

curl --request PUT --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '{
  "name": "my-bucket-new",
  "type": "STANDARD",
  "use_encryption": true,
  "encryption_configuration": {
    "type": "managed"
  }
}'

API call method

Method	Request URL
PUT	https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket

Request headers

Header	Type	Required	Description
X-Auth-Token	String	Yes	Enter the authentication token
Content-Type	String	Yes	Must be application/json

Request body

Field	Type	Required	Description
name	String	Yes	Bucket name
type	String	Yes	Bucket type - Standard (default): standard bucket
use_encryption	Boolean	No	Whether to enable bucket encryption Ignored if encryption_configuration is provided - false (default): do not encrypt - true: encrypt (same as encryption_configuration.type = managed)
encryption_configuration	Object	No	Encryption settings for the bucket
└─ type	String	Yes	Encryption method - managed (default): server-managed encryption - true (planned): KMS-managed encryption (future support)

Response syntax

Create bucket response syntax

{
  "account": "project-id",
  "project": "project-id",
  "name": "my-bucket-new",
  "type": "STANDARD",
  "bytes": 0,
  "objectCount": 0,
  "createdAt": "2022-04-25T10:28:57Z",
  "acl": {
    "permissions": null,
    "public": "read-only",
    "public_read_allow_ip_list": [
      "ip / cidr"
    ]
  },
  "lastModified": "2022-04-25T10:28:57Z",
  "use_encryption": true,
  "encryption_type": "managed",
  "storageClass": "STANDARD",
  "storagePolicy": "default-placement"
}

Response elements

Field	Type	Description
account (Deprecated)	String	Project ID (Account ID used in Swift API)
project	String	Project ID
name	String	Bucket name
type	String	Bucket type - STANDARD (default): standard bucket
bytes	String	Total usage in bytes
objectCount	Integer	Number of objects in the bucket
createdAt	String	Creation time (RFC3339 format)
use_encryption	Boolean	Whether encryption is enabled
encryption_type	String	Encryption type
lastModified	String	Last modified time (RFC3339 format)
storageClass	String	Storage class type - STANDARD (default): standard
storagePolicy	String	Storage policy zone - default-placement (default)
acl	Object	Bucket access permissions
└─ public	String	Public access level - read-only, deny
└─ public_read_allow_ip_list	List	List of allowed IPs for public access

HTTP status codes

HTTP status	Meaning	Description
200	OK	Success
400	Bad request	Input error
401	Unauthorized	No permission
409	Conflict	Bucket name already exists

Manage bucket

View bucket details

If you have the storage.buckets.get permission, you can retrieve detailed information about a specific bucket.
For more details on Object Storage permissions, refer to Role and permission.

Request syntax

View bucket details request syntax

curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

API call method

Method	Request URL
GET	https://objectstorage.{region_name}.kakaocloud.com/v1_ext/{bucket_name}

Path	Type	Required	Description
region_name	String	Yes	Region name - kr-central-2
bucket_name	String	Yes	Bucket name

Request header

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token

Response syntax

For detailed information about the bucket API model, refer to Bucket API model.

View bucket details response syntax

{    
    "project": "project-id",    
    "name": "test-bucket-01",    
    "type": "STANDARD",    
    "bytes": 0,    
    "objectCount": 0,    
    "createdAt": "2023-06-21T07:17:10Z",    
    "use_encryption": true,    
    "encryption_type": " ",    
    "lastModified": "2023-06-21T07:17:10Z",    
    "storageClass": "STANDARD",    
    "storagePolicy": "default-placement",    
    "acl": {        
        "public": "deny",        
        "public_read_allow_ip_list": null    
    }
}

Response elements

Field	Type	Description
project	String	Project ID - Visible when issuing a token - Used in S3 API
name	String	Name of the created bucket
type	String	Bucket type - standard (default): standard bucket
bytes	String	Total usage (unit: byte)
objectCount	Int	Number of objects in the bucket
createdAt	String	Creation time - Format: RFC3339
use_encryption	Boolean	Whether bucket encryption is enabled
encryption_type	String	Encryption type
lastModified	String	Last modified time - Format: RFC3339
storageClass	String	Storage class type (available only in kr-central-2) - standard (default)
storagePolicy	String	Storage policy zone
acl	Object	Access control settings
└─ public	String	Public read access level - read-only or deny
└─ public_read_allow_ip_list	List	List of IPs allowed for public access

HTTP status codes

HTTP status	Meaning	Description
200	OK	Success
400	Bad request	Invalid input
401	Unauthorized	Authentication failed
403	Forbidden	No permission

---

Query bucket list

You can query the list of buckets.

Permission

According to IAM roles, project admin or project member roles are required to query buckets.

Request syntax

Query bucket list request syntax

curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket?limit=100' \
--header 'X-Auth-Token: {x-auth-token}'

API call method

Method	Request URL
GET	https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket

Request path

Parameter	Type	Required	Description
region_name	String	Yes	Region name - kr-central-2

Request header

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token

Request query

Parameter	Type	Required	Description
offset	Query	No	Starting point of the result list (default: 0)
limit	Query	No	Maximum number of items to return (default: 20, up to 100)
prefix	Query	No	Filter bucket names by prefix
include	Query	No	Search buckets by inclusion string - Cannot be used with prefix
type	Query	No	Bucket type - STANDARD
by	Query	No	Sorting field - bucket_name, bucket_type, created_at, bytes_used
direct	Query	No	Sort order - asc (default), desc

Response syntax

Query bucket list response syntax

{
  "totalCount": 12,
  "offset": 0,
  "count": 10,
  "items": [SimpleBucket]
}

Response elements

Field	Type	Description
totalCount	Int	Total number of buckets
offset	Int	Offset for pagination
count	Int	Number of returned buckets
items	List	List of bucket details - See Model - Simple bucket

HTTP status codes

HTTP status	Meaning	Description
200	OK	Success
401	Unauthorized	Invalid token
403	Forbidden	No permission

Manage bucket access

You can manage access to your owned buckets.
Using the following request, you can configure public access and apply IP-based access control to your bucket.

Request syntax

Access control by IP list request syntax

curl --request POST --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '{
  "name": "my-bucket-new",
  "acl": {
    "public": "read-only",
    "public_read_allow_ip_list": [
      "1.1.1.1",
      "2.2.2.0/24"
    ]
  }
}'

API call method

Method	Request URL
POST	https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}

Path	Type	Required	Description
bucket_name	String	Yes	Bucket name

Request header

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token
Content-Type	String	Yes	Fixed to application/json

Request body

Field	Type	Required	Description
bucket_name	String	Yes	Bucket name
acl	Object	Yes	Access control list settings - Use null to delete existing ACL
└ public	String	Optional	Public access setting - read-only, deny (same as null)
└ public_read_allow_ip_list	List	Optional	List of IP addresses allowed for public read access

Response syntax

Manage bucket access response syntax

{
  "project": "0bc7a4c4a8fb4fee98dcf1936d8ed8eb",
  "account": "0bc7a4c4a8fb4fee98dcf1936d8ed8eb",
  "name": "my-bucket-new",
  "type": "STANDARD",
  "bytes": 0,
  "objectCount": 0,
  "createdAt": "2023-07-08T04:08:05Z",
  "use_encryption": true,
  "encryption_type": "managed",
  "lastModified": "2023-07-08T04:08:05Z",
  "storageClass": "STANDARD",
  "storagePolicy": "default-placement",
  "acl": {
    "public": "deny",
    "public_read_allow_ip_list": null
  }
}

Response elements

Field	Type	Description
account (deprecated)	String	Project ID (deprecated)
project	String	Project ID
name	String	Bucket name
type	String	Bucket type - STANDARD (default)
bytes	String	Total usage in bytes
objectCount	Int	Number of objects in the bucket
createdAt	String	Creation time (RFC3339)
use_encryption	Boolean	Encryption enabled or not
encryption_type	String	Type of encryption
lastModified	String	Last modified time (RFC3339)
storageClass	String	Storage class - STANDARD (default)
storagePolicy	String	Storage zone - default-placement
acl	Object	Access control settings
└ public	String	read-only, deny
└ public_read_allow_ip_list	List	List of allowed IPs for public access

HTTP status codes

HTTP status	Meaning	Description
200	OK	Success
401	Unauthorized	Invalid or expired token
403	Forbidden	Insufficient permissions
404	Not found	Bucket not found

---

Delete bucket

You can delete a bucket you own.
To delete a bucket, the storage.buckets.delete permission is required.

• You cannot delete a bucket that contains objects.

Request syntax

Delete bucket request syntax

curl --location --request DELETE 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

API call method

Method	Request URL
DELETE	https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}

Request path

Field	Type	Required	Description
region_name	String	Yes	Region name - kr-central-2
bucket_name	String	Yes	Name of the bucket to delete

Request header

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token

HTTP status codes

HTTP status	Meaning	Description
204	No content	Successfully deleted
401	Unauthorized	Authentication failed
404	Not found	Bucket not found
409	Conflict	Bucket is not empty

Bulk delete buckets and objects

Users with delete permissions can delete buckets and objects in bulk within a project.
The input list will be processed sequentially, and the result of each deletion will be returned as a single response body.

• Feature coming soon.

---

Empty bucket

If you have storage.objects.delete permission, you can delete all objects under a bucket.
For more details, refer to roles and permissions.

Request syntax

Empty bucket request syntax

curl --location --request DELETE 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/?dir-delete' \
--header 'X-Auth-Token: {X-Auth-Token}'

API call method

Method	Request URL
DELETE	https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/?dir-delete

Path	Type	Required	Description
account	String	Yes	Project ID - Used as account in Swift API
directory	String	Optional	Directory to delete under the bucket

Request header

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token

HTTP status codes

HTTP status	Description
200	Success
400	Bad request (invalid name or not found)
401	Unauthorized
403	Forbidden

---

Empty bucket folder

If you have storage.objects.delete permission, you can delete all objects under a specific path (folder) in a bucket.
For more details, refer to roles and permissions.

Request syntax

Empty bucket folder request syntax

curl --location --request DELETE 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{directory}/?dir-delete' \
--header 'X-Auth-Token: {X-Auth-Token}'

API call method

Method	Request URL
DELETE	https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{directory}/?dir-delete

Path	Type	Required	Description
account	String	Yes	Project ID
bucket_name	String	Yes	Bucket name
directory	String	Optional	Directory name to delete under the bucket

Request header

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token

HTTP status codes

HTTP status	Description
200	Success
400	Bad request (invalid name or not found)
401	Unauthorized
403	Forbidden

---

Query bucket metadata

If you have storage.buckets.get permission, you can query the metadata of a bucket.
Refer to roles and permissions for more details.

You can retrieve bucket metadata using either the GET or HEAD method.

GET method

Request syntax

Query bucket metadata (GET)

curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

API call method

Method	Request URL
GET	https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}

Path	Type	Required	Description
bucket_name	String	Yes	Bucket name

Request header

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token

Response header

Header	Type	Description
X-Container-Meta-*	String	User-defined metadata

Response elements

Field	Type	Description
project	String	Project ID
name	String	Bucket name
type	String	Bucket type (e.g., STANDARD)
bytes	Int	Total used capacity (updated every 30 minutes)
objectCount	Int	Number of objects (updated every 30 minutes)
createdAt	Time	Bucket creation time
use_encryption	Boolean	Whether encryption is enabled
lastModified	Time	Last modified timestamp
storageClass	String	Storage class (e.g., STANDARD)
acl ▼	List	Access control settings
public	String	Public access setting (read-only, deny)
public_read_allow_ip_list	String	Allowed IP list for public access

HTTP status codes

HTTP status	Description
200	Success
401	Unauthorized
403	Forbidden
404	Not found

HEAD method

Request syntax

Query bucket metadata (HEAD)

curl --location --request HEAD 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'X-Object-Meta-Company: kakao enterprise'

API call method

Method	Request URL
HEAD	https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}

Path	Type	Required	Description
account	String	Yes	Project ID
bucket_name	String	Yes	Bucket name

Request header

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token

Response header

Header	Type	Description
X-Container-Meta-*	String	User-defined metadata
Date	Time	Request time (bucket creation time)
X-Container-Bytes-Used	Int	Total object size (updated every 30 minutes)
X-Container-Bytes-Used-Actual	Int	Allocated backend storage block size
X-Container-Object-Count	Int	Number of objects (updated every 30 minutes)
X-Storage-Class	String	Storage class (STANDARD)
X-Storage-Policy	String	Storage policy (default-placement)

HTTP status codes

HTTP status	Description
200	Success
401	Unauthorized
403	Forbidden
404	Not found

Change bucket metadata

If you have the storage.buckets.update permission, you can modify metadata for a bucket you have access to.
Refer to roles and permissions for more details on Object Storage permissions.

Request syntax

Change bucket metadata request syntax

curl --location --request POST 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'X-Object-Meta-Company: kakao enterprise'

API call method

Method	Request URL
POST	https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}

Request parameters

Path	Type	Required	Description
region_name	String	Yes	Region name (e.g., kr-central-2)
account	String	Yes	Project ID (used as account in Swift API)
bucket_name	String	Yes	Bucket name

Request headers

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token
X-Object-Meta-{name}	String	Yes	Custom metadata key/value to be set for the bucket

HTTP status codes

HTTP status	Description
200	Success
401	Unauthorized

---

Bucket CORS policy

Configure new CORS policy

Users with the storage.buckets.setIamPolicy permission can set CORS policies for individual buckets.
For more details, refer to roles and permissions.

• If "cors": [] or an empty body is passed, all existing CORS configurations will be removed and the default CORS policy will be applied.
• This setting only affects the following APIs:
  • /v1/:account/:container
  • /v1/:account/:container/*object
  • /:bucket (kr-central-2 S3 API)
  • /:bucket/*object (kr-central-2 S3 API)

info

If no CORS policy is set, access from external domains (non-console) will be denied.

Request syntax

CORS policy configuration request syntax

curl --request PUT --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors' \
--header 'X-Auth-Token: {x-auth-token}'     \
--header 'Content-Type: application/json'   \
--data '{
  "cors": [
    {
      "allowed_origins": [
        "https://www.example1.com"
      ],
      "allowed_methods": [
        "PUT",
        "GET"
      ],
      "allowed_headers": [
        "*"
      ],
      "expose_headers": [],
      "max_age_seconds": 10
    },
    {
      "allowed_origins": [
        "https://www.example2.com"
      ],
      "allowed_methods": [
        "PUT",
        "GET",
        "DELETE"
      ],
      "allowed_headers": [
        "*"
      ],
      "expose_headers": [
        "X-Object-Meta-User-Defined"
      ],
      "max_age_seconds": 10
    }
  ]
}'

API call method

Method	Request URL
PUT	https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors

Request parameters

Path	Type	Required	Description
region_name	String	Yes	Region name (e.g., kr-central-2)
bucket_name	String	Yes	Bucket name

Request headers

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token
Content-Type	String	Yes	Must be application/json

Request body elements

Field	Type	Required	Description
cors ▼	List	Yes	CORS policy array (maximum of 10 entries)
allowed_origins	List	Yes	List of allowed origins (e.g., "https://example.com")
allowed_methods	List	Yes	HTTP methods allowed (e.g., GET, PUT, DELETE)
allowed_headers	List	Yes	List of allowed headers
expose_headers	List	Yes	Headers exposed to browsers
max_age_seconds	Int	No	Duration to cache preflight request results

Response syntax

CORS policy configuration response syntax

{
  "cors": [
    {
      "allowed_origins": [
        "https://www.example1.com"
      ],
      "allowed_headers": [
        "*"
      ],
      "allowed_methods": [
        "PUT",
        "GET"
      ],
      "expose_headers": [],
      "max_age_seconds": 10
    },
    {
      "allowed_origins": [
        "https://www.example2.com"
      ],
      "allowed_headers": [
        "*"
      ],
      "allowed_methods": [
        "PUT",
        "GET",
        "DELETE"
      ],
      "expose_headers": [
        "X-Object-Meta-User-Defined"
      ],
      "max_age_seconds": 10
    }
  ]
}

HTTP status codes

HTTP status	Description
200	OK (Success)
400	Bad request
401	Unauthorized
403	Forbidden
404	Bucket not found

Query bucket CORS policy

If you have the storage.buckets.getIamPolicy permission, you can query the CORS configuration for an individual bucket.
Refer to roles and permissions for more information on Object Storage access control.

Request syntax

CORS policy query request syntax

curl --request GET --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors' \
--header 'X-Auth-Token: {x-auth-token}'     \
--header 'Content-Type: application/json'

API call method

Method	Request URL
GET	https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors

Request parameters

Path	Type	Required	Description
region_name	String	Yes	Region name (e.g., kr-central-2)
bucket_name	String	Yes	Bucket name

Request headers

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token
Content-Type	String	Yes	Must be application/json

Response syntax

CORS policy query response syntax

{
  "cors": [
    {
      "allowed_origins": ["https://www.example1.com"],
      "allowed_headers": ["*"],
      "allowed_methods": ["PUT", "GET"],
      "expose_headers": [],
      "max_age_seconds": 10
    },
    {
      "allowed_origins": ["https://www.example2.com"],
      "allowed_headers": ["*"],
      "allowed_methods": ["PUT", "GET", "DELETE"],
      "expose_headers": ["X-Object-Meta-User-Defined"],
      "max_age_seconds": 10
    }
  ]
}

Response elements

Field	Type	Required	Description
cors ▼	List	Yes	CORS policies (up to 10 entries)
allowed_origins	List	Yes	List of allowed origins (supports one *, max length: 200 per origin)
allowed_methods	List	Yes	Allowed HTTP methods
allowed_headers	List	Yes	Allowed HTTP headers
expose_headers	List	Yes	Headers exposed to browsers
max_age_seconds	Int	No	Preflight request result cache duration

HTTP status codes

HTTP status	Description
200	OK (Success)
400	Bad request
401	Unauthorized (auth failed)
403	Forbidden (no permission)

---

CORS preflight request

You can send a CORS preflight request to a bucket.

• If a CORS configuration was applied via PUT /v1_ext/bucket/:name/cors, the APIs listed below will respond accordingly:
  • /v1/:account/:container
  • /v1/:account/:container/*object
  • /:bucket (kr-central-2 S3 API)
  • /:bucket/*object (kr-central-2 S3 API)

Request syntax

CORS preflight request syntax

curl --location --request OPTIONS 'http://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/test.txt' \
--header 'Origin: https://www.example1.com' \
--header 'Access-Control-Request-Headers: X-Auth-Token,Content-Type' \
--header 'Access-Control-Request-Method: GET'

Request parameters

Path	Type	Required	Description
account	String	Yes	Project ID (used as account in Swift API)
bucket_name	String	Yes	Bucket name

Request headers

Header	Type	Required	Description
Origin	String	Yes	Full origin (protocol + host + port)
Access-Control-Request-Headers	List	Yes	Requested headers (e.g., X-Auth-Token, Content-Type)
Access-Control-Request-Method	List	Yes	Requested methods (e.g., PUT, GET, DELETE)

API call method

Method	Request URL
OPTIONS	Multiple variations depending on the object path and region, such as: - /v1/:account/:name - /v1/:account/:name/*object - /v1_ext/bucket/:name - /v1_ext/bucket/:name/policy/:id

Response headers

Header	Type	Description
Content-Length	Int	Body size
Access-Control-Allow-Credentials	Boolean	Whether to allow credentials (true or false)
Access-Control-Allow-Headers	String	Allowed HTTP headers
Access-Control-Allow-Methods	String	Allowed HTTP methods
Access-Control-Allow-Origin	String	Allowed origin
Access-Control-Expose-Headers	String	Headers exposed to browser
Access-Control-Max-Age	Int	Cache duration for preflight request results

Response syntax

CORS preflight request response syntax

HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: PUT, GET
Access-Control-Allow-Origin: https://www.example1.com
Access-Control-Expose-Headers:
Access-Control-Max-Age: 10
Vary: Origin
Strict-Transport-Security: max-age=31536000; includeSubDomains

HTTP status codes

HTTP status	Description
200	OK (Success)
401	Unauthorized (auth failed)
403	Forbidden (no permission)

Requests other than CORS preflight

CORS validation is performed based on the request. If the request does not comply with the configured CORS policy, headers such as Access-Control-Allow-Header, Access-Control-Allow-Methods, and Access-Control-Max-Age will not be included in the response.
To apply CORS, the Origin header must be set in the request.

Request syntax

Request syntax for non-preflight CORS

curl --location --request GET 'http://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{object}' \
--header 'x-auth-token: {x-auth-token}' \
--header 'Origin: https://www.example1.com'

API call method

Method	Request URL
GET	http://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{object}

Request parameters

Path	Type	Required	Description
region_name	String	Yes	Region name (e.g., kr-central-2)
account	String	Yes	Project ID (used in Swift API as the account value)
bucket_name	String	Yes	Bucket name
object	String	Yes	Object name

Request headers

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token

Response syntax

Response header for non-preflight CORS

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 10
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: https://www.example1.com
Access-Control-Allow-Methods: PUT, GET
Access-Control-Expose-Headers: {}
Etag: {ETag value}
Last-Modified: Thu, 07 Jul 2022 08:13:27 GMT
Vary: Origin

Response elements

Header	Description
Content-Type	Indicates the media type of the resource
Content-Length	Size of the response body in bytes
Access-Control-Allow-Credentials	Allows credential sharing between domains - true: allowed - false: not allowed
Access-Control-Allow-Origin	Allowed origin
Access-Control-Expose-Headers	Headers exposed to the browser
Etag	Unique hash value for the object - Helps optimize caching and detect mid-air collisions
Last-Modified	Last modified time of the object

HTTP status codes

HTTP status	Description
200	OK (success)
401	Unauthorized
403	Forbidden

Bucket lifecycle

To create and manage a bucket lifecycle, the storage.buckets.update permission is required.
For more information about Object Storage permissions, refer to Roles and permissions.

Create bucket lifecycle

When a new lifecycle configuration is created, any existing configuration will be overwritten.
Therefore, if only a portion of an existing lifecycle needs to be updated, the full configuration must be retrieved, modified, and resubmitted.

Request syntax

Create bucket lifecycle request syntax

PUT /v1_ext/bucket/{bucket_name}/lifecycle
X-Auth-Token: {x-auth-token}

<?xml version="1.0"?>
<LifecycleConfiguration>
    <Rule>
        <ID>day1Rule</ID>
        <Expiration>
            <Days>1</Days>
        </Expiration>
        <Prefix>expire1/</Prefix>
        <Status>Enabled</Status>
    </Rule>
    <Rule>
        <ID>dateRule</ID>
        <Expiration>
            <Date>2023-06-10T00:00:00.000Z</Date>
        </Expiration>
        <Prefix>20230-06-08/</Prefix>
        <Status>Enabled</Status>
    </Rule>
</LifecycleConfiguration>

API call method

Method	Request URL
PUT	https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle

Request header

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token

Request body

Element	Type	Required	Description
Rule ▼	List	Yes	List of lifecycle policies
ID	String	Optional	Unique identifier for the rule (max 255 characters)
Expiration ▼	Struct	Yes	Expiration configuration (must include either Date or Days)
Date	Timestamp	Optional	Expiration date in ISO 8601 format
Days	Integer	Optional	Number of days after object creation until expiration (positive integer)
Filter ▼	Struct	Optional	Filtering conditions for the rule
Prefix	String	Yes	Prefix to apply the rule to Special characters must be escaped using XML entities
Status	String	Yes	Enable or disable the rule (Enabled, Disabled)

Response syntax

Create bucket lifecycle response syntax

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 01 Feb 2023 07:23:12 GMT
Content-Length: 376

<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
    <Rule>
        <ID>day1Rule</ID>
        <Expiration>
            <Days>1</Days>
        </Expiration>
        <Prefix>expire1/</Prefix>
        <Status>Enabled</Status>
    </Rule>
    <Rule>
        <ID>dateRule</ID>
        <Expiration>
            <Date>2023-06-10T00:00:00.000Z</Date>
        </Expiration>
        <Prefix>20230-06-08/</Prefix>
        <Status>Enabled</Status>
    </Rule>
</LifecycleConfiguration>

HTTP status codes

HTTP status	Description
200	OK (success)
400	Bad request (invalid configuration)
401	Unauthorized
403	Forbidden
404	Not found (bucket not found)

View bucket lifecycle list

If you have storage.buckets.update permission, you can manage the lifecycle configuration for a bucket to automate object expiration and optimize storage space.

info

The expiration rule runs once daily at midnight (00:00).
If the policy is deleted before midnight on the expiration date, it will not be applied.

Request syntax

View bucket lifecycle list request syntax

curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle' \
--header 'X-Auth-Token: {X-Auth-Token}'

API call method

Method	Request URL
GET	https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle

Request header

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token

Response syntax

View bucket lifecycle list response syntax

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 01 Feb 2023 07:23:12 GMT
Content-Length: 376

<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
    <Rule>
        <ID>day1Rule</ID>
        <Expiration>
            <Days>1</Days>
        </Expiration>
        <Prefix>expire1/</Prefix>
        <Status>Enabled</Status>
    </Rule>
    <Rule>
        <ID>dateRule</ID>
        <Expiration>
            <Date>2023-06-10T00:00:00.000Z</Date>
        </Expiration>
        <Prefix>20230-06-08/</Prefix>
        <Status>Enabled</Status>
    </Rule>
</LifecycleConfiguration>

HTTP status codes

HTTP status	Description
200	OK (success)
400	Bad request (invalid configuration)
401	Unauthorized
403	Forbidden
404	Not found (bucket not found)

Delete bucket lifecycle

A user with lifecycle access can delete a bucket’s lifecycle configuration.

Request syntax

Delete bucket lifecycle request syntax

curl --location --request DELETE 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle' \
--header 'X-Auth-Token: {X-Auth-Token}'

API call method

Method	Request URL
DELETE	https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle

Request header

Header	Type	Required	Description
X-Auth-Token	String	Yes	User authentication token

HTTP status codes

HTTP status	Description
200	OK (success)
400	Bad request (invalid configuration)
401	Unauthorized
403	Forbidden
404	Not found (bucket not found)