search
Log in

Objects

Basic Operations with Objects

hashtag
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 Object Storage API requests are authenticated using the AWS signature. The IONOS 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 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 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 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 Object Storage starts listing after this specified key. StartAfter can be any key in the bucket.

Responses
chevron-right
200

Successul operation

application/xml
get
/{Bucket}?list-type=2

hashtag
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

IONOS Object Storage API requests are authenticated using the AWS signature. The IONOS 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
delimiterstringOptional

A delimiter is a character you use to group keys.

encoding-typestring · enumOptional

Requests IONOS 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 Object Storage encode the keys in the response.

Possible values:
markerstringOptional

Marker is where you want IONOS Object Storage to start listing from. IONOS 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
chevron-right
200

Successful operation

application/xml
get
/{Bucket}

hashtag
OPTIONSObject

options
/{Bucket}

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

Authorizations
AuthorizationstringRequired

IONOS Object Storage API requests are authenticated using the AWS signature. The IONOS 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
Header parameters
OriginstringRequired
Access-Control-Request-MethodstringRequired

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

Access-Control-Request-HeadersstringOptional
Responses
chevron-right
200

Success

options
/{Bucket}
No content

hashtag
GetObject

get
/{Bucket}/{Key}

Retrieves objects from IONOS Object Storage.

An IONOS 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 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

hashtag
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 Object Storage returns depends on whether you also have the ListBucket permission:

  • If you have the ListBucket permission on the bucket, IONOS Object Storage will return an HTTP status code 404.

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

hashtag
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 Object Storage behaves as if the object was deleted and includes x-amz-delete-marker: true in the response.

hashtag
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 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.

hashtag
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 7232arrow-up-right.

S3 API Compatibility

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

Authorizations
AuthorizationstringRequired

IONOS Object Storage API requests are authenticated using the AWS signature. The IONOS 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
Keystring · min: 1Required
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
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 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 Object Storage uses this header for a message integrity check to ensure that the encryption key was transmitted without error.

Responses
chevron-right
200

Successful operation

application/xml
get
/{Bucket}/{Key}

hashtag
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

IONOS Object Storage API requests are authenticated using the AWS signature. The IONOS 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
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 Object Storage (AES256).

Possible values:
x-amz-storage-classstring · enumOptional

IONOS 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-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 Object Storage to use in encrypting data. This value is used to store the object and then it is discarded; IONOS 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

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

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

Specifies the IONOS 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
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
chevron-right
200

Success

application/xml
objectOptional
post
/{Bucket}/{Key}
200

Success

hashtag
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 Object Storage never adds partial objects; if you receive a success response, IONOS Object Storage added the entire object to the bucket.

IONOS 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 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 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 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 Object Storage Object Lock .

Versioning

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

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

You can optionally request server-side encryption. With server-side encryption, IONOS 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 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

IONOS Object Storage API requests are authenticated using the AWS signature. The IONOS 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
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

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 Object Storage (AES256).

Possible values:
x-amz-storage-classstring · enumOptional

The valid value is STANDARD.

Possible values:
x-amz-website-redirect-locationstringOptional
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

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

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

Specifies the IONOS 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-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
chevron-right
200

Successful operation

text/plain
put
/{Bucket}/{Key}
Request
200

Successful operation

hashtag
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 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

IONOS Object Storage API requests are authenticated using the AWS signature. The IONOS 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
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
delete
/{Bucket}/{Key}
204

Success

hashtag
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 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 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 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 Object Storage returns the `304 Not Modified` response code.

For more information about conditional requests, see RFC 7232arrow-up-right.

Permissions

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

  • If you have the `ListBucket` permission on the bucket, IONOS Object Storage returns an HTTP status code 404 ("no such key") error.

  • If you don’t have the `ListBucket` permission, IONOS Object Storage returns an HTTP status code 403 ("access denied") error.

Authorizations
AuthorizationstringRequired

IONOS Object Storage API requests are authenticated using the AWS signature. The IONOS 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
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
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 Object Storage to use in encrypting data. This value is used to store the object and then it is discarded; IONOS 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

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

Responses
chevron-right
200

Success

application/xml
head
/{Bucket}/{Key}

hashtag
CopyObject

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

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

You can store individual objects of up to 5 TB in IONOS 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

IONOS Object Storage API requests are authenticated using the AWS signature. The IONOS 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
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-sourcestringRequiredPattern: \/.+\/.+
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 Object Storage (AES256).

Possible values:
x-amz-storage-classstring · enumOptional

IONOS 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 Object Storage stores the value of this header in the object metadata.

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

Specifies the customer-provided encryption key for IONOS Object Storage to use in encrypting data. This value is used to store the object and then it is discarded; IONOS 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

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

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

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

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
chevron-right
200

Success

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

Success

hashtag
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 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 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

IONOS Object Storage API requests are authenticated using the AWS signature. The IONOS 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
deleteboolean · enumRequiredPossible values:
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

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
chevron-right
200

Successful operation

application/xml
post
/{Bucket}?delete
200

Successful operation

PreviousBucketsNextCORS

Last updated

Was this helpful?