Object_file & folder

Use the Object:File&Folder API to create and manage policies and metadata related to files and folders.

Prerequisite

To call the API, refer to the API preparation guide.

API endpoint URL

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

Object_file & folder API endpoint format

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

Supported specifications

The Object REST API follows the OpenStack Swift API specifications.

Object REST-API	Swift API terminology
Account	Bucket account
Container	Bucket name
Object	Folder and file - Folder example: `images/small` - File example: `image/small/icon.jpg`

Create folder

Users with Owner or Read-Write permissions can create folders within a bucket.

Request syntax

Create folder request syntax
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}/' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/directory' \
--header 'X-Object-Meta-Company: kakao enterprise'

API call method

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

Path	Type	Required	Description
region_name	String	Required	Region name: `kr-central-2`
account	String	Required	Project ID - Available during token issuance (used/confirmed during token issuance process) - Used as the Account value in Swift API
bucket_name	String	Required	Name of the bucket
path	String	Required	Full folder path - Example: `image/small`, `images/small/icon.jpg`

Request header

Header	Type	Required	Description
X-Auth-Token	String	Required	User authentication token
Content-Type	String	Required	Fixed to `application/directory`
`X-Object-Meta-{key_name}`	String	Optional	Bucket metadata key specified by user - Applies the Swift API prefix
`X-amz-Meta-{key_name}`	String	Optional	Bucket metadata key specified by user - Applies the S3 API prefix

Response syntax

Status codes

HTTP Status	Response	Description
`201`	Created	Success
`401`	Unauthorized	Authentication failed
`403`	Forbidden	No permission

Create and upload file

Users with Owner or Read-Write permissions can create or upload files to a bucket.

Request syntax

Create and upload file request syntax
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}/{file}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: text/plain' \
--data-raw '{Content}'

API call method

Method	Request URL
PUT	`https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}/{file}`

Path	Type	Required	Description
region_name	String	Required	Region name: `kr-central-2`
account	String	Required	Project ID - Confirmed during token issuance - Used as Account in Swift API
bucket_name	String	Required	Bucket name
path	String	Required	Full folder path - Example: `image/small`, `images/small/icon.jpg`
file	String	Required	File name - Example: `icon.jpg`

Request header

Header	Type	Required	Description
X-Auth-Token	String	Required	User authentication token
Content-Type	String	Optional	MIME type of uploaded object - If omitted, defaults to `application/octet-stream`
`X-Object-Meta-{name}`	String	Optional	Metadata key specified by user
Content-Length	Int	Optional	Length of content
Transfer-Encoding	String	Optional	Encoding method: - `chunked`: sends data in chunks (must omit `Content-Length`) - `compress`, `deflate`, `gzip`, `identity`: compression algorithms

Request body elements

Element	Type	Required	Description
Content	Raw data	Required	Content of the file

Status codes

HTTP Status	Response	Description
`201`	Created	Success
`401`	Unauthorized	Authentication failed
`403`	Forbidden	Permission denied

Upload large file

Since HTTP does not maintain persistent connections, file uploads can be interrupted if the TCP connection is lost. KakaoCloud Object Storage provides large object upload methods for reliable upload of large files.

caution

Not supported on encrypted buckets.
If uploading a file with the same name but a different size, leftover segment files may remain.
We recommend checking for and deleting orphaned segment files using object listing.

Large object upload methods

Method	Description
DLO (Dynamic Large Object)	Treats segmented objects as a single large object - Swift protocol
SLO (Static Large Object)	No naming or size restrictions on segments - Swift protocol

DLO (Dynamic Large Object) method

The DLO method allows segmented objects to be recognized as one large object. It does not guarantee the integrity of each segment. When downloading the object, the Object Storage server recognizes the manifest and assembles the segments.

Split a large object into segments.
Upload each segment under a path.
Upload a manifest object with X-Object-Manifest header. (The manifest can be uploaded first.)

DLO segment object upload

Request syntax

DLO segment object upload
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}/{Segment Objects...}' \
--header 'X-Auth-Token: {x-auth-token}' \
--data-raw '{segment_content}'

Example

DLO segment upload example
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/test-bucket/DLO/00000001 --data-binary '1'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/test-bucket/DLO/00000002 --data-binary '2'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/test-bucket/DLO/00000003 --data-binary '3'

API call method

Method	URL
PUT	`https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}/{Segment Objects…}`

Path parameters

Parameter	Type	Required	Description
region_name	String	Yes	`kr-central-2`
account	String	Yes	Project ID
bucket_name	String	Yes	Bucket name
DLO Manifest Object	String	Yes	Manifest object name
Segment Objects…	String	Yes	Segmented object files in sequence

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

Status codes

HTTP Status	Response	Description
`201`	Created	Success

Upload DLO manifest object

Request syntax

DLO manifest upload request syntax
curl --location --request PUT '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}/{DLO Manifest Object}' \

DLO manifest object upload example
curl -X PUT -H 'X-Auth-Token: <token>' -H 'X-Object-Manifest: test-bucket/DLO' https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/test-bucket/DLO --data-binary ''

API call method

Method	URL
PUT (Upload segmented objects)	`https:/objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}/{Segment Object…}`
PUT (Upload manifest object itself)	`https:/objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}`

Path	Type	Required	Description
region_name	String	Required	`kr-central-2`
account	String	Required	Project ID - Confirmed during token issuance - Used as Account in Swift API
bucket_name	String	Required	Bucket name
DLO Manifest Object	String	Required	Name of the manifest object
Segment Object…	String	Required	Multiple segment objects can be uploaded

Request header

Header	Type	Required	Description
X-Auth-Token	String	Required	User authentication token
X-Object-Manifest	String	Required	Path to the uploaded segment objects - Format: `{bucket_name}/{DLO Manifest Object}`

Response syntax

Status codes

HTTP Status	Response	Description
`201`	Created	Success

Download DLO

Request syntax

Download LO request syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}' \
--header 'X-Auth-Token: {x-auth-token}' \

Download DLO example
curl -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/test-bucket/DLO

API call method

Method	URL
GET	`https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}`

Path	Type	Required	Description
region_name	String	Required	`kr-central-2`
account	String	Required	Project ID - Confirmed during token issuance - Used as Account in Swift API
bucket_name	String	Required	Bucket name
DLO Manifest Object	String	Required	Name of the manifest object

Request header

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

Response syntax

Status codes

HTTP Status	Response	Description
`201`	Created	Success

DLO download

Request syntax

DLO download request syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}' \
--header 'X-Auth-Token: {x-auth-token}' \

DLO download example
curl -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/test-bucket/DLO

API method

Method	URL
PUT	`https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}`

Path	Type	Required	Description
region_name	String	Required	`kr-central-2`
account	String	Required	Project ID - Available when issuing a token - Used as the Account value in Swift API
bucket_name	String	Required	Bucket name
DLO Manifest Object	String	Required	Manifest object name

Request header

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

Response syntax

Status codes

HTTP status	Response	Description
`201`	Created	Success

SLO (static large object) method

The SLO method also uploads data by splitting it into segments, similar to the DLO method. However, it differs in that it does not impose naming restrictions on segments, and the segment sizes do not need to be uniform. Additionally, the manifest must be uploaded last. The SLO manifest object must contain a list of segment objects in the correct order. KC Object Storage currently supports including up to 1,000 segment objects in a single manifest.

When a request is made to create an SLO manifest object, the system verifies that each segment object exists at the specified path and that the etag value and segment size match the metadata. If the information does not match, the manifest object is not created. The use of etag also ensures the integrity of each segment object referenced in the manifest.

A large object is split into segments according to the desired size.
Each segment is uploaded to a bucket with proper access permissions. Segments do not have to be in the same bucket, but must reside in buckets that belong to a project (account) with access rights.
A manifest object is uploaded by specifying the path, etag, and size of each uploaded segment in the body of the request.

info

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

Upload SLO segment object

Request syntax

SLO segment upload request syntax
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}/{segment_object}' \
--header 'X-Auth-Token: {x-auth-token}' \
--data-raw '{segment_content}'

SLO segment object upload example
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/test-bucket/slo_test_1.txt --data-binary '@./slo_test_1.txt'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/other-bucket/slo_test_2.txt --data-binary '@./slo_test_2.txt'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/other1-bucket/slo_test_3.txt --data-binary '@./slo_test_3.txt'

API method

Method	URL
PUT	`https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}/{segment_object}`

Path	Type	Required	Description
region_name	String	Required	`kr-central-2`
account	String	Required	Project ID - Available when issuing a token - Used as the Account value in Swift API
bucket_name	String	Required	Bucket name
path	String	Required	Path where the segment object is uploaded
segment_object	String	Required	Name of the segment object

Request header

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

Request elements

Field	Type	Required	Description
segment_content	Raw-data	Required	Content of the segment object

Response syntax

Status codes

HTTP status	Response	Description
`201`	Created	Success

Upload SLO manifest

Request syntax

SLO manifest upload request syntax
curl --location --request PUT '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": "{path}/{segment object}",
            "etag": "{etag value of the segment object}",
            "size_bytes": "{segment object size}"
        },
        ....
    ]
}'

SLO manifest object upload example
curl -X PUT -H 'X-Auth-Token: <token>' -H 'Content-Type: application/json' https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/bucket/SLO?multipart-manifest=put \
--data \
'
[
   {
      "path": "test-bucket/slo_test_1.txt",
      "etag": "ba1f2511fc30423bdbb183fe33f3dd0f",
      "size_bytes": 4
   },
   {
      "path": "other-bucket/slo_test_2.txt",
      "etag": "441295deac01cf5d6bdc7db3173adfdf",
      "size_bytes": 1369
   },
   {
      "path": "other1-bucket/slo_test_3.txt",
      "etag": "aa3f5bb8c988fa9b75a1cdb1dc4d93fc",
      "size_bytes": 4
   }
]
'

API method

Method	URL
PUT	`https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{SLO Manifest Object}?multipart-manifest=put`

Path	Type	Required	Description
account	String	Required	Project ID - Available when issuing a token - Used as the Account value in Swift API
bucket_name	String	Required	Bucket name
SLO Manifest Object	String	Required	Name of the manifest object

Request header

Header	Type	Required	Description
X-Auth-Token	String	Required	User authentication token
Content-Type	String	Required	Type of the content

Request elements

Field	Type	Required	Description
path	String	Required	Enter in the format `{path}/{segment object}` - `{path}`: Path where the object is uploaded - `{segment object}`: Segment object under the specified path
etag	String	Optional	`etag` value of the segment object
size_bytes	Int	Optional	Size of the segment object

info

When performing a manifest PUT operation, the system compares the input etag and size_bytes with those of the already uploaded segment objects. If they do not match, an error is returned.

Response syntax

Status codes

HTTP status	Response	Description
`201`	Created	Success

Download SLO

Request syntax

SLO download request syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{SLO Manifest Object}' \
--header 'X-Auth-Token: {x-auth-token}' \

SLO download example
curl -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/bucket/SLO

API method

Method	URL
PUT	`https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{SLO Manifest Object}`

Path	Type	Required	Description
account	String	Required	Project ID - Available when issuing a token - Used as the Account value in Swift API
bucket_name	String	Required	Bucket name
SLO Manifest Object	String	Required	Name of the manifest object

Request header

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

Response syntax

Status codes

HTTP status	Response	Description
`201`	Created	Success

Download SLO manifest

SLO allows downloading only the SLO manifest object separately. By using the query parameter multipart-manifest=get, you can retrieve only the manifest object without downloading the full large object.

Request syntax

SLO manifest download request syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{SLO Manifest Object}?multipart-manifest=get' \
--header 'X-Auth-Token: {x-auth-token}' \

SLO manifest object download example
curl -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/test-bucket/SLO?multipart-manifest=get

API method

Method	URL
PUT	`https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{SLO Manifest Object}?multipart-manifest=get`

Path	Type	Required	Description
account	String	Required	Project ID - Available when issuing a token - Used as the Account value in Swift API
bucket_name	String	Required	Bucket name
SLO Manifest Object	String	Required	Name of the manifest object

Request header

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

Response syntax

Status codes

HTTP status	Response	Description
`201`	Created	Success

Multipart upload

Provides an extension of the OpenStack Swift Object API for multipart upload. This enables large file uploads using a method similar to the S3 multipart upload API.
The S3 multipart upload API, provided by AWS, allows uploading large files by splitting them into multiple parts, uploading them individually, and then combining them.
For more information on the S3 multipart upload API, refer to the S3 multipart upload documentation.
Object Storage does not support the Swift SLO (static large object) or DLO (dynamic large object) APIs.

Multipart upload consists of the following three steps:

Step 1. Initiate multipart upload

Request syntax

Initiate multipart upload request syntax
curl --location --request POST 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}?uploads' \
--header 'X-Auth-Token: {x-auth-token}' 

API method

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

Path	Type	Required	Description
account	String	Required	Project ID - Available during token issuance - Used as the Account value in Swift API
bucket_name	String	Required	Bucket name
path	String	Required	Full folder path - Example: `image/small`, `images/small/icon.jpg`

Request header

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

Response syntax

Initiate multipart upload response syntax
<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult>
    <Tenant>{tenant-id}</Tenant>
    <Bucket>{bucket-name}</Bucket>
    <Key>{object-path}</Key>
    <UploadId>{upload-id}</UploadId>
</InitiateMultipartUploadResult>

Response elements

Field	Type	Description
tenant-id	String	Project ID
bucket-name	String	Bucket name
object-path	String	File path
upload-id	String	Unique upload ID assigned by the server

Status codes

HTTP status	Response	Description
`201`	Created	Success
`401`	Unauthorized	Authentication failed
`403`	Forbidden	Access denied

Step 2. Upload part

Each part must be at least 5 MB in size.

Request syntax

Upload part request syntax
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}?uploadId={upload-id}&partNumber={part-number}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/octet-stream' \
--data '{path_name}'

API method

Method	Request URL
PUT	`https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}?uploadId={upload-id}&partNumber={part-number}`

Path	Type	Required	Description
account	String	Required	Project ID
bucket_name	String	Required	Bucket name
path	String	Required	Full folder path

Request query parameters

Parameter	Type	Required	Description
uploadId	Query	Required	Unique upload ID returned by `CreateMultipartUpload`
partNumber	Query	Required	Sequence number of the current part (1–10000)

Request header

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

Response header

Header	Type	Description
etag	String	ETag of the uploaded part

Status codes

HTTP status	Response	Description
`200`	Created	Success
`401`	Unauthorized	Authentication failed
`403`	Forbidden	Access denied

Step 3. Complete multipart upload

Request syntax

Complete multipart upload request syntax
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}?uploadId={upload-id}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/xml' \
--data '<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUpload>
    <Part>
        <ETag>"<etag of 5MB_1.file>"</ETag>
        <PartNumber>1</PartNumber>
    </Part>
    <Part>
        <ETag>"<etag of 5MB_2.file>"</ETag>
        <PartNumber>2</PartNumber>
    </Part>
    <Part>
        <ETag>"<etag of remain.file>"</ETag>
        <PartNumber>3</PartNumber>
    </Part>
</CompleteMultipartUpload>'

API method

Method	Request URL
PUT	`https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}?uploadId={upload-id}`

Path	Type	Required	Description
account	String	Required	Project ID
bucket_name	String	Required	Bucket name
path	String	Required	Full folder path

Request query parameters

Parameter	Type	Required	Description
uploadId	Query	Required	Unique upload ID returned by `CreateMultipartUpload`

Request header

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

Response elements

Field	Type	Description
ETag	String	ETag of the uploaded part
PartNumber	Integer	Part number of the uploaded part

Status codes

HTTP status	Response	Description
`201`	Created	Success
`401`	Unauthorized	Authentication failed
`403`	Forbidden	Access denied

Manage object

Query object metadata

Users with Owner, Read-Only, or Read-Write permissions can query object metadata in a bucket. This provides metadata for stored objects (files, folders) in the bucket.

Request syntax

Query object metadata request syntax
curl --location --request HEAD 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}' \
--header 'X-Auth-Token: {x-auth-token}'

API method

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

Path	Type	Required	Description
region_name	String	Required	Region name: `kr-central-2`
account	String	Required	Project ID - Available during token issuance - Used as the Account value in Swift API
bucket_name	String	Required	Bucket name
path	String	Required	Full path to the object - Example: `image/small`, `images/small/icon.jpg`

Request header

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

Status codes

HTTP status	Response	Description
`200`	Success	Success
`401`	Unauthorized	Authentication failed
`403`	Forbidden	Access denied

Change object metadata

Users with Owner or Read-Write permissions can update object metadata for files or folders stored in the bucket.

Request syntax

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

API method

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

Path	Type	Required	Description
region_name	String	Required	Region name: `kr-central-2`
account	String	Required	Project ID
bucket_name	String	Required	Bucket name
path	String	Required	Full path to the object

Request header

Header	Type	Required	Description
X-Auth-Token	String	Required	User authentication token
`X-Object-Meta-{name}`	String	Optional	Metadata to assign to the object. Replace `{name}` with the metadata key.

Status codes

HTTPS status	Response	Description
`200`	Success	Success
`401`	Unauthorized	Authentication failed
`403`	Forbidden	Access denied

Query object list

Users with Owner, Read-Write, or Read-Only permissions can list objects (files, folders) stored in a bucket.

Request syntax

Query object list request syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}?format=json' \
--header 'X-Auth-Token: {x-auth-token}'

API method

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

Path	Type	Required	Description
region_name	String	Required	Region name: `kr-central-2`
account	String	Required	Project ID
bucket_name	String	Required	Bucket name

Request header

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

Request query parameters

Parameter	Type	Required	Description
prefix	Query	Optional	Directory path - Example: `image/small`
delimiter	Query	Optional	Use `/` as delimiter when listing with key prefix
limit	Query	Optional	Maximum number of items - Default: `1000` (maximum 1,000 items)
marker	Query	Optional	Listing starts after the specified object name
format	Query	Optional	Response format - `plain` (default) - `json` - `xml`

Response syntax

JSON object list
[
    {
        "name": "document",
        "content_type": "application/directory",
        "bytes": 0,
        "hash": "d41d8cd98f00b204e9800998ecf8427e",
        "last_modified": "2020-06-26T11:12:03+09:00"
    },
    {
        "name": "document/hello.txt",
        "content_type": "application/octet-stream",
        "bytes": 7,
        "hash": "083d9fe8506415ba02f2f86e0531527f",
        "last_modified": "2020-06-26T11:14:50+09:00"
    }
]

Response elements

Field	Type	Description
name	String	Object name
content_type	String	Value returned from the `Content-Type` at the time of upload
bytes	int	Object size
hash	String	Unique file hash
last_modified	String	Last modified timestamp - Format: RFC3339
subdir	String	Provided only for pseudo-directories

Status codes

HTTPS status	Response	Description
`200`	OK	Success
`401`	Unauthorized	Authentication failed
`403`	Forbidden	Access denied

Download object

Users with Owner, Read-Write, or Read-Only permissions can download objects from a bucket.
If the specified path is a folder, the response will contain a content size of 0. To list contents inside a folder, use the object list API.

Request syntax

Download object request syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}' \
--header 'X-Auth-Token: {x-auth-token}'

API method

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

Path	Type	Required	Description
region_name	String	Required	Region name: `kr-central-2`
account	String	Required	Project ID
bucket_name	String	Required	Bucket name
path	String	Required	Full object path (e.g., `image/small`, `images/small/icon.jpg`)

Request header

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

Response syntax

Object download response syntax
{
   Content-Length (Header),
   Content-Type (Header),
   Last-Modified (Header),
   ETag (Header),
   Content (Body)
}

Response headers

Header	Type	Description
Content-Length	int	Size of the object - For files: actual file size - For folders: `0`
Content-Type	String	Type of the content
Last-Modified	String	Last modified timestamp
ETag	String	MD5 hash of the binary object (folders may return meaningless ETags)

Response elements

Field	Type	Description
Content	Raw data	Not returned for folder-type objects

Status codes

Status code	Response	Description
`200`	OK	Success
`401`	Unauthorized	Access denied
`404`	Not found	File not found

Delete object

Users with Owner or Read-Write permissions can delete objects from a bucket.

Request syntax

Delete object request syntax
curl --location --request DELETE 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}' \
--header 'X-Auth-Token: {x-auth-token}'

API method

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

Request header

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

Status codes

HTTPS status	Response	Description
`204`	No content	Success
`401`	Unauthorized	Access denied
`404`	Not found	File not found

Copy object

Copying an object requires read permission on the source and Read-Write permission on the destination.

Request syntax

Copy object request syntax
curl --location --request COPY 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Destination: /{target-bucket-name}/{target-path}'

API method

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

Request header

Header	Type	Required	Description
X-Auth-Token	String	Required	User authentication token
Destination	String	Required	Destination path for the copy - Example: `{target-bucket-name}/{target-path}`

Status codes

HTTPS status	Response	Description
`201`	Created	Success
`401`	Unauthorized	Access denied
`404`	Not found	File not found

Move object

To move an object, the source bucket must grant storage.objects.get permission, and the destination bucket must allow storage.objects.create.

Not available for encrypted buckets in kr-central-2 region.

Request syntax

Move object request syntax
curl --location --request MOVE 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Destination: /{target-bucket-name}/{target-path}'

API method

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

Request header

Header	Type	Required	Description
X-Auth-Token	String	Required	User authentication token
Destination	String	Required	Destination path for the move - Example: `{target-bucket-name}/{target-path}`

Status codes

HTTPS status	Response	Description
`201`	Created	Success
`401`	Unauthorized	Access denied
`404`	Not found	File not found

Create temp URL for downloading object

Users with access to the object can generate a temporary URL for downloading it. The temp_url_expires parameter defines the validity period, allowing the object to be downloaded until the specified expiration time.

Request syntax

Create temp URL for downloading object request syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}?temp_url&temp_url_expires={temp_url_expires}' \
--header 'X-Auth-Token: {x-auth-token}'

API method

Method	Request URL
GET	`https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}?temp_url&temp_url_expires={temp_url_expires}`

Path	Type	Required	Description
account	String	Required	Project ID - Available during token issuance - Used as the Account value in the Swift API
bucket_name	String	Required	Bucket name
path	String	Required	Full object path - Example: `image/small`, `images/small/icon.jpg`

Request header

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

Request query parameters

Parameter	Type	Required	Description
temp_url	String	Required	Indicates the request is for generating a temp URL
temp_url_expires	Timestamp	Required	Expiration time of the generated temp URL (in seconds)

Response syntax

Create temp URL for downloading object response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Thu, 09 Mar 2023 04:44:00 GMT
Content-Length: 209

{
  "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

Field	Type	Description
url	String	Temporary URL to download the object within the expiration time
sig	String	Signature used to validate the temp URL until the expiration time

Status codes

HTTPS status	Response	Description
`200`	OK	Success
`403`	Forbidden	Access denied
`404`	Not found	Bucket not found

Download object using temp URL

A generated temp URL allows object download within the specified valid time. Since the download does not require X-Auth-Token, the URL should only be shared with trusted users.

Request syntax

Download object using temp URL request syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}?temp_url_sig={temp_url_sig}&temp_url_expires={temp_url_expires}'

API method

Method	Request URL
GET	`https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}?temp_url_sig=value&temp_url_expires=value&filename=name`

Path	Type	Required	Description
region_name	String	Required	Region name: `kr-central-2`
account	String	Required	Project ID
bucket_name	String	Required	Bucket name
path	String	Required	Full object path

Request query parameters

Parameter	Type	Required	Description
temp_url_sig	Query	Required	Signature from the temp URL response
temp_url_expires	Query	Required	Expiration timestamp in Unix epoch format
filename	Query	Optional	Custom filename for download in browser (UTF-8 percent-encoded string)

Response syntax

Download using temp URL response syntax
{
   Content-Length (Header),
   Content-Type (Header),
   Last-Modified (Header),
   ETag (Header),
   Content-Disposition (Header),
   Content (Body)
}

Response headers

Header	Type	Description
Content-Length	int	Object size - `0` if the object is a folder
Content-Type	String	Media type of the object
Last-Modified	String	Last modification timestamp
ETag	String	MD5 hash of the object (may be invalid for folders)
Content-Disposition	String	Download filename for browser (UTF-8 encoded)

Response elements

Field	Type	Description
Content	Body	Not provided if the object is a folder

Status codes

HTTPS status	Response	Description
`200`	Success	Success
`403`	Forbidden	Temp URL has expired

Prerequisite​

API endpoint URL​

Supported specifications​

Create folder​

Request syntax​

API call method​

Request header​

Response syntax​

Status codes​

Create and upload file​

Request syntax​

API call method​

Request header​

Request body elements​

Status codes​

Upload large file​

Large object upload methods​

DLO (Dynamic Large Object) method​

Request syntax​

Example​

API call method​

Path parameters​

Header​

Status codes​

Request syntax​

API call method​

Request header​

Response syntax​

Status codes​

Request syntax​

API call method​

Request header​

Response syntax​

Status codes​

Request syntax​

API method​

Request header​

Response syntax​

Status codes​

SLO (static large object) method​

Upload SLO segment object​

Request syntax​

API method​

Request header​

Request elements​

Response syntax​

Status codes​

Upload SLO manifest​

Request syntax​

API method​

Request header​

Request elements​

Response syntax​

Status codes​

Download SLO​

Request syntax​

API method​

Request header​

Response syntax​

Status codes​

Download SLO manifest​

Request syntax​

API method​

Request header​

Response syntax​

Status codes​

Multipart upload​

Step 1. Initiate multipart upload​

Request syntax​

API method​

Request header​

Response syntax​

Response elements​

Status codes​

Step 2. Upload part​

Request syntax​

API method​

Request query parameters​

Request header​

Response header​

Prerequisite

API endpoint URL

Supported specifications

Create folder

Request syntax

API call method

Request header

Response syntax

Status codes

Create and upload file

Request syntax

API call method

Request header

Request body elements

Status codes

Upload large file

Large object upload methods

DLO (Dynamic Large Object) method

Request syntax

Example

API call method

Path parameters

Header

Status codes

Request syntax

API call method

Request header

Response syntax

Status codes

Request syntax

API call method

Request header

Response syntax

Status codes

Request syntax

API method

Request header

Response syntax

Status codes

SLO (static large object) method

Upload SLO segment object

Request syntax

API method

Request header

Request elements

Response syntax

Status codes

Upload SLO manifest

Request syntax

API method

Request header

Request elements

Response syntax

Status codes

Download SLO

Request syntax

API method

Request header

Response syntax

Status codes

Download SLO manifest

Request syntax

API method

Request header

Response syntax

Status codes

Multipart upload

Step 1. Initiate multipart upload

Request syntax

API method

Request header

Response syntax

Response elements

Status codes

Step 2. Upload part

Request syntax

API method

Request query parameters

Request header

Response header