# Introduction

ColdStack is a Decentralized Cloud Aggregator, which provides an S3 endpoint to the most effective decentralized storages.

ColdStack is a Decentralized Cloud Aggregator that allows for the aggregation of Decentralized Cloud Storage Platforms or Decentralized Storage Networks (DSNs) such as Filecoin, SIA, Arweave, and Storj. Coldstack enables the easy use of these platforms without significant integration efforts, regardless of an individual's familiarity with DSNs. ColdStack allows one to access almost any DSN through the S3 protocol, making migration to ColdStack easy. \
\
As the first-to-market Decentralized Cloud Aggregator, ColdStack offers a single entry point to any DSN, optimizing the final costs for consumers with our proprietary AI-based pipeline. Much like how Uber supplies its clients with convenient and cost-effective rides and deliveries from a huge pool of drivers, or how 1inch sources liquidity from a number of different exchange pools, ColdStack supplies its users with the most convenient way to access the world’s most affordable, secure, and efficient storage space from any decentralized cloud. \
\
Coldstack’s AI selects the best storage option for your data available on the market and allows users to save up to 80% on storage costs. Not all files and data are the same, and different parameters such as file size, type, and duration of storage can greatly impact one’s overall storage costs. Our AI also continuously scans the decentralized storage marketplace, in order to ensure that data is continuously stored most efficiently. \
\
Instead of users manually migrating their data between platforms to obtain the best price and greatest efficiency, our AI can rebalance a user’s files without being prompted. ColdStack’s protocol also saves on storage costs through techniques such as the utilization of cold storage for files which do not need to be frequently accessed, the bulk purchasing of storage space on various DSNs, and the usage of storage auctions.\
\
Our protocol's main purpose is to store and retrieve user’s data in a stack of Clouds via Unified Data Exchange API, which is 100% compatible with Amazon S3 API. That allows any project to use any AWS library or SDK and start to use our System without significant integration efforts. We will publish an open-source library with AWS S3 compatible API to the most of Decentralized Storages. Here is a document set concerning our API and it's implementation.\ <br>

{% content-ref url="/pages/-MWtKmMWlOT4YWCv2jl6" %}
[Supported tools](/tools/supported-tools)
{% endcontent-ref %}


# ColdStack FAQ

Frequently asked questions

**Why use decentralized storage?**\
Amazon, Dropbox, and Google have made it seem easier than ever to store large amounts of data. However, storing data with these centralized companies comes with a number of problems. In short, centralized storage is much less secure than decentralized storage, and is subject to both censorship and outages from system demand. Decentralized storage offers greater security through immutability, and gives people far more control over their personal data. Decentralized storage is also typically cheaper than centralized solutions, thanks to the removal of “middle-men” and other associated fees.\
\
**Why would I use ColdStack instead of directly using decentralized storages?**\
Decentralized storages are often hard to use and integrate to products, while S3 Compatible Storages have gained huge popularity, as S3 Storages are easy to integrate. ColdStack gives projects that are already working with centralized S3 providers the ability to migrate to decentralized storages without any code changes and security loses.

There is also the fact that you cannot access all decentralized storages from a single point-of-entry without ColdStack - by going directly with a single decentralized storage, you miss out on the advantages other DSNs can offer.

By utilizing the $CLS token, users gain access to nearly any decentralized storage, and are no longer required to research the particular strengths of each service in addition to comparing costs. Fully utilizing these storages would require users to purchase the particular tokens used for each network, making this process very expensive under current circumstances. As it currently stands, the ColdStack platform will be the only way a user can store their data across the many different DSNs with a single token.\
\
**Which decentralized storages do you support?**\
We currently support Filecoin, Arweave, Sia/Skynet, Lambda, and Crust as storage solutions. We are currently in the process of integrating Storj, BitTorrent, 0xChain, and Stratos.

Such variation makes ColdStack vastly superior compared to other projects, and our infrastructure makes the integration of new DSNs (and their advantages) relatively simple.\
\
**What client-side instruments does ColdStack support?**\
ColdStack offers a number of client-side instruments such as GUI, Console, SDK clients, and our list is growing! The list of supported clients you can see in the Supported tools page. If you do not see your prefered instruments, please contact a team member to make a suggestion.\
\
**How does ColdStack keep prices lower than Amazon or Filebase?**\
ColdStack is not only able to access a far greater amount of storage solutions when compared to our competitors, we are also able to store individual files more efficiently. Simply put, all data is different, there are a number of factors which determine how to most efficiently store certain files such as size, type, geolocation, and the frequency at which the data must be accessed. \
\
Our AI-based pipeline is not only able to determine the most cost-efficient solution for every file a user uploads based on their preferences, but is also able to rebalance how this data is stored based on storage market prices. Our system is also able to purchase storage in bulk, as well as take part in storage auctions in order to further improve costs.

We have an article outlining the process here: <https://medium.com/coldstack/how-coldstack-keeps-prices-low-fd4d669fd586>\
\
**Does ColdStack compete with other decentralized storages?**\
ColdStack does not compete with other decentralized storages - we aggregate them, and seek to further the entire decentralized storage ecosystem and provide a means for DSNs to properly compete with centralized storages such as Amazon.

By aggregating these various services, ColdStack can provide a single, simple, S3 compatible entry-point for DSNs, while finding the most cost-efficient solution possible. Such functionality will prove critical to mass adoption of decentralized storage. Instead of an ecosystem in which these storages strictly compete with one another, ColdStack seeks to create a unified ecosystem in which these storages work together to provide the best user experience possible.\
\
**Does ColdStack have a minimum monthly charge?**\
ColdStack currently does not have a minimum requirement for data storage, or a minimum cost threshold for storage. Users simply need to maintain an applicable amount of $CLS tokens to pay for data storage.\
\
**How do I close my ColdStack account?**\
Due to the nature of our service, customers must first remove all of their data before canceling their account. This can be done using our API clients such as the S3 browser or the AWS CLI to delete your data.\
\
**Can I use ColdStack without a cryptocurrency wallet?**\
No, not yet. However, we plan to implement such functionality in the near future, as well as other features to make our platform easier to access for those who are unfamiliar with cryptocurrency.


# Binance Smart Chain Bridge

ColdStack Binance Smart Chain Bridge Intoduction

### Introduction

The ColdStack BSC bridge is designed to enable cross-chain CLS token transfers between the Ethereum and Binance Smart Chain Network, as well as BSC tokens bridged to the Ethereum network.

### Supported wallets

Currently the ColdStack BSC bridge only supports Metamask. We plan to eventually include support for Trezor, Ledger, and Binance Chain Wallet, as well as others.


# Release

### Release 1.0.0

Current release version 1.0.0 (16 November 2021)

Supports cross-chain bridge transfers between BSC and Ethereum for CLS tokens. It supports Metamask wallet only.


# Customer Support

ColdStack

### Customer Support Contact

Support email: <info@coldstack.io>

Support Telegram: <https://t.me/coldstacksupport>

ColdStack will NEVER ask for your private key, recovery phrases, or passwords. NEVER, under any situation, should you ever give someone your private key or recovery phrases. Immediately block and report anyone that does.


# FAQ

### Are there any costs associated with swapping?

There are no costs apart from gas fees, which depend on market conditions

### Are there any restrictions on swapping?

The minimum for transferring from Ethereum to BSC is 10 CLS tokens, and 25 CLS if transferring from BSC to Ethereum

### Who can I contact for assistance?

Please contact <info@coldstack.io>

### What do I do if my transaction did not go through, or if I did not receive my funds?

You can check your transaction on [BSCscan](https://bscscan.com/token/0x668048E70284107A6aFab1711f28D88dF3E72948?a=0x1c1a3D6968aF93e0aB9C242F06213cb9a29316D4) or [Etherscan](https://etherscan.io/token/0x675bbc7514013e2073db7a919f6e4cbef576de37?a=0x1c1a3D6968aF93e0aB9C242F06213cb9a29316D4) with our exchange address.

Cross-chain transactions may take longer than others to confirm. Please contact the team if your transaction has not gone through or your funds have not appeared on the receiving network.

Please ensure that you are swapping from the correct network, you must be connected to the Ethereum mainnet to swap from Ethereum to BSC, and you must be connected to BSC in order to swap to Ethereum. Failure to provide the proper swap destination can result in a loss of funds.

### Can I reuse the deposit address?

Yes, you currently can reuse the address. However, please stay updated, as this may change in future versions.


# Step-by-Step Guide

ColdStack Binance Smart Chain Bridge User Guide

Dear community members, we are happy to present our simple guide on how to perform cross-chain CLS token transfers between the Ethereum and Binance Smart Chain Network through our native bridge. This bridge is a vital part of our plan to offer CLS on the BSC network, and anyone seeking to bring their Ethereum based CLS tokens should follow the steps below.

**1.** Go to our bridges webpage <https://coldstack.io/bridge/>.

**2.** Click "Unlock Wallet":

![](https://lh3.googleusercontent.com/nd3AUwW4oNlFMBu32j-ZMB4PclPsxd2z40PjLZ5Zfp7rLvRe1ujDBtNGcOUlo16fdm8nr2yz9YfIrBi-DuGjGsOHXFVnOqkJLIOoRapbW_CEFib8ozeWi3fFhgZmxmjV44uOXe-o)

![Connecting Metamask wallet](/files/QIRVA3hGnjbM54X4uYJL)

**3.** Make sure your wallet is connected to the correct network - you can click this “Add network” to add the BSC network to your MetaMask wallet, and “Add CLS to you Metamask token list” if you don’t yet have CLS listed in your wallet:

![Adding CLS token and BSC to Metamask](https://lh5.googleusercontent.com/NjZP-zbxGALMuUGnbJZtMLUrdVL0r4SJ6bIvo5aQ-P2vC3OvgCWa39LXsVqXNY3C0UFH0YZng6g-1NGTrevYENyRH6IGD-5N07q-T0D7Z0R71kvtcD8jF_XQ4DQeZbCiAYSNMcxG)

**4.** Select the networks that you wanna transfer tokens between, and the amount of tokens you would like to transfer - minimum for transferring from Ethereum to BSC is 10 CLS tokens, and 25 CLS if transferring from BSC to Ethereum. And then click “Next”.

![Main form for submitting transmission](https://lh5.googleusercontent.com/tDIm1aZWovO5IZQHgbEtec9H_rfv4U4ohXh3JdO0HEznQRbnbvgInUlarxXvE10j40gVfgxes1Wj-vNbOqk-AsRaalnFPL__8T7w9WtmBqtAkzo7Enuhqq8BzUQUUC3fuCelK2KX)

**5.** Check “You will receive” and “Gas fee”, and then click “Confirm”.

![](https://lh4.googleusercontent.com/i-qy_QF_bQvvbP7SmZ_sWg6W8rPhupWTyjPUnhQPb-GM7N5GLTZqgwDzVpC5jypOjEYsWx4IKkWyH9J8ju00-A3r7ibUdkqcfQlH_yXfY0f_CGnrON1Fnw3tgJ2LVmb2rm2cJT4U)

**6.** Confirm the transaction in your wallet:

![](https://lh4.googleusercontent.com/oVpXfe5P-kkEn17B4bNJr9LJahu1tPdXzQz5DqYOId7Dpe2Gd2dH_NLpqXq3kAFE26j7tsjQA9QYIdlW_ClMsh4XyrTlGlguA64Xd8JD5ArwggM5O9moqta7vOPYEgiEPB1Cmr8_)

**7.** Wait for the transaction to be confirmed on both networks (You can view the transaction with the link provided).

![](https://lh5.googleusercontent.com/2YPH3JbL9OKfdw8KjHfsFp0fT_PcQtmL6ZkZaCmsP3ubf1KRVECJDKgg5_8x8nEhMgTVRwwgIppC8dnaDpOo9WGYhG9nqw1vYnAvgX7fpPHuRouwizBqs6m0KkMGCa6t0QaUwbJL)![](https://lh5.googleusercontent.com/YQo-9qg_jeGzYRl0cE65CreI_FbEOliXoRepXlMUT0Zn4X-ihnhZrN9n4yC4pGF_0i-LpBnhC70RnUCzRpUkHtAS5llhFkcW6-fUY31dDHZtkHyig1nH8wElYd7fcadaOdI3pj-8)

**8.** Switch networks to the destination network to check if the transaction went through.

After completing these steps, you should have your desired amount of CLS transferred to the network of your choice.

Should you encounter any issues, please do not hesitate to contact support! Our team is happy to help.

Please note our bridge UX only supports Metamask at the moment. However, users with other wallets can simply send CLS tokens to the exchange address shown.


# Bucket versioning

Bucket versioning is the capability to store the history of an object using versions. Each version is a complete copy of the object and occupies space in ColdStack. By using version control, you can protect your data from both unintentional user actions and application faults.

Versioning is enabled at the bucket level and applied to every object in the bucket.

For more information about how to enable versioning, see [Managing bucket versioning](/http-api-compatible-with-amazon-s3/api-reference/bucket/putbucketversioning).

* After you enable this feature, the `version_id` parameter is added to each uploaded object. It lets you manage specific object versions.
* Before versioning is enabled, each bucket object is assigned a version ID (`version_id`) equal to `null`.

  When versioning is paused, the `version_id` of existing objects no longer changes. Each new object is assigned a version ID of `null`. If a `null` version already exists, it's overwritten.
* When you overwrite an object version, a new object with the same ID and a randomly generated `version_id` is created.

  To access a previous version of the object, use the object ID and the desired `version_id`.

**Note**

Enabling versioning is irreversible. You can't disable versioning later, but you can stop creating new versions. After you pause versioning, new objects are saved as `null` versions.

When you delete an object version, a delete marker is added to the version and it no longer takes up space.


# Logging actions with a bucket

In ColdStack, there is an option to log all actions with a bucket. You can record logs, for example, to run an internal security audit or get more granular information about bucket operations.

Logging is disabled by default. After you enable this option, ColdStack will write actions with the bucket to an object once an hour.

To save logs, do the following:

* Define the *source* bucket that you want to log actions with.
* Create a *target* bucket where you want to save the logs.
* [Enable logging](/http-api-compatible-with-amazon-s3/api-reference/bucket/putbucketlogging).
* (optional) Select the prefix of the object key.

### Prerequisites

The source and target buckets must be in the same region.

### Format of the key for the log object

ColdStack uses the following format of the key for the log object:

```
<prefix>/YYYY-MM-DD-HH-MM-SS-<ID>
```

Where:

* `prefix`: The prefix of the key for the log object. You can specify your own prefix when enabling logging.
* `YYYY-MM-DD-HH-MM-SS`: Date and time of saving the log object in the target bucket (UTC format).
* `ID`: A unique record ID that prevents the object from being overwritten.

#### Prefix of the key

The key prefix lets you distinguish:

* Data belonging to different buckets, if the logs for multiple source buckets are saved to the same target bucket.
* Logging actions from other actions with the bucket, if the logs are saved to the source bucket. That's because the logging operation is also considered an action with the bucket in this case.

### Format of the log object

Logs are saved to a text file. For every action with the bucket, a record is written to the file in the following format:

| Field            | Type   | Description                                                                                                                                                                                                                                                       |
| ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bucket`         | String | Bucket name.                                                                                                                                                                                                                                                      |
| `bytes_received` | Int64  | Size of the request in bytes.                                                                                                                                                                                                                                     |
| `bytes_send`     | Int64  | Response size in bytes.                                                                                                                                                                                                                                           |
| `handler`        | String | Request method in the `REST format.<HTTP method>.<subject>`.                                                                                                                                                                                                      |
| `http_referer`   | String | URL of the request source.                                                                                                                                                                                                                                        |
| `ip`             | String | User's IP address.                                                                                                                                                                                                                                                |
| `method`         | String | HTTP request method.                                                                                                                                                                                                                                              |
| `object_key`     | String | [The object's key](https://cloud.yandex.com/en-ru/docs/storage/concepts/server-logs#key-format) in [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding) format.                                                                                          |
| `protocol`       | String | Data transfer protocol version.                                                                                                                                                                                                                                   |
| `range`          | String | An HTTP header that defines the range of bytes to load from the object.                                                                                                                                                                                           |
| `requester`      | String | User ID.                                                                                                                                                                                                                                                          |
| `request_args`   | String | Arguments of the URL request.                                                                                                                                                                                                                                     |
| `request_id`     | String | Request ID.                                                                                                                                                                                                                                                       |
| `request_path`   | String | Full path of the request.                                                                                                                                                                                                                                         |
| `request_time`   | Int64  | Request processing time, in milliseconds.                                                                                                                                                                                                                         |
| `scheme`         | String | <p>Type of data transfer protocol.<br>Acceptable values:<br>- <code>http</code>, an application layer protocol.<br>- <code>https</code>, an application layer protocol with encryption support.</p>                                                               |
| `ssl_protocol`   | String | Security protocol.                                                                                                                                                                                                                                                |
| `status`         | Int64  | HTTP [response](https://cloud.yandex.com/en-ru/docs/storage/s3/api-ref/response-codes) code.                                                                                                                                                                      |
| `storage_class`  | String | [Storage class](https://cloud.yandex.com/en-ru/docs/storage/concepts/storage-class) of the object.                                                                                                                                                                |
| `timestamp`      | String | Date and time of the operation with the bucket, in the `YYYY-MM-DDTHH:MM:MMZ` format.                                                                                                                                                                             |
| `user_agent`     | String | Client application (User Agent) that executed the request.                                                                                                                                                                                                        |
| `version_id`     | String | Version of the object.                                                                                                                                                                                                                                            |
| `vhost`          | String | <p>Virtual host of the request.<br>Acceptable values:<br>– <code>storage.yandexcloud.net</code>.<br>– <code>bucket name>.storage.yandexcloud.net</code>.<br>– <code>website.yandexcloud.net</code>.<br>– <code>\<bucket name>.website.yandexcloud.net</code>.</p> |

### Logging specifics

There are several points to note about how actions with a bucket are logged in ColdStack.

#### Best-effort log delivery

Most requests to a bucket are written to the log file (if the bucket was set up correctly to support logging). Most records are written within a few hours after the request is actually processed.

However, ColdStack doesn't guarantee that the logs are saved in a complete and timely manner. It may take several hours to record an action with the bucket in a log file. In some cases, a record might fail to appear in the file.

The log file provides an overview of the nature of traffic in the bucket, but is not intended for logging every request. In the payment documents, you can find several requests that are not saved in the log file.

### Pricing

The standard ColdStack pricing rules apply to logging.


# Supported tools

ColdStack supports a lot of clients, that you can use to store your files, backups and personal documents.

ColdStack supports several of the Amazon S3 HTTP API methods. This allows you to use not only ColdStack tools when working with the storage, but also popular tools for working with Amazon S3.

* GUI clients
  * [CyberDuck](/tools/supported-tools/cyberduck) (for Mac, Windows)
  * [S3 Browser](/tools/supported-tools/s3-browser) (for Windows)
* Console clients
  * [AWS CLI Console client](/tools/supported-tools/aws-cli-console-client)
* SDK
  * [AWS Java SDK](/tools/supported-tools/sdk/aws-sdk-for-java)
  * [Python SDK (boto)](/tools/supported-tools/sdk/python-sdk-boto)
  * [JavaScript SDK](/tools/supported-tools/sdk/javascript-sdk)

### Troubleshooting

#### Download fails or does not finish

Make sure that your client is configured to download files using **only one connection**. If you are using CyberDuck then take a look at our [CyberDuck manual](/tools/supported-tools/cyberduck). If you use another client and still have problems with download then try to contact our support.


# CyberDuck S3 Client

Cyberduck is a cloud storage browser for Mac and Windows with support for ColdStack, FTP, SFTP, WebDAV, Amazon S3, OpenStack Swift, Backblaze B2, Microsoft Azure & OneDrive, Google Drive and Dropbox.

To download CyberDuck go to the official website: [https://cyberduck.io/](<https://cyberduck.io/ >)

### Setting up CyberDuck

Press the + button:

![](/files/-MiS6XppwkQ16y_DfpPM)

In the popup:

1. At the top select `Amazon S3`
2. In the  `Server`  section type `s3.coldstack.io` &#x20;
3. In the  `Port`  section type `443` &#x20;
4. Put in your `Access Key ID`  and  `Secret Access Key` &#x20;

![](/files/-MiVU70ZDJQPfjIAXZcM)

Then click on `Preferences` :

![](/files/-MiVaV1sPUMUTwK5RspF)

Then click on `Transfers` :

![](/files/-MiVaeEtgDpWKkz5Shyf)

And make sure that the `Segmented downloads with multiple connections per file` checkbox is turned off:

![](/files/-MiVaoBD-jUFxjEZibLJ)

Congrats! Now you are ready to use ColdStack! You will see a new connection. Click on it:

![](/files/-MiVUdFmiMHEwJ5gl3Kk)

It will open the list of your buckets:

![](/files/-MiVVAFHEiUenhrKmfEW)

Lets upload some files to ColdStack!

![](/files/-MiVVWdoYMguuc1Z-xBf)

![](/files/-MiVVu6t8zjSL1BpwhJ9)

![](/files/-MiVVwJg0BtaOEI3Okzv)


# S3 Browser

S3 Browser is the most popular client for S3 compatible storages built for Windows OS.

To download S3 Browser go to the official website: <https://s3browser.com/>

First of all, click the `Accounts`  button in the top menu, then `Add new account...` :

![](/files/-MiVWhKtAiK3njjfTGv_)

Now you have to set up your account settings.&#x20;

* In `Account Name`  section type `ColdStack`&#x20;
* In `Account Type`  choose `S3 Compatible Storage`&#x20;
* In `REST Endpoint`  type `s3.coldstack.io`&#x20;
* Put in your credentials in `Access Key ID` and `Secret Access Key` sections

![Setting up ColdStack credentials in S3 Browser](/files/-MiVXF0pCnQLkS4DR1nc)

Then click on `Advanced S3-compatible storage settings` at the bottom of the window. It will open a new window. Select `Signature V4` and then click on the `Close`  button:

![Setting Signature V4](/files/-MiVX_UTwO-fNHRsNjUr)

#### Turning off multipart downloads

Go to Tools -> Options:

![](/files/-MlJbTUGabgSFfWgmjHq)

A popup will open. In that windows go to the section "General" and turn off the option "Enable multipart downloads with part size":

![](/files/-MlJbnG6kjcqf79ds15K)

#### Using ColdStack

Now you are ready to use ColdStack! Lets create a bucket:

![](/files/-MiVXlBj1_9-6QUWb9La)

Type a name for your bucket. Be sure to include only letters, number and dashes:

![](/files/-MiVXtXEZzMv4DR9jKro)

Now you can upload files to your bucket:

![](/files/-MiVXx_o3T5ORkeQ9xs1)


# AWS CLI Console client

AWS Command Line Interface (AWS CLI)

[AWS CLI](https://aws.amazon.com/ru/cli/) — is a command line interface for working with AWS services. For the [general order of calling commands](https://docs.aws.amazon.com/cli/latest/reference/), see the official Amazon documentation.

To work with ColdStack using AWS CLI, you can use the following sets of commands:

* [s3api](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) — commands corresponding to operations in the REST API. Please check the [list of supported operations](/http-api-compatible-with-amazon-s3/api-reference#operations-list) before use.
* [s3](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html) — additional commands that simplify work with a large number of objects.

### Preparation for work

Current status of the system is private alpha testing. To get an access key, you need to contact the admin in [our telegram channel](https://t.me/coldstackio) to get an access key. Please note that you cannot upload more than 10Tb during this test.

### Installation <a href="#installation" id="installation"></a>

To install the AWS CLI, follow the [instructions](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) on the manufacturer's website.

### Setting up <a href="#setup" id="setup"></a>

Use the `aws configure` command to configure the AWS CLI. The command will ask for values for the following parameters:

1. `AWS Access Key ID` — enter the key id that you received from our admin.
2. `AWS Secret Access Key` — enter the secret key that you received from our admin.
3. `Default region name` — enter value `us-east-1`.

   **Note**\
   To work with ColdStack, always specify the region `us-east-1`. Other region values may result in an authorization error.
4. `Default output format` - leave unchanged.
5. Leave the rest of the parameters unchanged.

#### Config files

As a result of its work, the `aws configure` command will save the settings in files:

* Static key in `.aws/credentials` in the following format:

  ```
  [default]
              aws_access_key_id = id
              aws_secret_access_key = secretKey
  ```
* Default region in `.aws/config` in the following format:

  ```
  [default]
              region=us-east-1
  ```

### Notes <a href="#specifics" id="specifics"></a>

When using AWS CLI to work with ColdStack, consider the following features of this tool:

* AWS CLI treats Object Storage as a hierarchical file system and object keys are in the form of a file path.
* When running the aws command to work with ColdStack, the `--endpoint` parameter is required, and the value should be `https://s3.coldstack.io` since by default the client is configured to work with Amazon servers.
* When working in macOS, in some cases it is required to launch the following:

  ```
  export PYTHONPATH=/Library/Python/2.7/site-packages; aws --endpoint-url=https://s3.coldstack.io s3 ls
  ```

### Examples <a href="#aws-cli-examples" id="aws-cli-examples"></a>

#### Create a bucket and list them

Lets check what buckets do you own:

```bash
aws --endpoint=https://s3.coldstack.io s3 ls
```

If you are a new user and have not created any bucket yet, then this command will not show any buckets. You have to create a bucket for yourself. Lets do it, just replace `my-new-bucket`  with your desired name:

```bash
aws --endpoint=https://s3.coldstack.io s3 mb s3://my-new-bucket
```

Now you created a bucket, lets list them one more time:

```bash
aws --endpoint=https://s3.coldstack.io s3 ls
```

At this moment you should see at least one bucket, that you just created:

```
2021-08-18 11:31:56 my-new-bucket
```

#### Upload objects <a href="#uploading-objects" id="uploading-objects"></a>

You can load objects in different ways, for example:

* Load all objects from local directory:

  ```
  aws --endpoint=https://s3.coldstack.io \
      s3 cp --recursive local_files/ s3://my-new-bucket/path_style_prefix/
  ```
* Load objects described in the `--include` filter and skip objects described in the `--exclude` filter

  ```
  aws --endpoint=https://s3.coldstack.io \
      s3 cp --recursive --exclude "*" --include "*.log" \
      local_files/ s3://my-new-bucket/path_style_prefix/
  ```
* Load objects one at a time by running a command of the following type for each object:

  ```
  aws --endpoint=https://s3.coldstack.io \
      s3 cp testfile.txt s3://my-new-bucket/path_style_prefix/textfile.txt
  ```

#### Get the list of objects <a href="#getting-objects-list" id="getting-objects-list"></a>

```
aws --endpoint=https://s3.coldstack.io \
    s3 ls --recursive s3://my-new-bucket
```

#### Get an object <a href="#retrieving-objects" id="retrieving-objects"></a>

```
aws --endpoint=https://s3.coldstack.io \
    s3 cp s3://my-new-bucket/textfile.txt textfile.txt
```


# SDKs for different languages

Examples are available for these SDKs:

* [AWS Java SDK](/tools/supported-tools/sdk/aws-sdk-for-java)
* [Python SDK (boto)](/tools/supported-tools/sdk/python-sdk-boto)
* [JavaScript SDK](/tools/supported-tools/sdk/javascript-sdk)

### Documentation for other SDKs

{% hint style="warning" %}
**Note:** any SDKs requires you to manually set the S3 endpoint to `https://s3.coldstack.io` . On how to set the endpoint for a specific SDK please take a look in it's documentation.
{% endhint %}

* [Using the AWS SDK for .NET](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingTheMPDotNetAPI.html)
* [Using the AWS SDK for PHP](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingTheMPphpAPI.html)
* [Using the AWS SDK for Ruby](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingTheMPRubyAPI.html)
* [Using the AWS Mobile SDKs for iOS and Android](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-mobile-sdks.html)


# JavaScript SDK

### List buckets

```typescript
await s3.listBuckets().promise();
```

### List objects

#### List objects in root folder

```typescript
await s3.listObjectsV2({
    Bucket: 'BUCKET',
    Delimeter: '/',
}).promise();
```

#### List objects in the folder

```typescript
await s3.listObjectsV2({
    Bucket: 'BUCKET',
    Delimeter: '/',
    Prefix: 'my-folder'
}).promise();
```

### Get files metadata

```typescript
const result = await s3.headObject({
    Bucket: 'BUCKET',
    Key: 'folder/file-name.txt',
}).promise();

/*
{
    Metadata: {key: 'value'},
    ContentLength: 123,
    ETag: '...',
    ...
}
*/
```

### Edit objects metadata

Note that you can not change values of these metadatas: `file-hash`, `storage`,`location`. When you set `MetadataDirective: 'REPLACE'` any existing metadatas will be overridden. So if you want to edit only some of metadatas then include existing metadatas too.

```typescript
await s3.copyObject({
  Bucket: 'BUCKET',
  Key: 'file.txt',
  CopySource: 'BUCKET/file.txt',
  Metadata: {
    'key': 'value',
    'key2': 'value2'
  },
  MetadataDirective: 'REPLACE'
}).promise()
```

### Make object private or public

```typescript
await s3.putObjectAcl({
  Bucket: 'BUCKET',
  Key: 'folder/file-name.txt',
  ACL: 'public-read',
}).promise()

await s3.putObjectAcl({
  Bucket: 'BUCKET',
  Key: 'folder/file-name.txt',
  ACL: 'private'
}).promise()
```

### Delete an object

```typescript
await s3.deleteObject({
  Bucket: 'BUCKET',
  Key: 'folder/file-name.txt',
}).promise();
```


# Using extended API with JavaScript

### Initialization

```bash
npm i axios aws4-axios
```

```typescript
import axios from 'axios';
import { aws4Interceptor } from 'aws4-axios';

const client = axios.create({
  baseURL: 'https://s3.coldstack.io'
})

client.interceptors.request.use(aws4Interceptor({
  region: 'us-east-1',
  service: 's3',
}, {
  accessKeyId: '...',
  secretAccessKey: '...',
}));
```

### Getting extended list of buckets

```typescript
const response = await client.get('/?extendedBuckets', {
    params: {
        format: 'json',
        perPage: 10,
        page: 1,
    },
});

console.log(response.data)
```

#### Result

```javascript
{
  "ListAllMyBucketsExtendedResult": {
    "PerPage": 10,
    "Page": 1,
    "Owner": {
      "ID": "...",
      "DisplayName": "..."
    },
    "Buckets": [
      {
        "Name": "bucket-1",
        "CreationDate": "2021-04-11T16:34:16.364Z",
        "ObjectsCount": "14",
        "ObjectsWithoutFoldersCount": "13"
      },
      {
        "Name": "bucket-2",
        "CreationDate": "2021-05-30T14:53:33.899Z",
        "ObjectsCount": "0",
        "ObjectsWithoutFoldersCount": "0"
      }
    ]
  }
}
```

### Getting extended list of objects

```typescript
const response = await client.get('/BUCKET?extendedObjects', {
    params: {
        format: 'json',
        perPage: 10,
        page: 1,
        delimiter: '/',
        prefix: 'folder/nested-folder/',
    },
});

console.log(response.data)
```

#### Result

```javascript
{
  "ListExtendedObjects": {
    "Name": "BUCKET",
    "PerPage": 10,
    "Page": 1,
    "Prefix": "folder/nested-folder/",
    "KeyCount": 2, // Количество результатов в данном ответе сервера
    "AvailableKeyCount": 2, // Количество файлов в этой папке
    "Delimiter": "/",
    "IsTruncated": false, // Урезан ли список файлов
    "Contents": [
      {
        "Key": "folder/nested-folder/15mb.random",
        "LastModified": "2021-08-12T22:14:53.608Z",
        "ETag": "\"bc71d03e01a1d931e15cf07bd0a90c2f-2\"",
        "Size": "15000000",
        "SizeReadable": "15 MB",
        "StorageClass": "STANDARD",
        "StorageClassReadable": "Standrad",
        "ContentType": "application/octet-stream",
        "ACL": "private",
        "FileType": "file"
      },
      {
        "Key": "folder/nested-folder/icon.png",
        "LastModified": "2021-08-12T22:13:05.894Z",
        "ETag": "\"629e4d5c1d0086a8c833bef7f3427994\"",
        "Size": "6459",
        "SizeReadable": "15 MB",
        "StorageClass": "STANDARD",
        "StorageClassReadable": "Standrad",
        "ContentType": "image/png",
        "ACL": "public-read",
        "FileType": "file"
      }
    ],
    "CommonPrefixes": [
      {
        "Prefix": "folder/nested-folder/other-nested-folder/",
        "Size": "6459",
        "SizeReadable": "15 MB",
        "LastModified": "2021-08-12T22:13:05.894Z"
      }
    ]
  }
}
```

### Get statistics

```typescript
const response = await client.get('/?statistics', {
    params: { format: 'json' } },
);

console.log(response.data);
```

#### Result

```javascript
{
  "Statistics": {
    "BucketsCount": 4,
    "ObjectsCount": 14,
    "UsedStorage": {
      "UsedStorageBytes": "286249388",
      "UsedStorageReadableQuantity": "286",
      "UsedStorageReadableUnit": "MB"
    },
    "Bandwidth": {
      "BandwidthBytes": "20159227",
      "BandwidthReadableQuantity": "20.2",
      "BandwidthReadableUnit": "MB"
    }
  }
}
```

### Get bandwidth analytics

```typescript
const response = await client.get('/?bandwidthAnalytics', {
  params: {
    format: 'json',
    fromDate: '...',
    toDate: '...',
  }
});

console.log(response.data);
```

#### Result

```javascript
{
  "BandwidthAnalytics": {
    "Records": [
      {
        "Date": "2021-08-13",
        "DownloadBandwidth": "15000000",
        "DownloadBandwidthReadable": "15 MB",
        "UploadBandwidth": "5159227",
        "UploadBandwidthReadable": "5.16 MB"
      },
      {
        "Date": "2021-08-14",
        "DownloadBandwidth": "15000000",
        "DownloadBandwidthReadable": "15 MB",
        "UploadBandwidth": "5159227",
        "UploadBandwidthReadable": "5.16 MB"
      }
    ]
  }
}
```

### Get storage usage analytics

```typescript
const response = await client.get('/?storageAnalytics', {
  params: {
    format: 'json',
    fromDate: '...',
    toDate: '...',
  }
});

console.log(response.data);
```

#### Result

```javascript
{
  "StorageUsageAnalytics": {
    "Records": [
      {
        "Timestamp": "2021-08-31T01:00:00.000Z",
        "UsedStorage": "15000000",
        "UsedStorageReadable": "15 MB"
      },
      {
        "Timestamp": "2021-08-31T02:00:00.000Z",
        "UsedStorage": "16000000",
        "UsedStorageReadable": "16 MB"
      }
    ]
  }
}
```

### Rename bucket

```typescript
await client({
  url: '/old-bucket-name',
  method: 'MOVE',
  headers: {
    'Destination': 'new-bucket-name',
  },
});
```

### Rename a file

```typescript
await client({
  url: '/old-bucket-name/file.txt',
  method: 'MOVE',
  headers: {
    'Destination': 'file-2.txt',
  },
});
```

### Rename a folder

```typescript
await client({
  url: '/old-bucket-name/folder/',
  method: 'MOVE',
  headers: {
    'Destination': 'folder-2/',
    'X-ColdStack-Prefix': 'true',
  },
});
```

### Get Extended info about file (extended HeadObject)

```typescript
await client({
  url: '/old-bucket-name/file?extendedInfo',
  method: 'GET',
  params: {
    format: 'json',
  },
});
```

#### Result

```javascript
{
  "ObjectExtendedInfo": {
    "CacheControl": "...",
    "ContentDisposition": "...",
    "ContentEncoding": "...",
    "ContentLanguage": "...",
    "Expires": "...",
    "ContentType": "...",
    "FileType": "...",
    "ETag": "...",
    "Size": 1024,
    "SizeReadable": "1 KB",
    "LastModified": "...",
    "StorageClass": "...",
    "StorageClassReadable": "...",
    "Metadata": {
      "key": "value"
    },
    "ACL": "private" | "public-read",
    "Owner": {
      "ID": "...",
      "DisplayName": "..."
    }
  }
}
```

### Check if user can upload

```typescript
await client({
  url: '/?canUpload',
  method: 'GET',
});
```

#### Result

```typescript
{
    "CanUpload": true
}
```

or

```typescript
{
    "CanUpload": true,
    "Message": "To store files or create folders you have to maintain balance in CLS worth of at least 1 dollar."
}
```

### Check if user can download

```typescript
await client({
  url: '/?canDownload',
  method: 'GET',
});
```

#### Result

```typescript
{
    "CanDownload": true
}
```

or

```typescript
{
    "CanDownload": true,
    "Message": "To store files or create folders you have to maintain balance in CLS worth of at least 1 dollar."
}
```

### Search files

```typescript
await client({
  url: '/?searchFiles',
  method: 'GET',
  params: {
    "perPage": 10,
    "page": 1,
    "format": "json",
    "filename": "video"
  }
});
```

Result

```json
{
  "SearchFilesResult": {
    "Query": {
      "perPage": 10,
      "page": 1
    },
    "Files": [
      {
        "Key": "videos/pres-video.mp4",
        "FileType": "video",
        "Bucket": "personal-files",
        "FileName": "pres-video.mp4"
      },
      {
        "Key": "other-files/videos-list.txt",
        "FileType": "file",
        "Bucket": "other-bucket",
        "FileName": "videos-list.txt"
      }
    ]
}
```


# AWS SDK for Java

[The AWS SDK for Java](https://aws.amazon.com/ru/sdk-for-java/) is a development kit for working with AWS services.

### Preparation for work <a href="#before-you-begin" id="before-you-begin"></a>

1. Create a service account .
2. Assign a role to a service account .
3. Create a static access key .

### Installation <a href="#installation" id="installation"></a>

To install the AWS SDK for JAVA, follow the [instructions](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-install.html) on the manufacturer's website.

### Customization <a href="#setup" id="setup"></a>

To configure, create configuration files in your home directory and specify in them:

* Static key in file `.aws/credentials`:

  ```
  [default]
              aws_access_key_id = <id>
              aws_secret_access_key = <secretKey>
  ```
* Default region in file `.aws/config`:

  ```
  [default]
              region=us-east-1
  ```

Use the address to access ColdStack `s3.coldstack.io`.

### Code examples <a href="#java-sdk-examples" id="java-sdk-examples"></a>

The sample code is located in the directory `aws-java-sdk/samples/AmazonS3`in the archive with the SDK distribution kit.

To connect to Object Storage, replace the code in the example

```java
AmazonS3 s3 = AmazonS3ClientBuilder.standard()
    .withCredentials(new AWSStaticCredentialsProvider(credentials))
    .withRegion("us-west-2")
    .build();
```

on the

```java
AmazonS3 s3 = AmazonS3ClientBuilder.standard()
    .withCredentials(new AWSStaticCredentialsProvider(credentials))
    .withEndpointConfiguration(
        new AmazonS3ClientBuilder.EndpointConfiguration(
            "s3.coldstack.io", "us-east-1"
        )
    )
    .build();
```


# Python SDK (boto)

## boto3 and boto

[boto3](https://github.com/boto/boto3) and [boto](https://github.com/boto/boto) are development kits (SDKs) for the Python 2.x and 3.x programming languages. SDKs are designed to work with AWS services.

### Preparation for work <a href="#before-you-begin" id="before-you-begin"></a>

1. Create a service account .
2. Assign a role to a service account .
3. Create a static access key .

### Installation <a href="#installation" id="installation"></a>

To install boto, follow the instructions in the developer's repository: [boto3](https://github.com/boto/boto3/blob/develop/README.rst#quick-start) , [boto](https://github.com/boto/boto#installation) .

### Customization <a href="#setup" id="setup"></a>

To configure, create configuration files in your home directory and specify in them:

* Static key in file `.aws/credentials`:

  ```
  [default]
              aws_access_key_id = <id>
              aws_secret_access_key = <secretKey>
  ```
* Default region in file `.aws/config`:

  ```
  [default]
              region=us-east-1
  ```

Use the address to access Object Storage `s3.coldstack.io`.

### Example <a href="#boto-example" id="boto-example"></a>

{% tabs %}
{% tab title="boto3" %}

```python
#!/usr/bin/env python
#-*- coding: utf-8 -*-
import boto3
session = boto3.session.Session()
s3 = session.client(
    service_name='s3',
    endpoint_url='https://s3.coldstack.io'
)

# Uploading objects to the bucket

## From a string
s3.put_object(Bucket='bucket-name', Key='object_name', Body='TEST', StorageClass='COLD')

## From a file
s3.upload_file('this_script.py', 'bucket-name', 'py_script.py')
s3.upload_file('this_script.py', 'bucket-name', 'script/py_script.py')

# Get a list of objects in bucket
for key in s3.list_objects(Bucket='bucket-name')['Contents']:
    print(key['Key'])

# Download an object and print the contents to the console
get_object_response = s3.get_object(Bucket='bucket-name',Key='py_script.py')
print(get_object_response['Body'].read())
```

{% endtab %}

{% tab title="boto" %}

```python
#!/usr/bin/env python
#-*- coding: utf-8 -*-
import os
from boto.s3.key import Key
from boto.s3.connection import S3Connection
os.environ['S3_USE_SIGV4'] = 'True'
conn = S3Connection(
    host='s3.coldstack.io'
)
conn.auth_region_name = 'us-east-1'

# Создать новый бакет
conn.create_bucket('bucket-name')
bucket = conn.get_bucket('bucket-name')

# Загрузить объекты в бакет

## Из строки
bucket.new_key('test-string').set_contents_from_string('TEST')

## Из файла
file_key_1 = Key(bucket)
file_key_1.key = 'py_script.py'
file_key_1.set_contents_from_filename('this_script.py')
file_key_2 = Key(bucket)
file_key_2.key = 'script/py_script.py'
file_key_2.set_contents_from_filename('this_script.py')

# Получить список объектов в бакете
keys_list=bucket.list()
for key in keys_list:
    print key.key

# Удалить несколько объектов
response = bucket.delete_keys(['test-string', 'py_script.py'])

# Получить объект
key = bucket.get_key('script/py_script.py')
print key.get_contents_as_string()
```

{% endtab %}
{% endtabs %}


# How to use the API

### Preparation for work <a href="#before-you-start" id="before-you-start"></a>

To use the API, you need to get an access key id and secret key.

Static key authorization is required to access the HTTP API directly and is supported by the tools listed in the [Supported Tools](/tools/supported-tools) section .

For a list of supported Amazon S3 HTTP API methods, see the [API Reference](/http-api-compatible-with-amazon-s3/api-reference) .

### General view of the API request <a href="#common-request-form" id="common-request-form"></a>

```
{GET|HEAD|PUT|DELETE|MOVE} /<bucket>/<key> HTTP/1.1
Host: s3.coldstack.io
Content-Length: length
Date: date
Authorization: authorization string (AWS Signature Version 4)

Request_body
```

The bucket name can be specified as part of the hostname. In this case, the request will take the form:

```
{GET|HEAD|PUT|DELETE|MOVE} /<key>} HTTP/1.1
Host: <bucket>.s3.coldstack.io
...
```

The set of headers depends on the specific request and is described in the documentation for the corresponding request.

If you use the API directly (without SDK and applications), then you will have to generate the header yourself to sign the requests `Authorization`. For information on how to do this, see the [Authenticating Requests (AWS Signature Version 4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) section of the Amazon S3 documentation.

#### Request URL <a href="#request-url" id="request-url"></a>

The URL can take one of the following forms:

* `https://s3.coldstack.io/<bucket>/<key>?<parameters>`
* `https://<bucket>.s3.coldstack.io/<key>?<parameters>`


# Signing Requests

Many requests to ColdStack are authenticated on the service side and the user submitting the request must sign it.

Object Storage supports AWS Signature V4.

The signing process consists of the following stages:

1. Generating a signing key
2. Generating a signature line
3. Signing a string with a key

For signing, you must use the [HMAC](https://ru.wikipedia.org/wiki/HMAC) mechanism with the [SHA256](https://ru.wikipedia.org/wiki/SHA-2) hashing function . Support for the corresponding methods is available in many programming languages. The examples assume that there is a function `sign(KEY, STRING)`that encodes an input string with a given key.

## Generating a signing key

To generate a signing key, you need to have static ColdStack access keys. For information on how to get them, contact us.

Generating a signing key:

1. Encode date using private key:

   ```
   DateKey = sign("AWS4" + "SecretKey", "yyyymmdd")
   ```
2. Encode the region using the key obtained in the previous step `DateKey`:

   ```
   RegionKey = sign(DateKey, "ru-central1")
   ```
3. Encode the service using the key obtained in the previous step `RegionKey`:

   ```
   ServiceKey = sign(RegionKey, "s3")
   ```
4. Get the signing key:

   ```
   SigningKey = sign(ServiceKey, "aws4_request")
   ```

### Generating a signature line <a href="#string-to-sign-gen" id="string-to-sign-gen"></a>

The signature line ( `StringToSign`) depends on the ColdStack usage scenario:

* Accessing an Amazon S3-compatible API without the need for an SDK or specialized utilities.
* Signing URLs using query parameters .

### Signing a string with a key <a href="#signing" id="signing"></a>

To get the signature of a string, you must use a mechanism `HMAC`with a hashing function `SHA256`, and convert the resulting result to hexadecimal representation.

```
signature = Hex(sign(SigningKey, StringToSign))
```


# API Reference

The ColdStack HTTP API provides the following services:

| Service                                                                                        | Description                        |
| ---------------------------------------------------------------------------------------------- | ---------------------------------- |
| [Bucket](/http-api-compatible-with-amazon-s3/api-reference#bucket-service)                     | Manages buckets.                   |
| [Object](/http-api-compatible-with-amazon-s3/api-reference#object-service)                     | Manages objects.                   |
| [Multipart upload](/http-api-compatible-with-amazon-s3/api-reference#multipart-upload-service) | Controls loading of large objects. |

### Supported Operations <a href="#operations-list" id="operations-list"></a>

#### Bucket service <a href="#bucket-service" id="bucket-service"></a>

| Method                                                                                            | Description                                            |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [HeadBucket](/http-api-compatible-with-amazon-s3/api-reference/bucket/getmeta)                    | Checks for the existence of a bucket and access to it. |
| [ListObjects/ListObjectsV2](/http-api-compatible-with-amazon-s3/api-reference/bucket/listobjects) | Returns a list of objects in a bucket.                 |
| [ListBuckets](/http-api-compatible-with-amazon-s3/api-reference/bucket/listbuckets)               | Returns a list of buckets.                             |
| [RenameBucket](/http-api-compatible-with-amazon-s3/api-reference/bucket/renamebucket)             | Changes bucket's name.                                 |

#### Object service <a href="#object-service" id="object-service"></a>

| Method                                                                                | Description                                |
| ------------------------------------------------------------------------------------- | ------------------------------------------ |
| [PutObject](/http-api-compatible-with-amazon-s3/api-reference/object/upload)          | Loads an object into Object Storage.       |
| [GetObject](/http-api-compatible-with-amazon-s3/api-reference/object/get)             | Unloads an object from Object Storage.     |
| [HeadObject](/http-api-compatible-with-amazon-s3/api-reference/object/getobjectmeta)  | Unloads the object's metadata.             |
| [RenameObject](/http-api-compatible-with-amazon-s3/api-reference/object/renameobject) | Changes object's key (renames the object). |

#### Multipart upload service <a href="#multipart-upload-service" id="multipart-upload-service"></a>

| Method                                                                                                       | Description                   |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------- |
| [CreateMultipartUpload](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/startupload)      | Initializes a composite load. |
| [UploadPart](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/uploadpart)                  | Loads part of an object.      |
| [CompleteMultipartUpload](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/completeupload) | Ends a multipart load.        |

### see also <a href="#see-also" id="see-also"></a>

* [How to use the API](/http-api-compatible-with-amazon-s3/how-to-use-the-api)
* [Supported tools](/tools/supported-tools)


# Bucket

### All Bucket Methods

| Method                                                                                            | Description                                            |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [HeadBucket](/http-api-compatible-with-amazon-s3/api-reference/bucket/getmeta)                    | Checks for the existence of a bucket and access to it. |
| [ListObjects/ListObjectsV2](/http-api-compatible-with-amazon-s3/api-reference/bucket/listobjects) | Returns a list of objects in a bucket.                 |
| [ListBuckets](/http-api-compatible-with-amazon-s3/api-reference/bucket/listbuckets)               | Returns a list of buckets.                             |
| [RenameBucket](/http-api-compatible-with-amazon-s3/api-reference/bucket/renamebucket)             | Changes bucket's name.                                 |


# HeadBucket

Returns bucket metadata or an error.

Lets check:

* Does a bucket exist.
* Does the user have sufficient rights to access the bucket.

### Request Syntax <a href="#request" id="request"></a>

```http
HEAD /{Bucket} HTTP/1.1
```

#### Request Parameters <a href="#path-parameters" id="path-parameters"></a>

| Parameter | Description  |
| --------- | ------------ |
| `Bucket`  | Bucket name. |

#### Request body

Request does not have body.

### Response <a href="#response" id="response"></a>

```http
HTTP/1.1 200
```


# ListObjects/ListObjectsV2

Returns a list of objects in a bucket.

When issuing, pagination is used; in one request, you can get a list of no longer than 1000 objects. If there are more objects, then it is necessary to execute several queries in a row.

**Note**

This method has two versions.

* `listObjectsV2` - up-to-date version, more convenient to use.
* `listObjectsV1` - previous version.

To call both methods, the same is used `URL`, but it differs in the query parameter. To invoke `listObjectsV2`, use the parameter `list-type=2`.

### listObjectsV2 <a href="#listobjectsv2" id="listobjectsv2"></a>

#### Request <a href="#requestv2" id="requestv2"></a>

```
GET /{bucket}?list-type=2&continuation-token=ContinuationToken&delimiter=Delimiter&encoding-type=EncodingType&max-keys=MaxKeys&prefix=Prefix&start-after=StartAfter HTTP/1.1
```

**Path parameters**

| Parameter | Description  |
| --------- | ------------ |
| `bucket`  | Bucket name. |

**Query parameters**

All parameters listed in the table are optional.

| Parameter            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `continuation-token` | <p>Used to get the next part of the list if all the results do not fit into one answer.<br>To get the next part of the list, use the value <code>NextContinuationToken</code>from the previous answer.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `delimiter`          | <p>Separator character.<br><br>If specified, Object Storage treats the key as a file path, where directories are separated by a character <code>delimiter</code>. In response to the request, the user will see a list of files and directories in the bucket. Files will be displayed in items <code>Contents</code>, and directories in items <code>CommonPrefixes</code>.<br><br>If a parameter is also specified in the request <code>prefix</code>, then Object Storage will return a list of files and directories in the directory <code>prefix</code> .</p>                                                                                                                                                                                                                                               |
| `encoding-type`      | <p>Server response encoding.<br><br>Object Storage, at the request of the client, can encode the response in the required form.<br><br>Possible values: <code>url</code>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `max-keys`           | <p>The maximum number of items in a response.<br><br>By default, Object Storage yields no more than 1000 items <code>Contents</code>and <code>CommonPrefixes</code>. This parameter should be used if you need to get less than 1000 items in one response.<br><br>If more keys fall under the selection criteria than fit in the search results, then the answer contains <code>\<IsTruncated>true\</IsTruncated></code>.<br><br>To get all the elements of the issue, if there are more of them <code>max-keys</code>, it is necessary to perform several consecutive requests to Object Storage with a parameter <code>continuation-token</code>, where for each request <code>continuation-token</code>is equal to the value of the element <code>NextContinuationToken</code>from the previous response.</p> |
| `prefix`             | <p>The string that the key should start with.<br><br>Object Storage will only select keys that start with <code>prefix</code>.<br><br>It can be used simultaneously with the parameter <code>delimiter</code>. In this case, the output logic is determined by the parameter <code>delimiter</code>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `start-after`        | The key to start the listing with.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

**Headings**

Use only [generic headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in your request .

#### Response <a href="#responsev2" id="responsev2"></a>

**Headings**

The response can only contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) .

**Response codes**

For a list of possible answers, see the [Answers](/http-api-compatible-with-amazon-s3/api-reference/answers) section .

The successful response contains additional data in XML format, the schema of which is described below.

**Data schema**

```markup
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
   <IsTruncated>boolean</IsTruncated>
   <Contents>
      <ETag>string</ETag>
      <Key>string</Key>
      <LastModified>timestamp</LastModified>
      <Size>integer</Size>
      <StorageClass>string</StorageClass>
   </Contents>
   ...
   <Name>string</Name>
   <Prefix>string</Prefix>
   <Delimiter>string</Delimiter>
   <MaxKeys>integer</MaxKeys>
   <CommonPrefixes>
      <Prefix>string</Prefix>
   </CommonPrefixes>
   ...
   <EncodingType>string</EncodingType>
   <KeyCount>integer</KeyCount>
   <ContinuationToken>string</ContinuationToken>
   <NextContinuationToken>string</NextContinuationToken>
   <StartAfter>string</StartAfter>
</ListBucketResult>
```

| Element                 | Description                                                                                                                                                                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ListBucketResult`      | Root element.                                                                                                                                                                                                                                                                                                            |
| `IsTruncated`           | <p>A flag indicating whether all results were returned in this response.<br><br><code>True</code>- everything. <code>False</code>- Not all.<br><br>Path: <code>/ListBucketResult/IsTruncated</code>.</p>                                                                                                                 |
| `Contents`              | <p>Description of the object.<br><br>The response will contain as many elements <code>Contents</code>as the keys match the request conditions.<br><br>Path: <code>/ListBucketResult/Contents</code>.</p>                                                                                                                 |
| `ETag`                  | <p>MD5 hash of the object. Metadata is not included in the hash calculation.<br><br>Path: <code>/ListBucketResult/Contents/ETag</code>.</p>                                                                                                                                                                              |
| `Key`                   | <p>Object key.<br><br>Path: <code>/ListBucketResult/Contents/Key</code>.</p>                                                                                                                                                                                                                                             |
| `LastModified`          | <p>The date and time the object was last modified.<br><br>Path: <code>/ListBucketResult/Contents/LastModified</code>.</p>                                                                                                                                                                                                |
| `Size`                  | <p>The size of the object in bytes.<br><br>Path: <code>/ListBucketResult/Contents/Size</code>.</p>                                                                                                                                                                                                                       |
| `StorageClass`          | <p>Object storage class: <code>STANDARD</code>or <code>COLD</code>.<br><br>Path: <code>/ListBucketResult/Contents/StorageClass</code>.</p>                                                                                                                                                                               |
| `Name`                  | <p>Bucket name.<br><br>Path: <code>/ListBucketResult/Name</code>.</p>                                                                                                                                                                                                                                                    |
| `Prefix`                | <p>The value of the query parameter <code>prefix</code>.<br><br>Path: <code>/ListBucketResult/Prefix</code>.</p>                                                                                                                                                                                                         |
| `Delimiter`             | <p>The value of the query parameter <code>delimiter</code>.<br><br>Path: <code>/ListBucketResult/Delimiter</code>.</p>                                                                                                                                                                                                   |
| `MaxKeys`               | <p>The value of the query parameter <code>max-keys</code>.<br><br>Path: <code>/ListBucketResult/MaxKeys</code>.</p>                                                                                                                                                                                                      |
| `CommonPrefixes`        | <p>The part of the key name that is determined when processing query parameters <code>delimiter</code>and <code>prefix</code>.<br><br>Path: <code>/ListBucketResult/CommonPrefixes</code>.</p>                                                                                                                           |
| `EncodingType`          | <p>The encoding in which Object Storage represents the key in the XML response.<br><br>Appears if the client passed a parameter when requested <code>encoding-type</code>.<br><br>Path: <code>/ListBucketResult/EncodingType</code>.</p>                                                                                 |
| `KeyCount`              | <p>The number of keys returned by the query.<br>The number of keys will always be less than or equal <code>MaxKeys</code>.<br><br>Path: <code>/ContinuationToken/KeyCount</code>.</p>                                                                                                                                    |
| `ContinuationToken`     | <p>The value of the query parameter <code>continuation-token</code>.<br><br>Path: <code>/ContinuationToken/ContinuationToken</code>.</p>                                                                                                                                                                                 |
| `NextContinuationToken` | <p>The value that must be substituted into the query parameter <code>continuation-token</code>to get the next part of the list, if the entire list does not fit into the current response.<br>Refundable only if <code>IsTruncated = true</code>.<br><br>Path: <code>/ListBucketResult/NextContinuationToken</code>.</p> |
| `StartAfter`            | <p>The value of the query parameter <code>start-after</code>.<br><br>Path: <code>/ListBucketResult/StartAfter</code>.</p>                                                                                                                                                                                                |

### ListObjects <a href="#listobjectsv1" id="listobjectsv1"></a>

#### Request <a href="#requestv1" id="requestv1"></a>

```
GET /{bucket}?delimiter=Delimiter&encoding-type=EncodingType&marker=Marker&max-keys=MaxKeys&prefix=Prefix HTTP/1.1
```

**Path parameters**

| Parameter | Description  |
| --------- | ------------ |
| `bucket`  | Bucket name. |

**Query parameters**

All parameters listed in the table are optional.

| Parameter       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `delimiter`     | <p>Separator character.<br><br>If specified, Object Storage treats the key as a file path, where directories are separated by a character <code>delimiter</code>. In response to the request, the user will see a list of files and directories in the bucket. Files will be displayed in items <code>Contents</code>, and directories in items <code>CommonPrefixes</code>.<br><br>If a parameter is also specified in the request <code>prefix</code>, then Object Storage will return a list of files and directories in the directory <code>prefix</code> .</p>                                                                                                                                                                                                            |
| `encoding-type` | <p>Server response encoding.<br><br>Object Storage, at the request of the client, can encode the response in the required form.<br><br>Possible values: <code>url</code>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `marker`        | <p>The key from which the issuance will begin.<br><br>In the resulting output, Object Storage will leave the keys starting from the next one after <code>marker</code>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `max-keys`      | <p>The maximum number of items in a response.<br><br>By default, Object Storage yields no more than 1000 items <code>Contents</code>and <code>CommonPrefixes</code>. This parameter should be used if you need to get less than 1000 items in one response.<br><br>If more keys fall under the selection criteria than fit in the search results, then the answer contains <code>\<IsTruncated>true\</IsTruncated></code>.<br><br>To get all the elements of the issue, if there are more of them <code>max-keys</code>, it is necessary to perform several consecutive requests to Object Storage with a parameter <code>marker</code>, where for each request <code>marker</code>is equal to the value of the element <code>NextMarker</code>from the previous response.</p> |
| `prefix`        | <p>The string that the key should start with.<br><br>Object Storage will only select keys that start with <code>prefix</code>.<br><br>It can be used simultaneously with the parameter <code>delimiter</code>. In this case, the output logic is determined by the parameter <code>delimiter</code>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

**Headings**

Use only [generic headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in your request .

#### Response <a href="#responsev1" id="responsev1"></a>

**Headings**

The response can only contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) .

**Response codes**

For a list of possible answers, see the [Answers](/http-api-compatible-with-amazon-s3/api-reference/answers) section .

The successful response contains additional data in XML format, the schema of which is described below.

**Data schema**

```
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult>
   <IsTruncated>boolean</IsTruncated>
   <Marker>string</Marker>
   <NextMarker>string</NextMarker>
   <Contents>
      <ETag>string</ETag>
      <Key>string</Key>
      <LastModified>timestamp</LastModified>
      <Size>integer</Size>
      <StorageClass>string</StorageClass>
   </Contents>
   ...
   <Name>string</Name>
   <Prefix>string</Prefix>
   <Delimiter>string</Delimiter>
   <MaxKeys>integer</MaxKeys>
   <CommonPrefixes>
      <Prefix>string</Prefix>
   </CommonPrefixes>
   ...
   <EncodingType>string</EncodingType>
</ListBucketResult>
```

| Element            | Description                                                                                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ListBucketResult` | Root element.                                                                                                                                                                                                                              |
| `IsTruncated`      | <p>A flag indicating whether all results were returned in this response.<br><br><code>True</code>- everything. <code>False</code>- Not all.<br><br>Path: <code>/ListBucketResult/IsTruncated</code>.</p>                                   |
| `Marker`           | <p>The value of the query parameter <code>marker</code>.<br><br>Path: <code>/ListBucketResult/Marker</code>.</p>                                                                                                                           |
| `NextMarker`       | <p>The value that must be substituted into the query parameter <code>marker</code>to get the next part of the list, if the entire list does not fit into the current response.<br><br>Path: <code>/ListBucketResult/NextMarker</code>.</p> |
| `Contents`         | <p>Description of the object.<br><br>The response will contain as many elements <code>Contents</code>as the keys match the request conditions.<br><br>Path: <code>/ListBucketResult/Contents</code>.</p>                                   |
| `ETag`             | <p>MD5 hash of the object. Metadata is not included in the hash calculation.<br><br>Path: <code>/ListBucketResult/Contents/ETag</code>.</p>                                                                                                |
| `Key`              | <p>Object key.<br><br>Path: <code>/ListBucketResult/Contents/Key</code>.</p>                                                                                                                                                               |
| `LastModified`     | <p>The date and time the object was last modified.<br><br>Path: <code>/ListBucketResult/Contents/LastModified</code>.</p>                                                                                                                  |
| `Size`             | <p>The size of the object in bytes.<br><br>Path: <code>/ListBucketResult/Contents/Size</code>.</p>                                                                                                                                         |
| `StorageClass`     | <p>Object storage class: <code>STANDARD</code>or <code>COLD</code>.<br><br>Path: <code>/ListBucketResult/Contents/StorageClass</code>.</p>                                                                                                 |
| `Name`             | <p>Bucket name.<br><br>Path: <code>/ListBucketResult/Name</code>.</p>                                                                                                                                                                      |
| `Prefix`           | <p>The value of the query parameter <code>prefix</code>.<br><br>Path: <code>/ListBucketResult/Prefix</code>.</p>                                                                                                                           |
| `Delimiter`        | <p>The value of the query parameter <code>delimiter</code>.<br><br>Path: <code>/ListBucketResult/Delimiter</code>.</p>                                                                                                                     |
| `MaxKeys`          | <p>The value of the query parameter <code>max-keys</code>.<br><br>Path: <code>/ListBucketResult/MaxKeys</code>.</p>                                                                                                                        |
| `CommonPrefixes`   | <p>The part of the key name that is determined when processing query parameters <code>delimiter</code>and <code>prefix</code>.<br><br>Path: <code>/ListBucketResult/CommonPrefixes</code>.</p>                                             |
| `EncodingType`     | <p>The encoding in which Object Storage represents the key in the XML response.<br><br>Appears if the client passed a parameter when requested <code>encoding-type</code>.<br><br>Path: <code>/ListBucketResult/EncodingType</code>.</p>   |


# PutBucketVersioning

Enables or pauses versioning of the bucket.

Versioning can be set to one of two statuses:

* `Enabled`: Turn on version management for objects in the bucket. All new objects added to the bucket get a unique version ID.
* `Suspended`: Suspends version management for objects in the bucket. All new objects added to the bucket get `null` as the version ID.

### Request

```
PUT /{bucket}?versioning HTTP/1.1
```

#### Path parameters

| Parameter | Description  |
| --------- | ------------ |
| `bucket`  | Bucket name. |

#### Query parameters

| Parameter    | Description                                              |
| ------------ | -------------------------------------------------------- |
| `versioning` | Required parameter that indicates the type of operation. |

#### Data schema

```
<?xml version="1.0" encoding="UTF-8"?>
<VersioningConfiguration>
   <Status>string</Status>
</VersioningConfiguration>
```

| Element  | Description                                                                                      |                      |
| -------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| `Status` | <p>Status of the bucket versioning option.<br><br>Type: String<br>Possible values: <code>Enabled | Suspended</code></p> |

#### Headers

Use only [common request headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in requests.

### Response

#### Headers

Responses can only contain [common response headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers).

#### Response codes

For a list of possible responses, see [Responses](/http-api-compatible-with-amazon-s3/api-reference/answers).

A successful response does not contain any additional data.

<br>


# PutBucketLogging

Enables and disables the [mechanism for logging actions with the bucket](https://cloud.yandex.com/docs/storage/concepts/server-logs).

### Request

```
PUT /{bucket}?logging HTTP/1.1
```

#### Path parameters

| Parameter | Description         |
| --------- | ------------------- |
| `bucket`  | Name of the bucket. |

#### Query parameters

| Parameter | Description                                              |
| --------- | -------------------------------------------------------- |
| `logging` | Required parameter that indicates the type of operation. |

#### Data schema

**To enable logging of actions with the bucket:**

```
<?xml version="1.0" encoding="UTF-8" ?>
<BucketLoggingStatus xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <LoggingEnabled>
      <TargetBucket>bucket-logs</TargetBucket>
      <TargetPrefix>logs/</TargetPrefix>
   </LoggingEnabled>
</BucketLoggingStatus>
```

| Element               | Description                                                                                  |
| --------------------- | -------------------------------------------------------------------------------------------- |
| `BucketLoggingStatus` | Root element.                                                                                |
| `TargetBucket`        | <p>The name of the target bucket where the objects are saved with logs.<br>Type: String.</p> |
| `TargetPrefix`        | <p>Object key prefix with logs.<br>Type: String.</p>                                         |

**To disable logging of actions with the bucket:**

```
<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01" />
```

#### Headers

Use only [common request headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in requests.

### Response

#### Headers

Responses can only contain [common response headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers).

#### Response codes

For a list of possible responses, see [Responses](https://cloud.yandex.com/docs/storage/s3/api-ref/response-codes).

A successful response does not contain any additional data.

<br>


# RenameBucket

Renames a bucket. This operation is an extension to the standard S3 protocol, and was implemented to give users far more functionality.

### Request <a href="#request" id="request"></a>

```http
MOVE /{bucket} HTTP/1.1
Destination: {newBucketName}
```

#### Path parameters <a href="#path-parameters" id="path-parameters"></a>

| Parameter       | Description                 |
| --------------- | --------------------------- |
| `bucket`        | Current name of the bucket. |
| `newBucketName` | New name for the bucket.    |

#### Headings <a href="#request-headers" id="request-headers"></a>

Use only [generic headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in your request .

### Response <a href="#response" id="response"></a>

#### Headings <a href="#response-headers" id="response-headers"></a>

The response can only contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) .

#### Response codes <a href="#response-codes" id="response-codes"></a>

For a list of possible responses, see the [Responses](/http-api-compatible-with-amazon-s3/api-reference/answers) section .

A successful response does not contain additional data and means that the bucket was successfully renamed.


# GetBucketLocation

Returns buckets region. Since ColdStack is available only in one region, this operation will always return `eu-east-1` .

### Request <a href="#request" id="request"></a>

```http
GET /{bucket}?location HTTP/1.1
```

#### Path parameters <a href="#path-parameters" id="path-parameters"></a>

| Parameter | Description                 |
| --------- | --------------------------- |
| `bucket`  | Current name of the bucket. |

#### Headings <a href="#request-headers" id="request-headers"></a>

Use only [generic headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in your request .

### Response <a href="#response" id="response"></a>

#### Headings <a href="#response-headers" id="response-headers"></a>

The response can only contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) .

#### Response codes <a href="#response-codes" id="response-codes"></a>

For a list of possible responses, see the [Responses](/http-api-compatible-with-amazon-s3/api-reference/answers) section .

A successful response does not contain additional data and means that the bucket was successfully renamed.


# ListBuckets

Returns a list of buckets available to the user.

### Request <a href="#request" id="request"></a>

```
GET / HTTP/1.1
```

#### Headings <a href="#request-headers" id="request-headers"></a>

Use only [generic headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in your request .

### Answer <a href="#response" id="response"></a>

#### Headings <a href="#response-headers" id="response-headers"></a>

The response can only contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) .

#### Answer codes <a href="#response-codes" id="response-codes"></a>

For a list of possible answers, see the [Answers](/http-api-compatible-with-amazon-s3/api-reference/answers) section .

The successful response contains additional data in XML format, the schema of which is described below.

#### Data schema <a href="#response-scheme" id="response-scheme"></a>

```
<ListAllMyBucketsResult>
  <Buckets>
    <Bucket>
      <Name>bucket-name</Name>
      <CreationDate>date_time</CreationDate>
    </Bucket>
    ...
  </Buckets>
</ListAllMyBucketsResult>
```

| Element                  | Description                                                                                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Bucket`                 | <p>Contains a description of the bucket.<br><br>Path: <code>/ListAllMyBucketsResult/Buckets/Bucket</code>.</p>                                           |
| `Buckets`                | <p>Contains a list of buckets.<br><br>Path: <code>/ListAllMyBucketsResult/Buckets</code>.</p>                                                            |
| `CreationDate`           | <p>Bucket creation time in <code>yyyy-mm-ddThh:mm:ss.timezone</code>.<br><br>Path: <code>/ListAllMyBucketsResult/Buckets/Bucket/CreationDate</code>.</p> |
| `ListAllMyBucketsResult` | <p>The root element of the response.<br><br>Path: <code>/ListAllMyBucketsResult</code>.</p>                                                              |
| `Name`                   | <p>Bucket name.<br><br>Path: <code>/ListAllMyBucketsResult/Buckets/Bucket/Name</code>.</p>                                                               |


# Object

### All Object Methods

| Method                                                                                | Description                                |
| ------------------------------------------------------------------------------------- | ------------------------------------------ |
| [PutObject](/http-api-compatible-with-amazon-s3/api-reference/object/upload)          | Loads an object into Object Storage.       |
| [GetObject](/http-api-compatible-with-amazon-s3/api-reference/object/get)             | Unloads an object from Object Storage.     |
| [HeadObject](/http-api-compatible-with-amazon-s3/api-reference/object/getobjectmeta)  | Unloads the object's metadata.             |
| [RenameObject](/http-api-compatible-with-amazon-s3/api-reference/object/renameobject) | Changes object's key (renames the object). |


# PutObject

Loads an object and its metadata to ColdStack.

**Note**

ColdStack does not block an object for writing and can accept several requests for writing one object at the same time, however, by default, the user will be able to get only the last written object from ColdStack. To preserve history when overwriting or deleting objects, turn on versioning .

Use a header to ensure that the object is transmitted over the network without damage `Content-MD5`. ColdStack will calculate `MD5`for the stored object and if the calculated `MD5`does not match the one passed in the header, it will return an error. This validation can also be performed on the client side by comparing the `ETag` ColdStack response with the precomputed one `MD5`.

### Request <a href="#request" id="request"></a>

```http
PUT /{bucket}/{key} HTTP/1.1
Content-Type: ContentType
Content-Length: ContentLength
Content-Disposition: ContentDisposition
```

#### Path parameters <a href="#path-parameters" id="path-parameters"></a>

| Parameter | Description                                                                    |
| --------- | ------------------------------------------------------------------------------ |
| `bucket`  | Bucket name.                                                                   |
| `key`     | Object key. The identifier under which the object will be stored in ColdStack. |

#### Headings <a href="#request-headers" id="request-headers"></a>

Use the required [common headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in the request .

Additionally, you can use the headings listed in the table below.

| Heading                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                             |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-amz-meta-*`                                | <p>Custom object metadata.<br><br>All headers starting with <code>x-amz-meta-</code>ColdStack are treated as custom headers, they are not processed and stored in the form in which they are transmitted.<br><br>The total size of custom headers must not exceed 2KB. The size of the user data is defined as the length of the UTF-8 encoded string. The size takes into account both the names of the headings and their values.</p> |
| `x-amz-storage-class`                         | <p>Object storage class.<br><br>Can have any of the following values:<br>- <code>STANDARD</code>to load an object into the standard storage.<br>- <code>COLD</code>, <code>STANDARD\_IA</code>and <code>NEARLINE</code>to load the object into cold storage.<br><br>If the header is not specified, then the object is saved in the storage set in the bucket settings.</p>                                                             |
| `x-amz-server-side-encryption`                | The default encryption algorithm for encrypting new objects.                                                                                                                                                                                                                                                                                                                                                                            |
| `x-amz-server-side-encryption-aws-kms-key-id` | The default KMS key identifier used to encrypt new objects.                                                                                                                                                                                                                                                                                                                                                                             |

Using the headers listed below, you can set the ACL for the loaded object.

| Heading                    | Description                                                                           |
| -------------------------- | ------------------------------------------------------------------------------------- |
| `x-amz-acl`                | Sets a predefined ACL for an object.                                                  |
| `x-amz-grant-read`         | Sets the recipient to read permission on the object.                                  |
| `x-amz-grant-read-acp`     | Sets the recipient to read the object's ACL.                                          |
| `x-amz-grant-write-acp`    | Sets the recipient to write access to the object's ACL.                               |
| `x-amz-grant-full-control` | Sets the access permission recipient: `READ`, `WRITE`, `READ_ACP`, `WRITE_ACP`object. |

The value for headers `x-amz-grant-*`is a comma-separated list of recipients. Each accessor is identified by a view structure `<тип получателя доступа>:<идентификатор получателя доступа>`. ColdStack supports the following recipient types:

* `id` - access recipient is a cloud user.
* `uri` - access recipient - system group.

Example:

```
x-amz-grant-read: uri="http://acs.amazonaws.com/groups/s3/AuthenticatedUsers"
```

### Answer <a href="#response" id="response"></a>

#### Headings <a href="#response-headers" id="response-headers"></a>

The response can only contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) .

#### Answer codes <a href="#response-codes" id="response-codes"></a>

For a list of possible answers, see the [Answers](/http-api-compatible-with-amazon-s3/api-reference/answers) section .


# GetObject

Returns an object from ColdStack.

### Request <a href="#request" id="request"></a>

```
GET /{bucket}/{key} HTTP/1.1
```

#### Path parameters <a href="#path-parameters" id="path-parameters"></a>

| Parameter | Description  |
| --------- | ------------ |
| `bucket`  | Bucket name. |
| `key`     | Object key.  |

#### Query parameters <a href="#request-params" id="request-params"></a>

| Parameter                      | Description                                            |
| ------------------------------ | ------------------------------------------------------ |
| `response-content-type`        | Sets the header of the response `Content-Type`.        |
| `response-content-language`    | Sets the header of the response `Content-Language`.    |
| `response-expires`             | Sets the header of the response `Expires`.             |
| `response-cache-control`       | Sets the header of the response `Cache-Control`.       |
| `response-content-disposition` | Sets the header of the response `Content-Disposition`. |
| `response-content-encoding`    | Sets the header of the response `Content-Encoding`.    |
| `version-id`                   | A link to a specific version of the object.            |

#### Headings <a href="#request-headers" id="request-headers"></a>

Use the required [common headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in the request .

You can also use the following headers in the request:

| Heading               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Range`               | <p>Specifies the range of bytes to load from the object.<br><br>Read more about the Range header in the HTTP specification <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35"><http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35></a> .</p>                                                                                                                                                                                                                                                                   |
| `If-Modified-Since`   | <p>If specified, ColdStack returns:<br>- Object. If it changed after the specified time.<br>- Code 304. If the object has not changed after the specified time.<br><br>If the query at the same time there are headers <code>If-Modified-Since</code>and <code>If-None-Match</code>and check it settled like <code>If-Modified-Since -> true</code>and <code>If-None-Match -> false</code>then ColdStack returns the code 304. For details, see <a href="https://tools.ietf.org/html/rfc7232">RFC 7232</a> .</p>                                   |
| `If-Unmodified-Since` | <p>If specified, ColdStack returns:<br>- Object. If it hasn't changed since the specified time.<br>- Code 412. If the object has not changed since the specified time.<br><br>If the request headers are present simultaneously <code>If-Unmodified-Since</code>and <code>If-Match</code>resolved as checks on them <code>If-Unmodified-Since -> false</code>, and <code>If-Match -> true</code>then ColdStack returns a code 200, and the requested data. See <a href="https://tools.ietf.org/html/rfc7232">RFC 7232 for</a> details .</p>        |
| `If-Match`            | <p>If specified, ColdStack returns:<br>- Object. If it <code>ETag</code>matches the one passed.<br>- Code 412. If it <code>ETag</code>does not match the transmitted one.<br><br><br>If the request headers are present simultaneously <code>If-Unmodified-Since</code>and <code>If-Match</code>resolved as checks on them <code>If-Unmodified-Since -> false</code>, and <code>If-Match -> true</code>then ColdStack returns a code 200, and the requested data. See <a href="https://tools.ietf.org/html/rfc7232">RFC 7232 for</a> details .</p> |
| `If-None-Match`       | <p>If specified, ColdStack returns:<br>- Object. If its <code>ETag</code>not the same as the one passed.<br>- Code 304. If it <code>ETag</code>matches the transmitted one.<br><br><br>If the query at the same time there are headers <code>If-Modified-Since</code>and <code>If-None-Match</code>and check it settled like <code>If-Modified-Since -> true</code>and <code>If-None-Match -> false</code>then ColdStack returns the code 304. For details, see <a href="https://tools.ietf.org/html/rfc7232">RFC 7232</a> .</p>                   |

### Answer <a href="#response" id="response"></a>

#### Headings <a href="#response-headers" id="response-headers"></a>

In addition to the [general headers,](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) you can see the headers listed in the table below in the response.

| Heading                                       | Description                                                                                                                                                                    |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `x-amz-meta-*`                                | The custom metadata of the object, saved with the object.                                                                                                                      |
| `x-amz-storage-class`                         | <p>Object storage class.<br>Matters <code>COLD</code>if the object is in Cold Storage.<br><br>If the object is saved in the Standard storage, then there will be no title.</p> |
| `x-amz-server-side-encryption`                | The encryption algorithm used to encrypt the object. Returned if the object was loaded with encryption enabled .                                                               |
| `x-amz-server-side-encryption-aws-kms-key-id` | KMS key identifier . Returned if the object was loaded with encryption enabled .                                                                                               |

#### Answer codes <a href="#response-codes" id="response-codes"></a>

For a list of possible answers, see the [Answers](/http-api-compatible-with-amazon-s3/api-reference/answers) section .


# HeadObject

Returns the metadata of the object.

The method is equivalent to the [GetObject](/http-api-compatible-with-amazon-s3/api-reference/object/get) method , but the object itself is missing from the response.

### Request <a href="#request" id="request"></a>

```
HEAD /{bucket}/{key} HTTP/1.1
```

#### Path parameters <a href="#path-parameters" id="path-parameters"></a>

| Parameter | Description  |
| --------- | ------------ |
| `bucket`  | Bucket name. |
| `key`     | Object key.  |

#### Headings <a href="#request-headers" id="request-headers"></a>

Use the required [common headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in the request .

You can also use the following headers in the request:

| Heading               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Range`               | <p>Specifies the range of bytes to load from the object.<br><br>Read more about the Range header in the HTTP specification <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35"><http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35></a> .</p>                                                                                                                                                                                                                                                                       |
| `If-Modified-Since`   | <p>If specified, ColdStack returns:<br>- Object. If it changed after the specified time.<br>- Code 304. If the object has not changed after the specified time.<br><br>If the query at the same time there are headers <code>If-Modified-Since</code>and <code>If-None-Match</code>and check it settled like <code>If-Modified-Since -> true</code>and <code>If-None-Match -> false</code>then ColdStack returns the code 304. For details, see <a href="https://tools.ietf.org/html/rfc7232">RFC 7232</a> .</p>                                       |
| `If-Unmodified-Since` | <p>If specified, ColdStack returns:<br>- Object. If it hasn't changed since the specified time.<br>- Code 412. If the object has not changed since the specified time.<br><br>If the request headers are present simultaneously <code>If-Unmodified-Since</code>and <code>If-Match</code>resolved as checks on them <code>If-Unmodified-Since -> false</code>, and <code>If-Match -> true</code>then ColdStack returns a code 200, and the requested data. See <a href="https://tools.ietf.org/html/rfc7232">RFC 7232 for</a> details .</p>            |
| `If-Match`            | <p>If specified, ColdStack returns:<br><br>- Object. If it <code>ETag</code>matches the one passed.<br>- Code 412. If it <code>ETag</code>does not match the transmitted one.<br><br><br>If the request headers are present simultaneously <code>If-Unmodified-Since</code>and <code>If-Match</code>resolved as checks on them <code>If-Unmodified-Since -> false</code>, and <code>If-Match -> true</code>then ColdStack returns a code 200, and the requested data. See <a href="https://tools.ietf.org/html/rfc7232">RFC 7232 for</a> details .</p> |
| `If-None-Match`       | <p>If specified, ColdStack returns:<br><br>- Object. If its <code>ETag</code>not the same as the one passed.<br>- Code 304. If it <code>ETag</code>matches the transmitted one.<br><br><br>If the query at the same time there are headers <code>If-Modified-Since</code>and <code>If-None-Match</code>and check it settled like <code>If-Modified-Since -> true</code>and <code>If-None-Match -> false</code>then ColdStack returns the code 304. For details, see <a href="https://tools.ietf.org/html/rfc7232">RFC 7232</a> .</p>                   |

### Answer <a href="#response" id="response"></a>

#### Headings <a href="#response-headers" id="response-headers"></a>

In addition to the [general headers,](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) you can see the headers listed in the table below in the response.

| Heading                                       | Description                                                                                                                                                                    |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `x-amz-meta-*`                                | The custom metadata of the object, saved with the object.                                                                                                                      |
| `x-amz-storage-class`                         | <p>Object storage class.<br>Matters <code>COLD</code>if the object is in Cold Storage.<br><br>If the object is saved in the Standard storage, then there will be no title.</p> |
| `x-amz-server-side-encryption`                | The encryption algorithm used to encrypt the object. Returned if the object was loaded with encryption enabled .                                                               |
| `x-amz-server-side-encryption-aws-kms-key-id` | KMS key identifier . Returned if the object was loaded with encryption enabled .                                                                                               |

#### Answer codes <a href="#response-codes" id="response-codes"></a>

For a list of possible answers, see the [Answers](/http-api-compatible-with-amazon-s3/api-reference/answers) section .


# RenameObject

Renames an object. This operation is an extension to the standard S3 protocol, and was implemented to give users far more functionality.

### Request <a href="#request" id="request"></a>

```http
MOVE /{bucket}/{key} HTTP/1.1
Destination: {newObjectKey}
X-ColdStack-Prefix: IsPrefix
```

#### Path parameters <a href="#path-parameters" id="path-parameters"></a>

| Parameter      | Description                                   |
| -------------- | --------------------------------------------- |
| `bucket`       | Name of the bucket.                           |
| `key`          | Current key of the object.                    |
| `newObjectKey` | New key for the object.                       |
| `IsPrefix`     | For renaming prefixes (e.g. renaming folders) |

#### Headings <a href="#request-headers" id="request-headers"></a>

Use only [generic headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in your request .

### Response <a href="#response" id="response"></a>

#### Headings <a href="#response-headers" id="response-headers"></a>

The response can only contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) .

#### Response codes <a href="#response-codes" id="response-codes"></a>

For a list of possible responses, see the [Responses](/http-api-compatible-with-amazon-s3/api-reference/answers) section .

A successful response does not contain additional data and means that the object was successfully renamed.


# PutObjectAcl

Set's objects visibility. At the moment, for security and simplicity of use ColdStack supports only `private` and `publlic-read`  canned ACLs.

### Request <a href="#request" id="request"></a>

```http
PUT /{bucket}/{key}?acl HTTP/1.1
X-Amz-ACL: {CannedACL}
```

#### Path parameters <a href="#path-parameters" id="path-parameters"></a>

| Parameter   | Description                                                  |
| ----------- | ------------------------------------------------------------ |
| `bucket`    | Name of the bucket.                                          |
| `key`       | Key of the object.                                           |
| `CannedACL` | The canned ACL setting. Should be `private` or `public-read` |

#### Headings <a href="#request-headers" id="request-headers"></a>

Use only [generic headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in your request .

### Response <a href="#response" id="response"></a>

#### Headings <a href="#response-headers" id="response-headers"></a>

The response can only contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) .

#### Response codes <a href="#response-codes" id="response-codes"></a>

For a list of possible responses, see the [Responses](/http-api-compatible-with-amazon-s3/api-reference/answers) section .

A successful response does not contain additional data and means that the object was successfully renamed.


# Multipart upload

### All Multipart Upload Methods

| Method                                                                                                       | Description                   |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------- |
| [CreateMultipartUpload](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/startupload)      | Initializes a composite load. |
| [UploadPart](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/uploadpart)                  | Loads part of an object.      |
| [CompleteMultipartUpload](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/completeupload) | Ends a multipart load.        |


# General multipart upload order

Composite loading allows you to save objects to ColdStack in parts. This can be useful when loading or copying large objects. We recommend using multiple uploads for objects of 100 MB or more.

Composite loading consists of the following steps:

1. Boot initialization.\
   The user submits a [request to start a composite upload](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/startupload) , and ColdStack returns an identifier that should be used for all subsequent upload operations.\
   The custom object metadata should be passed in at this stage of the download.
2. Loading an object in parts.\
   Each part of the object is sent as a [separate request](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/uploadpart) and must have a sequence number that is used to assemble the object on the Object Storage side. If Object Storage receives two parts of an object with the same numbers, it will save the last one that came.\
   For each part loaded, Object Storage returns a header `ETag`in the response. The user must keep the numbers and their corresponding `ETag`for all downloaded parts. This is required for the download completion operation.
3. Completion of the download.\
   When [requested to complete the upload,](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/completeupload) Object Storage collects all the uploaded parts into a single object and attaches the metadata that was passed when the upload was initialized to the object.

   In addition to the request to complete the download, the user can send a request to interrupt the download . In this case, Object Storage will delete all received parts of the object for the specified load and delete the load itself.\
   Once the download is complete or interrupted, the user will no longer be able to use the download ID in requests.

A user can run multiple compound downloads at the same time.

Composite loading methods:

| Method                                                                                                       | Description                   |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------- |
| [CreateMultipartUpload](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/startupload)      | Initializes a composite load. |
| [UploadPart](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/uploadpart)                  | Loads part of an object.      |
| [CompleteMultipartUpload](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/completeupload) | Ends a multipart load.        |


# CreateMultipartUpload

Returns an identifier that should be used in all further operations to load the object.

If custom metadata needs to be stored with the object, then it should be passed in this request.

### Request <a href="#request" id="request"></a>

```
POST /{bucket}/{key}?uploads HTTP/1.1
```

#### Path parameters <a href="#path-parameters" id="path-parameters"></a>

| Parameter | Description                                                                 |
| --------- | --------------------------------------------------------------------------- |
| `bucket`  | Bucket name.                                                                |
| `key`     | Object key. The object will be saved in ColdStack under the specified name. |

#### Query parameters <a href="#request-parameters" id="request-parameters"></a>

| Parameter | Description                                 |
| --------- | ------------------------------------------- |
| `uploads` | A flag denoting a composite load operation. |

#### Headings <a href="#request-headers" id="request-headers"></a>

Use the required [common headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in the request .

Additionally, you can use the headings listed in the table below.

| Heading               | Description                                                                                                                                                                                                                                                                                                                                                                                                                             |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-amz-meta-*`        | <p>Custom object metadata.<br><br>All headers starting with <code>x-amz-meta-</code>ColdStack are treated as custom headers, they are not processed and stored in the form in which they are transmitted.<br><br>The total size of custom headers must not exceed 2KB. The size of the user data is defined as the length of the UTF-8 encoded string. The size takes into account both the names of the headings and their values.</p> |
| `x-amz-storage-class` | <p>Object storage class.<br><br>Can have any of the following values:<br>- <code>STANDARD</code>to load an object into the standard storage.<br>- <code>COLD</code>, <code>STANDARD\_IA</code>and <code>NEARLINE</code>to load the object into cold storage.<br><br>If the header is not specified, then the object is saved in the storage set in the bucket settings.</p>                                                             |

### Answer <a href="#response" id="response"></a>

#### Headings <a href="#response-headers" id="response-headers"></a>

The response can only contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) .

#### Answer codes <a href="#response-codes" id="response-codes"></a>

For a list of possible answers, see the [Answers](/http-api-compatible-with-amazon-s3/api-reference/answers) section .

The successful response contains additional data in XML format, the schema of which is described below.

#### Data schema <a href="#response-scheme" id="response-scheme"></a>

```
<InitiateMultipartUploadResult>
  <Bucket>bucket-name</Bucket>
  <Key>object-key</Key>
  <UploadId>upload-id</UploadId>
</InitiateMultipartUploadResult>
```

| Tag                             | Description                                                                                                                                                            |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `InitiateMultipartUploadResult` | <p>The root tag of the response.<br><br>Path: <code>/InitiateMultipartUploadResult</code>.</p>                                                                         |
| `Bucket`                        | <p>The name of the bucket into which the object is loaded.<br><br>Path: <code>/InitiateMultipartUploadResult/Bucket</code>.</p>                                        |
| `Key`                           | <p>The key that is associated with the object after the download is complete.<br><br>Path: <code>/InitiateMultipartUploadResult/Key</code>.</p>                        |
| `UploadId`                      | <p>Download ID.<br><br>All subsequent upload operations must pass this identifier to ColdStack.<br><br>Path: <code>/InitiateMultipartUploadResult/UploadId</code>.</p> |


# UploadPart

Retains part of the object.

The user independently numbers the parts of the object and transfers the numbers to ColdStack. The number uniquely identifies the part and determines its order in the overall sequence. A number is an integer between 1 and 10,000, inclusive.

If multiple chunks with the same number are loaded, ColdStack retains the last one that arrived.

Each part, except the last, must be at least 5MB in size.

For more information, see [General Multipart Upload Procedure](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/general-multipart-upload-order) .

### Request <a href="#request" id="request"></a>

```
PUT /{bucket}/{key}?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
```

#### Path parameters <a href="#path-parameters" id="path-parameters"></a>

| Parameter | Description  |
| --------- | ------------ |
| `bucket`  | Bucket name. |
| `key`     | Object key.  |

#### Query parameters <a href="#request-parameters" id="request-parameters"></a>

| Parameter    | Description                                                                                                                                           |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `partNubmer` | The ID that you assigned to the downloadable part.                                                                                                    |
| `uploadId`   | The composite load ID that ColdStack returned upon [initialization](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/startupload) . |

#### Headings <a href="#request-headers" id="request-headers"></a>

Use the required [common headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in the request .

The title is `Content-Length`required.

### Answer <a href="#response" id="response"></a>

#### Headings <a href="#response-headers" id="response-headers"></a>

The response can contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) and the headers listed in the table below.

| Heading               | Description                                                                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `x-amz-storage-class` | <p>Object storage class.<br>Matters <code>COLD</code>if the object is in Cold Storage.<br><br>If the object is saved in the Standard storage, then there will be no title.</p> |

#### Answer codes <a href="#response-codes" id="response-codes"></a>

For a list of possible answers, see the [Answers](/http-api-compatible-with-amazon-s3/api-reference/answers) section .

Additionally, ColdStack may return the errors described in the table below.

| Mistake          | Description                                                                                                                  | HTTP code       |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------- |
| `NoSuchUpload`   | The specified download does not exist. The download ID may be incorrect, or the download may have completed or been deleted. | 404 Not Found   |
| `EntityTooSmall` | <p>Part size is too small.<br><br>The downloadable part must be at least 5MB.</p>                                            | 400 Bad Request |


# CompleteMultipartUpload

The request completes the composite download.

When receiving an Object Storage request:

* Assembles the final object from the parts obtained during the download process in the order of their numbers
* Removes the download ID so that all subsequent requests with the download ID will return an error `NoSuchUpload`.

When the download is complete, the client must provide a list of the parts that he sent. The description of each part should contain `ETag`, which the client receives in response to each downloaded part. See section [The UploadPart Method](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/uploadpart) .

Depending on the size of the object and the number of parts, the operation may take several minutes.

If the request fails, then the client application should be ready to retry the request.

### Request <a href="#request" id="request"></a>

```
POST /{bucket}/{key}?uploadId=UploadId HTTP/1.1
```

#### Path parameters <a href="#path-parameters" id="path-parameters"></a>

| Parameter | Description  |
| --------- | ------------ |
| `bucket`  | Bucket name. |
| `key`     | Object key.  |

#### Query parameters <a href="#request-parameters" id="request-parameters"></a>

| Parameter  | Description                                                                                                                                           |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uploadId` | The composite load ID that ColdStack returned upon [initialization](/http-api-compatible-with-amazon-s3/api-reference/multipart-upload/startupload) . |

#### Headings <a href="#request-headers" id="request-headers"></a>

Use the required [common headers](/http-api-compatible-with-amazon-s3/api-reference/common-request-headers) in the request .

#### Data schema <a href="#request-scheme" id="request-scheme"></a>

The list of parts of a composite download is sent as an XML file in the following format:

```
<CompleteMultipartUpload>
  <Part>
    <PartNumber>PartNumber</PartNumber>
    <ETag>ETag</ETag>
  </Part>
  ...
</CompleteMultipartUpload>
```

| Tag                       | Description                                                                                                                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `CompleteMultipartUpload` | <p>Request data.<br><br>Path: <code>/CompleteMultipartUpload</code>.</p>                                                                                                                   |
| `Part`                    | <p>Data about the loaded part of the object.<br><br>Path: <code>/CompleteMultipartUpload/Part</code>.</p>                                                                                  |
| `PartNumber`              | <p>Part number.<br><br>A unique identifier that identifies the position of the part among other parts in the load.<br><br>Path: <code>/CompleteMultipartUpload/Part/PartNumber</code>.</p> |
| `ETag`                    | <p>The identifier that the client received from ColdStack in response to downloading the part.<br><br>Path: <code>/CompleteMultipartUpload/Part/ETag</code>.</p>                           |

### Answer <a href="#response" id="response"></a>

#### Headings <a href="#response-headers" id="response-headers"></a>

The response can only contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) .

#### Answer codes <a href="#response-codes" id="response-codes"></a>

For a list of possible answers, see the [Answers](/http-api-compatible-with-amazon-s3/api-reference/answers) section .

Additionally, ColdStack may return the errors described in the table below.

| Mistake            | Description                                                                                                                                                                    | HTTP code       |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
| `NoSuchUpload`     | The specified download does not exist. The download ID may be incorrect, or the download may have completed or been deleted.                                                   | 404 Not Found   |
| `InvalidPart`      | <p>Some of the specified parts have not been found.<br><br>Possible causes:<br>- Parts not loaded.<br>- The transmitted one <code>ETag</code>does not match the saved one.</p> | 400 Bad Request |
| `InvalidPartOrder` | <p>The list of parts is not transmitted in ascending order.<br><br>The list should be sorted in ascending order by part number.</p>                                            | 400 Bad Request |

The successful response contains additional data in XML format, the schema of which is described below.

#### Data schema <a href="#request-scheme1" id="request-scheme1"></a>

```
<CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Location>http://Example-Bucket.s3.coldstack.io/Example-Object</Location>
  <Bucket>Example-Bucket</Bucket>
  <Key>Example-Object</Key>
  <ETag>"3858f62230ac3c915f300c664312c11f-9"</ETag>
</CompleteMultipartUploadResult>
```

| Tag                             | Description                                                                                                                      |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `CompleteMultipartUploadResult` | <p>Response data.<br><br>Path: <code>/CompleteMultipartUploadResult</code>.</p>                                                  |
| `Location`                      | <p>The URI of the resulting download of the object.<br><br>Path: <code>/CompleteMultipartUploadResult/Location</code>.</p>       |
| `Bucket`                        | <p>The name of the bucket in which the object is located.<br><br>Path: <code>/CompleteMultipartUploadResult/Bucket</code>.</p>   |
| `Key`                           | <p>The key of the created object.<br><br>Path: <code>/CompleteMultipartUploadResult/Key</code>.</p>                              |
| `ETag`                          | <p>The hash of the object.<br><br>ETag may or may not be MD5.<br><br>Path: <code>/CompleteMultipartUploadResult/ETag</code>.</p> |


# ListMultipartUploads

Returns a list of current multipart uploads.

The response may contain no more than 1,000 elements. If there are more uploads, Object Storage returns the `IsTruncated` element and the `NextKeyMarker` and `NextUploadIdMarker` elements to be used for the `key-marker` and `upload-id-​marker` parameters of a subsequent request.

### Request

```
GET /{bucket}?uploads HTTP/1.1
```

#### Path parameters <a href="#path-parameters" id="path-parameters"></a>

| Parameter | Description  |
| --------- | ------------ |
| `bucket`  | Bucket name. |

#### Query parameters <a href="#request-parameters" id="request-parameters"></a>

| Parameter           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `delimiter`         | <p>Delimiter character.<br><br>If this parameter is specified, Object Storage interprets the key as the path to the file with folder names separated by the <code>delimiter</code> character. The user gets a list of files and folders in the root of the bucket. Files are output in the <code>Uploads</code> elements, and the folders in the <code>CommonPrefixes</code> elements.<br><br>If the request also specifies the <code>prefix</code> parameter, Object Storage returns the a of files and folders in the <code>prefix</code> folder.</p>                                                                                                                                                                                       |
| `max-uploads`       | <p>Maximum number of uploads in a response.<br><br>By default, Object Storage outputs a maximum of 1000 keys. This parameter should be used if you need to get less than 1000 keys in a single response.<br><br>If the number of keys meeting the selection criteria is greater than the number that could fit in the output, the response contains <code>\<IsTruncated>true\</IsTruncated></code>.<br><br>To get all output objects if their number exceeds the <code>max-keys</code> value, make several consecutive requests to Object Storage with the <code>key-marker</code> parameter, where the <code>key-marker</code> of each request is equal to the value of the <code>NextKeyMarker</code> element in the previous response.</p> |
| `key-marker`        | <p>Key. Output begins with the key that follows the one specified in the parameter value.<br><br>Use it together with the <code>upload-id-marker</code> for output filtering.<br><br>If the <code>upload-id-marker</code> is specified, then the output also contains the <code>key-marker</code>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `prefix`            | <p>String to start the key from.<br><br>Object Storage selects only those keys that start with <code>prefix</code>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `upload-id-​marker` | <p>Upload ID.<br><br>Output begins with the upload whose ID follows the one specified in the parameter value. The <code>key-marker</code> value is processed, meaning that the output contains the uploads that match filtering by both <code>upload-id-​marker</code> and <code>key-marker</code>.<br><br>If no<code>key-marker</code> is specified, the <code>upload-id-​marker</code> is ignored.</p>                                                                                                                                                                                                                                                                                                                                      |
| `uploads`           | Flag indicating a multipart upload operation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

#### Headers <a href="#request-headers" id="request-headers"></a>

Use the necessary [common request headers](https://cloud.yandex.com/docs/storage/s3/api-ref/common-request-headers) in requests.

### Response <a href="#response" id="response"></a>

#### Headers <a href="#response-headers" id="response-headers"></a>

Responses can only contain [common response headers](https://cloud.yandex.com/docs/storage/s3/api-ref/common-response-headers).

#### Response codes <a href="#response-codes" id="response-codes"></a>

For a list of possible responses, see [Responses](https://cloud.yandex.com/docs/storage/s3/api-ref/response-codes).

A successful response contains additional data in XML format with the schema described below.

#### Data schema <a href="#response-scheme" id="response-scheme"></a>

```
<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Bucket>bucket</Bucket>
  <KeyMarker></KeyMarker>
  <UploadIdMarker></UploadIdMarker>
  <NextKeyMarker>my-movie.m2ts</NextKeyMarker>
  <NextUploadIdMarker>YW55IGlkZWEgd2h5IGVsdmluZydzIHVwbG9hZCBmYWlsZWQ</NextUploadIdMarker>
  <MaxUploads>3</MaxUploads>
  <IsTruncated>true</IsTruncated>
  <Upload>
    <Key>my-divisor</Key>
    <UploadId>XMgbGlrZSBlbHZpbmcncyBub3QgaGF2aW5nIG11Y2ggbHVjaw</UploadId>
    <Initiator>
      <ID>...</ID>
      <DisplayName>...</DisplayName>
    </Initiator>
    <StorageClass>STANDARD</StorageClass>
    <Initiated>2010-11-10T20:48:33.000Z</Initiated>
  </Upload>
  <Upload>
    <Key>my-movie.m2ts</Key>
    <UploadId>VXBsb2FkIElEIGZvciBlbHZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZA</UploadId>
    <Initiator>
      <ID>...</ID>
      <DisplayName>...</DisplayName>
    </Initiator>
    <StorageClass>COLD</StorageClass>
    <Initiated>2010-11-10T20:48:33.000Z</Initiated>
  </Upload>
  <Upload>
    <Key>my-movie.m2ts</Key>
    <UploadId>YW55IGlkZWEgd2h5IGVsdmluZydzIHVwbG9hZCBmYWlsZWQ</UploadId>
    <Initiator>
      <ID>...</ID>
      <DisplayName>...</DisplayName>
    </Initiator>
    <StorageClass>STANDARD</StorageClass>
    <Initiated>2010-11-10T20:49:33.000Z</Initiated>
  </Upload>
</ListMultipartUploadsResult>
```

| Tag                                  | Description                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ListMultipartUploadsResult`         | <p>Root tag for the response.<br><br>Path: <code>/ListMultipartUploadsResult</code>.</p>                                                                                                                                                                                                                                                             |
| `Bucket`                             | <p>The bucket that the multipart upload belongs to.<br><br>Path: <code>/ListMultipartUploadsResult/Bucket</code>.</p>                                                                                                                                                                                                                                |
| `KeyMarker`                          | <p>Key.<br><br>The output begins with the key that follows the one specified in the element value.<br><br>See the <code>key-marker</code> request parameter description.<br><br>Path: <code>/ListMultipartUploadsResult/KeyMarker</code>.</p>                                                                                                        |
| `UploadIdMarker`                     | <p>Upload ID.<br><br>Output begins with the upload whose ID follows the one specified in the parameter value.<br><br>See the <code>upload-id-marker</code> parameter description.<br><br>Path: <code>/ListMultipartUploadsResult/UploadIdMarker</code>.</p>                                                                                          |
| `NextKeyMarker`                      | <p>Key.<br><br>If the output failed to include all the elements the user should have received, this value is to be used in the <code>key-marker</code> parameter for subsequent requests.<br><br>Present if some of the elements do not fit in the response.<br><br>Path: <code>/ListMultipartUploadsResult/NextKeyMarker</code>.</p>                |
| `NextUploadIdMarker`                 | <p>Upload ID.<br><br>If the output failed to include all the elements the user should have received, this value is to be used in the <code>upload-id-marker</code> parameter for subsequent requests.<br><br>Present if some of the elements do not fit in the response.<br><br>Path: <code>/ListMultipartUploadsResult/NextUploadMarker</code>.</p> |
| `Encoding-Type`                      | <p>Encoding in which Object Storage provides a key in an XML response.<br><br>See the <code>encoding-type</code> request parameter description.<br><br>Path: <code>/ListMultipartUploadsResult/Encoding-Type</code>.</p>                                                                                                                             |
| `MaxUploads`                         | <p>Maximum list length for a single response.<br><br>See the <code>max-uploads</code> request parameter description.<br><br>Path: <code>/ListMultipartUploadsResult/MaxUploads</code>.</p>                                                                                                                                                           |
| `IsTruncated`                        | <p>Flag indicating that a list is incomplete.<br><br>If <code>IsTruncated</code> is <code>true</code>, this means that Object Storage returned an incomplete list of uploads.<br><br>Path: <code>/ListMultipartUploadsResult/IsTruncated</code>.</p>                                                                                                 |
| `Upload`                             | <p>Upload description.<br><br>Path: <code>/ListMultipartUploadsResult/Upload</code>.</p>                                                                                                                                                                                                                                                             |
| `Key`                                | <p>Key of the last upload object.<br><br>Path: <code>/ListMultipartUploadsResult/Upload/Key</code>.</p>                                                                                                                                                                                                                                              |
| `UploadId`                           | <p>Multipart upload ID.<br><br>Path: <code>/ListMultipartUploadsResult/Upload/UploadId</code>.</p>                                                                                                                                                                                                                                                   |
| `Initiator`                          | <p>Multipart upload initiator.<br><br>Path: <code>/ListMultipartUploadsResult/Upload/Initiator</code>.</p>                                                                                                                                                                                                                                           |
| `ID`                                 | <p>User ID.<br><br>Possible paths:<br>- <code>/ListMultipartUploadsResult/Upload/Initiator/ID</code></p>                                                                                                                                                                                                                                             |
| `DisplayName`                        | <p>User name displayed.<br><br>Possible paths:<br>- <code>/ListMultipartUploadsResult/Upload/Initiator/DisplayName</code></p>                                                                                                                                                                                                                        |
| `StorageClass`                       | <p>Object storage class: <code>STANDARD</code> or <code>COLD</code>.<br><br>Path: <code>/ListMultipartUploadsResult/Upload/StorageClass</code>.</p>                                                                                                                                                                                                  |
| `Initiated`                          | Date and time of the request for [starting multipart upload](https://cloud.yandex.com/docs/storage/s3/api-ref/multipart/startupload).                                                                                                                                                                                                                |
| `/ListMultipartUploadsResult/Prefix` | <p>Key prefix.<br><br>See the <code>prefix</code> request parameter description.<br><br>Path: <code>/ListMultipartUploadsResult/Prefix</code>.</p>                                                                                                                                                                                                   |
| `Delimiter`                          | <p>Delimiter character that was used when generating output.<br><br>See the description of the <code>delimiter</code> request parameter.<br><br>Path: <code>/ListMultipartUploadsResult/Delimiter</code>.</p>                                                                                                                                        |
| `CommonPrefixes`                     | <p>Contains the <code>Prefix</code> element.<br><br>Path: <code>/ListMultipartUploadsResult/CommonPrefixes</code>.</p>                                                                                                                                                                                                                               |
| `CommonPrefixes/Prefix`              | <p>Part of the key name identified when processing the <code>delimiter</code> and <code>prefix</code> request parameters.<br><br>Path: <code>/ListMultipartUploadsResult/CommonPrefixes/Prefix</code>.</p>                                                                                                                                           |


# Analytics


# GetStatistics

Returns overall usage statistics.

This operation is an extension to the standard S3 API, and is implemented to provide more information to the about their usage.

### Request <a href="#request" id="request"></a>

```
GET /?statistics HTTP/1.1
```

### Response

**Headings**

The response can only contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) .

**Response codes**

For a list of possible answers, see the [Answers](/http-api-compatible-with-amazon-s3/api-reference/answers) section .

The successful response contains additional data in XML format, the schema of which is described below.

**Data schema**

```markup
<?xml version="1.0" encoding="UTF-8"?>
<Statistics>
  <BucketsCount>4</BucketsCount>
  <ObjectsCount>12</ObjectsCount>
  <UsedStorage>
    <UsedStorageBytes>271242929</UsedStorageBytes>
    <UsedStorageReadableQuantity>271</UsedStorageReadableQuantity>
    <UsedStorageReadableUnit>MB</UsedStorageReadableUnit>
  </UsedStorage>
  <Bandwidth>
    <BandwidthBytes>271242929</BandwidthBytes>
    <BandwidthReadableQuantity>271</BandwidthReadableQuantity>
    <BandwidthReadableUnit>MB</BandwidthReadableUnit>
  </Bandwidth>
</Statistics>
```

| Element                       | Description                                         |
| ----------------------------- | --------------------------------------------------- |
| `Statistics`                  | Root element.                                       |
| `BucketsCount`                | Number of buckets.                                  |
| `ObjectsCount`                | Overall number of objects in all owned buckets.     |
| `UsedStorage`                 | Used disk storage.                                  |
| `UsedStorageBytes`            | Used storage size represented as bytes.             |
| `UsedStorageReadableQuantity` | Quantity of used storage readable representation.   |
| `UsedStorageReadableUnit`     | Unit of used storage readable representation.       |
| `Bandwidth`                   | Used bandwidth.                                     |
| `BandwidthBytes`              | Used bandwidth represented as bytes.                |
| `BandwidthReadableQuantity`   | Quantity of used bandwidth readable representation. |
| `BandwidthReadableUnit`       | Unit of used bandwidth readable representation.     |


# GetBandwidthAnalytics

Returns bandwidth analytics over time.

This operation is an extension to the standard S3 API, and is implemented to provide more information to the about their usage.

### Request <a href="#request" id="request"></a>

```http
GET /?bandwidthAnalytics&fromDate=FromDate&toDate=ToDate HTTP/1.1
```

### Response

**Headings**

The response can only contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) .

**Response codes**

For a list of possible answers, see the [Answers](/http-api-compatible-with-amazon-s3/api-reference/answers) section .

The successful response contains additional data in XML format, the schema of which is described below.

**Data schema**

```markup
<?xml version="1.0" encoding="UTF-8"?>
<BandwidthAnalytics>
  <Record>
    <Date>2021-08-13</Date>
    <UploadBandwidth>0</UploadBandwidth>
    <UploadBandwidthReadable>0 B</UploadBandwidthReadable>
    <DownloadBandwidth>15000000</DownloadBandwidth>
    <DownloadBandwidthReadable>15 MB</DownloadBandwidthReadable>
  </Record>
  ...
</BandwidthAnalytics>
```

| Element                     | Description                                                                                                                                                       |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BandwidthAnalytics`        | Root element.                                                                                                                                                     |
| `Record`                    | Array of records of analytics. There is only one record for a day, but if no bandwidth was used for a specific day then no record for that day will be available. |
| `Date`                      | Date of the record                                                                                                                                                |
| `UploadBandwidth`           | Upload bandwidth represented as bytes.                                                                                                                            |
| `UploadBandwidthReadable`   | Readable upload bandwidth.                                                                                                                                        |
| `DownloadBandwidth`         | Download bandwidth represented as bytes.                                                                                                                          |
| `DownloadBandwidthReadable` | Readable download bandwidth.                                                                                                                                      |


# GetStorageAnalytics

Returns storage analytics over time.

This operation is an extension to the standard S3 API, and is implemented to provide more information to the about their usage.

### Request <a href="#request" id="request"></a>

```http
GET /?storageAnalytics&fromDate={FromDate}&toDate={ToDate}&format={json/xml} HTTP/1.1
```

### Response

**Headings**

The response can only contain [general headers](/http-api-compatible-with-amazon-s3/api-reference/common-response-headers) .

**Response codes**

For a list of possible answers, see the [Answers](/http-api-compatible-with-amazon-s3/api-reference/answers) section .

The successful response contains additional data in XML format, the schema of which is described below.

**Data schema**

```markup
<?xml version="1.0" encoding="UTF-8"?>
<StorageUsageAnalytics>
  <Record>
    <Timestamp>2021-08-13</Timestamp>
    <UsedStorage>0</UsedStorage>
    <UsedStorageReadable>0 B</UsedStorageReadable>
  </Record>
  ...
</StorageUsageAnalytics>
```

| Element                 | Description                                                                                                                                                           |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `StorageUsageAnalytics` | Root element.                                                                                                                                                         |
| `Record`                | Array of records of analytics. There is only one record for an hour, but if no bandwidth was used for a specific hour then no record for that hour will be available. |
| `Timestamp`             | Date and hour of the record                                                                                                                                           |
| `UsedStorage`           | Used storage at that timestamp.                                                                                                                                       |
| `UsedStorageReadable`   | Used storage at that timestamp in readable format.                                                                                                                    |


# Common request headers

| Heading                | Description                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization`        | <p>Any request to ColdStack must be authorized.<br><br>Along with this heading <code>Date</code>, either a heading or a heading must be used <code>x-amz-date</code>.<br><br>Read about the authorization methods in the corresponding sections of the manual.</p>                                                                                                              |
| `Cache-Control`        | A set of directives for caching data according to [RFC 2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9) .                                                                                                                                                                                                                                                 |
| `Content-​Disposition` | The name under which Object Storage will offer to save the object as a file when unloading. [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1) compliant .                                                                                                                                                                                            |
| `Content-Encoding`     | Defines the encoding of the content according to [RFC 2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11) .                                                                                                                                                                                                                                                 |
| `Content-Length`       | <p>The length of the request body (without headers) in accordance with <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.13">RFC 2616</a> .<br><br>The header is required for all requests that transfer any data to Object Storage, for example, when loading an object.</p>                                                                              |
| `Content-Type`         | <p>The data type in the request. Eg <code>text/html</code>. For more information about data types, see the Wikipedia article <a href="https://ru.wikipedia.org/wiki/%D0%A1%D0%BF%D0%B8%D1%81%D0%BE%D0%BA_MIME-%D1%82%D0%B8%D0%BF%D0%BE%D0%B2">List of MIME Types</a> .<br><br>Set by default <code>binary/octet-stream</code>.</p>                                              |
| `Content-MD5`          | <p>128-bit MD5 hash of the request body, encoded <code>base64</code>.<br><br>Compliant with <a href="http://www.ietf.org/rfc/rfc1864.txt">RFC 1864</a> specification .<br><br>Object Storage uses a header to ensure that the data sent matches the received data.</p>                                                                                                          |
| `Date`                 | <p>The date and time the request was sent.<br><br>Format: <code>Thu, 18 Jan 2018 09:57:35 GMT</code>.<br><br>When set <code>x-amz-date</code>, Object Storage ignores the header <code>Date</code>.</p>                                                                                                                                                                         |
| `Expect`               | <p>Expected code <code>100-continue</code>.<br><br>When loading data into Object Storage, an application can use the following logic:<br>- Send a request without a body, but with the Expect: 100-continue header set.<br>- Send a request with a body after receiving a response <code>100-continue</code>. This request <code>Expect</code>should not contain a header .</p> |
| `Expires`              | The expiration date of the answer. [RFC 2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21) compliant .                                                                                                                                                                                                                                                     |
| `Host`                 | <p>The receiving host of the request.<br><br>The header is required for HTTP / 1.1, but optional for HTTP / 1.0 requests.</p>                                                                                                                                                                                                                                                   |
| `x-amz-date`           | <p>Date and time at the source of the request.<br><br>Format: <code>Thu, 18 Jan 2018 09:57:35 GMT</code>.<br><br>When set <code>x-amz-date</code>, Object Storage ignores the header <code>Date</code>.</p>                                                                                                                                                                     |


# Common response headers

In addition to [standard HTTP headers,](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields) ColdStack uses additional headers that may be present in responses.

Additional headings are described in the table below, as well as standard headings for which additional explanation is required.

| Heading            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ETag`             | <p><a href="https://ru.wikipedia.org/wiki/MD5">MD5 hash of the</a> object, if the object is loaded as a single file. If the object is loaded using a <a href="/pages/-MWtO76juk_huxULp3uu">compound load</a> , then for the calculation <code>ETag</code>it is necessary to obtain the MD5 hash from the sum of the MD5 hashes of the loaded parts (let's call it <code>MD5\_sum</code>) and attach the number of parts ( <code>N</code>): to the resulting string <code>"MD5\_sum-N"</code>.<br><br>Does not include object metadata.</p> |
| `x-amz-request-id` | <p>Unique identifier for the request.<br><br>It may be needed when contacting ColdStack support in case of problems.</p>                                                                                                                                                                                                                                                                                                                                                                                                                   |


# Responses

### Successful response <a href="#success" id="success"></a>

If there are no errors, ColdStack responds with 2xx HTTP codes. The response code and body depend on the request and are discussed in the request descriptions.

### Error response <a href="#error" id="error"></a>

When an error occurs, ColdStack responds with a message with the appropriate HTTP code and optional XML description.

```
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchKey</Code>
  <Message>The resource you requested does not exist</Message>
  <Resource>/mybucket/myfoto.jpg</Resource>
  <RequestId>4442587FB7D0A2F9</RequestId>
</Error>
```

| Tag         | Description                                                                                                                       |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `Code`      | <p>Error code.<br><br>See the list of codes below in the text.</p>                                                                |
| `Message`   | Description of the error in English.                                                                                              |
| `RequestId` | <p>The identifier of the request that caused the error.<br><br>Equal to the value of the title <code>x-amz-request-id</code>.</p> |
| `Resource`  | The bucket or object that encountered an error.                                                                                   |

#### Error codes <a href="#error_codes" id="error_codes"></a>

| HTTP | Error code                            | Description                                                                                                                                                                                                             |
| ---- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 301  | `PermanentRedirect`                   | The specified bucket should always be addressed to the address indicated in the response.                                                                                                                               |
| 307  | `Redirect`                            | The specified bucket should be temporarily addressed at the address indicated in the response.                                                                                                                          |
| 307  | `TemporaryRedirect`                   | Redirect for the duration of the DNS update.                                                                                                                                                                            |
| 400  | `BadDigest`                           | The hash passed in the header `Content-MD5`does not match the one calculated on the ColdStack side.                                                                                                                     |
| 400  | `CredentialsNotSupported`             | Credentials are not supported.                                                                                                                                                                                          |
| 400  | `EntityTooSmall`                      | The loaded object is less than the minimum size allowed.                                                                                                                                                                |
| 400  | `EntityTooLarge`                      | The loaded object is larger than the maximum allowed.                                                                                                                                                                   |
| 400  | `ExpiredToken`                        | The provided token has expired.                                                                                                                                                                                         |
| 400  | `IncompleteBody`                      | The size of the sent data is smaller than indicated in the header `Content-Length`.                                                                                                                                     |
| 400  | `IncorrectNumberOfFilesInPostRequest` | The POST method requires the transfer of exactly one file.                                                                                                                                                              |
| 400  | `InlineDataTooLarge`                  | The request data exceeded the maximum size allowed.                                                                                                                                                                     |
| 400  | `InvalidDigest`                       | The hash passed in the Content-MD5 header is not correct.                                                                                                                                                               |
| 400  | `InvalidArgument`                     | Invalid argument.                                                                                                                                                                                                       |
| 400  | `InvalidBucketName`                   | Invalid bucket name.                                                                                                                                                                                                    |
| 400  | `InvalidPart`                         | One or more parts of the composite load were not found. Check the list is correct. Possibly missing parts were not loaded.                                                                                              |
| 400  | `InvalidPartOrder`                    | The list of parts for a composite load is incorrect. Parts must be sorted in ascending order.                                                                                                                           |
| 400  | `InvalidRequest`                      | Use AWS4-HMAC-SHA256.                                                                                                                                                                                                   |
| 400  | `InvalidRequest`                      | <p>An attempt was made to exceed the maximum bucket size.<br><br>Error description in response: "You have attempted to exceed the max size configured for the bucket."</p>                                              |
| 400  | `InvalidStorageClass`                 | Invalid storage class.                                                                                                                                                                                                  |
| 400  | `InvalidTargetBucketForLogging`       | The bucket does not exist, or you are not the bucket owner, or the log delivery group does not have sufficient rights.                                                                                                  |
| 400  | `InvalidToken`                        | The token is incorrectly formed or incorrect for another reason.                                                                                                                                                        |
| 400  | `InvalidURI`                          | It was not possible to parse the passed URI.                                                                                                                                                                            |
| 400  | `KeyTooLongError`                     | The key is too long.                                                                                                                                                                                                    |
| 400  | `MalformedACLError`                   | The provided XML document is malformed or does not conform to the schema.                                                                                                                                               |
| 400  | `MalformedPOSTRequest`                | The request body does not match the format `multipart/form-data`.                                                                                                                                                       |
| 400  | `MalformedXML`                        | The provided XML document is malformed or does not conform to the schema.                                                                                                                                               |
| 400  | `MaxMessageLengthExceeded`            | The allowed request length was exceeded.                                                                                                                                                                                |
| 400  | `MaxPostPreDataLengthExceededError`   | The HTTP message header has exceeded the allowed size.                                                                                                                                                                  |
| 400  | `MetadataTooLarge`                    | The metadata headers are out of size.                                                                                                                                                                                   |
| 400  | `MissingRequestBodyError`             | <p>Empty request body.<br><br>Occurs when an empty XML document is sent.</p>                                                                                                                                            |
| 400  | `MissingSecurityHeader`               | Required title is missing.                                                                                                                                                                                              |
| 400  | `NoLoggingStatusForKey`               | Key logging status is missing.                                                                                                                                                                                          |
| 400  | `RequestIsNotMultiPartContent`        | The request must contain data of type `multipart/form-data`.                                                                                                                                                            |
| 400  | `RequestTimeout`                      | Read / write timeout.                                                                                                                                                                                                   |
| 400  | `TokenRefreshRequired`                | Refresh the token.                                                                                                                                                                                                      |
| 400  | `TooManyBuckets`                      | Exceeding the limit on the number of buckets.                                                                                                                                                                           |
| 400  | `UnexpectedContent`                   | There should be no content in the request.                                                                                                                                                                              |
| 400  | `UnresolvableGrantByEmailAddress`     | Unregistered e-mail.                                                                                                                                                                                                    |
| 400  | `UserKeyMustBeSpecified`              | The request must contain the title specified in the error description.                                                                                                                                                  |
| 403  | `AccessDenied`                        | Access is denied.                                                                                                                                                                                                       |
| 403  | `AccountProblem`                      | <p>Account issue preventing operations from completing successfully.<br><br>Contact ColdStack support.</p>                                                                                                              |
| 403  | `InvalidAccessKeyId`                  | Unknown key.                                                                                                                                                                                                            |
| 403  | `InvalidObjectState`                  | The request could not be completed for the current state of the object.                                                                                                                                                 |
| 403  | `InvalidPayer`                        | Access to the object is blocked.                                                                                                                                                                                        |
| 403  | `InvalidSecurity`                     | The provided secret keys are not valid.                                                                                                                                                                                 |
| 403  | `NotSignedUp`                         | The account is not allowed to use ColdStack.                                                                                                                                                                            |
| 403  | `RequestTimeTooSkewed`                | The difference between the time the request was sent and the time on the server is too big.                                                                                                                             |
| 403  | `SignatureDoesNotMatch`               | The supplied request signature does not match the computed ColdStack.                                                                                                                                                   |
| 404  | `NoSuchBucket`                        | The specified bucket does not exist.                                                                                                                                                                                    |
| 404  | `NoSuchKey`                           | The specified key does not exist.                                                                                                                                                                                       |
| 404  | `NoSuchUpload`                        | <p>The specified composite load does not exist.<br><br>The error occurs in the following cases:<br>- An invalid download ID was specified.<br>- Download interrupted.<br>- Loading is complete.</p>                     |
| 405  | `MethodNotAllowed`                    | The HTTP method is not applicable to the specified resource.                                                                                                                                                            |
| 409  | `KeyAlreadyExists`                    | The specified key already exists. This error can occur when trying to change object's key to an already used one (see [RenameObject](/http-api-compatible-with-amazon-s3/api-reference/object/renameobject) operation). |
| 409  | `BucketAlreadyExists`                 | A bucket with the same name already exists, please select a different name.                                                                                                                                             |
| 409  | `BucketNotEmpty`                      | The bucket you are deleting is not empty.                                                                                                                                                                               |
| 409  | `InvalidBucketState`                  | The request could not be completed for the current state of the bucket.                                                                                                                                                 |
| 409  | `OperationAborted`                    | Conflicting conditional operations.                                                                                                                                                                                     |
| 411  | `MissingContentLength`                | Add `Content-Length`to headers.                                                                                                                                                                                         |
| 412  | `Precondition Failed`                 | One of the conditions specified in the request has not been met.                                                                                                                                                        |
| 416  | `InvalidRange`                        | Invalid header range `Range`.                                                                                                                                                                                           |
| 429  | `TooManyRequests`                     | Too many requests to ColdStack. Reduce the frequency of calls.                                                                                                                                                          |
| 500  | `InternalError`                       | Internal ColdStack error. Reissue your request.                                                                                                                                                                         |
| 501  | `NotImplemented`                      | The passed header is not processed by ColdStack.                                                                                                                                                                        |
| 503  | `ServiceUnavailable`                  | <p>ColdStack is not available.<br>Reduce the frequency of your requests.</p>                                                                                                                                            |
| 503  | `SlowDown`                            | Reduce the frequency of your requests.                                                                                                                                                                                  |