IONOS Cloud S3 Object Storage API (2.0.0)

Overview

The IONOS Cloud S3 Object Storage API is a REST-based API that allows users to create, manage, and delete Object Storage devices, as well as visualize Object Storage network data usage. The Object Storage is fully S3-compliant, which means that it can be used to manage buckets and objects using existing S3 clients.

Endpoints

Region Endpoints
de S3-eu-central-1.ionoscloud.com,

S3 legacy endpoint: s3-de-central.profitbricks.com
eu-central-2 S3-eu-central-2.ionoscloud.com
eu-south-2 S3-eu-south-2.ionoscloud.com

swagger 3 Source url

Authentication

API key

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

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

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

Note: Curl and OpenSSL can be used to access the S3 Object Storage API, but this is a time-consuming process. Even for simple requests, the process of generating and signing the curl request requires several steps.


ACL

Read a bucket ACL

This implementation of the GET operation uses the acl subresource to return the access control list (ACL) of a bucket. To use GET to return the ACL of the bucket, you must have READ_ACP access to the bucket. If READ_ACP permission is granted to the anonymous user, you can return the ACL of the bucket without using an authorization header.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}acl Try out

Create a bucket ACL

Sets the permissions on an existing bucket using access control lists (ACL). To set the ACL of a bucket, you must have WRITE_ACP permission.

You can use one of the following two ways to set a bucket's permissions:

You cannot specify access permission using both the body and the request headers.

Depending on your application needs, you may choose to set the ACL on a bucket using either the request body or the headers. For example, if you have an existing application that updates a bucket ACL using the request body, then you can continue to use that approach.

put http://S3-eu-central-1.ionoscloud.com /{Bucket}acl Try out

Read an object's ACL

Returns the access control list (ACL) of an object. To use this operation, you must have READ_ACP access to the object.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}acl Try out

Create an object's ACL

Uses the acl subresource to set the access control list (ACL) permissions for a new or existing object in an S3 bucket. You must have WRITE_ACP permission to set the ACL of an object. For more information, see What permissions can I grant?

Depending on your application needs, you can choose to set the ACL on an object using either the request body or the headers. For example, if you have an existing application that updates a bucket ACL using the request body, you can continue to use that approach. For more information, see Access Control List (ACL) Overview.

put http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}acl Try out

Basic Operations

Copy an object

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

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

put http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}x-amz-copy-source Try out

Create a new bucket

Creates a new S3 bucket. To create a bucket, you must register with IONOS Cloud S3 Object Storage and have a valid Access Key ID to authenticate requests. Anonymous requests are never allowed to create buckets. By creating the bucket, you become the bucket owner.

Not every string is an acceptable bucket name. For information about bucket naming restrictions, see Bucket naming rules.

Buckets are created in the location specified in the endpoint used to make the request. Once a bucket is created, it can be accessed at that location. Any requests targeting an existing bucket using an endpoint with an incorrect location will result in a 404 NoSuchkey.

When creating a bucket using this operation, you can optionally specify the accounts or groups that should be granted specific permissions on the bucket. There are two ways to grant the appropriate permissions using the request headers.


Delete a bucket

Deletes the bucket. All objects (including all object versions and delete markers) in the bucket must be deleted before the bucket itself can be deleted.

delete http://S3-eu-central-1.ionoscloud.com /{Bucket} Try out

Read a bucket's headers

This operation is useful to determine if a bucket exists and you have permission to access it. The operation returns a 200 OK if the bucket exists and you have permission to access it.

If the bucket does not exist or you do not have permission to access it, the HEAD request returns a generic 404 Not Found or 403 Forbidden code. A message body is not included, so you cannot determine the exception beyond these error codes.

To use this operation, you must have permissions to perform the ListBucket operation. The bucket owner has this permission by default and can grant this permission to others.

head http://S3-eu-central-1.ionoscloud.com /{Bucket} Try out

List objects in a bucket(v1)

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.

get http://S3-eu-central-1.ionoscloud.com /{Bucket} Try out

Preflight request for cross-origin resource sharing

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

options http://S3-eu-central-1.ionoscloud.com /{Bucket} Try out

Upload an object to a bucket using HTML form

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.

post http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key} Try out

Delete an Object

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

delete http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key} Try out

Read an Object

Retrieves objects from IONOS Cloud S3 Object Storage. To use GET, you must have READ access to the object. If you grant READ access to the anonymous user, you can return the object without using an authorization header.

An IONOS Cloud S3 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 examplebucket, specify the resource as /examplebucket/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 S3 Object Storage, then when you GET the object, you must use the following headers:

Assuming you have the relevant permission to read object tags, the response also returns the x-amz-tagging-count header that provides the count of number of tags associated with the object.

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

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 S3 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 S3 Object Storage accepts when you create an object. The response headers that you can override for the GET response are Content-Type, Content-Language, Expires, Cache-Control, Content-Disposition, and Content-Encoding. To override these header values in the GET response, you use the following request parameters.

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 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, S3 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, S3 returns 304 Not Modified response code.

For more information about conditional requests, see RFC 7232.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key} Try out

Read object metadata

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 S3 Object Storage, then when you retrieve the metadata from the object, you must use the following headers:

  • Encryption request headers, like x-amz-server-side-encryption, should not be sent for GET requests if your object uses server-side encryption with KMS keys (SSE-KMS) or server-side encryption with IONOS Cloud S3 Object Storage–managed encryption keys (SSE-S3). If your object does use these types 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:

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

head http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key} Try out

Create (upload) an object

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

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

IONOS Cloud S3 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 S3 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 S3 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 S3 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 IAM permissions.

  • To successfully change the objects acl of your PutObject request, you must have the PutObjectAcl in your IAM permissions.

  • The Content-MD5 header is required for any request to upload an object with a retention period configured using IONOS Cloud S3 Object Storage Object Lock .

Server-side Encryption

You can optionally request server-side encryption. With server-side encryption, IONOS Cloud S3 Object Storage encrypts your data as it writes it to disks in its data centers and decrypts the data when you access it. You have the option to provide your own encryption key or use IONOS Cloud S3 Object Storage managed encryption keys (SSE-S3 or SSE-KMS).

If you request server-side encryption using IONOS Cloud S3 Object Storage Key Management Service (SSE-KMS), you can enable an S3 Bucket Key at the object-level in the IONOS Cloud S3 Object Storage User Guide.

Access Control List (ACL)-Specific Request Headers

You can use headers to grant ACL- based permissions. By default, all objects are private. Only the owner has full access control. When adding a new object, you can grant permissions to individual IONOS Cloud S3 Object Storage accounts or to predefined groups defined by IONOS Cloud S3 Object Storage. These permissions are then added to the ACL on the object.

Storage Class Options

By default, IONOS Cloud S3 Object Storage uses the STANDARD Storage Class to store newly created objects. The STANDARD storage class provides high durability and high availability. Depending on performance needs, you can specify a different Storage Class.

Versioning

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

put http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key} Try out

Delete multiple objects

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

post http://S3-eu-central-1.ionoscloud.com /{Bucket}delete Try out

List buckets in a service instance

Returns a list of all buckets owned by the authenticated sender of the request.


get http://S3-eu-central-1.ionoscloud.com / Try out

List objects in a bucket (v2)

Returns some or all (up to 1,000) of the objects in a bucket with each request. 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. Make sure to design your application to parse the contents of the response and handle it appropriately. Objects are returned sorted in an ascending order of the respective key names in the list.

To use this operation, you must have READ access to the bucket.

To use this operation in an Identity and Access Management (IAM) policy, you must have permissions to perform the ListBucket operation. The bucket owner has this permission by default and can grant this permission to others.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}list-type=2 Try out

Restore an archived copy of an object

Restores an archived copy of an object back into IONOS Cloud S3 Object Storage

This operation performs the following types of requests:

To use this operation, you must have permissions to perform the RestoreObject operation. The bucket owner has this permission by default and can grant this permission to others.

post http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}restore Try out

CORS

Delete a CORS configuration

Deletes the CORS configuration information set for the bucket.

To use this operation, you must have permission to perform the PutBucketCORS operation. The bucket owner has this permission by default and can grant this permission to others.

delete http://S3-eu-central-1.ionoscloud.com /{Bucket}cors Try out

Read a CORS configuration

Returns the cors configuration information set for the bucket.

To use this operation, you must have permission to perform the GetBucketCORS operation. By default, the bucket owner has this permission and can grant it to others.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}cors Try out

Configure CORS

Sets the CORS configuration for your bucket. If the configuration exists, it will be overwritten and replaced.

To use this operation, you must be allowed to perform the PutBucketCORS operation. By default, the bucket owner has this permission and can grant it to others.

You set this configuration on a bucket so that the bucket can service cross-origin requests. For example, you might want to enable a request whose origin is http://www.example.com to access your IONOS Cloud S3 Object Storage bucket at my.example.bucket.com by using the browser's XMLHttpRequest capability.

To enable cross-origin resource sharing (CORS) on a bucket, you add the cors subresource to the bucket. The cors subresource is an XML document in which you configure rules that identify origins and the HTTP methods that can be executed on your bucket. The document is limited to 64 KB in size.

When IONOS Cloud S3 Object Storage receives a cross-origin request (or a pre-flight OPTIONS request) against a bucket, it evaluates the cors configuration on the bucket and uses the first CORSRule rule that matches the incoming browser request to enable a cross-origin request. For a rule to match, the following conditions must be met:

put http://S3-eu-central-1.ionoscloud.com /{Bucket}cors Try out

Encryption

Delete a bucket's encryption

This implementation of the DELETE operation removes default encryption from the bucket.

To use this operation, you must have permissions to perform the PutEncryptionConfiguration operation. The bucket owner has this permission by default. The bucket owner can grant this permission to others.

delete http://S3-eu-central-1.ionoscloud.com /{Bucket}encryption Try out

Read a bucket's encryption

Returns the default encryption configuration for an IONOS Cloud S3 Object Storage bucket. If the bucket does not have a default encryption configuration, GetBucketEncryption returns ServerSideEncryptionConfigurationNotFoundError.

To use this operation, you must have permission to perform the GetEncryptionConfiguration operation. The bucket owner has this permission by default. The bucket owner can grant this permission to others.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}encryption Try out

Create a bucket encryption

This operation uses the encryption subresource to configure default encryption and IONOS Cloud S3 Object Storage Bucket Key for an existing bucket.

To use this operation, you must have permissions to perform the PutEncryptionConfiguration operation. The bucket owner has this permission by default. The bucket owner can grant this permission to others.

put http://S3-eu-central-1.ionoscloud.com /{Bucket}encryption Try out

LegalHold



Lifecycle

Delete a bucket's lifecycle configuration

Deletes the lifecycle configuration from the specified bucket. IONOS Cloud S3 Object Storage removes all the lifecycle configuration rules in the lifecycle subresource associated with the bucket. Your objects never expire, and IONOS Cloud S3 Object Storage no longer automatically deletes any objects on the basis of rules contained in the deleted lifecycle configuration.

To use this operation, you must have permission to perform the PutLifecycleConfiguration operation. By default, the bucket owner has this permission and the bucket owner can grant this permission to others.

There is usually some time lag before lifecycle configuration deletion is fully propagated to all the IONOS Cloud S3 Object Storage systems.

delete http://S3-eu-central-1.ionoscloud.com /{Bucket}lifecycle Try out

Read a bucket's lifecycle configuration

For an updated version of this API, see GetBucketLifecycleConfiguration. If you configured a bucket lifecycle using the filter element, you should see the updated version of this topic. This topic is provided for backward compatibility.

Returns the lifecycle configuration information set on the bucket.

To use this operation, you must have permission to perform the GetLifecycleConfiguration operation. The bucket owner has this permission by default. The bucket owner can grant this permission to others.

GetBucketLifecycle has the following special error:


get http://S3-eu-central-1.ionoscloud.com /{Bucket}lifecycle Try out

Create a bucket's lifecycle configuration

For an updated version of this API, see PutBucketLifecycleConfiguration. This version has been deprecated. Existing lifecycle configurations will work. For new lifecycle configurations, use the updated API.

Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration.


put http://S3-eu-central-1.ionoscloud.com /{Bucket}lifecycle Try out

Location

Read a bucket's location (region)

Returns the Region the bucket resides in. You set the bucket's Region using the LocationConstraint request parameter in a CreateBucket request.

To use this implementation of the operation, you must be the bucket owner.

To use this API against an access point, provide the alias of the access point in place of the bucket name.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}location Try out

Lock

Retrieves the current object lock configuration of a bucket

Gets the Object Lock configuration for a bucket. Only the bucket owner is allowed to execute this method.


get http://S3-eu-central-1.ionoscloud.com /{Bucket}object-lock Try out

Create an object's lock configuration for a bucket

Places an Object Lock configuration on the specified bucket. The rule specified in the Object Lock configuration will be applied by default to every new object placed in the specified bucket.

  • The DefaultRetention settings require both a mode and a period.

  • The DefaultRetention period can be either Days or Years but you must select one. You cannot specify Days and Years at the same time.

  • You can only enable Object Lock for new buckets. If you want to turn on Object Lock for an existing bucket, contact IONOS Cloud S3 Object Storage Support.

put http://S3-eu-central-1.ionoscloud.com /{Bucket}object-lock Try out

Logging

Read a bucket's logging configuration

Returns the logging status of a bucket and the permissions users have to view and modify that status. To use GET, you must be the bucket owner.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}logging Try out

Create a bucket's logging configuration

Set the logging parameters for a bucket and to specify permissions for who can view and modify the logging parameters. All logs are saved to buckets in the same IONOS Cloud S3 Object Storage Region as the source bucket. To set the logging status of a bucket, you must be the bucket owner.

The bucket owner is automatically granted FULL_CONTROL to all logs. You use the Grantee request element to grant access to other people. The Permissions request element specifies the kind of access the grantee has to the logs.

put http://S3-eu-central-1.ionoscloud.com /{Bucket}logging Try out

Policy

Delete a bucket's policy

This implementation of the DELETE operation uses the policy subresource to delete the policy of a specified bucket. If you are using an identity other than the root user of the IONOS Cloud S3 Object Storage account that owns the bucket, the calling identity must have the DeleteBucketPolicy permissions on the specified bucket and belong to the bucket owner's account to use this operation.

If you don't have DeleteBucketPolicy permissions, IONOS Cloud S3 Object Storage returns a 403 Access Denied error. If you have the correct permissions, but you're not using an identity that belongs to the bucket owner's account, IONOS Cloud S3 Object Storage returns a 405 Method Not Allowed error.

As a security precaution, the root user of the IONOS Cloud S3 Object Storage that owns a bucket can always use this operation, even if the policy explicitly denies the root user the ability to perform this operation.

delete http://S3-eu-central-1.ionoscloud.com /{Bucket}policy Try out

Read a bucket's policy

Returns the policy of a specified bucket. If you are using an identity other than the root user of the IONOS Cloud S3 Object Storage account that owns the bucket, the calling identity must have the GetBucketPolicy permissions on the specified bucket and belong to the bucket owner's account in order to use this operation.

If you don't have GetBucketPolicy permissions, IONOS Cloud S3 Object Storage returns a 403 Access Denied error. If you have the correct permissions, but you're not using an identity that belongs to the bucket owner's account, IONOS Cloud S3 Object Storage returns a 405 Method Not Allowed error.

As a security precaution, the root user of the IONOS Cloud S3 Object Storage account that owns a bucket can always use this operation, even if the policy explicitly denies the root user the ability to perform this operation.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}policy Try out

Create a bucket's policy

Applies an IONOS Cloud S3 Object Storage bucket policy to an IONOS Cloud S3 Object Storage bucket. If you are using an identity other than the root user of the IONOS Cloud S3 Object Storage account that owns the bucket, the calling identity must have the PutBucketPolicy permissions on the specified bucket and belong to the bucket owner's account in order to use this operation.

If you don't have PutBucketPolicy permissions, IONOS Cloud S3 Object Storage returns a 403 Access Denied error. If you have the correct permissions, but you're not using an identity that belongs to the bucket owner's account, IONOS Cloud S3 Object Storage returns a 405 Method Not Allowed error.

As a security precaution, the root user of the IONOS Cloud S3 Object Storage account that owns a bucket can always use this operation, even if the policy explicitly denies the root user the ability to perform this operation.

put http://S3-eu-central-1.ionoscloud.com /{Bucket}policy Try out

Read a bucket's policy status

Retrieves the policy status for an IONOS Cloud S3 Object Storage bucket, indicating whether the bucket is public. In order to use this operation, you must have the GetBucketPolicyStatus permission.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}policyStatus Try out

Replication

Delete a bucket's replication configuration

Deletes the replication configuration from the bucket.

To use this operation, you must have permissions to perform the PutReplicationConfiguration operation. The bucket owner has these permissions by default and can grant it to others.

delete http://S3-eu-central-1.ionoscloud.com /{Bucket}replication Try out

Read a bucket's replication configuration

Returns the replication configuration of a bucket.

It can take a while to propagate the put or delete a replication configuration to all IONOS Cloud S3 Object Storage systems. Therefore, a get request soon after put or delete can return a wrong result.

This operation requires permissions for the GetReplicationConfiguration operation.

If you include the Filter element in a replication configuration, you must also include the DeleteMarkerReplication and Priority elements. The response also returns those elements.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}replication Try out

Create a bucket's replication configuration

Creates a replication configuration or replaces an existing one.

Specify the replication configuration in the request body. In the replication configuration, you provide the name of the destination bucket or buckets where you want IONOS Cloud S3 Object Storage to replicate objects, the IAM role that IONOS Cloud S3 Object Storage can assume to replicate objects on your behalf, and other relevant information.

A replication configuration must include at least one rule, and can contain a maximum of 1,000. Each rule identifies a subset of objects to replicate by filtering the objects in the source bucket. To choose additional subsets of objects to replicate, add a rule for each subset.

To specify a subset of the objects in the source bucket to apply a replication rule to, add the Filter element as a child of the Rule element. You can filter objects based on an object key prefix, one or more object tags, or both. When you add the Filter element in the configuration, you must also add the following elements: DeleteMarkerReplication, Status, and Priority.

If you are using an earlier version of the replication configuration, IONOS Cloud S3 Object Storage handles replication of delete markers differently.

Handling Replication of Encrypted Objects

By default, IONOS Cloud S3 Object Storage doesn't replicate objects that are stored at rest using server-side encryption with KMS keys. To replicate IONOS Cloud S3 Object Storage KMS-encrypted objects, add the following: SourceSelectionCriteria, SseKmsEncryptedObjects, Status, EncryptionConfiguration, and ReplicaKmsKeyID.

Permissions

To create a PutBucketReplication request, you must have PutReplicationConfiguration permissions for the bucket.

By default, a resource owner, in this case the IONOS Cloud S3 Object Storage account that created the bucket, can perform this operation. The resource owner can also grant others permissions to perform the operation.

put http://S3-eu-central-1.ionoscloud.com /{Bucket}replication Try out

Retention

Read an object's retention configuration

Retrieves an object's retention settings.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}retention Try out

Create an object retention configuration

Places an Object Retention configuration on an object. Users or accounts require the PutObjectRetention permission in order to place an Object Retention configuration on objects. Bypassing a Governance Retention configuration requires the BypassGovernanceRetention permission.

Permissions

When the Object Lock retention mode is set to compliance, you need PutObjectRetention and BypassGovernanceRetention permissions. For other requests to PutObjectRetention, only PutObjectRetention permissions are required.

put http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}retention Try out

Tagging

Delete a set of bucket tags

Deletes the tags from the bucket.

To use this operation, you must have permission to perform the PutBucketTagging operation. By default, the bucket owner has this permission and can grant this permission to others.

delete http://S3-eu-central-1.ionoscloud.com /{Bucket}tagging Try out

Read a set of bucket tags

Returns the tag set associated with the bucket.

To use this operation, you must have permission to perform the GetBucketTagging operation. By default, the bucket owner has this permission and can grant this permission to others.

GetBucketTagging has the following special error:

get http://S3-eu-central-1.ionoscloud.com /{Bucket}tagging Try out

Add a set of tags to a bucket

Sets the tags for a bucket.

When this operation sets the tags for a bucket, it will overwrite any current tags the bucket already has. You cannot use this operation to add tags to an existing list of tags.

To use this operation, you must have permissions to perform the PutBucketTagging operation. The bucket owner has this permission by default and can grant this permission to others.

PutBucketTagging has the following special errors:

put http://S3-eu-central-1.ionoscloud.com /{Bucket}tagging Try out

Delete a set of object tags

Removes the entire tag set from the specified object.

To use this operation, you must have permission to perform the DeleteObjectTagging operation.

To delete tags of a specific object version, add the versionId query parameter in the request. You will need permission for the DeleteObjectVersionTagging operation.

delete http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}tagging Try out

Read a set of object tags

Returns the tag-set of an object. You send the GET request against the tagging subresource associated with the object.

To use this operation, you must have permission to perform the GetObjectTagging operation. By default, the GET operation returns information about current version of an object. For a versioned bucket, you can have multiple versions of an object in your bucket. To retrieve tags of any other version, use the versionId query parameter. You also need permission for the GetObjectVersionTagging operation.

By default, the bucket owner has this permission and can grant this permission to others.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}tagging Try out

Add a set of tags to an object

Sets the supplied tag-set to an object that already exists in a bucket.

A tag is a key-value pair. You can associate tags with an object by sending a PUT request against the tagging subresource that is associated with the object. You can retrieve tags by sending a GET request.

Note that IONOS Cloud S3 Object Storage limits the maximum number of tags to 10 tags per object.

To use this operation, you must have permission to perform the PutObjectTagging operation. By default, the bucket owner has this permission and can grant this permission to others.

To put tags of any other version, use the versionId query parameter. You also need permission for the PutObjectVersionTagging operation.

Special Errors

put http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}tagging Try out

Torrent

Read torrent files from a bucket

Returns torrent files from a bucket. BitTorrent can save you bandwidth when you're distributing large files.

You can get torrent only for objects that are less than 5 GB in size, and that are not encrypted using server-side encryption with a customer-provided encryption key.

To use this method, you must have READ access to the object.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}torrent Try out

Uploads

Abort a multipart upload

This operation aborts a multipart upload. After a multipart upload is aborted, no additional parts can be uploaded using that upload ID. The storage consumed by any previously uploaded parts will be freed. However, if any part uploads are currently in progress, those part uploads might or might not succeed. As a result, it might be necessary to abort a given multipart upload multiple times in order to completely free all storage consumed by all parts.

delete http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}uploadId Try out

Complete a multipart upload

Completes a multipart upload by assembling previously uploaded parts.

After successfully uploading all relevant parts of an upload, you call this operation to complete the upload. When IONOS Cloud S3 Object Storage receives this request, it concatenates all the parts in ascending order by part number to create a new object. The parts list must be included in the Complete Multipart Upload request. You must ensure that the parts list is complete. This operation concatenates the parts that you provide in the list. For each part in the list, you must provide the part number and the ETag value, returned after that part was uploaded.

A Complete Multipart Upload request could take several minutes to process. After IONOS Cloud S3 Object Storage begins processing the request, it sends an HTTP response header indicating a 200 OK response. While processing is in progress, IONOS Cloud S3 Object Storage sends white space characters on a regular basis to keep the connection from timing out. Because a request may fail after receiving the initial 200 OK response, it is advisable to check the response body to establish whether the request was successful.

CompleteMultipartUpload has the following special errors:

post http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}uploadId Try out

List parts of a multipart upload

Lists the parts that have been uploaded for a specific multipart upload. This operation must include the upload ID, which you obtain by sending the initiate multipart upload request. This request returns a maximum of 1,000 uploaded parts. The default number of parts returned is 1,000 parts. You can restrict the number of parts returned by specifying the max-parts request parameter. If your multipart upload consists of more than 1,000 parts, the response returns an IsTruncated field with the value of true, and a NextPartNumberMarker element. In subsequent ListParts requests you can include the part-number-marker query string parameter and set its value to the NextPartNumberMarker field value from the previous response.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}uploadId Try out

Upload a part of an object

Uploads a part in a multipart upload.

In this operation, you provide part data in your request. However, you have an option to specify your existing IONOS Cloud S3 Object Storage object as a data source for the part you are uploading. To upload a part from an existing object, you use the UploadPartCopy operation.

You must initiate a multipart upload (see CreateMultipartUpload) before you can upload any part. In response to your initiate request, IONOS Cloud S3 Object Storage returns an upload ID, a unique identifier, that you must include in your upload part request.

Part numbers can be any number from 1 to 10,000, inclusive. A part number uniquely identifies a part and also defines its position within the object being created. If you upload a new part using the same part number that was used with a previous part, the previously uploaded part is overwritten. Each part must be at least 5 MB in size, except the last part. There is no size limit on the last part of your multipart upload.

To ensure that data is not corrupted when traversing the network, specify the Content-MD5 header in the upload part request. IONOS Cloud S3 Object Storage checks the part data against the provided MD5 value. If they do not match, IONOS Cloud S3 Object Storage returns an error.

If the upload request is signed with Signature Version 4, then IONOS Cloud S3 Object Storage S3 uses the x-amz-content-sha256 header as a checksum instead of Content-MD5.

Note: After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, IONOS Cloud S3 Object Storage frees up the parts storage and stops charging you for the parts storage.

put http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}uploadId Try out

Create / Initiate a multipart upload

This operation initiates a multipart upload and returns an upload ID. This upload ID is used to associate all of the parts in the specific multipart upload. You specify this upload ID in each of your subsequent upload part requests. You also include this upload ID in the final request to either complete or abort the multipart upload request.

post http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}uploads Try out

List active multipart uploads

This operation lists in-progress multipart uploads. An in-progress multipart upload is a multipart upload that has been initiated using the Initiate Multipart Upload request, but has not yet been completed or aborted.

This operation returns at most 1,000 multipart uploads in the response. 1,000 multipart uploads is the maximum number of uploads a response can include, which is also the default value. You can further limit the number of uploads in a response by specifying the max-uploads parameter in the response. If additional multipart uploads satisfy the list criteria, the response will contain an IsTruncated element with the value true. To list the additional multipart uploads, use the key-marker and upload-id-marker request parameters.

In the response, the uploads are sorted by key. If your application has initiated more than one multipart upload using the same object key, then uploads in the response are first sorted by key. Additionally, uploads are sorted in ascending order within each key by the upload initiation time.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}uploads Try out

Upload the copy of an object

Uploads a part by copying data from an existing object as data source. You specify the data source by adding the request header x-amz-copy-source in your request and a byte range by adding the request header x-amz-copy-source-range in your request.

The minimum allowable part size for a multipart upload is 5 MB.

Instead of using an existing object as part data, you might use the UploadPart operation and provide data in your request.

You must initiate a multipart upload before you can upload any part. In response to your initiate request. IONOS Cloud S3 Object Storage returns a unique identifier, the upload ID, that you must include in your upload part request.

put http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}x-amz-copy-source&partNumber&uploadId Try out

Versions

Read the metadata of the objects in a bucket

Returns metadata about all versions of the objects in a bucket. You can also use request parameters as selection criteria to return metadata about a subset of all the object versions.

To use this operation, you must have permissions to perform the ListBucketVersions operation. Be aware of the name difference.

A 200 OK response can contain valid or invalid XML. Make sure to design your application to parse the contents of the response and handle it appropriately.

To use this operation, you must have READ access to the bucket.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}versions Try out

Versioning

Read a bucket's version

Returns the versioning state of a bucket.

To retrieve the versioning state of a bucket, you must be the bucket owner.

This implementation also returns the MFA Delete status of the versioning state. If the MFA Delete status is enabled, the bucket owner must use an authentication device to change the versioning state of the bucket.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}versioning Try out

Create a bucket's versioning state configuration

Sets the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner.

You can set the versioning state with one of the following values:

Enabled—Enables versioning for the objects in the bucket. All objects added to the bucket receive a unique version ID.

Suspended—Disables versioning for the objects in the bucket. All objects added to the bucket receive the version ID null.

If the versioning state has never been set on a bucket, it has no versioning state; a GetBucketVersioning request does not return a versioning state value.

If the bucket owner enables MFA Delete in the bucket versioning configuration, the bucket owner must include the x-amz-mfa request header and the Status and the MfaDelete request elements in a request to set the versioning state of the bucket.

If you have an object expiration lifecycle policy in your non-versioned bucket and you want to maintain the same permanent delete behavior when you enable versioning, you must add a noncurrent expiration policy. The noncurrent expiration lifecycle policy will manage the deletes of the noncurrent object versions in the version-enabled bucket. (A version-enabled bucket maintains one current and zero or more noncurrent object versions.)

put http://S3-eu-central-1.ionoscloud.com /{Bucket}versioning Try out

Website

Delete a website configuration

This operation removes the website configuration for a bucket. IONOS Cloud S3 Object Storage returns a 200 OK response upon successfully deleting a website configuration on the specified bucket. You will get a 200 OK response if the website configuration you are trying to delete does not exist on the bucket. IONOS Cloud S3 Object Storage returns a 404 response if the bucket specified in the request does not exist.

This DELETE operation requires the DeleteBucketWebsite permission. By default, only the bucket owner can delete the website configuration attached to a bucket. However, bucket owners can grant other users permission to delete the website configuration by writing a bucket policy granting them the DeleteBucketWebsite permission.

delete http://S3-eu-central-1.ionoscloud.com /{Bucket}website Try out

Read a website configuration

Returns the website configuration for a bucket.

This GET operation requires the GetBucketWebsite permission. By default, only the bucket owner can read the bucket website configuration. However, bucket owners can allow other users to read the website configuration by writing a bucket policy granting them the GetBucketWebsite permission.

get http://S3-eu-central-1.ionoscloud.com /{Bucket}website Try out

Create a website configuration

Sets the configuration of the website that is specified in the website subresource. To configure a bucket as a website, you can add this subresource on the bucket with website configuration information such as the file name of the index document and any redirect rules.

This PUT operation requires the PutBucketWebsite permission. By default, only the bucket owner can configure the website attached to a bucket; however, bucket owners can allow other users to set the website configuration by writing a bucket policy that grants them the PutBucketWebsite permission.

To redirect all website requests sent to the bucket's website endpoint, you add a website configuration with the following elements. Because all requests are sent to another website, you don't need to provide index document name for the bucket.

If you want granular control over redirects, you can use the following elements to add routing rules that describe conditions for redirecting requests and information about the redirect destination. In this case, the website configuration must provide an index document for the bucket, because some requests might not be redirected.

put http://S3-eu-central-1.ionoscloud.com /{Bucket}website Try out

Default Paths

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}uploadId Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}x-amz-copy-source Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket} Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}uploads Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}cors Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}encryption Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}policy Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}replication Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}tagging Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}website Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key} Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}tagging Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}delete Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}acl Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}lifecycle Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}location Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}logging Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}policyStatus Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}versioning Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}acl Try out


parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}object-lock Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}retention Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}torrent Try out

parameters http://S3-eu-central-1.ionoscloud.com / Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}uploads Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}versions Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}list-type=2 Try out

parameters http://S3-eu-central-1.ionoscloud.com /{Bucket}/{Key}x-amz-copy-source&partNumber&uploadId Try out