SWIFT & EXTENSION

KakaoCloud Object Storage is compatible with the Swift API and additionally provides KakaoCloud-specific Extension APIs.

Prerequisite

• For the prerequisite tasks required to call the API, refer to Prepare for API use.

API endpoint URL

After checking the region information, you can call the Object Storage API endpoint URL.

Object Storage API endpoint URL format

https://objectstorage.{region_name}.kakaocloud.com

List supported features

List supported Extension APIs

Extention API naming	Description
GetBucketMeta	Retrieve bucket metadata information (including bucket ACL information).
CreateBucket	Create a bucket. (Includes bucket encryption settings)
DeleteBucket	Delete a bucket.
ListBuckets	Retrieve the list of all buckets in the account.
UpdateBucketAcl	Modify the bucket ACL (Access Control List).
PutBucketLifecycleConfiguration	Create or modify the bucket lifecycle configuration.
GetBucketLifecycleConfiguration	Retrieve the bucket lifecycle configuration.
DeleteBucketLifecycleConfiguration	Delete the bucket lifecycle configuration.
GetBucketCors	Retrieve the bucket CORS configuration.
PutBucketCors	Create or update the bucket CORS configuration.

List supported Swift APIs

info

"KakaoCloud complies with the OpenStack Swift API specification, but for service stability and security, some parameters are restricted or provided with fixed default values. We recommend using primarily the parameters described below."

Swift naming	Description
Head Container	Check whether a container exists
List Containers	Retrieve the list of containers in the account
List Capability	Retrieve the list of features/permissions available to the account (extension)
Create Container	Create a new container
Delete Container	Delete a container
Update Container Metadata	Modify container metadata
Get Object	Download an object
Head Object	Retrieve object metadata
List Objects	Retrieve the list of objects in a container
Create Object	Upload an object
Update Object Metadata	Modify object metadata
Delete Object	Delete an object
Copy Object	Copy an object
Initiate Multipart Upload	Initialize multipart upload
Upload Part	Upload a multipart part
List Parts	Retrieve the list of uploaded parts
List Multipart Uploads	Retrieve the list of in-progress multipart uploads
Abort Multipart Upload	Abort multipart upload
Complete Multipart Upload	Complete multipart upload
Create SLO Manifest	Upload a Static Large Object (SLO) manifest
Create DLO Manifest	Upload a Dynamic Large Object (DLO) manifest
Get Object Temp URL	Issue a temporary URL that can access the object (extension)

Use Extension API guide

GetBucketMeta

If you have the storage.buckets.get permission, you can retrieve bucket metadata.

API call method

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

Request Syntax

Request Syntax

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

Path Parameters

Variable	Description
region_name	Service region name (example: kr-central-2)
bucket_name	Target bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

GetBucketMeta Response Syntax

  {
      "project": "1b3c5b406a194bf09ac446627a39d916",
      "account": "1b3c5b406a194bf09ac446627a39d916",
      "name": "bucket_name",
      "type": "STANDARD",
      "bytes": 0,
      "objectCount": 0,
      "createdAt": "2025-10-15T07:30:40Z",
      "use_encryption": true,
      "encryption_type": "managed",
      "lastModified": "2025-10-15T07:30:40Z",
      "storageClass": "STANDARD",
      "storagePolicy": "default-placement",
      "acl": {
          "public": "deny",
          "public_read_allow_ip_list": null
      }
  }

Response Header

Request	Type	Required	Description
X-Container-Meta-*	String	Required	User-defined metadata information

Response Elements

Response	Type	Description
project	string	Project ID
name	string	Bucket name
type	string	Bucket type - STANDARD
bytes	int	Total size of objects in the bucket - Updated every 30 minutes, so it may differ from the current usage
objectCount	int	Total number of objects in the bucket - Updated every 30 minutes, so it may differ from the current count
createdAt	time	Bucket creation date and time
use_encryption	boolean	Whether bucket encryption is enabled
lastModified	time	Bucket last modified date and time
storageClass	string	Storage class type - STANDARD
acl ▼	List	Access control policy
public	string	Whether public access is allowed - read-only,deny
public_read_allow_ip_list	string	List of IPs allowed for public access - If an IP list is configured, unauthenticated access is allowed only from those IPs

CreateBucket

Create a bucket.

API call method

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

Request Syntax

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": "bucket_name",
    "type": "STANDARD",
    "use_encryption": true,
    "encryption_configuration": {
        "type": "managed"
    }
}'

Path Parameters

Variable	Description
region_name	Service region name (example: kr-central-2)

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	Enter the user authentication token
Content-Type	String	Required	Fixed to application/json

Request Body

Request Syntax

  {
    "name": "bucket_name",
    "type": "STANDARD",
    "use_encryption": true,
    "encryption_configuration": {
      "type": "managed"
    }
  }

Variable	Type	Required	Description
name	String	Required	Bucket name
type	String	Required	Bucket type - Standard(default): standard bucket
use_encryption	Boolean	Optional	Whether bucket encryption is enabled If encryption_configuration is provided, this value is ignored - false(default): no encryption - true: encrypted (Same as encryption_configuration.type = managed)
encryption_configuration ▼	Structure	Optional	Bucket encryption settings
type	String	Required	Encryption method - managed(default): automatic encryption provided by KakaoCloud - true(planned support): encryption integrated with a key management service using KMS

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

CreateBucket Response Syntax

{
   "account": "project-id",
   "project": "project-id",
   "name": "bucket_name",
   "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

Response	Type	Description
account (Deprecated)	String	Project ID - Account value in the Swift API. Can be checked when issuing a token (project ID used/checked during token issuance)
project	String	Project ID
name	String	Created bucket name
type	String	Created bucket type - STANDARD(default): standard bucket
bytes	String	Total usage - Unit: Byte
objectCount	Int	Number of objects in the bucket
createdAt	String	Creation date - Format: RFC3339 - Example: 2020-07-01T00:00:00Z
use_encryption	Boolean	Whether bucket encryption is enabled - false(default): no encryption - true: encrypted
encryption_type	String	Bucket encryption type
lastModified	String	Last modified date - Format: RFC3339 - Example: 2020-07-01T00:00:00Z
storageClass	String	Storage class type - STANDARD(default): bucket in the standard class
storagePolicy	String	Zone of the storage class - default-placement(default)
acl ▼	-	Access permission for the bucket - If null is entered, the existing ACL settings are deleted
public	String	Whether public access is allowed - read-only, deny
public_read_allow_ip_list	List	List of IPs allowed for public access

DeleteBucket

You can delete a bucket owned by the user. To delete a bucket, the storage.buckets.delete permission is required.

• If objects exist in the bucket, the bucket cannot be deleted.

API call method

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

Request Syntax

Request Syntax

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

Path Parameters

Variable	Description
region_name	Service region name (example: kr-central-2)
bucket_name	Target bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 204 response.

ListBuckets

You can retrieve the bucket list.

API call method

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

Request Syntax

ListBuckets Request Syntax

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

Path Parameters

Variable	Description
region_name	Service region name (example: kr-central-2)

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token

Request Query

Request	Type	Required	Description
offset	Query	Optional	Retrieve n bucket items starting from the offset - Offset starts from 0 - Default: 0
limit	Query	Optional	Limit the number of items - Default: 20 (up to 100 items can be retrieved)
prefix	Query	Optional	Search bucket names by prefix
include	Query	Optional	Search bucket names by included string - Cannot be used together with Prefix
type	Query	Optional	Type search condition - STANDARD (kr-central-2)
by	Query	Optional	Sort field - bucket_name: bucket name - bucket_type: bucket type - created_at: bucket last modified date - bytes_used: bucket usage
direct	Query	Optional	Sort order - asc: ascending (default) - desc: descending

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

ListBuckets Response Syntax

  {
    totalCount: int
    offset: int
    count: int
    items: [SimpleBucket]
  }  

Response Elements

Response	Type	Description
totalCount	Int	Total number of buckets
offset	Int	Retrieve n bucket items starting from the offset - From the i-th to the i+n-th item
count	Int	Number of returned buckets
items	List	Detailed bucket information

UpdateBucketAcl

You can manage access to a bucket owned by the user. Through the following request, you can apply public access or IP list-based access control to a bucket owned by the user.

API call method

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

Request Syntax

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"
    ]
  }
}'

Path Parameters

Variable	Description
region_name	Service region name (example: kr-central-2)
bucket_name	Target bucket name

Request Header

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

Request Elements

Request	Type	Required	Description
bucket_name	String	Required	Bucket name
acl ▼	Structure	Required	Access permission for the bucket - If null is entered, the existing ACL settings are deleted
public	String	Optional	Whether public access is allowed - read-only: allowed - deny: not allowed (same as acl = null)
public_read_allow_ip_list	List	Optional	List of IPs to allow access

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

Bucket access control 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

Response	Type	Description
account (Deprecated)	String	Project ID - Can be checked when issuing a token (project ID used/checked during token issuance). Scheduled for deletion
project	String	Project ID - Can be checked when issuing a token (project ID used/checked during token issuance)
name	String	Created bucket name
type	String	Created bucket type - STANDARD(default): standard bucket
bytes	String	Total usage- Unit: Byte
objectCount	Int	Number of objects in the bucket
createdAt	String	Creation date - Format: https://www.rfc-editor.org/rfc/rfc3339 - Example: 2020-07-01T00:00:00Z
use_encryption	Boolean	Whether bucket encryption is enabled - false(default): no encryption - true: encrypted
encryption_type	String	Bucket encryption type
lastModified	String	Last modified date - Format: https://www.rfc-editor.org/rfc/rfc3339 - Example: 2020-07-01T00:00:00Z
storageClass	String	Storage class type - STANDARD(default): bucket in the standard class
storagePolicy	String	Zone of the storage class - default-placement(default)
acl ▼	-	Access permission for the bucket - If null is entered, the existing ACL settings are deleted
public	String	Whether public access is allowed - read-only, deny
public_read_allow_ip_list	List	List of IPs allowed for public access

PutBucketLifecycleConfiguration

You can configure object lifecycle policies.

warning

The existing lifecycle policy is overwritten. Therefore, if you need to update only part of the existing lifecycle policy, you must retrieve the full configuration, modify only the required parts, and then send the update request.

API call method

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

Request Syntax

Request Syntax

curl --request PUT --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/xml' \
--data-raw '<?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>2023-06-08/</Prefix>
        <Status>Enabled</Status>
    </Rule>
</LifecycleConfiguration>'

Path Parameters

Variable	Description
region_name	Service region name (example: kr-central-2)
bucket_name	Target bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token

Request Body

Request	Type	Required	Description
Rule ▼	List	Required	Lifecycle policy
ID	String	Optional	ID that identifies the rule - Unique string within 255 characters
Expiration ▼	Structure	Required	Deletion settings - You must enter either the Date or Days field
Date	Timestamp	Optional	Date to delete the object - Only GMT ISO 8601 format 2023-06-10T00:00:00.000Z is allowed
Days	integer	Optional	Object lifecycle - The object is deleted after the configured number of days from the creation date - Only positive integers other than 0 can be entered
Filter ▼	Structure	Optional	Specifies conditions for objects to which the lifecycle policy applies
Prefix	String	Required	Prefix of objects to which the rule applies - The following special characters must be replaced with XML entity codes ' → &apos; ” → &quot; & → &amp; < → &lt; > → &gt; \r → &#13; or &#x0D; \n → &#10; or &#x0A; For more information, refer to AWS XML-related object key constraints documentation
Status	String	Required	Whether the lifecycle policy is enabled - Enabled : enabled - Disabled : disabled

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

Lifecycle policy configuration 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>

Response Elements

Response	Type	Description
Rule ▼	List	Lifecycle policy
ID	string	ID that identifies the rule - Unique string within 255 characters
Prefix	string	Prefix of objects to which the rule applies - The following special characters are replaced with XML entity codes ' → &apos; ” → &quot; & → &amp; < → &lt; > → &gt; \r → &#13; or &#x0D; \n → &#10; or &#x0A; For more information, refer to AWS XML-related object key constraints documentation
Status	string	Whether the lifecycle policy is enabled - Enabled: enabled - Disabled: disabled
Expiration	integer	Deletion settings

GetBucketLifecycleConfiguration

If you have the storage.buckets.update permission, you can create and manage the Object Storage lifecycle and define a set of lifecycle rules to apply to groups of objects. Through the bucket lifecycle, you can efficiently manage storage space by deleting unused files.

Notice

The Expiry Rule of the lifecycle runs once a day, at 00:00 (midnight). If you delete the lifecycle policy before 00:00 or before 12:00 on the day the object expires, the policy is not applied immediately.

API call method

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

Request Syntax

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}' 

Path Parameters

Variable	Description
region_name	Service region name (example: kr-central-2)
bucket_name	Target bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

Bucket lifecycle list retrieval 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>

Response Elements

Response	Type	Description
Rule ▼	List	Lifecycle policy
ID	string	ID that identifies the rule - Unique string within 255 characters
Prefix	string	Prefix of objects to which the rule applies - The following special characters are replaced with XML entity codes ' → &apos; ” → &quot; & → &amp; < → &lt; > → &gt; \r → &#13; or &#x0D; \n → &#10; or &#x0A; For more information, refer to AWS XML-related object key constraints documentation
Status	string	Whether the lifecycle is enabled - Enabled : lifecycle enabled - Disabled : lifecycle disabled
Expiration	integer	Deletion settings

DeleteBucketLifecycleConfiguration

A user with lifecycle access permission can delete the bucket lifecycle.

API call method

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

Request Syntax

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}'

Path Parameters

Variable	Description
region_name	Service region name (example: kr-central-2)
bucket_name	Target bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

GetBucketCors

If you have the storage.buckets.getIamPolicy permission, you can retrieve the CORS configuration value for an individual bucket.

API call method

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

Request Syntax

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'

Path Parameters

Variable	Description
region_name	Service region name (example: kr-central-2)
bucket_name	Target bucket name

Request Header

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

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

CORS policy retrieval 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

Request	Type	Required	Description
cors ▼	List	Required	CORS policy - Maximum number of CORS policies that can be configured: 10
allowed_origins	List	Required	Allowed origins for access - Includes up to one * (wildcard) character - Maximum allowed length per origin: 200
allowed_methods	List	Required	Allowed access methods (HTTP)
allowed_headers	List	Required	Allowed access headers
expose_headers	List	Required	Headers exposed to the browser
max_age_seconds	Int	Optional	Lifetime for caching preflight request results

PutBucketCors

A user with the storage.buckets.setIamPolicy permission can configure the CORS policy for an individual bucket. For detailed Object Storage permissions, refer to Roles and permissions. When a new CORS configuration is applied to a bucket, the entire list is updated.

Notice

If no CORS policy is configured, access from external domains other than the console is not allowed.

API call method

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

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
    }
  ]
}'

Path Parameters

Variable	Description
region_name	Service region name (example: kr-central-2)
bucket_name	Target bucket name

Request Header

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

Request Body

Request	Type	Required	Description
cors ▼	list	Required	CORS policy- Maximum number of CORS policies that can be configured: 10
allowed_origins	List	Required	Allowed origins for access - Includes protocol such as http or https - Includes up to one * (wildcard) character - Maximum allowed length per origin: 200 - Port can be specified - If port 80 or 443 is explicitly specified together with the protocol, and the subsequently entered Origin Header specifies only the protocol without the port, the CORS allowed header is not returned
allowed_methods	List	Required	Allowed access methods - PUT, POST, GET, DELETE, etc.
allowed_headers	List	Optional	Allowed access headers
expose_headers	List	Optional	Headers exposed to the browser
max_age_seconds	Int	Optional	Lifetime for caching preflight request results - If omitted, not cached

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

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
    }
  ]
}

Request CORS preflight

You can send a CORS preflight request for a bucket.

If CORS is configured for a bucket, you can perform a CORS preflight (OPTIONS) request through the Swift(ext) API or S3 API path, and the request returns CORS response headers for the bucket and object path.

If a CORS policy is configured for a bucket, the browser performs a preflight request using the OPTIONS method before sending the actual request.
For testing purposes, developers can verify it directly with curl as follows.

Request Syntax

CORS preflight request Request Syntax

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

Path Parameters

Variable	Description
region_name	Service region name (example: kr-central-2)
account	Project ID - Can be checked when issuing a token (project ID used/checked during token issuance) - Used as the Account value in the Swift API
bucket_name	Bucket name
object_name	Object name

Request Header

Request	Type	Required	Description
Origin	String	Required	Origin - The server location including protocol, host, and port
Access-Control-Request-Headers	List	Required	List of headers for the preflight request - X-Auth-Token, Content-Type
Access-Control-Request-Method	List	Required	List of methods for the preflight request - Example: PUT, POST, GET, DELETE

Response Header

Response	Type	Description
Content-Length	Int	Body length
Access-Control-Allow-Credentials	Boolean	Option that allows cookie sharing across different domains - true: allow - false: do not allow
Access-Control-Allow-Headers	String	HTTP headers that are allowed to access the resource
Access-Control-Allow-Methods	String	Specifies the HTTP methods that are allowed to access the resource
Access-Control-Allow-Origin	String	Allowed origin for access
Access-Control-Expose-Headers	String	Headers exposed to the browser
Access-Control-Max-Age	Int	Time for which the preflight request result can be cached

Status code

For a CORS preflight (OPTIONS) request, the server responds with a 204 No Content status code, and whether CORS is allowed is determined based on the response headers (Access-Control-Allow-*).

Notice

If a 403 Forbidden error occurs in the browser after completing the CORS configuration (PutBucketCors), first check with the curl command above whether the preflight request returns the allowed Origin and Method.

Use Swift API guide

Head Container

API call method

Method	Request URL
HEAD	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}

Request Syntax

Head Container Request Syntax

curl --request HEAD --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Target bucket name

Request Header

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

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

Response Header

Request	Type	Description
X-Container-Object-Count	Integer	Total number of objects in the bucket
X-Container-Bytes-Used	Integer	Logical total size of objects stored in the bucket (Byte)
X-Container-Bytes-Used-Actual	Integer	Actual physical total size occupied on disk including replicas (Replication), etc. (Byte)
X-Storage-Policy	String	Name of the storage policy applied to the bucket (example: Policy-0)
X-Timestamp	Float	Unix timestamp when the bucket was created or last modified
X-Trans-Id	String	Unique transaction identifier for request processing (used for incident response)
X-Openstack-Request-Id	String	Unique request ID assigned by the OpenStack service
Content-Type	String	Format of the response data (usually text/plain; charset=utf-8)

List Containers

Retrieve the list of all buckets created in the project.

API call method

Method	Request URL
GET	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}

Request Syntax

List Containers Request Syntax

curl --request GET --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project

Request Header

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

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

ListBuckets Response Syntax

[
  my-bucket-01
  my-bucket-02
  my-bucket-03
  my-bucket-04
  my-bucket-05
]

Response Header

Request	Description
X-Acoount-Container-Count	Total number of buckets (Containers) created in the project (Acoount)
X-Acoount-Object-Count	Total sum of all objects stored in all buckets in the project
X-Acoount-Bytes-Used	Logical total size of all objects in the project Sum of the original file sizes uploaded by the user (unit: Byte)
X-Acoount-Bytes-Used-Actual	Actual physical total size occupied by all objects in the project Replication capacity for data protection (unit: Byte)
X-Acoount-Storage-Policy-Default-Placement-Container-Count	Number of buckets to which the 'Default-Placement' policy is applied
X-Acoount-Storage-Policy-Default-Placement-Object-Count	Total number of objects in buckets with the 'Default-Placement' policy applied
X-Acoount-Storage-Policy-Default-Placement-Bytes-Used	Logical total usage in the 'Default-Placement' policy environment
X-Acoount-Storage-Policy-Default-Placement-Bytes-Used-Actual	Actual physical total occupied size in the 'Default-Placement' policy environment
X-Timestamp	Unix timestamp when the project information was last modified or the statistics were updated
X-Trans-Id	Unique transaction identifier assigned by the system for the request Used for log tracing when an error occurs
X-Openstack-Request-Id	Unique request ID assigned by the OpenStack infrastructure

ListCapability

Retrieve the list of Object Storage features and permissions available to the project.

API call method

Method	Request URL
GET	https://objectstorage.{Region_Name}.kakaocloud.com/info

Request Syntax

ListCapability Request Syntax

curl --request GET --location 'https://objectstorage.{Region_Name}.kakaocloud.com/info'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)

Request Header

This request may not require a separate authentication header. (Depends on configuration)

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

ListCapability Response Syntax

{
    "swift": {
        "version": "objectstorage-api-v2.0.21-126",
        "Acoount_listing_limit": 1000,
        "max_meta_length": 4096,
        "min_meta_value_length": 0,
        "max_meta_value_length": 512,
        "container_listing_limit": 1000,
        "max_file_size": 5368709120,
        "max_object_name_length": 396,
        "min_object_name_length": 1,
        "min_meta_name_length": 2,
        "max_meta_name_length": 64,
        "max_Acoount_name_length": 32,
        "min_container_name_length": 4,
        "max_container_name_length": 63,
        "policies": [
            {
                "name": "default-placement",
                "default": true
            }
        ]
    },
    "tempurl": {
        "methods": [
            "GET"
        ]
    },
    "slo": {
        "max_manifest_segments": 1000,
        "min_segment_size": 1,
        "max_manifest_size": 8392704
    },
    "tempauth": {}
}

Response Element

Request	Type	Description
version	String	Current version of the Object Storage API
Acoount_listing_limit	Integer	Maximum number of bucket lists that can be retrieved in a single request (1,000)
max_file_size	Integer	Maximum file size that can be processed in a single upload (unit: Byte, approximately 5 GB)
max_meta_name_length	Integer	Maximum length of the metadata key name (64 characters)
max_meta_value_length	Integer	Maximum length of the metadata value (512 characters)
max_meta_length	Integer	Maximum total length of all metadata (4,096 characters)
max_object_name_length	Integer	Maximum allowed length of the object name (Key) (396 characters)
min_container_name_length	Integer	Minimum length of the bucket name (4 characters)
max_container_name_length	Integer	Maximum length of the bucket name (63 characters)
policies	Array	List of supported storage policies
policies.name	String	Name of the policy (example: default-placement)
policies.default	Boolean	Whether the policy is applied by default
tempurl	Object	Information related to the temporary URL issuance feature
methods	Array	List of HTTP methods allowed through the temporary URL (example: GET)
slo	Object	Constraints related to Static Large Object (SLO)
max_manifest_segments	Integer	Maximum number of parts that can be included in one SLO manifest (1,000)
min_segment_size	Integer	Minimum size of a part when configuring SLO (1 Byte)
max_manifest_size	Integer	Maximum size of the SLO manifest file itself (Byte)
tempauth	Object	Object indicating whether the temporary authentication module is enabled

Create Container

Create a new bucket.

API call method

Method	Request URL
PUT	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}

Request Syntax

Create Container Request Syntax

curl --request PUT --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Target bucket name

Request Header

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

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 201 response.

Delete Container

Delete a bucket.

API call method

Method	Request URL
DELETE	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}

Request Syntax

Delete Container Request Syntax

curl --request DELETE --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Target bucket name

Request Header

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

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 204 No Content response.

Update Container Metadata

Create, modify, or delete bucket metadata.

API call method

Method	Request URL
POST	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}

Request Syntax

Update Container Metadata Request Syntax

curl --request POST --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Target bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token
Content-Type	String	Required	Fixed to application/json
X-Container-Meta-key	String	Optional	Metadata value Value ex) key = metadata key name, Value = metadata value
X-Remove-Container-Meta-key	String	Optional	Delete metadata

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 204 No Content response.

Get Object

Download an object.

API call method

Method	Request URL
GET	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}

Request Syntax

Get Object Request Syntax

curl --request GET --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Target bucket name
Object_Key	Unique key of the object (including path)

Request Header

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

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response. Loads the requested object.

Response Header

Request	Description
Date	Response creation time
Content-Type	Format of the content contained in the body
Content-Length	Object size
Connection	Whether the connection is reused
Accept-Ranges	The client can request a portion of the file in bytes
Etag	Identifier used by the web server to identify whether the content or metadata of the resource has changed
Last-Modified	Last modified date
X-Object-Storage-Class	Integer
X-Openstack-Request-Id	String
X-Trans-Id	String
X-Rgw-Object-Type	String

Head Object

Retrieve object head information.

API call method

Method	Request URL
HEAD	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}

Request Syntax

Head Object Request Syntax

curl --request HEAD --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Target bucket name
Object_Key	Unique key of the object (including path)

Request Header

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

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

Response Header

Request	Description
Date	Response creation time
Content-Type	Format of the content contained in the body
Content-Length	Object size
Connection	Whether the connection is reused
Accept-Ranges	The client can request a portion of the file in bytes
Etag	Identifier used by the web server to identify whether the content or metadata of the resource has changed
Last-Modified	Last modified date
X-Object-Storage-Class	Integer
X-Openstack-Request-Id	String
X-Trans-Id	String
X-Rgw-Object-Type	String

List Objects

Retrieve the list of objects (files, folders) stored in a bucket.

API call method

Method	Request URL
GET	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}?format=json

Request Syntax

List Containers Request Syntax

curl --request GET --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}?format=json' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Target bucket name

Request Query

Request	Type	Required	Description
prefix	Query	Optional	Directory path - Example: image/small
delimiter	Query	Optional	If delimiter is used as the key, enter /
limit	Query	Optional	Number of items - Default: 1000 (up to 1,000 items can be retrieved)
marker	Query	Optional	Search condition - (Object name > Marker )
format	Query	Optional	Format to receive the response - plain(default) - json - xml

Request Header

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

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

List Objects Response Syntax

[
    {
        "name": "apple1.JPG",
        "hash": "4fabff2e18b68ae780cf0bc54d1fec82",
        "bytes": 1699756,
        "content_type": "image/jpeg",
        "last_modified": "2026-02-19T04:44:38.302Z"
    },
]    

Response Elements

Response	Type	Description
name	String	Object name
content_type	String	Returns the Content-Type value entered when the object was PUT - Type: directory / image / generic binary, etc.
bytes	int	Object size
hash	String	Unique file value
last_modified	String	Last modified date and time - Format: RFC3339 - Example: 2020-07-01T00:00:00Z
subdir	String	Only this value is provided in the case of a pseudo-directory

Create Object

Upload an object to a bucket.

API call method

Method	Request URL
PUT	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}

Request Syntax

Create Object Request Syntax

curl --request PUT --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'
--data-binary {local_file_part_path}

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Target bucket name
Object_Key	Unique key of the object (including path)

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token
Content-Type	String	Optional	If the object being Put (uploaded) is a file, enter the mime type string - If the content type is not entered during Put (upload), Object Storage internally treats the type of the currently uploaded file as application/octet-stream
X-Object-Meta-{name}	String	Optional	Bucket metadata, where the user-defined metadata name is entered in {name}
Content-Length	int	Optional	Content length
Transfer-Encoding	String	Optional	Encoding method - chunked : a method of transferring data divided into a series of chunks, and if the chunked value is specified, the Content-Length Header must not be sent - compress : compression method using the LZW algorithm - deflate : compression method using the deflate algorithm - gzip : compression method using the LZ77 algorithm - identity : transfer method without compression or modification

Request Body

Object data. (This is the actual data being uploaded.)
Transfer the file stream (Byte Stream) directly in the body.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

Update Object Metadata

Create, modify, or delete object metadata.

API call method

Method	Request URL
POST	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}

Request Syntax

Update Object Metadata Request Syntax

curl --request POST --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Target bucket name
Object_Key	Unique key of the object (including path)

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token
Content-Type	String	Optional	If the object being Put (uploaded) is a file, enter the mime type string - If the content type is not entered during Put (upload), Object Storage internally treats the type of the currently uploaded file as application/octet-stream
X-Object-Meta-{name}	String	Optional	Bucket metadata, where the user-defined metadata name is entered in {name}
Content-Length	int	Optional	Content length

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

Delete Object

Delete an object.

API call method

Method	Request URL
DELETE	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}

Request Syntax

Delete Object Request Syntax

curl --request DELETE --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}' \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Target bucket name
Object_Key	Unique key of the object (including path)

Request Query

Request	Type	Required	Description
multipart-manifest	Query	Required	Enter the delete value to specify deleting all connected segments together.

Request Header

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

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 204 response.

Copy Object

Copy an object.

API call method

Method	Request URL
PUT	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{dest_Bucket_Name}/{dest_Object_Key}

Request Syntax

Copy Object Request Syntax

curl --request PUT --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{dest_Bucket_Name}/{dest_Object_Key}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Length: 0' \
--header 'X-Copy-From: /{src_bucket_name}/{src_object_key}' 

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
dest_Bucket_Name	Name of the target (destination) bucket where the copied object will be stored
dest_Object_Key	Unique key (including path) of the target (destination) object to be newly created by copying

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token
Content-Length	String	Required	Fixed to application/json
X-Fresh-Metadata	String	Optional	If set to True, the source metadata is not copied and only the new metadata included in the request is applied
X-Copy-From	String	Required	Path of the source object

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 201 response.

Initiate Multipart Upload

Initialize multipart upload for large object upload.
This request must succeed before a unique UploadId can be issued to upload file parts.

API call method

Method	Request URL
POST	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_name}/{Object_Key}?uploads

Request Syntax

Initiate Multipart Upload Request Syntax

curl --request POST --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_name}/{Object_Key}?uploads` \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Target bucket name
Object_Key	Unique key of the object (including path)

Request Header

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

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

DeleteObjects Response Syntax

    <?xml version="1.0" encoding="UTF-8"?>
    <InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
        <Tenant>String</Tenant>
        <Bucket>String</Bucket>
        <Key>String</Key>
        <UploadId>String</UploadId>
    </InitiateMultipartUploadResult>

Response Elements

Response	Description
Tenant	Project ID
Bucket	Bucket name where the upload is in progress
Key	Name (Path) of the object to be uploaded
UploadId	Unique ID that identifies the multipart upload. Used when calling UploadPart and CompleteMultipartUpload

Upload Part

Upload a large object divided into multiple parts.
After all parts are uploaded, you must call CompleteMultipartUpload to combine them into a single object.

API call method

Method	Request URL
PUT	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?partNumber={n}&uploadId={Upload_Id}

Request Syntax

Upload Part Request Syntax

curl --request PUT --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?partNumber={n}&uploadId={Upload_Id}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/octet-stream' \
--upload-file {local_file_part_path}

Path Parameters

| Path | Description | | --- | --- | --- | --- | | Region_Name | Service region name (example: kr-central-2) | | Acoount | Unique ID of the project | | Bucket_Name | Bucket name | | Object_Key | Unique key of the object (including path) |

Request Query

Request	Type	Required	Description
uploadId	Query	Required	Unique upload ID of the large object returned from Initiate Multipart Upload
partNumber	Query	Required	Part number of the current file part being uploaded in the large object (1~10000)

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token
Content-Type	String	Required	Fixed to application/octet-stream

Request Body

Object data. (This is the actual data being uploaded.)
Transfer the file stream (Byte Stream) directly in the body.

Response Syntax

If the operation succeeds, the service returns an HTTP 201 response.

Response Header

Request	Description
Date	Response creation time
Etag	Identifier used by the web server to identify whether the content or metadata of the resource has changed
X-Trans-Id	String
X-Openstack-Request-Id	String

List Part

Retrieve the list of parts successfully uploaded for a specific multipart upload.

API call method

Method	Request URL
GET	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploadId={Upload_Id}

Request Syntax

List Part Request Syntax

curl --request GET --location 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploadId={Upload_Id}' \
--header 'X-Auth-Token: {x-auth-token}' \

Path Parameters

Path	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Bucket name
Object_Key	Unique key of the object (including path)

Request Query

Request	Type	Required	Description
uploadId	Query	Required	Unique upload ID of the large object returned from Initiate Multipart Upload

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

Response Header

Request	Description
Date	Response creation time
Etag	Identifier used by the web server to identify whether the content or metadata of the resource has changed
X-Trans-Id	String
X-Openstack-Request-Id	String

List Multipart Uploads

Retrieve the list of all incomplete and in-progress multipart uploads in a specific bucket.

API call method

Method	Request URL
GET	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploads

Request Syntax

List Multipart Uploads Request Syntax

curl --request GET --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploads` \
--header 'X-Auth-Token: {x-auth-token}' \

Path Parameters

Path	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Bucket name
Object_Key	Unique key of the object (including path)

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

List Multipart Uploads Response Syntax

  <?xml version="1.0" encoding="UTF-8"?>
  <ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
      <Tenant>String</Tenant>
      <Bucket>String</Bucket>
      <NextKeyMarker>String</NextKeyMarker>
      <NextUploadIdMarker>String</NextUploadIdMarker>
      <MaxUploads>Integer</MaxUploads>
      <IsTruncated>Boolean</IsTruncated>
      <Upload>
          <Key>String</Key>
          <UploadId>String</UploadId>
          <Initiator>
              <ID>String</ID>
              <DisplayName>String</DisplayName>
          </Initiator>
          <Owner>
              <ID>String</ID>
              <DisplayName>String</DisplayName>
          </Owner>
          <StorageClass>String</StorageClass>
          <Initiated>Timestamp</Initiated>
      </Upload>
  </ListMultipartUploadsResult>

Response Elements

Response	Type	Description
Tenant	String	Project ID
Bucket	String	Bucket name
NextKeyMarker	String	Value to use for the key-marker request parameter in the next request
NextUploadIdMarker	String	Value to use for the upload-id-marker request parameter in the next request
MaxUploads	Integer	Maximum number of multipart uploads
IsTruncated	String	Whether the part list is truncated
Key	String	Object key to upload
UploadId	String	Multipart upload ID
ID	String	Project ID
DisplayName	String	Project name
StorageClass	String	Storage class
Initiated	Timestamp	Multipart upload start date and time

Abort Multipart Upload

Abort an in-progress multipart upload and delete all uploaded parts.
The aborted UploadId can no longer be used.

API call method

Method	Request URL
DELETE	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploadId={upload_id}

Request Syntax

Abort Multipart Upload Request Syntax

curl --request DELETE --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploadId={upload_id}` \
--header 'X-Auth-Token: {x-auth-token}' \

Path Parameters

Path	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Bucket name
Object_Key	Unique key of the object (including path)

Request Query

Request	Type	Required	Description
uploadId	Query	Required	Unique upload ID of the large object returned from Initiate Multipart Upload

Request Header

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

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 204 response.

CompleteMultipartUpload

API call method

Method	Request URL
POST	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploadId={upload_id}

Request Syntax

CompleteMultipartUpload Request Syntax

curl --request POST --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{Object_Key}?uploadId={upload_id}` \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '<CompleteMultipartUpload>
    <Part>
        <PartNumber>1</PartNumber>
        <ETag>"897a0f868d69985acdbf1e9f9d6f3603"</ETag>
    </Part>
</CompleteMultipartUpload>'

Path Parameters

Path	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Bucket name
Object_Key	Unique key of the object (including path)

Request Query

Request	Type	Required	Description
uploadId	Query	Required	Unique upload ID of the large object returned from Initiate Multipart Upload

Request Header

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

Request Body

CompleteMultipartUpload Response Syntax

<CompleteMultipartUpload>
   <Part>
      <ETag>String</ETag>
      <PartNumber>Integer</PartNumber>
   </Part>
   ...
</CompleteMultipartUpload>

Request Elements

Request	Type	Required	Description
ETag	String	Optional	Hash value of the object
PartNumber	Integer	Optional	Part identifier number (positive integer between 1 and 10,000)

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

SLO(Static Large Object) method

The SLO method uploads segments by splitting them as with DLO, but differs in that there is no segment naming restriction and the sizes do not have to be the same. Also, the manifest must be uploaded last. The SLO Manifest Object must be entered by listing the Segment Object entries in order. Currently, KC Object Storage supports up to 1,000 Segment Objects in one manifest.

When you send a request to create an SLO Manifest Object, it checks whether each Segment Object exists at the specified path and whether the etag value and Segment object size match. If the information does not match, the Manifest Object is not created. In addition, the integrity of the Segment Object is guaranteed through the etag in the manifest.

1. Split a single large object into segments of the size desired by the user.
2. Upload each segment to a bucket for which you have access permission. It does not have to be the same bucket, but it must be a bucket in a project (Acoount) for which you have access permission.
3. Upload the SLO Manifest Object by entering the manifest containing the Path, Etag, and Size of the uploaded Segment objects in the body.

Notice

For detailed examples of the manifest, refer to https://objectstorage.kr-central-2.kakaocloud.com/info.

Create SLO Manifest

Create a static large object (SLO) by uploading a JSON manifest file containing information about the uploaded segments (parts).

API call method

Method	Request URL
PUT	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{SLO Manifest Object}?multipart-manifest=put

Request Syntax

Create SLO Manifest Request Syntax

curl --request PUT --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{SLO Manifest Object}?multipart-manifest=put` \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '[
   {
      "path": "{Bucket_Name}/{Segment Object}",
      "etag": "{Segment Object Etag}}",
      "size_bytes": {Segment Object Size}
   },
   {
      "path": "{Bucket_Name}/{Segment Object}",
      "etag": "{Segment Object Etag}}",
      "size_bytes": {Segment Object Size}
   },
   {
      "path": "{Bucket_Name}/{Segment Object}",
      "etag": "{Segment Object Etag}}",
      "size_bytes": {Segment Object Size}
   }
]'

Path Parameters

Path	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Bucket name
SLO Manifest Object	Manifest object name

Request Header

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

Request Body

Create SLO Manifest Response Syntax

[
   {
      "path": "jay-cool-1/video_part_aa",
      "etag": "841aa70a236b55d22260aa4defe699cf",
      "size_bytes": 52428800
   },
   {
      "path": "jay-cool-1/video_part_ab",
      "etag": "30c4e8955088e398b2b87d52554d3f90",
      "size_bytes": 23052099
   }
   ...
]

Request Elements

Request	Type	Required	Description
Path	String	Required	Enter in the Path/Segment Object format - Path: path to upload the object - Segment Object: segment object under the path
ETag	String	Required	Hash value of the object
size_bytes	Integer	Required	Size of the Segment Object

Notice

When entering etag and size_bytes during Manifest PUT, if the values do not match the etag and size_bytes values of the previously uploaded segment object, an error occurs

Response Syntax

If the operation succeeds, the service returns an HTTP 201 response.

Create DLO Manifest

Create a manifest file that groups objects with a specific prefix into one large object.

API call method

Method	Request URL
PUT	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{DLO Manifest Object}

Request Syntax

Create DLO Manifest Request Syntax

curl --request PUT --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Account}/{Bucket_Name}/{DLO Manifest Object}` \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'X-Object-Manifest: {Bucket_Name}/{Segment_Object_Prefix}' \
--header 'Content-Length: 0'

Path Parameters

Path	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Bucket name
Object_Key	Unique key of the object (including path)

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	User authentication token
X-Object-Manifest	String	Required	Specify {bucket name}/{prefix} where the segment files are located. - Ascending sequence number naming is required (example: segment_0001 ... segment_0002 )

Response Syntax

If the operation succeeds, the service returns an HTTP 201 response.

Get Object Temp URL

Create temp URL for Object download

Create a temp URL for object download.
A user who has access permission to the object creates a download temp URL valid for a specific period. temp_url_expires is used as the expiration time so that the object can be downloaded until the time specified by the user.

API call method

Method	Request URL
GET	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}?temp_url&temp_url_expires={temp_url_expires}

Request Syntax

Create temp URL for Object download Request Syntax

curl --request GET --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}?temp_url&temp_url_expires={temp_url_expires}` \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Target bucket name
Object_Key	Unique key of the object (including path)

Request Header

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

Request Query

Request	Type	Required	Description
temp_url	String	Required	Key indicating a TempUrl issuance request
temp_url_expires	timestamp	Required	Valid time of the issued TempUrl - Unit: sec

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response.

Response Body

Get Object Temp URL response Syntax

    {
        "url": "/v1/{project_id}/object-reg-test-1/test.txt?temp_url_sig={temp_url_sig}&temp_url_expires={temp_url_expires}",
        "sig": "{sig}"
    }

Response Elements

Response	Type	Description
url	string	Temporary URL that can download the object within the expire time
sig	string	Signature of the URL, valid within the expire time of the object

Download Object using Temp URL

Download an object using a Temp URL.
By using the created Temp URL, you can download the object during the valid time requested when it was issued.
When using a Temp URL, the object can be downloaded without X-Auth-Token, so the issuer of the Temp URL must deliver it only to trusted users.

API call method

Method	Request URL
GET	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}?temp_url&temp_url_expires={temp_url_expires}

Request Syntax

Download Object using Temp URL Request Syntax

curl --request GET --location `https://objectstorage.{Region_Name}.kakaocloud.com/v1/{Acoount}/{Bucket_Name}/{Object_Key}?temp_url_sig={temp_url_sig}&temp_url_expires={temp_url_expires}` \
--header 'X-Auth-Token: {x-auth-token}'
--header 'Content-Type: application/json'

Path Parameters

Variable	Description
Region_Name	Service region name (example: kr-central-2)
Acoount	Unique ID of the project
Bucket_Name	Target bucket name
Object_Key	Unique key of the object (including path)

Request Query

Request	Type	Required	Description
temp_url_sig	Query	Required	Signature information from the issued Temp URL response
temp_url_expires	Query	Required	Valid time information from the issued Temp URL response - Unit: Unix epoch time
filename	Query	Optional	Custom file name to use when downloading the object from the browser - UTF-8 percent-encoded string

Request Header

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

Request Body

This request does not have a body value.

Response Syntax

If the operation succeeds, the service returns an HTTP 200 response. Loads the requested object.

Common status codes

HTTP Status	Response content	Description
200	OK	Success
204	No Content	Success
400	BadRequest	Request information error
401	Unauthorized	Authentication failed
403	Forbidden	No permission
404	Not Found	Requested resource not found
409	Conflicts	Conflict