Objects

Basic Operations with Objects

ListObjectsV2

get

/{Bucket}?list-type=2

Retrieves a partial or complete list (with a maximum of 1000 objects per request) from a specified bucket. The request parameters can serve as selection criteria to filter and return a subset of objects from the bucket.

A 200 OK response can contain either valid or invalid XML, so it's crucial to construct your application in such a way that it can correctly parse and handle the response content. In the resulting list, objects are organized in ascending order according to their key names.

Permissions

You must be the contract owner or an administrator to perform this operation. If not, they can grant you permission to perform the s3:ListBucket operation using Bucket Policy.

Authorizations

AuthorizationstringRequired

IONOS CLOUD Object Storage API requests are authenticated using the AWS signature. The IONOS CLOUD Object Storage API authenticates users using a customized HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code). The process of generating the proper Authorization header is somewhat involved. We recommend that you make use of a tool such as Postman.

In the Authorization tab for a request, select AWS Signature from the Type dropdown list. Specify where Postman should append your authorization data using the Add authorization data to drop-down menu.

If you select Request Headers, Postman populates the Headers tab with Authorization and X-Amz- prefixed fields.
If you select Request URL, Postman populates the Params tab with authentication details prefixed with X-Amz-.

Note: The parameters listed below contain confidential information. We recommend using variables to keep this data secure while working in a collaborative environment.

For Access Key, enter your access key directly in the fields or through variables for added security.
For Secret Key, enter your secret key directly in the fields or through variables for added security.

Advanced fields are optional, but Postman will attempt to generate them automatically if necessary.

For AWS Region, enter one of the regions (eu-central-3) where your bucket is hosted.
For Service Name, enter s3. The name of the service that receives the requests.
For Session Token, leave the field blank. This is only required when temporary security credentials are used.

Path parameters

Bucketstring · min: 3 · max: 63Required

The bucket name.

Example: my-bucket

Query parameters

list-typestring · enumRequiredPossible values:

delimiterstringOptional

A delimiter is a character you use to group keys.

Example: /

encoding-typestring · enumOptional

Requests IONOS CLOUD Object Storage to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that IONOS CLOUD Object Storage encode the keys in the response.

Possible values:

max-keysinteger · min: 1 · max: 1000Optional

Sets the maximum number of keys returned in the response. By default the operation returns up to 1000 key names. The response might contain fewer keys but will never contain more.

Default: 1000

prefixstring · max: 1024Optional

Limits the response to keys that begin with the specified prefix.

Example: folder/subfolder/

continuation-tokenstringOptional

ContinuationToken indicates IONOS CLOUD Object Storage that the list is being continued on this bucket with a token. ContinuationToken is obfuscated and is not a real key.

fetch-ownerboolean · enumOptional

The owner field is not present in listV2 by default, if you want to return owner field with each key in the result then set the fetch owner field to true.

Default: falsePossible values:

start-afterstringOptional

StartAfter is where you want to start listing from. IONOS CLOUD Object Storage starts listing after this specified key. StartAfter can be any key in the bucket.

Responses

200

Successul operation

application/xml

403

AccessDenied or Forbidden

application/xml

404

NoSuchBucket

application/xml

get/{Bucket}?list-type=2

GET /{Bucket}?list-type=2?list-type=2 HTTP/1.1
Host: s3.eu-central-3.ionoscloud.com
Authorization: YOUR_API_KEY
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>my-bucket</Name>
    <Prefix></Prefix>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>my-image-1.png</Key>
        <LastModified>2024-02-15T16:43:41.459Z</LastModified>
        <ETag>&quot;d41d8cd98f00b204e9800998ecf8427e&quot;</ETag>
        <Size>0</Size>
        <StorageClass>STANDARD</StorageClass>
        <Type>Normal</Type>
    </Contents>
    <Contents>
        <Key>my-image-2.png</Key>
        <LastModified>2024-03-13T15:53:14.199Z</LastModified>
        <ETag>&quot;994e15aa13aa642f3d82801c8f57b81b&quot;</ETag>
        <Size>2797180</Size>
        <StorageClass>STANDARD</StorageClass>
        <Type>Normal</Type>
    </Contents>
    <KeyCount>2</KeyCount>
</ListBucketResult>

ListObjects

get

/{Bucket}

Returns some or all (up to 1,000) of the objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket. A 200 OK response can contain valid or invalid XML. Be sure to design your application to parse the contents of the response and handle it appropriately.

Permissions

You must be the contract owner or an administrator to perform this operation. If not, they can grant you permission to perform the s3:ListBucket operation using Bucket Policy.

S3 API Compatibility

The x-amz-expected-bucket-owner header isn't supported.

Authorizations

AuthorizationstringRequired

If you select Request Headers, Postman populates the Headers tab with Authorization and X-Amz- prefixed fields.
If you select Request URL, Postman populates the Params tab with authentication details prefixed with X-Amz-.

Note: The parameters listed below contain confidential information. We recommend using variables to keep this data secure while working in a collaborative environment.

For Access Key, enter your access key directly in the fields or through variables for added security.
For Secret Key, enter your secret key directly in the fields or through variables for added security.

Advanced fields are optional, but Postman will attempt to generate them automatically if necessary.

For AWS Region, enter one of the regions (eu-central-3) where your bucket is hosted.
For Service Name, enter s3. The name of the service that receives the requests.
For Session Token, leave the field blank. This is only required when temporary security credentials are used.

Path parameters

Bucketstring · min: 3 · max: 63Required

The bucket name.

Example: my-bucket

Query parameters

delimiterstringOptional

A delimiter is a character you use to group keys.

encoding-typestring · enumOptional

Possible values:

markerstringOptional

Marker is where you want IONOS CLOUD Object Storage to start listing from. IONOS CLOUD Object Storage starts listing after this specified key. Marker can be any key in the bucket.

max-keysintegerOptional

Sets the maximum number of keys returned in the response. By default the operation returns up to 1,000 key names. The response might contain fewer keys but will never contain more.

prefixstringOptional

Limits the response to keys that begin with the specified prefix.

MaxKeysstringOptional

Pagination limit

MarkerstringOptional

Pagination token

Header parameters

x-amz-request-payerstring · enumOptional

Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests.

Possible values:

Responses

200

Successful operation

application/xml

403

AccessDenied

application/xml

404

NoSuchBucket

application/xml

get/{Bucket}

GET /{Bucket} HTTP/1.1
Host: s3.eu-central-3.ionoscloud.com
Authorization: YOUR_API_KEY
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>my-bucket</Name>
    <Prefix></Prefix>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>my-image-1.png</Key>
        <LastModified>2024-02-15T16:43:41.459Z</LastModified>
        <ETag>&quot;d41d8cd98f00b204e9800998ecf8427e&quot;</ETag>
        <Size>0</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>31000000</ID>
            <DisplayName>Some Name</DisplayName>
        </Owner>
        <Type>Normal</Type>
    </Contents>
    <Contents>
        <Key>my-image-2.png</Key>
        <LastModified>2024-03-13T15:53:14.199Z</LastModified>
        <ETag>&quot;994e15aa13aa642f3d82801c8f57b81b&quot;</ETag>
        <Size>2797180</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>31000000</ID>
            <DisplayName>Some Name</DisplayName>
        </Owner>
        <Type>Normal</Type>
    </Contents>
    <Marker></Marker>
</ListBucketResult>

OPTIONSObject

options

/{Bucket}

This API is used to issue a preflight request to the IONOS CLOUD Object Storage to determine if it can send an actual request with the specific origin, HTTP method, and headers.

Authorizations

AuthorizationstringRequired

If you select Request Headers, Postman populates the Headers tab with Authorization and X-Amz- prefixed fields.
If you select Request URL, Postman populates the Params tab with authentication details prefixed with X-Amz-.

Note: The parameters listed below contain confidential information. We recommend using variables to keep this data secure while working in a collaborative environment.

For Access Key, enter your access key directly in the fields or through variables for added security.
For Secret Key, enter your secret key directly in the fields or through variables for added security.

Advanced fields are optional, but Postman will attempt to generate them automatically if necessary.

For AWS Region, enter one of the regions (eu-central-3) where your bucket is hosted.
For Service Name, enter s3. The name of the service that receives the requests.
For Session Token, leave the field blank. This is only required when temporary security credentials are used.

Path parameters

Bucketstring · min: 3 · max: 63Required

The bucket name.

Example: my-bucket

Header parameters

OriginstringRequired

Identifies the origin of the cross-origin request to the IONOS CLOUD Object Storage.

Access-Control-Request-MethodstringRequired

Identifies what HTTP method will be used in the actual request.

Access-Control-Request-HeadersstringOptional

A comma-delimited list of HTTP headers that will be sent in the actual request.

For example, to put an object with server-side encryption, this preflight request will determine if it can include the `x-amz-server-side-encryption` header with the request.

Responses

200

Success

403

AccessDenied

options/{Bucket}

OPTIONS /{Bucket} HTTP/1.1
Host: s3.eu-central-3.ionoscloud.com
Authorization: YOUR_API_KEY
Origin: text
Access-Control-Request-Method: text
Accept: */*

No content

GetObject

get

/{Bucket}/{Key}

Retrieves objects from IONOS CLOUD Object Storage.

An IONOS CLOUD Object Storage bucket has no directory hierarchy such as you would find in a typical computer file system. You can, however, create a logical hierarchy by using object key names that imply a folder structure. For example, instead of naming an object test.jpg, you can name it photos/2022/July/test.jpg.

To get an object from such a logical hierarchy, specify the full key name for the object in the GET operation:

For a virtual hosted-style request example, if you have the object photos/2022/July/test.jpg, specify the resource as /photos/2022/July/test.jpg.
For a path-style request example, if you have the object photos/2022/July/test.jpg in the bucket named my-bucket, specify the resource as /my-bucket/photos/2022/July/test.jpg.

This operation returns an InvalidObjectStateError error.

If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-C) when you store the object in IONOS CLOUD Object Storage, then when you GET the object, you must use the following headers:

x-amz-server-side-encryption-customer-algorithm
x-amz-server-side-encryption-customer-key
x-amz-server-side-encryption-customer-key-md5

Permissions

You must be the contract owner or an administrator to perform this operation. If not, they can grant you permission to perform the s3:ListBucket operation using Bucket Policy.

If the object you request does not exist, the error IONOS CLOUD Object Storage returns depends on whether you also have the ListBucket permission:

If you have the ListBucket permission on the bucket, IONOS CLOUD Object Storage will return an HTTP status code 404.
If you don’t have the ListBucket permission, IONOS CLOUD Object Storage will return an HTTP status code 403 ("Access denied") error.

Versioning

By default, the GET operation returns the current version of an object. To return a different version, use the versionId subresource.

You need the GetObjectVersion permission to access a specific version of an object.
If the current version of the object is a delete marker, IONOS CLOUD Object Storage behaves as if the object was deleted and includes x-amz-delete-marker: true in the response.

Overriding Response Header Values

There are times when you want to override certain response header values in a GET response. For example, you might override the Content-Disposition response header value in your GET request.

You can override values for a set of response headers using the following query parameters. These response header values are sent only on a successful request, that is, when status code 200 OK is returned. The set of headers you can override using these parameters is a subset of the headers that IONOS CLOUD Object Storage accepts when you create an object.

The response headers that you can override for the GET response are the following:

Content-Type
Content-Language
Expires
Cache-Control,
Content-Disposition
Content-Encoding.

To override these header values in the GET response, you use the following request parameters:

partNumber
versionId
response-content-type
response-content-language
response-expires
response-cache-control
response-content-disposition
response-content-encoding

You must sign the request, either using an Authorization header or a presigned URL, when using these parameters. They cannot be used with an unsigned (anonymous) request.

Additional Considerations about Request Headers

If a Etag value sent in the If-Match header doesn't match the object's ETag, then the Precondition Failed error is returned.
If both of the If-Match and If-Unmodified-Since headers are present in the request as follows: If-Match condition evaluates to true, and; If-Unmodified-Since condition evaluates to false; then, the API returns 200 OK and the data requested.
If both of the If-None-Match and If-Modified-Since headers are present in the request as follows: If-None-Match condition evaluates to false, and; If-Modified-Since condition evaluates to true; then, the API returns 304 Not Modified response code.

For more information about conditional requests, see RFC 7232.

S3 API Compatibility

The x-amz-expected-bucket-owner header isn't supported.

Authorizations

AuthorizationstringRequired

If you select Request Headers, Postman populates the Headers tab with Authorization and X-Amz- prefixed fields.
If you select Request URL, Postman populates the Params tab with authentication details prefixed with X-Amz-.

Note: The parameters listed below contain confidential information. We recommend using variables to keep this data secure while working in a collaborative environment.

For Access Key, enter your access key directly in the fields or through variables for added security.
For Secret Key, enter your secret key directly in the fields or through variables for added security.

Advanced fields are optional, but Postman will attempt to generate them automatically if necessary.

For AWS Region, enter one of the regions (eu-central-3) where your bucket is hosted.
For Service Name, enter s3. The name of the service that receives the requests.
For Session Token, leave the field blank. This is only required when temporary security credentials are used.

Path parameters

Bucketstring · min: 3 · max: 63Required

The bucket name.

Example: my-bucket

Keystring · min: 1Required

Key of the object to get.

Possible values: length ≥ 1

Query parameters

response-cache-controlstringOptional

Sets the Cache-Control header of the response.

response-content-dispositionstringOptional

Sets the Content-Disposition header of the response

response-content-encodingstringOptional

Sets the Content-Encoding header of the response.

response-content-languagestringOptional

Sets the Content-Language header of the response.

response-content-typestringOptional

Sets the Content-Type header of the response.

response-expiresstring · date-timeOptional

Sets the Expires header of the response.

versionIdstringOptional

VersionId used to reference a specific version of the object.

partNumberinteger · min: 1 · max: 10000Optional

Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a 'ranged' GET request for the part specified. Useful for downloading just a part of an object.

Header parameters

If-MatchstringOptional

Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).

If-Modified-Sincestring · date-timeOptional

Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).

If-None-MatchstringOptional

Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).

If-Unmodified-Sincestring · date-timeOptional

Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).

RangestringOptional

Downloads the specified range bytes of an object. For more information about the HTTP Range header, see Range.

IONOS CLOUD Object Storage doesn't support retrieving multiple ranges of data per `GET` request.

x-amz-server-side-encryption-customer-algorithmstring · enumOptional

Specifies the algorithm to use to when decrypting the object (AES256).

Possible values:

x-amz-server-side-encryption-customer-keystring · passwordOptional

Specifies the customer-provided encryption key for IONOS CLOUD Object Storage used to encrypt the data. This value is used to decrypt the object when recovering it and must match the one used when storing the data. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.

x-amz-server-side-encryption-customer-key-MD5stringOptional

Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. IONOS CLOUD Object Storage uses this header for a message integrity check to ensure that the encryption key was transmitted without error.

Responses

200

Successful operation

application/xml

404

NoSuchBucket or NoSuchKey

application/xml

412

Precondition Failed

application/xml

481

InvalidObjectState

application/xml

get/{Bucket}/{Key}

GET /{Bucket}/{Key} HTTP/1.1
Host: s3.eu-central-3.ionoscloud.com
Authorization: YOUR_API_KEY
Accept: */*

<?xml version="1.0"?>
<object>
	<Body>binary</Body>
	<Metadata>
		<ANY_ADDITIONAL_PROPERTY>
			<key1>x-amz-meta-key1</key1>
			<value1>value for x-amz-meta-key1</value1>
		</ANY_ADDITIONAL_PROPERTY>
	</Metadata>
</object>

POSTObject

post

/{Bucket}/{Key}

The POST operation adds an object to a specified bucket using HTML forms. POST is an alternate form of PUT that enables browser-based uploads of objects into buckets. Parameters passed to PUT via HTTP Headers are instead passed to POST as form fields in the multipart/form-data encoded message body.

Authorizations

AuthorizationstringRequired

If you select Request Headers, Postman populates the Headers tab with Authorization and X-Amz- prefixed fields.
If you select Request URL, Postman populates the Params tab with authentication details prefixed with X-Amz-.

Note: The parameters listed below contain confidential information. We recommend using variables to keep this data secure while working in a collaborative environment.

For Access Key, enter your access key directly in the fields or through variables for added security.
For Secret Key, enter your secret key directly in the fields or through variables for added security.

Advanced fields are optional, but Postman will attempt to generate them automatically if necessary.

For AWS Region, enter one of the regions (eu-central-3) where your bucket is hosted.
For Service Name, enter s3. The name of the service that receives the requests.
For Session Token, leave the field blank. This is only required when temporary security credentials are used.

Path parameters

Bucketstring · min: 3 · max: 63Required

The bucket name.

Example: my-bucket

Keystring · min: 1Required

Key name of the object to post.

Header parameters

Cache-ControlstringOptional

Can be used to specify caching behavior along the request/reply chain. For more information, see Cache-Control.

Content-DispositionstringOptional

Specifies presentational information for the object. For more information, see Content-Disposition.

Content-EncodingstringOptional

Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field. For more information, see Content-Encoding.

Content-LanguagestringOptional

The language the content is in.

Content-LengthintegerOptional

Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically. For more information, see Content-Length.

Content-MD5stringOptional

The base64 encoded MD5 digest of the message (without the headers) according to RFC 1864.

Content-TypestringOptional

A standard MIME type describing the format of the contents. For more information, see Content-Type.

Expiresstring · date-timeOptional

The date and time at which the object is no longer cacheable. For more information, see Expires.

x-amz-server-side-encryptionstring · enumOptional

The server-side encryption algorithm used when storing this object in IONOS CLOUD Object Storage (AES256).

Possible values:

x-amz-storage-classstring · enumOptional

IONOS CLOUD Object Storage uses the STANDARD Storage Class to store newly created objects. The STANDARD storage class provides high durability and high availability.

Possible values:

x-amz-website-redirect-locationstringOptional

If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. IONOS CLOUD Object Storage stores the value of this header in the object metadata.

In the following example, the request header sets the redirect to an object (anotherPage.html) in the same bucket:

`x-amz-website-redirect-location: /anotherPage.html`

In the following example, the request header sets the object redirect to another website:

`x-amz-website-redirect-location: http://www.example.com/`

x-amz-server-side-encryption-customer-algorithmstring · enumOptional

Specifies the algorithm to use to when encrypting the object (AES256).

Possible values:

x-amz-server-side-encryption-customer-keystring · passwordOptional

Specifies the customer-provided encryption key for IONOS CLOUD Object Storage to use in encrypting data. This value is used to store the object and then it is discarded; IONOS CLOUD Object Storage does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.

x-amz-server-side-encryption-customer-key-MD5stringOptional

x-amz-server-side-encryption-contextstring · passwordOptional

Specifies the IONOS CLOUD Object Storage Encryption Context to use for object encryption. The value of this header is a base64-encoded UTF-8 string holding JSON with the encryption context key-value pairs.

x-amz-server-side-encryption-bucket-key-enabledbooleanOptional

Specifies whether IONOS CLOUD Object Storage should use a Bucket Key for object encryption with server-side encryption. Setting this header to `true` causes IONOS CLOUD Object Storage to use a Bucket Key for object encryption.

Specifying this header with a PUT operation doesn’t affect bucket-level settings for Bucket Key.

x-amz-request-payerstring · enumOptional

Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests.

Possible values:

x-amz-taggingstringOptional

The tag-set for the object. The tag-set must be encoded as URL Query parameters. (For example, "Key1=Value1")

x-amz-object-lock-modestring · enumOptional

The Object Lock mode that you want to apply to this object.

Possible values:

x-amz-object-lock-retain-until-datestring · date-timeOptional

The date and time when you want this object's Object Lock to expire. Must be formatted as a timestamp parameter.

x-amz-object-lock-legal-holdstring · enumOptional

Specifies whether a legal hold will be applied to this object.

Possible values:

Body

BodystringOptional

Object data.

Responses

200

Success

application/xml

object · PostObjectOutputOptional

post/{Bucket}/{Key}

POST /{Bucket}/{Key} HTTP/1.1
Host: s3.eu-central-3.ionoscloud.com
Authorization: YOUR_API_KEY
Content-Type: application/xml
Accept: */*
Content-Length: 64

"<?xml version=1.0?>
<Body>text</Body>
<x-amz-meta->
	<ANY_ADDITIONAL_PROPERTY>text</ANY_ADDITIONAL_PROPERTY>
</x-amz-meta->
"

200

Success

<?xml version="1.0"?>
<object/>

PutObject

put

/{Bucket}/{Key}

Adds an object to a bucket. You must have WRITE permissions on a bucket to add an object to it.

IONOS CLOUD Object Storage never adds partial objects; if you receive a success response, IONOS CLOUD Object Storage added the entire object to the bucket.

IONOS CLOUD Object Storage is a distributed system. If it receives multiple write requests for the same object simultaneously, it overwrites all but the last object written. IONOS CLOUD Object Storage does not provide object locking; if you need this, make sure to build it into your application layer or use versioning instead.

To ensure that data is not corrupted traversing the network, use the `Content-MD5` header. When you use this header, IONOS CLOUD Object Storage checks the object against the provided MD5 value and, if they do not match, returns an error. Additionally, you can calculate the MD5 while putting an object to IONOS CLOUD Object Storage and compare the returned ETag to the calculated MD5 value.

To successfully complete the `PutObject` request, you must have the `PutObject` in your permissions.
To successfully change the objects acl of your `PutObject` request, you must have the `PutObjectAcl` in your permissions.
The `Content-MD5` header is required for any request to upload an object with a retention period configured using IONOS CLOUD Object Storage Object Lock .

Versioning

If you enable versioning for a bucket, IONOS CLOUD Object Storage automatically generates a unique version ID for the object being stored. IONOS CLOUD Object Storage returns this ID in the response. When you enable versioning for a bucket, if IONOS CLOUD Object Storage receives multiple write requests for the same object simultaneously, it stores all of the objects.

Server-side Encryption with IONOS CLOUD Object Storage managed keys (SSE-S3)

You can optionally request server-side encryption. With server-side encryption, IONOS CLOUD Object Storage encrypts your data as it writes it to disks in its data centers and decrypts the data when you access it.

the SSE-S3 encryption can be set as the default encryption for the bucket using PutBucketEncryption. This way all the newly created objects will be protected with SSE-S3 encryption even it was not specified in the `PutObject` operation.
the SSE-S3 encryption can be applied to the object at the time of upload by setting `x-amz-server-side-encryption` header to `AES256`. This can be skipped if the default encryption has been set up for the bucket as described in the previous clause.

Server-side Encryption with customer managed keys (SSE-C)

In order to apply encryption with customer-provided keys (SSE-C) to the uploading object add these headers to the request:

`x-amz-server-side-encryption-customer-algorithm` = `AES256`
`x-amz-server-side-encryption-customer-key` — the 256-bit, base64-encoded encryption key to use to encrypt and decrypt your data. You might use these commands to generate it:
1. to create the file with a key: `openssl rand 32 -out my-key.key`
2. to get base64-encoded string: `openssl enc -base64 -in my-key.key`, the example of the output: `4ZRNYBCCvL0YZeqo3f2+9qDyIfnLdbg5S99R2XWr0aw=`.
`x-amz-server-side-encryption-customer-key-MD5` — the base64-encoded 128-bit MD5 digest of the encryption key. Generate it with the following command: `echo my-key.key | openssl dgst -md5 -binary | openssl enc -base64`. The example of the output: `bPU7G1zD2MlOi5gqnkRqZg==`.

NOTE:

The SSE-C encryption will override the SSE-S3 encryption if the last one was enabled as a default encryption for the bucket.
In the response, IONOS CLOUD Object Storage returns the encryption algorithm and MD5 of the encryption key that you specified when uploading the object. The ETag that is returned is not the MD5 of the object.

Authorizations

AuthorizationstringRequired

If you select Request Headers, Postman populates the Headers tab with Authorization and X-Amz- prefixed fields.
If you select Request URL, Postman populates the Params tab with authentication details prefixed with X-Amz-.

Note: The parameters listed below contain confidential information. We recommend using variables to keep this data secure while working in a collaborative environment.

For Access Key, enter your access key directly in the fields or through variables for added security.
For Secret Key, enter your secret key directly in the fields or through variables for added security.

Advanced fields are optional, but Postman will attempt to generate them automatically if necessary.

For AWS Region, enter one of the regions (eu-central-3) where your bucket is hosted.
For Service Name, enter s3. The name of the service that receives the requests.
For Session Token, leave the field blank. This is only required when temporary security credentials are used.

Path parameters

Bucketstring · min: 3 · max: 63Required

The bucket name.

Example: my-bucket

Keystring · min: 1Required

Object key for which the PUT operation was initiated.

Header parameters

Cache-ControlstringOptional

Can be used to specify caching behavior along the request/reply chain. For more information, see Cache-Control.

Content-DispositionstringOptional

Specifies presentational information for the object. For more information, see Content-Disposition.

Content-EncodingstringOptional

Content-LanguagestringOptional

The language the content is in.

Content-LengthintegerOptional

Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically. For more information, see Content-Length.

Content-MD5stringOptional

The base64 encoded MD5 digest of the message (without the headers) according to RFC 1864.

Content-TypestringOptional

A standard MIME type describing the format of the contents. For more information, see Content-Type.

Expiresstring · date-timeOptional

The date and time at which the object is no longer cacheable. For more information, see Expires.

x-amz-server-side-encryptionstring · enumOptional

The server-side encryption algorithm used when storing this object in IONOS CLOUD Object Storage (AES256).

Possible values:

x-amz-storage-classstring · enumOptional

The valid value is STANDARD.

Possible values:

x-amz-website-redirect-locationstringOptional

In the following example, the request header sets the redirect to an object (anotherPage.html) in the same bucket:

`x-amz-website-redirect-location: /anotherPage.html`

In the following example, the request header sets the object redirect to another website:

`x-amz-website-redirect-location: http://www.example.com/`

x-amz-server-side-encryption-customer-algorithmstring · enumOptional

Specifies the algorithm to use to when encrypting the object. The valid option is AES256.

Possible values:

x-amz-server-side-encryption-customer-keystring · passwordOptional

Specifies the 256-bit, base64-encoded encryption key to use to encrypt and decrypt your data. For example, 4ZRNYBCCvL0YZeqo3f2+9qDyIfnLdbg5S99R2XWr0aw=.

x-amz-server-side-encryption-customer-key-MD5stringOptional

x-amz-server-side-encryption-contextstring · passwordOptional

x-amz-request-payerstring · enumOptional

Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests.

Possible values:

x-amz-taggingstringOptional

The tag-set for the object. The tag-set must be encoded as URL Query parameters. (For example, "Key1=Value1")

x-amz-object-lock-modestring · enumOptional

The Object Lock mode that you want to apply to this object.

Possible values:

x-amz-object-lock-retain-until-datestring · date-timeOptional

The date and time when you want this object's Object Lock to expire. Must be formatted as a timestamp parameter.

x-amz-object-lock-legal-holdstring · enumOptional

Specifies whether a legal hold will be applied to this object.

Possible values:

Body

BodystringOptional

Object data.

Responses

200

Successful operation

text/plain

put/{Bucket}/{Key}

Request

PUT /{Bucket}/{Key} HTTP/1.1
Host: s3.eu-central-3.ionoscloud.com
Accept: */*   
Authorization: authorization string   
Date: Tue, 04 Apr 2023 19:36:53 GMT
x-amz-server-side-encryption: AES256

200

Successful operation

HTTP/1.1 200 OK   
x-amz-request-id: 9a4f31b7-fed2-1fff-a148-3cecef3849fe
date: Tue, 04 Apr 2023 19:36:53 GMT
etag: "4f8d2c12500d851ed55fc08df311e868"
x-amz-server-side-encryption-customer-algorithm: AES256   
x-amz-server-side-encryption-customer-key-MD5: r4C1SZrweqvPoGPMtR6jTA==
content-length: 0

DeleteObject

delete

/{Bucket}/{Key}

Removes the null version (if there is one) of an object and inserts a delete marker, which becomes the latest version of the object. This operation is final - there is no way to recover a deleted object. Data stored in IONOS CLOUD Object Storage is erasure coded and distributed to multiple individual storage devices in multiple data centers. When data is deleted, various mechanisms exist which prevent recovery or reconstruction of the deleted objects.

Deletion of an object undergoes various stages. First, the metadata is marked to indicate the object is deleted, then, the data is removed. Eventually, deleted metadata is overwritten and the deleted data blocks are overwritten with new data in the course of normal operations. As soon as the metadata is marked deleted, it is not possible to read an object remotely.

Authorizations

AuthorizationstringRequired

If you select Request Headers, Postman populates the Headers tab with Authorization and X-Amz- prefixed fields.
If you select Request URL, Postman populates the Params tab with authentication details prefixed with X-Amz-.

Note: The parameters listed below contain confidential information. We recommend using variables to keep this data secure while working in a collaborative environment.

For Access Key, enter your access key directly in the fields or through variables for added security.
For Secret Key, enter your secret key directly in the fields or through variables for added security.

Advanced fields are optional, but Postman will attempt to generate them automatically if necessary.

For AWS Region, enter one of the regions (eu-central-3) where your bucket is hosted.
For Service Name, enter s3. The name of the service that receives the requests.
For Session Token, leave the field blank. This is only required when temporary security credentials are used.

Path parameters

Bucketstring · min: 3 · max: 63Required

The bucket name.

Example: my-bucket

Keystring · min: 1Required

Key name of the object to delete.

Query parameters

versionIdstringOptional

VersionId used to reference a specific version of the object.

Header parameters

x-amz-mfastringOptional

The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device. Required to permanently delete a versioned object if versioning is configured with MFA Delete enabled.

x-amz-bypass-governance-retentionbooleanOptional

Indicates whether Object Lock should bypass Governance-mode restrictions to process this operation. To use this header, you must have the PutBucketPublicAccessBlock permission.

Responses

204

Success

application/xml

Responseobject · DeleteObjectOutput

delete/{Bucket}/{Key}

DELETE /{Bucket}/{Key} HTTP/1.1
Host: s3.eu-central-3.ionoscloud.com
Authorization: YOUR_API_KEY
Accept: */*

204

Success

<?xml version="1.0"?>
<object/>

HeadObject

head

/{Bucket}/{Key}

The HEAD operation retrieves metadata from an object without returning the object itself. This operation is useful if you're only interested in an object's metadata. To use HEAD, you must have READ access to the object.

A `HEAD` request has the same options as a `GET` operation on an object. The response is identical to the `GET` response except that there is no response body. Because of this, if the `HEAD` request generates an error, it returns a generic `404 Not Found` or `403 Forbidden` code. It is not possible to retrieve the exact exception beyond these error codes.

If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-C) when you store the object in IONOS CLOUD Object Storage, then when you retrieve the metadata from the object, you must use the following headers:

`x-amz-server-side-encryption-customer-algorithm` = `AES256`
`x-amz-server-side-encryption-customer-key`
`x-amz-server-side-encryption-customer-key-MD5`
Encryption request headers, like `x-amz-server-side-encryption`, should not be sent for GET requests if your object uses the server-side encryption with IONOS CLOUD Object Storage–managed encryption keys (SSE-S3). If your object does use this type of keys, you’ll get an HTTP 400 BadRequest error.
The last modified property in this case is the creation date of the object.

Request headers are limited to 8 KB in size.

Consider the following when using request headers:

Consideration 1 – If both of the `If-Match` and `If-Unmodified-Since` headers are present in the request as follows:
- `If-Match` condition evaluates to `true`, and;
- `If-Unmodified-Since` condition evaluates to `false`;
Then IONOS CLOUD Object Storage returns `200 OK` and the data requested.
Consideration 2 – If both of the `If-None-Match` and `If-Modified-Since` headers are present in the request as follows:
- `If-None-Match` condition evaluates to `false`, and;
- `If-Modified-Since` condition evaluates to `true`;
Then IONOS CLOUD Object Storage returns the `304 Not Modified` response code.

For more information about conditional requests, see RFC 7232.

Permissions

You need the relevant read object (or version) permission for this operation. If the object you request does not exist, the error IONOS CLOUD Object Storage returns depends on whether you also have the ListBucket permission.

If you have the `ListBucket` permission on the bucket, IONOS CLOUD Object Storage returns an HTTP status code 404 ("no such key") error.
If you don’t have the `ListBucket` permission, IONOS CLOUD Object Storage returns an HTTP status code 403 ("access denied") error.

Authorizations

AuthorizationstringRequired

If you select Request Headers, Postman populates the Headers tab with Authorization and X-Amz- prefixed fields.
If you select Request URL, Postman populates the Params tab with authentication details prefixed with X-Amz-.

Note: The parameters listed below contain confidential information. We recommend using variables to keep this data secure while working in a collaborative environment.

For Access Key, enter your access key directly in the fields or through variables for added security.
For Secret Key, enter your secret key directly in the fields or through variables for added security.

Advanced fields are optional, but Postman will attempt to generate them automatically if necessary.

For AWS Region, enter one of the regions (eu-central-3) where your bucket is hosted.
For Service Name, enter s3. The name of the service that receives the requests.
For Session Token, leave the field blank. This is only required when temporary security credentials are used.

Path parameters

Bucketstring · min: 3 · max: 63Required

The bucket name.

Example: my-bucket

Keystring · min: 1Required

The object key.

Query parameters

versionIdstringOptional

VersionId used to reference a specific version of the object.

partNumberintegerOptional

Part number of the object being read. This is a positive integer between 1 and 10,000. Effectively performs a 'ranged' HEAD request for the part specified. Useful querying about the size of the part and the number of parts in this object.

Header parameters

If-MatchstringOptional

Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).

If-Modified-Sincestring · date-timeOptional

Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).

If-None-MatchstringOptional

Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).

If-Unmodified-Sincestring · date-timeOptional

Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).

RangestringOptional

Downloads the specified range bytes of an object. For more information about the HTTP Range header, see Range.

IONOS CLOUD Object Storage doesn't support retrieving multiple ranges of data per `GET` request.

x-amz-server-side-encryption-customer-algorithmstring · enumOptional

Specifies the algorithm to use to when encrypting the object (AES256).

Possible values:

x-amz-server-side-encryption-customer-keystring · passwordOptional

x-amz-server-side-encryption-customer-key-MD5stringOptional

Responses

200

Success

application/xml

480

NoSuchKey

application/xml

head/{Bucket}/{Key}

HEAD /{Bucket}/{Key} HTTP/1.1
Host: s3.eu-central-3.ionoscloud.com
Authorization: YOUR_API_KEY
Accept: */*

<?xml version="1.0"?>
<object>
	<AcceptRanges>bytes</AcceptRanges>
	<ContentLength>3191</ContentLength>
	<ContentType>image/jpeg</ContentType>
	<ETag>&quot;6805f2cfc46c0f04559748bb039d69ae&quot;</ETag>
	<LastModified>Wed, 06 Jul 2022 05:10:16 GMT</LastModified>
	<Metadata/>
	<VersionId>null</VersionId>
</object>

CopyObject

put

/{Bucket}/{Key}?x-amz-copy-source

Creates a copy of an object that is already stored in IONOS CLOUD Object Storage.

You can store individual objects of up to 5 TB in IONOS CLOUD Object Storage. You create a copy of your object up to 5 GB in size in a single atomic operation using this API. However, to copy an object greater than 5 GB, you must use the multipart upload Upload Part - Copy API.

All copy requests must be authenticated. Additionally, you must have read access to the source object and write access to the destination bucket. Both the Region that you want to copy the object from and the Region that you want to copy the object to must be enabled for your account.

Authorizations

AuthorizationstringRequired

If you select Request Headers, Postman populates the Headers tab with Authorization and X-Amz- prefixed fields.
If you select Request URL, Postman populates the Params tab with authentication details prefixed with X-Amz-.

Note: The parameters listed below contain confidential information. We recommend using variables to keep this data secure while working in a collaborative environment.

For Access Key, enter your access key directly in the fields or through variables for added security.
For Secret Key, enter your secret key directly in the fields or through variables for added security.

Advanced fields are optional, but Postman will attempt to generate them automatically if necessary.

For AWS Region, enter one of the regions (eu-central-3) where your bucket is hosted.
For Service Name, enter s3. The name of the service that receives the requests.
For Session Token, leave the field blank. This is only required when temporary security credentials are used.

Path parameters

Bucketstring · min: 3 · max: 63Required

The bucket name.

Example: my-bucket

Keystring · min: 1Required

The key of the destination object.

Header parameters

Cache-ControlstringOptional

Specifies caching behavior along the request/reply chain.

Content-DispositionstringOptional

Specifies presentational information for the object.

Content-EncodingstringOptional

Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.

Content-LanguagestringOptional

The language the content is in.

Content-TypestringOptional

A standard MIME type describing the format of the object data.

x-amz-copy-sourcestringRequired

Specifies the source object for the copy operation.

Pattern: \/.+\/.+

x-amz-copy-source-if-matchstringOptional

Copies the object if its entity tag (ETag) matches the specified tag.

x-amz-copy-source-if-modified-sincestring · date-timeOptional

Copies the object if it has been modified since the specified time.

x-amz-copy-source-if-none-matchstringOptional

Copies the object if its entity tag (ETag) is different than the specified ETag.

x-amz-copy-source-if-unmodified-sincestring · date-timeOptional

Copies the object if it hasn't been modified since the specified time.

Expiresstring · date-timeOptional

The date and time at which the object is no longer cacheable.

x-amz-metadata-directivestring · enumOptional

Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request.

Possible values:

x-amz-tagging-directivestring · enumOptional

Specifies whether the object tag-set are copied from the source object or replaced with tag-set provided in the request.

Possible values:

x-amz-server-side-encryptionstring · enumOptional

The server-side encryption algorithm used when storing this object in IONOS CLOUD Object Storage (AES256).

Possible values:

x-amz-storage-classstring · enumOptional

IONOS CLOUD Object Storage uses the STANDARD Storage Class to store newly created objects. The STANDARD storage class provides high durability and high availability.

Possible values:

x-amz-website-redirect-locationstringOptional

x-amz-server-side-encryption-customer-algorithmstringOptional

Specifies the algorithm to use to when encrypting the object (AES256).

x-amz-server-side-encryption-customer-keystring · passwordOptional

x-amz-server-side-encryption-customer-key-MD5stringOptional

x-amz-copy-source-server-side-encryption-customer-algorithmstringOptional

Specifies the algorithm to use when decrypting the source object (AES256).

x-amz-copy-source-server-side-encryption-customer-keystring · passwordOptional

Specifies the customer-provided encryption key for IONOS CLOUD Object Storage to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created.

x-amz-copy-source-server-side-encryption-customer-key-MD5stringOptional

x-amz-taggingstringOptional

The tag-set for the object destination object this value must be used in conjunction with the TaggingDirective. The tag-set must be encoded as URL Query parameters.

x-amz-object-lock-modestring · enumOptional

The Object Lock mode that you want to apply to the copied object.

Possible values:

x-amz-object-lock-retain-until-datestring · date-timeOptional

The date and time when you want the copied object's Object Lock to expire.

x-amz-object-lock-legal-holdstring · enumOptional

Specifies whether you want to apply a Legal Hold to the copied object.

Possible values:

Body

Responses

200

Success

application/xml

put/{Bucket}/{Key}?x-amz-copy-source

PUT /{Bucket}/{Key}?x-amz-copy-source HTTP/1.1
Host: s3.eu-central-3.ionoscloud.com
Authorization: YOUR_API_KEY
x-amz-copy-source: text
Content-Type: application/xml
Accept: */*
Content-Length: 50

"<?xml version=1.0?>
<x-amz-meta->
	<ANY_ADDITIONAL_PROPERTY>text</ANY_ADDITIONAL_PROPERTY>
</x-amz-meta->
"

200

Success

<?xml version="1.0"?>
<object>
	<CopyObjectResult>
		<ETag>&quot;6805f2cfc46c0f04559748bb039d69ae&quot;</ETag>
		<LastModified>2016-12-15T17:38:53.000Z</LastModified>
	</CopyObjectResult>
</object>

DeleteObjects

post

/{Bucket}?delete

This operation enables you to delete multiple objects from a bucket using a single HTTP request. If you know the object keys that you want to delete, then this operation provides a suitable alternative to sending individual delete requests, reducing per-request overhead.

The request contains a list of up to 1000 keys that you want to delete. In the XML, you provide the object key names, and optionally, version IDs if you want to delete a specific version of the object from a versioning-enabled bucket. For each key, IONOS CLOUD Object Storage performs a delete operation and returns the result of that delete, success, or failure, in the response. Note that if the object specified in the request is not found, IONOS CLOUD Object Storage returns the result as deleted.

The operation supports two modes for the response: verbose and quiet. By default, the operation uses verbose mode in which the response includes the result of deletion of each key in your request. In quiet mode the response includes only keys where the delete operation encountered an error. For a successful deletion, the operation does not return any information about the delete in the response body.

Authorizations

AuthorizationstringRequired

If you select Request Headers, Postman populates the Headers tab with Authorization and X-Amz- prefixed fields.
If you select Request URL, Postman populates the Params tab with authentication details prefixed with X-Amz-.

Note: The parameters listed below contain confidential information. We recommend using variables to keep this data secure while working in a collaborative environment.

For Access Key, enter your access key directly in the fields or through variables for added security.
For Secret Key, enter your secret key directly in the fields or through variables for added security.

Advanced fields are optional, but Postman will attempt to generate them automatically if necessary.

For AWS Region, enter one of the regions (eu-central-3) where your bucket is hosted.
For Service Name, enter s3. The name of the service that receives the requests.
For Session Token, leave the field blank. This is only required when temporary security credentials are used.

Path parameters

Bucketstring · min: 3 · max: 63Required

The bucket name.

Example: my-bucket

Query parameters

deleteboolean · enumRequiredPossible values:

Header parameters

x-amz-mfastringOptional

x-amz-bypass-governance-retentionbooleanOptional

Specifies whether you want to delete this object even if it has a Governance-type Object Lock in place. To use this header, you must have the PutBucketPublicAccessBlock permission.

Body

Responses

200

Successful operation

application/xml

post/{Bucket}?delete

POST /{Bucket}?delete?delete=true HTTP/1.1
Host: s3.eu-central-3.ionoscloud.com
Authorization: YOUR_API_KEY
Content-Type: application/xml
Accept: */*
Content-Length: 197

"<Delete xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Object>
      <Key>folder/object1.zip</Key>
  </Object>
  <Object>
      <Key>folder/object2.zip</Key>
  </Object>
</Delete>
"

200

Successful operation

<?xml version="1.0" encoding="UTF-8"?>
<DeleteResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Deleted>
        <Key>folder/object1.zip</Key>
    </Deleted>
    <Deleted>
        <Key>folder/object2.zip</Key>
    </Deleted>
</DeleteResult>

PreviousBuckets

NextCORS

Last updated 1 month ago

Was this helpful?