Object Storage (old)
The URL and methods of this Object Storage API version will be supported until 15.09.2026. After 15.09.2026, they will be disabled.
We recommend using the new version of the Object Storage API; for details, see the Configuring S3 after update guide.
S3 allows developers to integrate the storage with their own applications and websites. Interaction with the storage is organized via a REST API. This documentation describes the currently available Storage REST API calls, along with request and response formats. Currently, REST API requests can be used to perform the following operations:
- create links that allow third-party users to upload files to the storage;
- work with file versions;
- create users and set access permissions for them;
- download and decompress archives;
- work with special pages, etc.
Authorization methods and instructions for obtaining an API token are described in the Authorization and getting a token section of the Swift API (old) guide.
Limitations for additional users
Additional users have limitations when using the API, so the following actions must be performed by the primary S3 user:
- creating a bucket;
- deleting multiple files (using
?bulk-delete=true); - creating or modifying users;
- working with domains and custom SSL certificates;
- purging the CDN cache;
- obtaining logs;
- creating temporary tokens (
/temptokens).
Bucket operations
Creating an image gallery
Request parameters
Request example
curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/container -H "X-Auth-Token: $token" -H "X-Container-Metatype: gallery"
If the request is successful, the API returns a response with code 204.
Response example
HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers:
Downloading a bucket as a zip archive
The contents of any bucket can be downloaded as a zip archive. To do this, add the query parameter download-all-as-zip=[archive name] to the link to your bucket, for example:
wget https://api.selcdn.ru/v1/SEL_*****/container_name/?download-all-as-zip=container_name.zip
In public buckets, the zip archive download feature is disabled by default. To enable it, you must set the X-Container-Meta-Allow-ZipDownload: true header, for example:
curl -i -XPUT https://api.selcdn.ru/v1/SEL_***/container_name -H "X-Auth-Token: $token" -H "X-Container-Meta-Allow-ZipDownload: true"
The value of this X-Container-Meta-Allow-ZipDownload header is ignored in private buckets.
To download the content of any public bucket as a zip archive, the following commands can be used:
curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container?download-all-as-zip=test.zip -o name.zip
To download the content of any private bucket as a zip archive, the following commands can be used:
curl -i -XGET https://api.selcdn.ru/v1/SEL_*****/container?download-all-as-zip=test.zip -H "X-Auth-Token: $token" -o name.zip
To view the contents of the downloaded archive, use the following command:
unzip -l name.zip
Archive: name.zip
warning [name.zip]: 274 extra bytes at beginning or within zipfile (attempting to process anyway)
Length Date Time Name
--------- ---------- ----- ----
555436 1980-00-00 00:00 IMG_20180802_121146.jpg
39 1980-00-00 00:00 copied_file
245473 1980-00-00 00:00 mergetree.pdf
--------- -------
800948 3 files
This operation is primarily intended for ease of downloading, not for traffic saving, so files in the archive are not compressed.
The number of objects in a single bucket must not exceed 10,000, otherwise the command will fail and return an error.
You can download objects starting with a specific prefix (e.g., IMG) as a zip archive by specifying the prefix IMG in the IMG?download-all-as-zip parameter:
curl -i -XGET https://*****.selcdn.ru/container/?IMG?download-all-as-zip=test.zip -H "X-Auth-Token: $token" -o name.zip
Note: if a folder starts with this prefix, it will also be downloaded along with all its contents.
Downloading a folder as a zip archive
The contents of any folder can be downloaded as a zip archive. To do this, add the query parameter download-all-as-zip=[archive name] to the link to the folder, for example:
wget https://api.selcdn.ru/v1/SEL_*****/container_name/folder/?download-all-as-zip=container_name.zip
To download the content of any folder as a zip archive, the following commands can be used:
curl -i -XGET https://*****.selcdn.ru/container/folder?download-all-as-zip=test.zip -H "X-Auth-Token: $token" -o name.zip
To view the contents of the downloaded archive, use the following command:
unzip -l name.zip
Archive: name.zip
warning [name.zip]: 274 extra bytes at beginning or within zipfile (attempting to process anyway)
Length Date Time Name
--------- ---------- ----- ----
555436 1980-00-00 00:00 IMG_20180802_121146.jpg
39 1980-00-00 00:00 copied_file
245473 1980-00-00 00:00 mergetree.pdf
--------- -------
800948 3 files
This operation is primarily intended for ease of downloading, not for traffic saving, so files in the archive are not compressed.
The number of objects in a single folder must not exceed 10,000, otherwise the command will fail and return an error.
Working with files
Extracting archives
Archives in *.tar, *.tar.gz, and *.gzip formats can be extracted immediately after uploading to the storage. To extract an archive, add the query parameter extract-archive to the file upload request:
curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/new_container/archive.tar.gz/?extract-archive=tar.gz \
-H "X-Auth-Token: $token" -T "archive.tar.gz"
Creating a symbolic link to a file
When using storage as a backend for public services, it is often necessary to restrict access to files — for example, to make files placed in a private bucket available to a wide range of users.
Storage provides the ability to create symbolic links for such cases. Such links can be password-protected, and you can also set an expiration date for them.
Request example
curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/new_container/new_link \
-H "X-Auth-Token: $token" -H "Content-Type: x-storage/symlink" \
-H "X-Object-Meta-Location: /new_container/new_object" \
-H "X-Object-Meta-Link-Key: $key" -H "Content-Length: 0"
Response example
HTTP/1.1 201 Created
> etag: d41d8cd98f00b204e9800998ecf8427e
> Last-Modified: Mon, 27 May 2013 13:34:34 GM
Python X-Object-Meta-Link-Key generation example
import hashlib
# location of file, always with container specified
location = "/container/object"
# password
password = "12345"
# concatenate password + location and encode it
encoded_pass_loc = (password + location).encode('utf-8')
# generate sha1-hash
hash_object = hashlib.sha1(encoded_pass_loc)
# convert sha1-hash to hexadecimal digits
link_key = hash_object.hexdigest()
# show calculated value
print(link_key)
Creating a file download link
You can create special links that allow third-party users to download your files (including from private buckets). You do not need to make an API request to create such a link. Before generating links to account files, you need to manually set a secret key $key:
curl -i -XPOST http://*****.selcdn.ru/ -H "X-Auth-Token: $token" -H "X-Account-Meta-Temp-URL-Key: $key"
To create a link to a specific bucket, set a secret key $key by adding the bucket name:
curl -i -XPOST http://*****.selcdn.ru/container -H "X-Auth-Token: $token" -H "X-Container-Meta-Temp-URL-Key: $key"
Only users who are aware of the secret key will be able to access files using the generated link.
Python example
import hmac
from hashlib import sha1
from time import time
# access method (always GET)
method = "GET"
# reference valid 60 seconds
expires = int(time()) + 60
# the path to the file in the repository, always with the container specified
path = "/container/dir/file"
# secret key
link_secret_key = str.encode("$key")
# generate access key
hmac_body = str.encode('%s\n%s\n%s' % (method, expires, path))
# access key
sig = hmac.new(link_secret_key, hmac_body, sha1).hexdigest()
#show calculated values
print(sig,expires)
When using a link in the form of https://api.selcdn.ru/v1/SEL_ * **/container_name/object_name in the script above, the path variable should be in the form of /v1/SEL_ ***/container_name/object_name.
The key obtained as a result must then be specified in the link:
http://****.selcdn.ru/container/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=13909142
where:
* ****.selcdn.ru— base domain;temp_url_sig— access key;temp_url_expires— expiration time of the link (unixtime).
If a domain is attached to a bucket, it can be specified in the link. In this case, you do not need to specify the bucket name:
http://my.domain/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227
Management of the Content-Disposition header for data sent via links is supported. To do this, add the filename parameter with the corresponding value:
http://*****.selcdn.ru/container/dir/file?temp_url_sig=3f512dfed32111d6e742afc5522076c0621951cc&temp_url_expires=1390914227&filename=Other+file+name.doc
The secret key can be changed. After changing the secret key, all previously generated links will stop working.
Node.js example
const crypto = require('crypto');
// access method (always GET)
const method = 'GET';
// reference valid 60 seconds
const expires = Math.floor(Date.now() / 1000) + 60;
// the path to the file in the repository, always with the container specified
const path = '/container/dir/file';
// secret key
const linkSecretKey = '$key';
// generate access key
const hmacBody = `${method}\n${expires}\n${path}`;
// access key
const sig = crypto.createHmac('sha1', linkSecretKey).update(hmacBody).digest('hex');
// show calculated values
console.log(sig);
console.log(expires);
Creating a link for uploading files (sendmefile)
Request example
curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/container/upload \
-H "X-Auth-Token: $token" -H "Content-Type: x-storage/sendmefile+inplace" \
-H "X-Object-Meta-Sendmefile-Max-Size: 52428800" \
-H "X-Delete-After: 14400" \
-H "X-Object-Meta-Sendmefile-Secret: 5baa61e4c9b93f3f0682250b6cf8331b7ee68" \
-d "Helper text for upload page"
Versioning
Storage provides support for versions so that you can store not only the latest version of an object but also several previous ones.
Before you start working with versioning, create a bucket to store the versions.
When an object is deleted, the last working version is not returned to its place. All versions of the object, including the one that was there before deletion, are stored in the bucket for versions.
Request parameters
Request example
curl -i -XPUT https://api.selcdn.ru/v1/SEL_*****/container1/ -H "X-Auth-Token: $token" -H "X-Versions-Location: container2"
If the request is successfully completed, a response with code 202 will be returned.
Response example
HTTP/1.1 202 Accepted Content-Length: 76
Content-Type: text/html; charset=UTF-8
Access-Control-Allow-Origin: * Access-Control-Expose-Headers: Expires: 0 Pragma: no-cache
Cache-Control: no-cache, no-store, must-revalidate
Special pages
Special pages include:
- an index page returned in response to an anonymous GET request to a bucket or a folder placed in that bucket;
- an error page (404) — a file returned during an anonymous GET request to a non-existent object.
Index page
Request parameters
You can specify either an absolute or relative path to the file in the request.
Request example
Create an index file:
echo "<html>custom_index_file</html>" > my_index.html
curl -i -XPUT "https://api.selcdn.ru/v1/SEL_*****/container_name/my_index.html" -H "X-Auth-Token: $token" -T "./my_index.html"
To set the index page, set the Web-Index value for the bucket:
curl -i -XPUT "https://api.selcdn.ru/v1/SEL_*****/container_name/my_index.html" \
-H "X-Auth-Token: $token" -H "X-Container-Meta-Web-Index:/my_index.html"
404 page
Request parameters
Examples
Available template parameters
To pass information about the originally requested file, you can use special template parameters:
- {container} — bucket name;
- {path} — path to the requested file relative to the bucket.
By default, redirection is performed with code 307. Available options: 200, 307, 404. When setting an external link, only code 307 can be set.
Request example
Set the Web-404-Page value for the bucket:
curl -i -XPOST "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Web-404-Page: /404.html?file={path}"
Upon an anonymous request for a non-existent object, redirection to the specified file occurs:
curl -i "https://api.selcdn.ru/v1/SEL_*****/container_name/non_existing_object" \
> HTTP/1.1 307 Temporary Redirect
> Location: https://api.selcdn.ru/v1/SEL_*****/404.html?file=non_existing_object
By default, when sending an error page, code 404 is returned:
curl -i -XPOST "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Web-404-Page: /404.html?file={path}?{code}"
File listing
Request parameters
Request example
curl -i -XPOST "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Web-Listings: on"
To receive file listing via an anonymous request, enter:
curl -i -XGET "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Web-Mode: listing"
To receive a listing of a private bucket, specify the token of a user who has access to the bucket:
curl -i -XGET "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" -H "X-Web-Mode: listing"
For output in HTML format, you can define the design using the X-Container-Meta-Web-Listings-Css header, the value of which is the link to the style file in the bucket; you can also provide a link to an external style file.
Setting the Web-Listings-CSS value for the bucket:
curl -i -XPOST "https://api.selcdn.ru/v1/SEL_*****/container_name" -H "X-Auth-Token: $token" \
-H "X-Container-Meta-Web-Listings-Css: my_style.css"
User management
Viewing the user list
Request parameters
Request example
curl -i https://api.selcdn.ru/v1/users -H "X-Auth-Token: $token"
If the request is successful, the API returns a response with code 200.
Response example
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: text/plain; charset=utf-8
Content-Length: 80
main_user (true)
main_user (true)
user1 (true)
user2 (true)
user3 (true)
Adding a new user
Request parameters
Request example
curl -i -XPUT https://api.selcdn.ru/v1/users/my_test_user
-H "X-Auth-Token: $token"
-H "X-Auth-Key: $key"
-H "X-User-ACL-Containers-W: container1, container2, container3"
-H "X-User-ACL-Containers-R: container4"
-H "X-User-S3-Password: yes"
-H "X-User-Active: on"
If the request is successfully completed, the API returns a response with code 204.
Response example
HTTP/2 204 Created
access-control-allow-origin: *
Content-Type: text/html; charset=UTF-8
Content-Length: 0
Deleting a user
Request parameters
Request example
curl -i -X DELETE https://api.selcdn.ru/v1/users/my_test_user -H "X-Auth-Token: $token"
If the user is successfully deleted, the API returns a response with code 204.
Response example
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Date: Mon, 19 Mar 2018 10:04:25 GMT
Changing the primary user password
Request parameters
Request example
curl -i -XPOST https://api.selcdn.ru/v1/users -H "X-Auth-Token: $token" -H "X-Auth-Key: $key"
If the request is successfully completed, the API returns a response with code 204.
Response example
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Date: Mon, 19 Mar 2018 10:30:59 GMT
Domain management
Domains can be attached to buckets in the storage. All operations with domains are performed via the API.
Default domains
Each S3 user automatically receives a set of default domains that can be used to access objects in any bucket:
- *****.selcdn.ru — domain for public access to files in the storage;
- *****.selcdn.com — domain for distributing files via CDN over http.
Getting the list of attached domains
Request parameters
Request example
curl -i -XGET https://api.selcdn.ru/v1/domains -H "X-Auth-Token: $token"
If the request is successfully completed, the API returns a response with code 200.
Response example
HTTP/1.1 200 OK
Content-Length: 69
Content-Type: text/html
Date: Mon, 16 May 2016 07:36:35 GMT
Base Domains:
00000.selcdn.ru
00000.selcdn.com
Containers Domains:
container1 domain1.ru
container2 domain1.ru
Attaching a domain
Request parameters
Request example
curl -i -XPOST https://api.selcdn.ru/v1/SEL_*****/container -H "X-Add-Container-Domains: domain1.ru" -H "X-Auth-Token: $token"
If the request is successfully completed, the API will return a response with code 204.
Response example
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Date: Tue, 20 Mar 2018 12:09:38 GMT
Deleting a domain
Request parameters
Request example
curl -i -XPOST https://api.selcdn.ru/v1/SEL_*****/container -H "X-Remove-Container-Domains: domain1.ru" -H "X-Auth-Token: $token
If the request is successfully completed, the API returns a response with code 204.
Response example
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Editing the domain list
Request parameters
Request example
curl -i -XPOST https://api.selcdn.ru/v1/SEL_*****/container -H "X-Container-Domains: domain1.ru" -H "X-Auth-Token: $token"
If the request is successfully completed, the API returns a response with code 204.
Response example
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Backend-Timestamp, Etag, Last-Modified, X-Object-Manifest, X-Timestamp
Content-Type: text/plain; charset=utf-8
X-Content-Type-Options: nosniff
Managing custom SSL certificates
Getting the certificate list
Request parameters
Request example
curl -i -XGET https://api.selcdn.ru/v1/ssl -H "X-Auth-Token: $token"
Getting certificate information
Request parameters
Request example
curl -i -XGET https://api.selcdn.ru/v1/ssl/cert -H "X-Auth-Token: $token"
Adding a certificate
Request parameters
Request example
curl -i -XPUT https://api.selcdn.ru/v1/ssl/*****_cert1 -H "X-Auth-Token: $token" -T ./cert1.pem
Certificate Name ({cert_name}) should be passed in the format * *****_cert1, where the first part (digits) represents the user account number, and the second — any arbitrary combination of characters.
Certificate names must be unique; it is impossible to upload two certificates with the same name.
The certificate and private key itself must be passed in the request body in a single file.
Deleting a certificate
Request parameters
Storage cache purge
Request parameters:
- Request type — POST;
- URI —
https://api.selcdn.ru/v1/storage/purge; - Headers — authorization token X-Auth-Token;
- Description — purges the S3 cache for pages whose addresses were passed in the request.
Request example:
curl -i -XPOST https://api.selcdn.ru/v1/storage/purge -H "x-auth-token: $token" -d '{"objects":["https://example.domain.ru/test_purge/file","https://example2.domain.ru/test_purge/file2"]}'
If the request is successfully completed, the API returns a response with code 200.
Response example:
HTTP/2 200
content-type: application/json
date: Fri, 27 Aug 2021 13:00:42 GMT
content-length: 66
{"HttpStatus":201,"Detail":"Request accepted.","RejectedUrls":{}}
Getting logs
Request to create an export
Request parameters
Request body:
{
"since": "2019-05-14T06:00:00",
"till": "2019-12-09T13:43:00",
"fields": [
"container_name"
],
"filters": {
"host": [
"example.com",
"foo.bar.baz"
]
},
"container": "logs",
"delete_after": 3600
}
Description of request body fields:
- since — start of the period for export;
- till — end of the period for export;
- fields — list of required fields;
- filters — filters for export;
- container — bucket for export;
- delete_after — deletion of objects with logs after a specified time.
List of possible fields (fields):
- container_name
- timestamp
- host
- server_to_client_bytes
- client_to_server_bytes
- http_method
- status
- path
- query
- client_ip
List of possible filters (filters):
- host
- container_name
Request example
curl -i -XPOST -H 'X-Auth-Token: $token' -d '{"since": "2019-05-14T06:00:00","till": "2019-12-09T13:43:00", "fields": ["container_name"], "filters": {"host": ["example.com", "foo.bar.baz"]}, "container": "logs", "delete_after": 3600}' 'https://api.selcdn.ru/v1/logs'
If the request is successfully completed, the API returns a response with code 200.
Response example
HTTP/1.1 201 Created
Access-Control-Allow-Origin: *
Content-Length: 342
Content-Type: application/json
Date: Tue, 14 Jan 2020 13:01:34 GMT
{
"task": {
"id": "896aae80-bc7e-434d-8528-5ca2bfb41a56",
"created": "2020-01-14T13:01:34",
"updated": "2020-01-14T13:01:34",
"type": "storage_logs",
"data": {
"since": "2019-05-14T06:00:00",
"till": "2019-12-09T13:43:00",
"provider": "storage_access",
"container": "logs",
"fields": ["container_name"],
"filters": {"host": ["example.com", "foo.bar.baz"]},
"delete_after": 3600
},
"status": 0,
"progress": 0
}
}
Getting information about a created task
Request parameters
Request example
curl -i -XPOST -H 'X-Auth-Token: $token' -d '{"since": "2019-05-14T06:00:00","till": "2019-12-09T13:43:00", "fields": ["container_name"], "filters": {"host": ["example.com", "foo.bar.baz"]}, "container": "logs", "delete_after": 3600}' 'https://api.selcdn.ru/v1/logs'
Response example
{
"task": {
"id": "896aae80-bc7e-434d-8528-5ca2bfb41a56",
"created": "2020-01-14T13:01:34",
"updated": "2020-01-14T13:01:45",
"type": "storage_logs",
"data": {
"till": "2019-12-09T13:43:00",
"since": "2019-05-14T06:00:00",
"fields": ["container_name"],
"filters": {"host": ["example.com", "foo.bar.baz"]},
"provider": "storage_access",
"container": "logs",
"delete_after": 3600
},
"status": 2,
"progress": 100
}
}