---
title: "Swift"
description: "Swift API methods for working with S3"
---

import { CustomTable } from '@selectel/docux/components'

Using the Swift API (API based on OpenStack Object Storage API), you can work with S3 resources:

* view information about the number and volume of buckets and objects within an account;
* create and remove buckets;
* manage bucket limits;
* upload, view, copy, move, download, and remove objects in buckets.

To access the Swift API, a user must have a role with access to a project in S3; for more information, see the [Managing S3 access](/s3/about/manage-access/) guide.

## Authorization \{#authorization}

Authorization in Swift API is performed using an [IAM token for a project](/api/authorization/#iam-token-project-scoped), which is passed in every request in the `X-Auth-Token.` header.

The address (URL) can be viewed in the [list of URLs](/api/urls/).

Request example for viewing the list of buckets in an account project:

```bash
curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>'
```

Specify:

* `<x_auth_token>` —  [IAM token for a project](/api/authorization/#iam-token-project-scoped);
* `<swift_domain>` — [Swift API domain](/s3/manage/domains/#swift-api-domains) in the [pool](/infrastructure/locations/#pool) where S3 is located;
* `<project_id>` — project identifier. You can find the identifier in the [Control panel](https://my.selectel.ru/) in the **S3** section → project menu → **Project management**. The identifier is listed under the project name.

## Storage \{#storage}

<CustomTable>
  <table>
    <tbody>
      <tr>
        <td>HEAD</td><td>/v1/ {'{project_id}'}</td><td>[Get information about the storage](#get-info-about-storage)</td>
      </tr>

      <tr>
        <td>GET</td><td>/v1/ {'{project_id}'}</td><td>[Get information about the storage and a list of buckets](#get-storage-info-and-list-of-buckets)</td>
      </tr>

      <tr>
        <td>POST</td><td>/v1/ {'{project_id}'}</td><td>[Manage storage metadata](#manage-storage-metadata)</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

### Get information about the storage \{#get-info-about-storage}

Returns metadata with information about the number and storage volume of buckets and objects.

#### Request example \{#get-info-about-storage-request-example}

```bash
curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>'
```

#### Response example \{#get-info-about-storage-response-example}

On success, the request returns a response with code 204.

```
HTTP/1.1 204 No Content
Content-Length: 0
X-Account-Object-Count: 6
X-Timestamp: 1374058535.42927
X-Account-Meta-Temp-Url-Key: 00000
X-Account-Bytes-Used: 484474
X-Account-Container-Count: 3
X-Account-Meta-<...>: anyheader
X-Openstack-Requiest-Id: 0009ec57-2681-4b48-9105-71c57016edc6
X-Trans-Id: 0009ec57-2681-4b48-9105-71c57016edc6
```

#### Response parameters \{#get-info-about-storage-response-parameters}

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Parameter</th><th>Value</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>X-Account-Bytes-Used</td><td>Total volume of stored data (in bytes)</td>
      </tr>

      <tr>
        <td>X-Account-Container-Count</td><td>Number of buckets</td>
      </tr>

      <tr>
        <td>X-Account-Meta-\<...></td><td>Metadata, where \<...> is a custom header</td>
      </tr>

      <tr>
        <td>X-Account-Meta-Temp-Url-Key</td><td>Secret key used to access objects in a private bucket via a temporary URL (if available)</td>
      </tr>

      <tr>
        <td>X-Account-Object-Count</td><td>Total number of stored objects</td>
      </tr>

      <tr>
        <td>X-Account-Storage-Policy-Policy-0-Bytes-Used</td><td>Total volume of stored data by storage policy, where Policy-0 — policy name</td>
      </tr>

      <tr>
        <td>X-Account-Storage-Policy-Policy-0-Container-Count</td><td>Number of buckets using a storage policy, where Policy-0 — policy name</td>
      </tr>

      <tr>
        <td>X-Account-Storage-Policy-Policy-0-Object-Count</td><td>Number of objects using a storage policy, where Policy-0 — policy name</td>
      </tr>

      <tr>
        <td>X-Openstack-Request-Id<br />X-Trans-Id</td><td>Request ID</td>
      </tr>

      <tr>
        <td>X-Timestamp</td><td>Date and time in UNIX format when the account, bucket, or object was created</td>
      </tr>

      <tr>
        <td>Date</td><td>Date and time the request was sent</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

### Get information about the storage and a list of buckets \{#get-storage-info-and-list-of-buckets}

Returns information about the storage and a list of buckets.

A single request outputs a list that can contain up to 10,000 buckets. If there are more buckets, use additional requests with the [query parameter](#marker) `marker`.

To get additional information about buckets (size, update date, etc.), use the [query parameter](#format)`?format=json`.

#### Request example \{#get-storage-info-and-list-of-buckets-request-example}

```bash
curl \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>'
```

#### Response example \{#get-storage-info-and-list-of-buckets-response-example}

```
bucket1
bucket2
bucket3
```

### Manage storage metadata \{#manage-storage-metadata}

Sets, replaces, or deletes metadata passed in the request header.

#### Request headers \{#manage-storage-metadata-request-headers}

<CustomTable>
  <table>
    <tbody>
      <tr>
        <td>Header</td><td>Description</td>
      </tr>

      <tr>
        <td>X-Account-Meta-\<...></td><td>Storage metadata to be set, where \<...> is a custom header</td>
      </tr>

      <tr>
        <td>X-Remove-Account-Meta-\<...></td><td>Storage metadata required to be deleted, where \<...> is a custom header</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

#### Request example \{#manage-storage-metadata-request-example}

```bash
curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Account-Meta-<...>: anyheader' \
'https://<swift_domain>/v1/<project_id>'
```

#### Response example \{#manage-storage-metadata-response-example}

On success, the request returns a response with code 204.

## Buckets \{#buckets}

<CustomTable>
  <table>
    <tbody>
      <tr>
        <td>HEAD</td><td>/v1/ {'{project_id}'} /{'{bucket_name}'}</td><td>[Get bucket metadata](#get-bucket-metadata)</td>
      </tr>

      <tr>
        <td>GET</td><td>/v1/ {'{project_id}'} /{'{bucket_name}'}</td><td>[Get a list of objects and bucket metadata](#get-list-of-bucket-objects-and-metadata)</td>
      </tr>

      <tr>
        <td>PUT</td><td>/v1/ {'{project_id}'} /{'{bucket_name}'}</td><td>[Creating a bucket](#create-bucket)</td>
      </tr>

      <tr>
        <td>POST</td><td>/v1/ {'{project_id}'} /{'{bucket_name}'}</td><td>[Manage bucket metadata](#manage-bucket-metadata)</td>
      </tr>

      <tr>
        <td>DELETE</td><td>/v1/ {'{project_id}'} /{'{bucket_name}'}</td><td>[Remove a bucket](#delete-bucket)</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

### Get bucket metadata \{#get-bucket-metadata}

Displays bucket metadata, including the number of objects, storage volume (in bytes), and bucket headers.

#### Request example \{#get-bucket-metadata-request-example}

```bash
curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>'
```

#### Response example \{#get-bucket-metadata-response-example}

On success, the request returns a response with code 204.

### Get a list of objects and bucket metadata \{#get-list-of-bucket-objects-and-metadata}

Returns bucket metadata and displays a list of objects.

A single request outputs a list that can contain up to 10,000 objects. If there are more objects, use additional requests with the query parameters [`marker`](#marker) and [`limit`](#limit).

#### Request example \{#get-list-of-bucket-objects-and-metadata-request-example}

```bash
curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>'
```

#### Response example \{#get-list-of-bucket-objects-and-metadata-response-example}

On success, the request returns a response with code 200 or 204.

```
HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Type: text/plain
X-Container-Bytes-Used: 0
X-Container-Meta-Quota-Bytes: 52428800
X-Container-Meta-Quota-Count: 1000
X-Container-Meta-Type: public
X-Container-Object-Count: 1
X-Container-Storage-Policy-Index: 0
X-Container-Storage-Policy-Name: Policy-0
X-Openstack-Request-Id: 585ec880-d654-485f-949e-c0dc24926d00
X-Storage-Policy: Policy-0
X-Timestamp: 1688648194.11923
X-Trans-Id: 585ec880-d654-485f-949e-c0dc24926d00
X-Versions-Enabled: true
Date: Thu, 13 Jul 2023 15:13:53 GMT
Content-Length: 120
```

```
Object1
Object2
Object3
```

#### Response parameters \{#get-list-of-bucket-objects-and-metadata-response-parameters}

<CustomTable>
  <table>
    <tbody>
      <tr>
        <td>Parameter</td><td>Value</td>
      </tr>

      <tr>
        <td>X-Container-Object-Count</td><td>Number of objects in the bucket</td>
      </tr>

      <tr>
        <td>X-Container-Bytes-Used</td><td>Volume of objects in the bucket (in bytes)</td>
      </tr>

      <tr>
        <td>X-Container-Meta-Type</td><td>Bucket type</td>
      </tr>

      <tr>
        <td>X-Container-Meta-Quota-Bytes</td><td>Maximum storage capacity (in bytes)</td>
      </tr>

      <tr>
        <td>X-Container-Meta-Quota-Count</td><td>Maximum number of objects in the bucket</td>
      </tr>

      <tr>
        <td>X-Container-Meta-\<...></td><td>Bucket metadata, where \<...> is a custom header</td>
      </tr>

      <tr>
        <td>X-Versions-Enabled</td><td>Whether bucket versioning is enabled</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

### Create a bucket \{#create-bucket}

Creates a bucket with the parameters specified in the request.

#### Request headers \{#create-bucket-request-headers}

<CustomTable>
  <table>
    <tbody>
      <tr>
        <td>Header</td><td>Description</td>
      </tr>

      <tr>
        <td>X-Container-Meta-Type</td><td>public (public);<ul><li>private (private)</li><li>Bucket type:</li></ul></td>
      </tr>

      <tr>
        <td>X-Container-Meta-\<...></td><td>Bucket metadata. Specify {'\\\\<...>'} - metadata header</td>
      </tr>

      <tr>
        <td>X-Storage-Policy</td><td>Policy-0 (default) — standard storage;<ul><li>cold — cold storage</li><li>Storage class:</li></ul></td>
      </tr>

      <tr>
        <td>X-Versions-Enabled</td><td>Whether bucket versioning is enabled</td>
      </tr>

      <tr>
        <td>X-Container-Meta-Default-Delete-After</td><td>Retention period for all objects in the bucket (in seconds)</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

#### Request example \{#create-bucket-request-example}

```bash
curl -i -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Container-Meta-Type: public' \
-H 'X-Container-Meta-<...>: anyheader' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>'
```

#### Response example \{#create-bucket-response-example}

On success, the request returns a response with code 201.

```
HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html
X-Openstack-Requiest-Id: 0009ec57-2681-4b48-9105-71c57016edc6
X-Trans-Id: 0009ec57-2681-4b48-9105-71c57016edc6
```

### Manage bucket metadata \{#manage-bucket-metadata}

Sets, replaces, or deletes metadata passed in the request header.

#### Request headers \{#manage-bucket-metadata-request-header}

<CustomTable>
  <table>
    <tbody>
      <tr>
        <td>Header</td><td>Description</td>
      </tr>

      <tr>
        <td>X-Container-Meta-Type</td><td>public (public);<ul><li>private (private)</li><li>Bucket type:</li></ul></td>
      </tr>

      <tr>
        <td>X-Container-Meta-\<...></td><td>Bucket metadata to be set, where \<...> is a custom header</td>
      </tr>

      <tr>
        <td>X-Remove-Container-Meta-\<...></td><td>Bucket metadata required to be deleted, where \<...> is a custom header</td>
      </tr>

      <tr>
        <td>X-Versions-Enabled</td><td>Whether bucket versioning is enabled</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

#### Request example \{#manage-bucket-metadata-request-example}

Changing the bucket type:

```bash
curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Container-Meta-Type: private' \
-H 'X-Versions-Enabled: true' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>'
```

#### Response example \{#manage-bucket-metadata-response-example}

On success, the request returns a response with code 204.

### Remove a bucket \{#delete-bucket}

Removes a bucket in the storage. Before removing a bucket, remove all objects in it.

#### Request example \{#delete-bucket-request-example}

```bash
curl -i -XDELETE \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>'
```

#### Response example \{#delete-bucket-response-example}

On success, the request returns a response with code 204.

```
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: Text/html; charset=UTF-8
```

## Objects \{#objects}

<CustomTable>
  <table>
    <tbody>
      <tr>
        <td>GET</td><td>/v1/ {'{project_id}'} /{'{bucket_name}'} /{'{object_name}'}</td><td>[Get object](#get-object)</td>
      </tr>

      <tr>
        <td>PUT</td><td>/v1/ {'{project_id}'} /{'{bucket_name}'} /{'{object_name}'}</td><td>[Upload an object](#upload-object)</td>
      </tr>

      <tr>
        <td>POST</td><td>/v1/ {'{project_id}'}</td><td>[Delete multiple objects](#delete-several-objects)</td>
      </tr>

      <tr>
        <td>POST</td><td>/v1/ {'{project_id}'} /{'{bucket_name}'} /{'{object_name}'}</td><td>[Manage HTTP headers and object metadata](#manage-object-http-headers-and-metadata)</td>
      </tr>

      <tr>
        <td>COPY</td><td>/v1/ {'{project_id}'} /{'{bucket_name}'} /{'{object_name}'}</td><td>[Copy an object](#copy-object)</td>
      </tr>

      <tr>
        <td>DELETE</td><td>/v1/ {'{project_id}'} /{'{bucket_name}'} /{'{object_name}'}</td><td>[Delete an object](#delete-object)</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

### Get object \{#get-object}

Displays the body and headers of the object.

#### Request example \{#get-object-request-example}

```bash
curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>'
```

#### Response example \{#get-object-response-example}

On success, the request returns a response with code 200.

### Upload an object \{#upload-object}

Uploads an object to a bucket. Such an upload is used for objects up to 100 MB in size. For larger objects, use [segmented upload](#segmented-objects).

When using the `X-Copy-From` header, you can upload a copied object to a bucket. The object is copied along with the `X-Delete-At` header regardless of where the header was set (on the object or bucket).

#### Request headers \{#upload-object-request-headers}

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Header</th><th>Description</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>X-Delete-At</td><td>Object deletion time in Unix Timestamp format</td>
      </tr>

      <tr>
        <td>X-Delete-After</td><td>Object retention period (in seconds)</td>
      </tr>

      <tr>
        <td>Etag</td><td>Etag identifier</td>
      </tr>

      <tr>
        <td>X-Object-Meta-\<...></td><td>Object metadata, where \<...> is a custom header</td>
      </tr>

      <tr>
        <td>X-Copy-From</td><td>Path to the object to be copied</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

#### Request example \{#upload-object-request-example}

Upload an object:

```bash
curl -i -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Delete-After: 180' \
-d "@<object_body>" \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>'
```

Specify:

* `<object_body>` — object body;
* `<object_name>` — the name that will be assigned to the object.

Copy an object:

```bash
curl -i -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Copy-From: /<bucket_name_1>/<object_name_1>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name_2>/<object_name_2>'
```

Specify:

* `<bucket_name_2>` — the bucket to which the object will be copied;
* `<object_name_2>` — the name with which the object will be copied;
* `<bucket_name_1>` — the bucket where the object being copied is located;
* `<object_name_1>` — the object that needs to be copied.

#### Response example \{#upload-object-response-example}

When uploading an object, on success, the request returns a response with code 201.

```
HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html
Etag: b65ad34618e410d9d8bf624d61f8a980
Date: Thu, 15 Mar 2023 07:31:32 GMT
```

When copying an object, on success, the request returns a response with code 201.

```
HTTP/1.1 201
Created etag: 0f343b0931126a20f133d67c2b018a3b
X-Copied-From: bucket_name_1/object_name_1
X-Copied-From-Last-Modified: Mon, 27 May 2013 13:16:49 GMT
Last-Modified: Tue, 28 May 2018 06:30:51 GMT
```

### Delete multiple objects \{#delete-several-objects}

Removes multiple objects simultaneously, including objects from different buckets. Objects are removed sequentially.

#### Request example \{#delete-several-objects-request-example}

Removing objects from different buckets:

```bash
curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'Content-Type: text/plain' \
-d $'<bucket_name_1>/<object_name_1>\n<bucket_name_2>/<object_name_2>' \
'https://<swift_domain>/v1/<project_id>?bulk-delete=true&format=json'
```

Specify:

* `<bucket_name_1>/<object_name_1>` — path to the object in the first bucket;
* `<bucket_name_2>/<object_name_2>` — path to the object in the second bucket;
* `\n` — line break, must be specified between objects.

#### Response example \{#delete-several-objects-response-example}

On success, the request returns a response with code 200.

```
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 08 Jun 2018 13:37:53 GMT
Content-Length: 101
{'Number Not Found':0,'Response Status':'200 OK','Response Body':'','Errors':null,'Number Deleted':2}
```

### Manage HTTP headers and object metadata \{#manage-object-http-headers-and-metadata}

Sets values for custom and HTTP headers specified in the request. Headers are used to control caching on both the client side and intermediate proxy servers.

Supported HTTP headers:

* `Cache-Control`
* `Content-Encoding`
* `Content-Type`
* `Content-Disposition`
* `Link`

#### Request headers \{#manage-object-http-headers-and-metadata-request-headers}

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Header</th><th>Description</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>X-Container-Meta-\<...></td><td>Header whose parameters need to be set. Specify \<...> — header (e.g., X-Container-Meta-Cache-Control).</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

#### Request example \{#manage-object-http-headers-and-metadata-request-example}

Adding the `Link` header to an object:

```bash
curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'Link: rel=canonical' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>'
```

Adding a custom header:

```bash
curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Object-Meta-Some: metadata' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>'
```

#### Response example \{#manage-object-http-headers-and-metadata-response-example}

A request to add the `Link` header returns a response with code 202 on success.

```
HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html
```

On success, the request to add a custom header returns a response with code 201.

```
HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html
Etag: d41d8cd98f00b204e9800998ecf8427e
```

### Copy an object \{#copy-object}

The object will be copied to another bucket or to a different prefix. If the `X-Fresh-Metadata` header is set to `true`, then upon copying, a new object will be created with new headers, including ones without `X-Delete-At`.

#### Request headers \{#copy-object-request-headers}

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Header</th><th>Description</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Destination</td><td>Path where the object will be copied</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

#### Request example \{#copy-object-request-example}

```bash
curl -i -XCOPY \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'Destination: /<bucket_name_2>/<object_name_2>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name_1>/<object_name_1>'
```

Specify:

* `<bucket_name_1>` — the bucket where the object being copied is located;
* `<object_name_1>` — the object that needs to be copied.
* `<bucket_name_2>` — the bucket to which the object will be copied;
* `<object_name_2>` — the name with which the object will be copied.

#### Response example \{#copy-object-response-example}

On success, the request returns a response with code 201.

```
HTTP/1.1 201
Created etag: 0f343b0931126a20f133d67c2b018a3b
X-Copied-From: bucket1/file
X-Copied-From-Last-Modified: Mon, 27 May 2013 13:16:49 GMT
Last-Modified: Tue, 28 May 2013 06:30:51 GMT
```

### Delete an object \{#delete-object}

The object will be removed from the bucket.

To remove a segmented object, use the query parameter `?multipart-manifest=delete` — the object segments and the manifest will be removed.

#### Request example \{#delete-object-request-example}

```bash
curl -i -XDELETE \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>'
```

#### Response example \{#delete-object-response-example}

On success, the request returns a response with code 204.

```
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
```

#### Headers for delayed deletion \{#delete-object-headers-for-delayed-deletion}

Headers are specified when sending PUT and POST requests and determine when the object will be automatically deleted from the storage.

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Header</th><th>Value</th><th>Description</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>X-Delete-At</td><td>Timestamp value in Unix Epoch format (seconds)</td><td>The server will store the object until the time passed in the header. To convert it into a human-readable format, you can use [EpochConverter](https://www.epochconverter.com/).</td>
      </tr>

      <tr>
        <td>X-Delete-After</td><td>Integer number of seconds</td><td>The server converts this value into the X-Delete-At header. After the specified number of seconds, the request will begin returning a 404 response for the object, and the objects are automatically deleted after some time.</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

If both headers are specified, the `X-Delete-After` header takes priority.

Header operation features:

* if the object is uploaded using a PUT request with the `X-Delete-At` header, and the bucket has a modified header, the object header will be overwritten by the bucket header;
* if versioning is enabled in the bucket, the `X-Delete-At` and `X-Delete-After` headers are not carried over to the created version. The uploaded version will not be removed, but the object will disappear from the list.

## Segmented objects \{#segmented-objects}

There are no size restrictions on uploaded objects in the storage, but it is not recommended to place objects larger than 100 MB into the storage in one piece — you should break the object into segments, upload each segment of the object, and upload a manifest file that unites all segments of the object (DLO/SLO technology). More details on uploading segmented objects in the documentation guide [Upload an object](/s3/objects/upload-object/#segmented-upload).

When using segmented upload, you can upload two types of large objects:

* dynamic (DLO), when uploading a dynamic object manifest, you need to specify the bucket and segment prefix. You can upload and remove individual segments without needing to change the manifest file;
* static (SLO), when uploading a static object manifest, specify the path to each segment of which the object consists. Each time segments are changed, you must edit and upload the manifest file again. Optionally, for segments, you can specify their checksums (Etag) and size.

To get the manifest file, perform a [GET request to retrieve the object](#get-object) with the query parameter `?multipart-manifest=get`.

You can remove all segments and the object with the manifest using a [DELETE request](#delete-object) with the query parameter `?multipart-manifest=delete`.

### Upload object segments \{#upload-object-segments}

We recommend uploading segments first, and then creating or updating the manifest. Until all segments are uploaded, the object will not be available for download.

#### Request examples \{#segmented-objects-request-example}

```bash
curl -i -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-d "hello " \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>/00000001'

curl -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-d "world" \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>/00000002'

curl -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-d "!" \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>/00000003'
```

#### Response example \{#segmented-objects-response-example}

On success, the requests return responses with code 201.

### Upload a dynamic object manifest \{#upload-dynamic-object-manifest}

#### Request example \{#upload-dynamic-object-manifest-request-example}

```bash
curl -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Object-Manifest: <bucket_name>/<object_name>/' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>'
```

#### Response example \{#upload-dynamic-object-manifest-response-example}

On success, the request returns a response with code 201.

### Upload a static object manifest \{#upload-static-object-manifest}

#### Request example \{#upload-static-object-manifest-request-example}

In the body of the static object manifest, specify the path to each object segment.

```bash
curl -XPUT \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Static-Large-Object: True' \
-d "[{"path": "/<bucket_name>/<object_name>/00000001"}, {"path": "/<bucket_name>/<object_name>/00000002"}, {"path": "/<bucket_name>/<object_name>/00000003"} ...]" \
'https://<swift_domain>/v1/<project_id>/<bucket_name>/<object_name>?multipart-manifest=put'
```

#### Response example \{#upload-static-object-manifest-response-example}

On success, the request returns a response with code 201.

## Limits \{#limits}

<CustomTable>
  <table>
    <tbody>
      <tr>
        <td>POST</td><td>/v1/ {'{project_id}'} /{'{bucket_name}'}</td><td>[Set bucket limits](#set-bucket-limits)</td>
      </tr>

      <tr>
        <td>POST</td><td>/v1/ {'{project_id}'}</td><td>[Set project limits](#set-project-limits)</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

### Set bucket limits \{#set-bucket-limits}

Sets restrictions on a bucket, passed in the `X-Container-Meta-Quota-Bytes` and `X-Container-Meta-Quota-Count.` headers.

#### Request headers \{#set-bucket-limits-request-headers}

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Header</th><th>Description</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>X-Container-Meta-Quota-Bytes</td><td>Maximum storage capacity (in bytes)</td>
      </tr>

      <tr>
        <td>X-Container-Meta-Quota-Count</td><td>Maximum number of objects in the bucket</td>
      </tr>

      <tr>
        <td>X-Container-Meta-Default-Delete-After</td><td>Retention period for all objects in the bucket (in seconds). After this period, objects will be automatically removed</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

#### Request example \{#set-bucket-limits-request-example}

```bash
curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Container-Meta-Quota-Bytes: 52428800' \
-H 'X-Container-Meta-Quota-Count: 1000' \
-H 'X-Container-Meta-Default-Delete-After: 300' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>'
```

#### Response example \{#set-bucket-limits-response-example}

On successful request execution, a response with code 202 will be returned.

```
HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html
```

### Set project limits \{#set-project-limits}

Sets a restriction on a project, passed in the `X-Account-Meta-Quota-Bytes.` header.

#### Request headers \{#set-project-limits-request-headers}

<CustomTable>
  <table>
    <thead>
      <tr>
        <th>Header</th><th>Description</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>X-Container-Meta-Quota-Bytes</td><td>Maximum storage capacity (in bytes)</td>
      </tr>
    </tbody>
  </table>
</CustomTable>

#### Request example \{#set-project-limits-request-example}

```bash
curl -i -XPOST \
-H 'X-Auth-Token: <x_auth_token>' \
-H 'X-Account-Meta-Quota-Bytes: 52428800' \
'https://<swift_domain>/v1/<project_id>'
```

#### Response example \{#set-project-limits-response-example}

On successful request execution, a response with code 202 will be returned.

```
HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html
```

## Additional query parameters \{#additional-query-parameters}

In a request to [get a list of buckets](#get-list-of-bucket-objects-and-metadata) or [objects](#get-object), you can use additional query parameters.

### format \{#format}

Returns a list of objects in a specific format.

Request example:

```bash
curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>?format=json'
```

The list of objects will be returned in JSON format.

### limit \{#limit}

Sets the exact number of objects that will be included in the list (for example, when working with buckets that store a large number of objects).

Request example:

```bash
curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>?limit=20'
```

The first 20 objects will be included in the list.

### marker \{#marker}

Sets the object from which the list will be displayed.

Request example:

```bash
curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>?marker=<object_name>'
```

The list will display objects that follow the object `<object_name>`.

### prefix \{#prefix}

Includes objects in the list whose names start with the specified sequence of characters.

Request example:

```bash
curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>?prefix=my'
```

The list will display objects that start with the characters `my`.

### delimiter \{#delimiter}

S3 has a flat structure and does not support folders, but with the `delimiter` parameter, you can display a pseudo-hierarchy. A request with this parameter will return only the part of the object name that precedes the specified characters, if they are present in the object name output.

Request example:

```bash
curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>?delimiter=/'
```

Files and parts of prefixes (pseudo-folders) at the top level will be displayed:

```
photos/
videos/
file.jpg
```

Where:

* `photos/`, `videos/` — prefix parts up to the `/` character, which are present in the objects in the bucket;
* `file.jpg` — file without a prefix (the `/` character in the name).

The `delimiter` parameter can be used together with the `prefix` parameter to output a list of objects and pseudo-folders by the specified prefix.

Request example:

```bash
curl -i \
-H 'X-Auth-Token: <x_auth_token>' \
'https://<swift_domain>/v1/<project_id>/<bucket_name>?prefix=photos/&delimiter=/'
```

Output example:

```
photos/animals/
photos/file.jpg
```

## Symbolic links \{#symbolic-links}

A symbolic link is an empty object that points to another object. They can be used to access objects in another bucket:

* with a different storage policy — for example, to access an object in a cold storage bucket from a standard storage bucket;
* with a different type — for example, to access an object in a private bucket through a symbolic link placed in a public bucket.

You can create a symbolic link with an empty [PUT request to upload an object](#upload-object) with the `X-Symlink-Target: <bucket_name>/<object_name>.` header;.

By default, symbolic links are dynamic — they point to an object by its name. A symbolic link can be made static: when following the link, the Etag of the object is additionally checked. To do this, add the header `X-Symlink-Target-Etag: <etag>` to the request;.

If the symbolic link object is not empty, the request will return response 400.

To get an object with a symbolic link, perform a GET or HEAD request with the `?symlink=get.` parameter.