IBM Cloud Object Storage S3 API | IBM Cloud API Docs

Introduction

Last updated: 2024-07-16

The IBM Cloud® Object Storage API is a REST-based API for reading and writing objects. It uses IBM Cloud® Identity and Access Management for authentication/authorization, and supports a subset of the S3 API for easy migration of applications to IBM Cloud.

For details about using Object Storage, see the IBM Cloud docs.

Object Storage is a global service. The location of data is determined by the region where a bucket is created, and subsequent requests to that bucket must be sent to the same corresponding endpoint. The examples shown here assume that requests are sent to the US South region. For more details about selecting endpoints Object Storage, see the IBM Cloud docs.

Java developers can use this SDK to interact with Object Storage. The SDK is a fork of the official AWS SDK for Java. For more information, see the COS SDK for Java API Reference.

JavaScript developers can use this SDK to interact with Object Storage. The SDK is a fork of the official AWS SDK for JavaScript. For more information, see the COS SDK for JavaScript API Reference.

The SDK is supported on Node versions 4.x and later.

Python developers can use this SDK to interact with Object Storage. The SDK is a fork of the boto3 library. For more information, see the COS SDK for Python API Reference.

Go developers can use this SDK to interact with Object Storage. The SDK is a fork of the official AWS SDK for Go. For more information, see the COS SDK for Go API Reference.

The SDK supports Go versions 1.10 - 1.12.

The code examples on this tab use the client library that is provided for Java.

Maven

<dependency>
  <groupId>com.ibm.cos</groupId>
  <artifactId>ibm-cos-java-sdk</artifactId>
</dependency>
Copy to clipboard

GitHub

https://github.com/IBM/ibm-cos-sdk-java

The code examples on this tab use the client library that is provided for Node.js.

Installation

npm install ibm-cos-sdk

GitHub

https://github.com/IBM/ibm-cos-sdk-js

The code examples on this tab use the client library that is provided for Python.

Installation

pip install --upgrade ibm-cos-sdk

GitHub

https://github.com/IBM/ibm-cos-sdk-python

The code examples on this tab use the client library that is provided for Go.

go get -u github.com/IBM/ibm-cos-sdk-go

GitHub

https://github.com/IBM/ibm-cos-sdk-go

Error handling

The Object Storage service uses standard HTTP response codes to indicate if a method completes successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

For more details about response codes Object Storage, see the IBM Cloud docs.

This operation lists all buckets within the specified service instance, regardless of location. Note that while any endpoint may be used to list all buckets, any operations that target a specific bucket must use the appropriate endpoint for that bucket's location.

GET /

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.account.get_account_buckets

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.instance.list

Request

Custom Headers

ibm-service-instance-id
Required*
string
This header references the service instance that contains buckets to list. This value can be either the full Cloud Resource Name (CRN) or just the GUID segment that identifies the service instance.

Example: d6f76k03-6k4f-4a82-n165-697654o63903

Query Parameters

extended
boolean
If supplied, the returned listing will also include the provisioning code (LocationConstraint) for each bucket. This allows for inferring a bucket's location and associated endpoint.

Possible values: allows empty value

List buckets

curl -X "GET" "https://s3.$REGION.cloud-object-storage.appdomain.cloud/"      -H "Authorization: Bearer $IAM_TOKEN"      -H "ibm-service-instance-id: $SERVICE_INSTANCE_ID"
Copy to clipboard

List buckets with provisioning codes

curl -X "GET" "https://s3.$REGION.cloud-object-storage.appdomain.cloud?extended"      -H "Authorization: Bearer $IAM_TOKEN"      -H "ibm-service-instance-id: $SERVICE_INSTANCE_ID"
Copy to clipboard

List buckets

public static void getBuckets() {
  System.out.println("Retrieving list of buckets");

  final List<Bucket> bucketList = _cos.listBuckets();
  for (final Bucket bucket : bucketList) {
    System.out.printf("Bucket Name: %s\n", bucket.getName());
  }
}
Copy to clipboard

List buckets

def get_buckets():
    print("Retrieving list of buckets")
    try:
        buckets = cos.buckets.all()
        for bucket in buckets:
            print("Bucket Name: {0}".format(bucket.name))
    except ClientError as be:
        print("CLIENT ERROR: {0}\n".format(be))
    except Exception as e:
        print("Unable to retrieve list buckets: {0}".format(e))
Copy to clipboard

List buckets

function getBuckets() {
    console.log('Retrieving list of buckets');
    return cos.listBuckets()
    .promise()
    .then((data) => {
        if (data.Buckets != null) {
            for (var i = 0; i < data.Buckets.length; i++) {
                console.log(`Bucket Name: ${data.Buckets[i].Name}`);
            }
        }
    })
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}
Copy to clipboard

List buckets

func main() {

    // Create client
    sess := session.Must(session.NewSession())
    client := s3.New(sess, conf)

    // Call Function
    d, _ := client.ListBuckets(&s3.ListBucketsInput{})
    fmt.Println(d)
}                 
Copy to clipboard

Response

Response Body

BucketListing

This operation returns a list of all buckets within a service instance.

Status Code

200
Success

Example responses

Status 200: Example of a normal bucket listing response.

Success

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListAllMyBucketsResult>
  <Owner>
    <ID>{account-id}</ID>
    <DisplayName>{account-id}</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <Name>bucket-27200-lwx4cfvcue</Name>
      <CreationDate>2016-08-18T14:21:36.593Z</CreationDate>
    </Bucket>
    <Bucket>
      <Name>bucket-27590-drqmydpfdv</Name>
      <CreationDate>2016-08-18T14:22:32.366Z</CreationDate>
    </Bucket>
    <Bucket>
      <Name>bucket-27852-290jtb0n2y</Name>
      <CreationDate>2016-08-18T14:23:03.141Z</CreationDate>
    </Bucket>
    <Bucket>
      <Name>bucket-28731-k0o1gde2rm</Name>
      <CreationDate>2016-08-18T14:25:09.599Z</CreationDate>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>
Copy to clipboard

Status 200: Example of an extended bucket listing response.

Success

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Owner>
    <ID>{account-id}</ID>
    <DisplayName>{account-id}</DisplayName>
  </Owner>
  <IsTruncated>false</IsTruncated>
  <MaxKeys>1000</MaxKeys>
  <Prefix/>
  <Marker/>
  <Buckets>
    <Bucket>
      <Name>bucket-27200-lwx4cfvcue</Name>
      <CreationDate>2016-08-18T14:21:36.593Z</CreationDate>
      <LocationConstraint>us-south-standard</LocationConstraint>
      <CreationTemplateId>dca204eb-72b5-4e2a-a142-808d2a5c2a87</CreationTemplateId>
    </Bucket>
    <Bucket>
      <Name>bucket-27590-drqmydpfdv</Name>
      <CreationDate>2016-08-18T14:22:32.366Z</CreationDate>
      <LocationConstraint>seo01-standard</LocationConstraint>
      <CreationTemplateId>dca204eb-72b5-4e2a-a142-808d2a5c2a87</CreationTemplateId>
    </Bucket>
    <Bucket>
      <Name>bucket-27852-290jtb0n2y</Name>
      <CreationDate>2016-08-18T14:23:03.141Z</CreationDate>
      <LocationConstraint>eu-standard</LocationConstraint>
      <CreationTemplateId>dca204eb-72b5-4e2a-a142-808d2a5c2a87</CreationTemplateId>
    </Bucket>
    <Bucket>
      <Name>bucket-28731-k0o1gde2rm</Name>
      <CreationDate>2016-08-18T14:25:09.599Z</CreationDate>
      <LocationConstraint>us-cold</LocationConstraint>
      <CreationTemplateId>dca204eb-72b5-4e2a-a142-808d2a5c2a87</CreationTemplateId>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>
Copy to clipboard

To create a bucket, you must create a COS service instance, and create an API key or HMAC credentials to authenticate requests.

Bucket names must be globally unique and DNS-compliant; names between 3 and 63 characters long must be made of lowercase letters, numbers, and dashes. Bucket names must begin and end with a lowercase letter or number. Bucket names resembling IP addresses are not allowed. Bucket names must be unique because all buckets in the public cloud share a global namespace, allowing access to buckets without the need to provide any service instance or account information. It is not possible to create a bucket with a name beginning with cosv1- or account- as these prefixes are reserved by the system.

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 using any of the three networks: public, private, or direct. Any requests targeting an existing bucket using an endpoint with an incorrect location will result in a 404 NoSuchKey error.

All data in IBM Cloud Object Storage is encrypted at rest. This technology individually encrypts each object by using per-object generated keys. These keys are secured and reliably stored by using the same Information Dispersal Algorithms that protect object data by using an All-or-Nothing Transform (AONT). Key data is impossible to recover, even if individual nodes or hard disks are compromised. If it is necessary to control the encryption keys used, an IBM Key Protect or Hyper Protect Crypto Services root key CRN can be provided during bucket creation.

It is possible to create a bucket with a "storage class" that alters the way storage charges are incurred based on frequency of access. This can be helpful when dealing with "cool" data that might need to be accessed without the delay of restoring from an archive, but is unlikely to be accessed frequently. A provisioning code can be passed in the S3 API LocationConstraint parameter to specify the storage class of a new bucket. A storage class can not be altered after a bucket is created.

The S3 API concept of a "bucket owner" is not an individual user, but instead is considered to be the Service Instance associated with the bucket.

PUT /{Bucket}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.put_bucket

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket.create

Request

Custom Headers

ibm-service-instance-id
string
This header references the service instance where the bucket will be created and to which data usage will be billed. It is required when using IAM tokens, but it should not be used when using hmac credentials. This value can be either the full Cloud Resource Name (CRN) or just the GUID segment that identifies the service instance.

Example: d6f76k03-6k4f-4a82-n165-697654o63903
ibm-sse-kp-encryption-algorithm
string
The algorithm and key size used to for the managed encryption root key. Required if ibm-sse-kp-customer-root-key-crn is also present.

Allowable values: [AES256]
Example: AES256
ibm-sse-kp-customer-root-key-crn
string
The CRN of the root key used to encrypt the bucket. Required if ibm-sse-kp-encryption-algorithm is also present.

Example: crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d
x-amz-acl
string
The canned ACL to apply to the bucket. This header should not be used - instead create an IAM policy to grant public access to a bucket.

Allowable values: [private,public-read]

Path Parameters

Bucket
Required*
string
The name of the bucket to create.

Example: my-new-bucket

Request Body

text/xmlobject

Create a bucket in the US South region

curl -X "PUT" "https://s3.us-south.cloud-object-storage.appdomain.cloud/$NEW_BUCKET"      -H "Authorization: Bearer $IAM_TOKEN"      -H "ibm-service-instance-id: $SERVICE_INSTANCE_ID"
Copy to clipboard

Create a bucket with Key Protect in a Smart Tier billing class in the US South region

curl -X "PUT" "https://s3.us-south.cloud-object-storage.appdomain.cloud/$NEW_BUCKET"      -H "Authorization: Bearer $IAM_TOKEN"      -H "ibm-service-instance-id: $SERVICE_INSTANCE_ID"      -H "ibm-sse-kp-encryption-algorithm: AES256"      -H "ibm-sse-kp-customer-root-key-crn: $KP_ROOT_KEY_CRN"      -d "<CreateBucketConfiguration>
           <LocationConstraint>us-south-smart</LocationConstraint>
         </CreateBucketConfiguration>"
Copy to clipboard

Create a bucket

public static void createBucket(String bucketName) {
    System.out.printf("Creating new bucket: %s\n", bucketName);
    _cos.createBucket(bucketName);
    System.out.printf("Bucket: %s created!\n", bucketName);
}
Copy to clipboard

Create a bucket

def create_bucket(bucket_name):
    print("Creating new bucket: {0}".format(bucket_name))
    try:
        cos.Bucket(bucket_name).create(
            CreateBucketConfiguration={
                "LocationConstraint":COS_BUCKET_LOCATION
            }
        )
        print("Bucket: {0} created!".format(bucket_name))
    except ClientError as be:
        print("CLIENT ERROR: {0}\n".format(be))
    except Exception as e:
        print("Unable to create bucket: {0}".format(e))
Copy to clipboard

Create a bucket

function createBucket(bucketName) {
    console.log(`Creating new bucket: ${bucketName}`);
    return cos.createBucket({
        Bucket: bucketName,
        CreateBucketConfiguration: {
          LocationConstraint: 'us-standard'
        },        
    }).promise()
    .then((() => {
        console.log(`Bucket: ${bucketName} created!`);
    }))
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}
Copy to clipboard

Create a bucket

func main() {

    // Create client
    sess := session.Must(session.NewSession())
    client := s3.New(sess, conf)

    // Bucket Names
    newBucket := "<NEW_BUCKET_NAME>"
    newColdBucket := "<NEW_COLD_BUCKET_NAME>"

    input := &s3.CreateBucketInput{
        Bucket: aws.String(newBucket),
    }
    client.CreateBucket(input)

    input2 := &s3.CreateBucketInput{
        Bucket: aws.String(newColdBucket),
        CreateBucketConfiguration: &s3.CreateBucketConfiguration{
            LocationConstraint: aws.String("us-cold"),
        },
    }
    client.CreateBucket(input2)

    d, _ := client.ListBuckets(&s3.ListBucketsInput{})
    fmt.Println(d)
}
Copy to clipboard

Response

Status Code

200
Success
409
BucketAlreadyExists

No Sample Response

This method does not specify any sample responses.

Only empty buckets may be deleted. A bucket name is returned to the available namespace approximately 10 minutes after deletion.

DELETE /{Bucket}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.delete_bucket

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket.delete

Request

Path Parameters

Bucket
Required*
string
The name of the bucket to delete.

Delete a bucket in the US South region

curl -X "DELETE" "https://s3.us-south.cloud-object-storage.appdomain.cloud/$BUCKET"      -H "Authorization: Bearer $IAM_TOKEN" \  
Copy to clipboard

Delete a bucket

public static void deleteBucket(String bucketName) {
    System.out.printf("Deleting bucket: %s\n", bucketName);
    _cos.deleteBucket(bucketName);
    System.out.printf("Bucket: %s deleted!\n", bucketName);
}
Copy to clipboard

Delete a bucket

def delete_bucket(bucket_name):
    print("Deleting bucket: {0}".format(bucket_name))
    try:
        cos.Bucket(bucket_name).delete()
        print("Bucket: {0} deleted!".format(bucket_name))
    except ClientError as be:
        print("CLIENT ERROR: {0}\n".format(be))
    except Exception as e:
        print("Unable to delete bucket: {0}".format(e))
Copy to clipboard

Delete a bucket

function deleteBucket(bucketName) {
    console.log(`Deleting bucket: ${bucketName}`);
    return cos.deleteBucket({
        Bucket: bucketName
    }).promise()
    .then(() => {
        console.log(`Bucket: ${bucketName} deleted!`);
    })
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}
Copy to clipboard

Delete a bucket

func main() {

    // Bucket Name
    bucket := "<BUCKET_NAME>"

    // Create client
    sess := session.Must(session.NewSession())
    client := s3.New(sess, conf)

    input := &s3.DeleteBucketInput{
        Bucket: aws.String(bucket),
    }
    d, _ := client.DeleteBucket(input)
    fmt.Println(d)
}
Copy to clipboard

Response

Status Code

204
Success

No Sample Response

This method does not specify any sample responses.

This request is useful for checking whether a bucket has Key Protect enabled.

HEAD /{Bucket}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.head
cloud-object-storage.bucket.list_crk_id

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-metadata.read

Request

Path Parameters

Bucket
Required*
string
The name of the bucket being checked. The bucket must exist in the location specified by the endpoint for the request to succeed.

Fetch a bucket's headers

curl -X "GET" "https://s3.$REGION.cloud-object-storage.appdomain.cloud/$NEW_BUCKET"      -H "Authorization: Bearer $IAM_TOKEN"      -H "ibm-service-instance-id: $SERVICE_INSTANCE_ID"    
Copy to clipboard

Fetch a bucket's headers

public HeadBucketRequest(String bucketName)
Copy to clipboard

Fetch a bucket's headers

response = client.head_bucket(
    Bucket='string',
    ExpectedBucketOwner='string'
)

Fetch a bucket's headers

var params = {
  Bucket: 'STRING_VALUE' /* required */
};
s3.headBucket(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});
Copy to clipboard

Fetch a bucket's headers

func main() {

    // Bucket Name
    bucket := "<BUCKET_NAME>"

    sess := session.Must(session.NewSession())
    client := s3.New(sess, conf)

    d, _ := client.HeadBucket(bucket)
    fmt.Println(d)
}
Copy to clipboard

Response

Status Code

200
Success
404
NoSuchBucket

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. Make sure to design your application to parse the contents of the response and handle it appropriately. This version (v1) uses a marker parameter to list objects starting with a given object. Version 2 of this API provides a continuation token instead, making it a bit more straightforward to chain listing requests for buckets with large numbers of objects.

GET /{Bucket}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.get

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket.list

Request

Path Parameters

Bucket
Required*
string
The name of the bucket to be listed.

Query Parameters

delimiter
string
A delimiter is a character you use to group keys.
encoding-type
string
Requests COS to url-encode the object keys in the response. Object keys 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 COS encodes the keys in the response.

Allowable values: [url]
marker
string
Specifies the key to start with when listing objects in a bucket.
max-keys
integer
Sets the maximum number of keys returned in the response. By default the API returns up to 1,000 key names. The response might contain fewer keys but will never contain more.
prefix
string
Limits the response to keys that begin with the specified prefix.

List objects in a bucket (v1)

curl -X "GET" "https://s3.$REGION.cloud-object-storage.appdomain.cloud/$BUCKET"      -H "Authorization: Bearer $IAM_TOKEN" 
Copy to clipboard

List objects in a bucket (v1)

public static void getBucketContents(String bucketName) {
    System.out.printf("Retrieving bucket contents from: %s\n", bucketName);

    ObjectListing objectListing = _cos.listObjects(new ListObjectsRequest().withBucketName(bucketName));
    for (S3ObjectSummary objectSummary : objectListing.getObjectSummaries()) {
        System.out.printf("Item: %s (%s bytes)\n", objectSummary.getKey(), objectSummary.getSize());
    }
}
Copy to clipboard

List objects in a bucket (v1)

def get_bucket_contents(bucket_name):
    print("Retrieving bucket contents from: {0}".format(bucket_name))
    try:
        files = cos.Bucket(bucket_name).objects.all()
        for file in files:
            print("Item: {0} ({1} bytes).".format(file.key, file.size))
    except ClientError as be:
        print("CLIENT ERROR: {0}\n".format(be))
    except Exception as e:
        print("Unable to retrieve bucket contents: {0}".format(e))
Copy to clipboard

List objects in a bucket (v1)

function getBucketContents(bucketName) {
    console.log(`Retrieving bucket contents from: ${bucketName}`);
    return cos.listObjects(
        {Bucket: bucketName},
    ).promise()
    .then((data) => {
        if (data != null && data.Contents != null) {
            for (var i = 0; i < data.Contents.length; i++) {
                var itemKey = data.Contents[i].Key;
                var itemSize = data.Contents[i].Size;
                console.log(`Item: ${itemKey} (${itemSize} bytes).`)
            }
        }    
    })
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}
Copy to clipboard

List objects in a bucket (v1)

func main() {

    // Create client
    sess := session.Must(session.NewSession())
    client := s3.New(sess, conf)

    // Bucket Name
    Bucket := "<BUCKET_NAME>"

    // Call Function
    Input := &s3.ListObjectsInput{
            Bucket: aws.String(Bucket),
        }

    l, e := client.ListObjects(Input)
    fmt.Println(l)
    fmt.Println(e) // prints "<nil>"
}
Copy to clipboard

Response

Response Body

ListObjectsOutput

Status Code

200
Success
404
NoSuchBucket

Example responses

Status 200: Example of a normal bucket listing response.

Success

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>apiary</Name>
  <Prefix/>
  <Marker/>
  <MaxKeys>1000</MaxKeys>
  <Delimiter/>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>drone-bee</Key>
    <LastModified>2016-08-25T17:38:38.549Z</LastModified>
    <ETag>"0cbc6611f5540bd0809a388dc95a615b"</ETag>
    <Size>4</Size>
    <Owner>
      <ID>{account-id}</ID>
      <DisplayName>{account-id}</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <Contents>
    <Key>soldier-bee</Key>
    <LastModified>2016-08-25T17:49:06.006Z</LastModified>
    <ETag>"37d4c94839ee181a2224d6242176c4b5"</ETag>
    <Size>11</Size>
    <Owner>
      <ID>{account-id}</ID>
      <DisplayName>{account-id}</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <Contents>
    <Key>worker-bee</Key>
    <LastModified>2016-08-25T17:46:53.288Z</LastModified>
    <ETag>"d34d8aada2996fc42e6948b926513907"</ETag>
    <Size>467</Size>
    <Owner>
      <ID>{account-id}</ID>
      <DisplayName>{account-id}</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>
Copy to clipboard

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. Make sure to design your application to parse the contents of the response and handle it appropriately.

GET /{Bucket}?list-type=2

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.get

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket.list

Request

Path Parameters

Bucket
Required*
string
Bucket name to list.

Query Parameters

list-type
Required*
string
Allowable values: [2]
delimiter
string
A delimiter is a character you use to group keys.
encoding-type
string
Encoding type used by IBM COS to encode object keys in the response.

Allowable values: [url]
max-keys
integer
Sets the maximum number of keys returned in the response. By default the API returns up to 1,000 key names. The response might contain fewer keys but will never contain more.
prefix
string
Limits the response to keys that begin with the specified prefix.
continuation-token
string
ContinuationToken indicates IBM COS that the list is being continued on this bucket with a token. ContinuationToken is obfuscated and is not a real key.
fetch-owner
boolean
The owner field (Service Instance ID) is not present in listV2 by default, if you want to return the Service Instance ID with each key in the result, then set the fetch owner field to true.
start-after
string
StartAfter is where you want IBM COS to start listing from. IBM COS starts listing after this specified key. StartAfter can be any key in the bucket.

List objects in a bucket (v2)

curl -X "GET" "https://s3.$REGION.cloud-object-storage.appdomain.cloud/$BUCKET?list-type=2"      -H "Authorization: Bearer $IAM_TOKEN" 
Copy to clipboard

List objects in a bucket (v2)

def get_bucket_contents_v2(bucket_name, max_keys):
    print("Retrieving bucket contents from: {0}".format(bucket_name))
    try:
        # create client object
        cos_cli = ibm_boto3.client("s3",
            ibm_api_key_id=COS_API_KEY_ID,
            ibm_service_instance_id=COS_SERVICE_CRN,
            config=Config(signature_version="oauth"),
            endpoint_url=COS_ENDPOINT)

        more_results = True
        next_token = ""

        while (more_results):
            response = cos_cli.list_objects_v2(Bucket=bucket_name, MaxKeys=max_keys, ContinuationToken=next_token)
            files = response["Contents"]
            for file in files:
                print("Item: {0} ({1} bytes).".format(file["Key"], file["Size"]))

            if (response["IsTruncated"]):
                next_token = response["NextContinuationToken"]
                print("...More results in next batch!\n")
            else:
                more_results = False
                next_token = ""

    except ClientError as be:
        print("CLIENT ERROR: {0}\n".format(be))
    except Exception as e:
        print("Unable to retrieve bucket contents: {0}".format(e))
Copy to clipboard

List objects in a bucket (v2)

var params = {
  Bucket: 'STRING_VALUE', /* required */
  ContinuationToken: 'STRING_VALUE',
  Delimiter: 'STRING_VALUE',
  EncodingType: url,
  FetchOwner: true || false,
  MaxKeys: 'NUMBER_VALUE',
  Prefix: 'STRING_VALUE',
  StartAfter: 'STRING_VALUE'
};
s3.listObjectsV2(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});
Copy to clipboard

List objects in a bucket (v2)

func main() {

    // Create client
    sess := session.Must(session.NewSession())
    client := s3.New(sess, conf)

    // Bucket Name
    Bucket := "<BUCKET_NAME>"

    // Call Function
    Input := &s3.ListObjectsV2Input{
            Bucket: aws.String(Bucket),
        }

    l, e := client.ListObjectsV2(Input)
    fmt.Println(l)
    fmt.Println(e) // prints "<nil>"
}
Copy to clipboard

Response

Response Body

ListObjectsV2Output

Status Code

200
Success
404
NoSuchBucket

Example responses

Status 200: Example of a typical object listing response (version 1).

Success

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>apiary</Name>
  <Prefix/>
  <ContinuationToken>1dPe45g5uuxjyASPegLq80sQsZKL5OB2by4Iz_7YGR5NjiOENBPZXqvKJN6_PgKGVzZYTlws7qqdWaMklzb8HX2iDxxl72ane3rUFQrvNMeIih49MZ4APUjrAuYI83KxSMmfKHGZyKallFkD5N6PwKg</ContinuationToken>
  <NextContinuationToken>1a8j20CqowRrM4epIQ7fTBuyPZWZUeA8Epog16wYu9KhAPNoYkWQYhGURsIQbll1lP7c-OO-V5Vyzu6mogiakC4NSwlK4LyRDdHQgY-yPH4wMB76MfQR61VyxI4TJLxIWTPSZA0nmQQWcuV2mE4jiDA</NextContinuationToken>
  <KeyCount>1</KeyCount>
  <MaxKeys>1</MaxKeys>
  <Delimiter/>
  <IsTruncated>true</IsTruncated>
  <Contents>
    <Key>soldier-bee</Key>
    <LastModified>2016-08-25T17:49:06.006Z</LastModified>
    <ETag>"37d4c94839ee181a2224d6242176c4b5"</ETag>
    <Size>11</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>       
Copy to clipboard

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. Make sure to design your application to parse the contents of the response and handle it appropriately.

GET /{Bucket}?list-object=versions

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.get.versions

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket.list.versions

Request

Path Parameters

Bucket
Required*
string
Bucket name to list.

Query Parameters

list-type
Required*
string
Allowable values: [2]
delimiter
string
A delimiter is a character you use to group keys.
encoding-type
string
Encoding type used by IBM COS to encode object keys in the response.

Allowable values: [url]
key-marker
string
Key marker specifies the starting object for listing.

Allowable values: [url]
max-keys
integer
Sets the maximum number of keys returned in the response. By default the API returns up to 1,000 key names. The response might contain fewer keys but will never contain more.
prefix
string
Limits the response to keys that begin with the specified prefix.
version-id-marker
string
Version ID marker specifies the starting object version for listing.

List object versions

curl -X "GET" "https://s3.$REGION.cloud-object-storage.appdomain.cloud/$BUCKET?list-type=2"      -H "Authorization: Bearer $IAM_TOKEN" 
Copy to clipboard

List object versions

def get_bucket_contents_v2(bucket_name, max_keys):
    print("Retrieving bucket contents from: {0}".format(bucket_name))
    try:
        # create client object
        cos_cli = ibm_boto3.client("s3",
            ibm_api_key_id=COS_API_KEY_ID,
            ibm_service_instance_id=COS_SERVICE_CRN,
            config=Config(signature_version="oauth"),
            endpoint_url=COS_ENDPOINT)

        more_results = True
        next_token = ""

        while (more_results):
            response = cos_cli.list_objects_v2(Bucket=bucket_name, MaxKeys=max_keys, ContinuationToken=next_token)
            files = response["Contents"]
            for file in files:
                print("Item: {0} ({1} bytes).".format(file["Key"], file["Size"]))

            if (response["IsTruncated"]):
                next_token = response["NextContinuationToken"]
                print("...More results in next batch!\n")
            else:
                more_results = False
                next_token = ""

    except ClientError as be:
        print("CLIENT ERROR: {0}\n".format(be))
    except Exception as e:
        print("Unable to retrieve bucket contents: {0}".format(e))
Copy to clipboard

List object versions

var params = {
  Bucket: 'STRING_VALUE', /* required */
  ContinuationToken: 'STRING_VALUE',
  Delimiter: 'STRING_VALUE',
  EncodingType: url,
  FetchOwner: true || false,
  MaxKeys: 'NUMBER_VALUE',
  Prefix: 'STRING_VALUE',
  StartAfter: 'STRING_VALUE'
};
s3.listObjectsV2(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});
Copy to clipboard

List object versions

func main() {

    // Create client
    sess := session.Must(session.NewSession())
    client := s3.New(sess, conf)

    // Bucket Name
    Bucket := "<BUCKET_NAME>"

    // Call Function
    Input := &s3.ListObjectsV2Input{
            Bucket: aws.String(Bucket),
        }

    l, e := client.ListObjectsV2(Input)
    fmt.Println(l)
    fmt.Println(e) // prints "<nil>"
}
Copy to clipboard

Response

Response Body

ListVersionsResult

Status Code

200
Success
404
NoSuchBucket

Example responses

Status 200: Example of a typical object listing response (version 1).

Success

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>apiary</Name>
  <Prefix/>
  <ContinuationToken>1dPe45g5uuxjyASPegLq80sQsZKL5OB2by4Iz_7YGR5NjiOENBPZXqvKJN6_PgKGVzZYTlws7qqdWaMklzb8HX2iDxxl72ane3rUFQrvNMeIih49MZ4APUjrAuYI83KxSMmfKHGZyKallFkD5N6PwKg</ContinuationToken>
  <NextContinuationToken>1a8j20CqowRrM4epIQ7fTBuyPZWZUeA8Epog16wYu9KhAPNoYkWQYhGURsIQbll1lP7c-OO-V5Vyzu6mogiakC4NSwlK4LyRDdHQgY-yPH4wMB76MfQR61VyxI4TJLxIWTPSZA0nmQQWcuV2mE4jiDA</NextContinuationToken>
  <KeyCount>1</KeyCount>
  <MaxKeys>1</MaxKeys>
  <Delimiter/>
  <IsTruncated>true</IsTruncated>
  <Contents>
    <Key>soldier-bee</Key>
    <LastModified>2016-08-25T17:49:06.006Z</LastModified>
    <ETag>"37d4c94839ee181a2224d6242176c4b5"</ETag>
    <Size>11</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
</ListBucketResult>
Copy to clipboard

Adds an object to a bucket using a single request. IBM COS never adds partial objects; if you receive a success response, IBM COS added the entire object to the bucket. IBM COS is a distributed system. If it receives multiple write requests for the same object simultaneously, it overwrites all but the last object written.

All objects written to IBM COS are encrypted by default using SecureSlice. If you require possession of encryption keys, you can use Key Protect or SSE-C.

To ensure that data is not corrupted traversing the network, use the Content-MD5 header. When you use this header, IBM COS 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 IBM COS and compare the returned ETag to the calculated MD5 value. The Content-MD5 header is required for any request to upload an object with a retention period configured using Immutable Object Storage.

Larger objects (greater than 100 MiB) may benefit from breaking the object into multiple parts and uploading the parts in parallel. For more information, see the Multipart uploads methods.

PUT /{Bucket}/{Key}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.put

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object.write

Request

Custom Headers

x-amz-acl
string
The canned ACL to apply to the object.

Allowable values: [private,public-read]
If-Match
string
Upload the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
If-None-Match
string
Upload the object only if its entity tag (ETag) is different from the one specified, otherwise return a 412 (precondition failed).
If-Unmodified-Since
date-time
Upload the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
Cache-Control
string
Can be used to specify caching behavior along the request/reply chain. For more information, see RFC 2616.
Content-Disposition
string
Specifies presentational information for the object. For more information, see RFC 2616.
Content-Encoding
string
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 RFC 2616.
Content-Language
string
The language the content is in.
Content-Length
integer
Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically. For more information, see RFC 2616.
Content-MD5
string
The base64-encoded 128-bit MD5 digest of the payload (just the request body without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the data is the same data that was originally sent. Although it is optional, it is recommended to use the Content-MD5 mechanism as an end-to-end integrity check.
Content-Type
string
A standard MIME type describing the format of the contents. For more information, see RFC 2616.
Expires
date-time
The date and time at which the object is no longer cacheable. For more information, RFC 2616.
x-amz-server-side-encryption
string
The server-side encryption algorithm used when storing this object in IBM COS (AES256).

Allowable values: [AES256]
x-amz-website-redirect-location
string
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.
x-amz-server-side-encryption-customer-algorithm
string
Specifies the algorithm to use to when encrypting the object (for example, AES256).
x-amz-server-side-encryption-customer-key
password
Specifies the customer-provided encryption key for IBM COS to use in encrypting data. This value is used to store the object and then it is discarded; IBM COS 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-MD5
string
Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. IBM COS uses this header for a message integrity check to ensure that the encryption key was transmitted without error.
x-amz-tagging
string
A set of tags for the object. The tags must be encoded as URL duery parameters (For example, SomeKey=SomeValue).

Path Parameters

Bucket
Required*
string
The bucket that will hold the object.
Key
Required*
string
Object key for which the PUT operation was initiated.

Possible values: length ≥ 1

Request Body

Required*

text/xmlobject

Write an object

curl -X "PUT" "https://(endpoint)/(bucket-name)/(object-key)"  -H "Authorization: bearer (token)"  -H "Content-Type: (content-type)"  -d "(object-contents)"
Copy to clipboard

Write an object

cos.putObject(
    "sample", // the name of the destination bucket
    "myfile", // the object key
    new File("/home/user/test.txt") // the file name and path of the object to be uploaded
);
Copy to clipboard

Write an object

cos.Object(bucket_name, item_name).put(Body=filelike_object)

Write an object

function createTextFile(bucketName, itemName, fileText) {
    console.log(`Creating new item: ${itemName}`);
    return cos.putObject({
        Bucket: bucketName, 
        Key: itemName, 
        Body: fileText
    }).promise()
    .then(() => {
        console.log(`Item: ${itemName} created!`);
    })
    .catch((e) => {
        console.error(`ERROR: ${e.code} - ${e.message}\n`);
    });
}
Copy to clipboard

Write an object

func main() {

    // Create client
    sess := session.Must(session.NewSession())
    client := s3.New(sess, conf)

    // Variables and random content to sample, replace when appropriate 
    bucketName := "<BUCKET_NAME>"
    key := "<OBJECT_KEY>"
    content := bytes.NewReader([]byte("<CONTENT>"))

    input := s3.PutObjectInput{
        Bucket:        aws.String(bucketName),
        Key:           aws.String(key),
        Body:          content,
    }

    // Call Function to upload (Put) an object 
    result, _ := client.PutObject(&input)
    fmt.Println(result)
}
Copy to clipboard

Response

Status Code

200
OK

No Sample Response

This method does not specify any sample responses.

Retrieves objects from IBM COS. If the object you are retrieving has been archived, before you can retrieve the object you must first restore a copy. Otherwise, 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 IBM COS, 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

GET /{Bucket}/{Key}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.get

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object.read

Request

Custom Headers

If-Match
string
Returns the object only if its entity tag (ETag) is the same as the one specified, otherwise returns a 412 (precondition failed).
If-Modified-Since
date-time
Returns the object only if it has been modified since the specified time, otherwise returns a 304 (not modified).
If-None-Match
string
Returns the object only if its entity tag (ETag) is different from the one specified, otherwise returns a 304 (not modified).
If-Unmodified-Since
date-time
Returns the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).'
Range
string
Downloads the specified range bytes of an object. For more information about the HTTP Range header, see RFC 2516.
x-amz-server-side-encryption-customer-algorithm
string
Specifies the algorithm to use to when encrypting the object (for example, AES256).
x-amz-server-side-encryption-customer-key
password
Specifies the customer-provided encryption key for IBM COS to use in encrypting data. This value is used to store the object and then it is discarded; IBM COS 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-MD5
string
Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. IBM COS uses this header for a message integrity check to ensure that the encryption key was transmitted without error.

Path Parameters

Bucket
Required*
string
The bucket containing the object.
Key
Required*
string
Key of the object to get.

Possible values: length ≥ 1

Query Parameters

response-cache-control
string
Sets the Cache-Control header of the response.
response-content-disposition
string
Sets the Content-Disposition header of the response
response-content-encoding
string
Sets the Content-Encoding header of the response.
response-content-language
string
Sets the Content-Language header of the response.
response-content-type
string
Sets the Content-Type header of the response.
response-expires
date-time
Sets the Expires header of the response.
partNumber
integer
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.

Response

Response Body

GetObjectOutput

Status Code

200
Success
404
NoSuchKey

Example responses

Status 200

{
  "AcceptRanges": "bytes",
  "ContentLength": "10",
  "ContentRange": "bytes 0-9/43",
  "ContentType": "text/plain",
  "ETag": "\"0d94420ffd0bc68cd3d152506b97a9cc\"",
  "LastModified": "Thu, 09 Oct 2014 22:57:28 GMT",
  "Metadata": {},
  "VersionId": "null"
}
Copy to clipboard

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 or it's existence.

HEAD /{Bucket}/{Key}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.head
cloud-object-storage.bucket.list_crk_id

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-metadata.read

Request

Custom Headers

If-Match
string
Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
If-Modified-Since
date-time
Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
If-None-Match
string
Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
If-Unmodified-Since
date-time
Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
Range
string
Downloads the specified range bytes of an object. For more information about the HTTP Range header, see RFC 2516.
x-amz-server-side-encryption-customer-algorithm
string
Specifies the algorithm to use to when encrypting the object (for example, AES256).
x-amz-server-side-encryption-customer-key
password
Specifies the customer-provided encryption key for IBM COS to use in encrypting data. This value is used to store the object and then it is discarded; IBM COS 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-MD5
string
Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. IBM COS uses this header for a message integrity check to ensure that the encryption key was transmitted without error.

Path Parameters

Bucket
Required*
string
The bucket containing the object.
Key
Required*
string
The object key.

Possible values: length ≥ 1

Query Parameters

partNumber
integer
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.

Response

Status Code

200
Success
404
NoSuchKey

Permantently deletes an object. This operation is final - there is no way to recover a deleted object. Data stored in IBM COS 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 by a process of compaction 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. IBM's provider-managed encryption and erasure coding prevents data (both before and after deletion) from being accessible from within individual data centers.

DELETE /{Bucket}/{Key}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.delete

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object.delete

Request

Path Parameters

Bucket
Required*
string
The bucket containing the object.
Key
Required*
string
Key name of the object to delete.

Possible values: length ≥ 1

Response

Response Body

DeleteObjectOutput

Status Code

204
Success

Example responses

{}

Copies an object.

PUT /{Bucket}/{TargetKey}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

cloud-object-storage.object.copy
cloud-object-storage.object.copy_get

Auditing

Calling this method generates the following auditing events.

cloud-object-storage.object-copy.read
cloud-object-storage.object-copy.create

Request

Custom Headers

x-amz-copy-source
Required*
string
Specifies the source object for the copy operation.

Possible values: Value must match regular expression \/.+\/.+
x-amz-acl
string
The canned ACL to apply to the object.

Allowable values: [private,public-read]
Cache-Control
string
Specifies caching behavior along the request/reply chain.
Content-Disposition
string
Specifies presentational information for the object.
Content-Encoding
string
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 RFC 2616.
Content-Language
string
The language the content is in.
Content-Type
string
A standard MIME type describing the format of the contents. For more information, see RFC 2616.
x-amz-copy-source-if-match
string
Copies the object if its entity tag (ETag) matches the specified tag.
x-amz-copy-source-if-modified-since
date-time
Copies the object if it has been modified since the specified time.
x-amz-copy-source-if-none-match
string
Copies the object if its entity tag (ETag) is different than the specified ETag.
x-amz-copy-source-if-unmodified-since
date-time
Copies the object if it hasn't been modified since the specified time.
Expires
date-time
The date and time at which the object is no longer cacheable. For more information, RFC 2616.
x-amz-metadata-directive
string
Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request.

Allowable values: [COPY,REPLACE]
x-amz-tagging-directive
string
Specifies whether the object tag-set are copied from the source object or replaced with tag-set provided in the request.

Allowable values: [COPY,REPLACE]
x-amz-server-side-encryption
string
The server-side encryption algorithm used when storing this object.

Allowable values: [AES256]
x-amz-website-redirect-location
string
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.
x-amz-server-side-encryption-customer-algorithm
string
Specifies the algorithm to use to when encrypting the object (for example, AES256).
x-amz-server-side-encryption-customer-key
password
Specifies the customer-provided encryption key for use in encrypting data.
x-amz-server-side-encryption-customer-key-MD5
string
Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Used as a message integrity check to ensure that the encryption key was transmitted without error.
x-amz-copy-source-server-side-encryption-customer-algorithm
string
Specifies the algorithm to use when decrypting the source object (for example, AES256).
x-amz-copy-source-server-side-encryption-customer-key
password
Specifies the customer-provided encryption key for IBM COS 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-MD5
string
Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Used as a message integrity check to ensure that the encryption key was transmitted without error.
x-amz-tagging
string
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.

Path Parameters

Bucket
Required*
string
The name of the destination bucket.
TargetKey
Required*
string
The key of the destination object.

Possible values: length ≥ 1

Request Body

Required*

text/xmlobject

Response

Response Body

CopyObjectOutput

Status Code

200
Success
404
ObjectNotInActiveTierError

Example responses

Status 200

{
  "CopyObjectResult": {
    "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"",
    "LastModified": "2016-12-15T17:38:53.000Z"
  }
}
Copy to clipboard

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. For each key, IBM COS 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, IBM COS 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 /{Bucket}?delete

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.post_multi_delete

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object-batch.delete

Request

Path Parameters

Bucket
Required*
string
The bucket name containing the objects to delete.

Query Parameters

delete
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Request Body

Required*

text/xmlobject

Response

Response Body

DeleteObjectsOutput

Status Code

200
Success

Example responses

Status 200

{
  "Deleted": [
    {
      "Key": "HappyFace.jpg",
      "VersionId": "yoz3HB.ZhCS_tKVEmIOr7qYyyAaZSKVd"
    },
    {
      "Key": "HappyFace.jpg",
      "VersionId": "2LWg7lQLnY41.maGB5Z6SWW.dcq0vx7b"
    }
  ]
}
Copy to clipboard

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 /{Bucket}/{Key}?uploads

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.post_initiate_upload

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object-multipart.start

Request

Custom Headers

If-Match
string
Upload the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
If-None-Match
string
Upload the object only if its entity tag (ETag) is different from the one specified, otherwise return a 412 (precondition failed).
If-Unmodified-Since
date-time
Upload the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
Cache-Control
string
Specifies caching behavior along the request/reply chain.
Content-Disposition
string
Specifies presentational information for the object.
Content-Encoding
string
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 RFC 2616.
Content-Language
string
The language the content is in.
Content-Type
string
A standard MIME type describing the format of the contents. For more information, see RFC 2616.
Expires
date-time
The date and time at which the object is no longer cacheable. For more information, RFC 2616.
x-amz-server-side-encryption
string
The server-side encryption algorithm used when storing this object (for example, AES256).

Allowable values: [AES256]
x-amz-website-redirect-location
string
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.
x-amz-server-side-encryption-customer-algorithm
string
Specifies the algorithm to use to when encrypting the object (for example, AES256).
x-amz-server-side-encryption-customer-key
password
Specifies the customer-provided encryption key for encrypting data. IBM COS does not store the encryption key - it is discarded use. 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-MD5
string
Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321, ensuring the encryption key is transmitted without error.
x-amz-tagging
string
A set of key-value pairs, encoded as URL query parameters.
x-amz-acl
string
The canned ACL to apply to the object.

Allowable values: [private,public-read]

Path Parameters

Bucket
Required*
string
The name of the bucket to which to initiate the upload.
Key
Required*
string
Object key for which the multipart upload is to be initiated.

Possible values: length ≥ 1

Query Parameters

uploads
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Request Body

Required*

text/xmlobject

Response

Response Body

CreateMultipartUploadOutput

Status Code

200
Success

Example responses

Status 200

{
  "Bucket": "examplebucket",
  "Key": "largeobject",
  "UploadId": "ibZBv_75gd9r8lH_gqXatLdxMVpAlj6ZQjEs.OwyF3953YdwbcQnMA2BLGn8Lx12fQNICtMw5KyteFeHw.Sjng--"
}
Copy to clipboard

Completes a multipart upload by assembling previously uploaded parts.

After successfully uploading all parts of an upload, you call this operation to complete the upload. Upon receiving this request, IBM COS concatenates all the parts in ascending order by part number to create a new object. In the Complete Multipart Upload request, you must provide the parts list. 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.

POST /{Bucket}/{Key}?uploadId={uploadId}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.post_complete_upload

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object-multipart.complete

Request

Path Parameters

Bucket
Required*
string
Name of the bucket to which the multipart upload was initiated.
Key
Required*
string
Object key for which the multipart upload was initiated.

Possible values: length ≥ 1

Query Parameters

uploadId
Required*
string
ID for the initiated multipart upload.

Request Body

Required*

text/xmlobject

Response

Response Body

CompleteMultipartUploadOutput

Status Code

200
Success

Example responses

Status 200

{
  "Bucket": "acexamplebucket",
  "ETag": "\"4d9031c7644d8081c2829f4ea23c55f7-2\"",
  "Key": "bigobject",
  "Location": "https://examplebucket.s3.us-south.cloud-object-storage.appdomain.com/bigobject"
}
Copy to clipboard

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 by default returns a maximum of 1,000 uploaded 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 /{Bucket}/{Key}?uploadId={uploadId}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.get_uploads

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object-multipart.list

Request

Path Parameters

Bucket
Required*
string
The bucket where the parts have been uploaded.
Key
Required*
string
Object key for which the multipart upload was initiated.

Possible values: length ≥ 1

Query Parameters

uploadId
Required*
string
Upload ID identifying the multipart upload whose parts are being listed.
max-parts
integer
Sets the maximum number of parts to return.
part-number-marker
integer
Specifies the part after which listing should begin. Only parts with higher part numbers will be listed.

Response

Response Body

ListPartsOutput

Status Code

200
Success

Example responses

Status 200

{
  "Initiator": {
    "DisplayName": "owner-display-name",
    "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
  },
  "Owner": {
    "DisplayName": "owner-display-name",
    "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
  },
  "Parts": [
    {
      "ETag": "\"d8c2eafd90c266e19ab9dcacc479f8af\"",
      "LastModified": "2016-12-16T00:11:42.000Z",
      "PartNumber": "1",
      "Size": 26246026
    },
    {
      "ETag": "\"d8c2eafd90c266e19ab9dcacc479f8af\"",
      "LastModified": "2016-12-16T00:15:01.000Z",
      "PartNumber": "2",
      "Size": 26246026
    }
  ],
  "StorageClass": "STANDARD"
}
Copy to clipboard

Stops a current multipart upload and removes any parts of an incomplete upload, which would otherwise incur storage costs.

DELETE /{Bucket}/{Key}?uploadId={uploadId}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.delete_upload

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object-multipart.delete

Request

Path Parameters

Bucket
Required*
string
The destination bucket for the upload.
Key
Required*
string
Key of the object for which the multipart upload was initiated.

Possible values: length ≥ 1

Query Parameters

uploadId
Required*
string
Upload ID that identifies the multipart upload.

Response

Response Body

AbortMultipartUploadOutput

Status Code

204
Success
404
NoSuchUpload

Example responses

{}

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 /{Bucket}?uploads

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.get_uploads

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-multipart.list

Request

Path Parameters

Bucket
Required*
string
The name of the bucket to which the multipart upload was initiated.

Query Parameters

uploads
Required*
boolean
Allowable values: [true]
Possible values: allows empty value
delimiter
string
Character you use to group keys. All keys that contain the same string between the prefix, if specified, and the first occurrence of the delimiter after the prefix are grouped under a single result element, CommonPrefixes. If you don''t specify the prefix parameter, then the substring starts at the beginning of the key. The keys that are grouped under CommonPrefixes result element are not returned elsewhere in the response.
encoding-type
string
Requests IBM COS 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 IBM COS encode the keys in the response.

Allowable values: [url]
key-marker
string
Together with upload-id-marker, this parameter specifies the multipart upload after which listing should begin. If upload-id-marker is not specified, only the keys lexicographically greater than the specified key-marker will be included in the list. If upload-id-marker is specified, any multipart uploads for a key equal to the key-marker might also be included, provided those multipart uploads have upload IDs lexicographically greater than the specified upload-id-marker.
max-uploads
integer
Sets the maximum number of multipart uploads, from 1 to 1,000, to return in the response body. 1,000 is the maximum number of uploads that can be returned in a response.
prefix
string
Lists in-progress uploads only for those keys that begin with the specified prefix. You can use prefixes to separate a bucket into different grouping of keys. (You can think of using prefix to make groups in the same way you'd use a folder in a file system.)
upload-id-marker
string
Together with key-marker, specifies the multipart upload after which listing should begin. If key-marker is not specified, the upload-id-marker parameter is ignored. Otherwise, any multipart uploads for a key equal to the key-marker might be included in the list only if they have an upload ID lexicographically greater than the specified upload-id-marker.
MaxUploads
string
Pagination limit
KeyMarker
string
Pagination token
UploadIdMarker
string
Pagination token

Response

Response Body

ListMultipartUploadsOutput

Status Code

200
Success

Example responses

Status 200

{
  "Uploads": [
    {
      "Initiated": "2014-05-01T05:40:58.000Z",
      "Initiator": {
        "DisplayName": "display-name",
        "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
      },
      "Key": "JavaFile",
      "Owner": {
        "DisplayName": "display-name",
        "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
      },
      "StorageClass": "STANDARD",
      "UploadId": "examplelUa.CInXklLQtSMJITdUnoZ1Y5GACB5UckOtspm5zbDMCkPF_qkfZzMiFZ6dksmcnqxJyIBvQMG9X9Q--"
    },
    {
      "Initiated": "2014-05-01T05:41:27.000Z",
      "Initiator": {
        "DisplayName": "display-name",
        "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
      },
      "Key": "JavaFile",
      "Owner": {
        "DisplayName": "display-name",
        "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
      },
      "StorageClass": "STANDARD",
      "UploadId": "examplelo91lv1iwvWpvCiJWugw2xXLPAD7Z8cJyX9.WiIRgNrdG6Ldsn.9FtS63TCl1Uf5faTB.1U5Ckcbmdw--"
    }
  ]
}
Copy to clipboard

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 IBM COS 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, IBM COS returns an upload ID (a unique identifier) that you must include in your upload part requests.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. IBM COS checks the part data against the provided MD5 value. If they do not match, IBM COS returns an error. If the upload request uses HMAC authentication (AWS Signature Version 4), then IBM COS uses the x-amz-content-sha256 header as a checksum instead of Content-MD5.

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, IBM COS frees up the parts storage and stops charging you for the parts storage.

PUT /{Bucket}/{Key}?partNumber={partNumber}&uploadId={uploadId}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.put_part

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object-multipart.create

Request

Custom Headers

Content-Length
integer
Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically. For more information, see RFC 2616.
Content-MD5
string
The base64-encoded 128-bit MD5 digest of the payload (just the request body without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the data is the same data that was originally sent. Although it is optional, it is recommended to use the Content-MD5 mechanism as an end-to-end integrity check.
x-amz-server-side-encryption-customer-algorithm
string
Specifies the algorithm to use to when encrypting the object (for example, AES256).
x-amz-server-side-encryption-customer-key
password
Specifies the customer-provided encryption key for IBM COS to use in encrypting data. This value is used to store the object and then it is discarded; IBM COS 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. This must be the same encryption key specified in the initiate multipart upload request.
x-amz-server-side-encryption-customer-key-MD5
string
Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. IBM COS uses this header for a message integrity check to ensure that the encryption key was transmitted without error.
x-amz-request-payer
string
Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. For information about downloading objects from requester pays buckets, see Downloading Objects in Requestor Pays Buckets in the IBM COS Developer Guide.

Allowable values: [requester]
x-amz-expected-bucket-owner
string
The account id of the expected bucket owner. If the bucket is owned by a different account, the request will fail with an HTTP 403 (Access Denied) error.

Path Parameters

Bucket
Required*
string
The name of the bucket to which the multipart upload was initiated.
Key
Required*
string
Object key for which the multipart upload was initiated.

Possible values: length ≥ 1

Query Parameters

partNumber
Required*
integer
Part number of part being uploaded. This is a positive integer between 1 and 10,000.
uploadId
Required*
string
Upload ID identifying the multipart upload whose part is being uploaded.

Request Body

Required*

text/xmlobject

Response

Response Body

UploadPartOutput

Status Code

200
Success

Example responses

Status 200

{
  "ETag": "\"d8c2eafd90c266e19ab9dcacc479f8af\""
}

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 UploadPartoperation and provide data in your request.

You must initiate a multipart upload before you can upload any part. In response to your initiate request. IBM COS returns a unique identifier, the upload ID, that you must include in your upload part request.

Note the following additional considerations about the request headers x-amz-copy-source-if-match, x-amz-copy-source-if-none-match, x-amz-copy-source-if-unmodified-since, and x-amz-copy-source-if-modified-since:

If both of the x-amz-copy-source-if-match and x-amz-copy-source-if-unmodified-since headers are present in the request as follows: x-amz-copy-source-if-match condition evaluates to true, and x-amz-copy-source-if-unmodified-since condition evaluates to false, then IBM COS returns 200 OK and copies the data.
If both of the x-amz-copy-source-if-none-match and x-amz-copy-source-if-modified-since headers are present in the request as follows: x-amz-copy-source-if-none-match condition evaluates to false, and x-amz-copy-source-if-modified-since condition evaluates to true IBM COS returns 412 Precondition Failed response code.

PUT /{Bucket}/{TargetKey}?partNumber={partNumber}&uploadId={uploadId}

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

cloud-object-storage.object.copy_part
cloud-object-storage.object.copy_part_get

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object-multipart.create

Request

Custom Headers

x-amz-copy-source
Required*
string
Specifies the source object to use as a part in the multipart upload.

Possible values: Value must match regular expression \/.+\/.+
x-amz-copy-source-if-match
string
Copies the object if its entity tag (ETag) matches the specified tag.
x-amz-copy-source-if-modified-since
date-time
Copies the object if it has been modified since the specified time.
x-amz-copy-source-if-none-match
string
Copies the object if its entity tag (ETag) is different than the specified ETag.
x-amz-copy-source-if-unmodified-since
date-time
Copies the object if it hasn't been modified since the specified time.
x-amz-copy-source-range
string
The range of bytes to copy from the source object. The range value must use the form bytes=first-last, where the first and last are the zero-based byte offsets to copy. For example, bytes=0-9 indicates that you want to copy the first 10 bytes of the source. You can copy a range only if the source object is greater than 5 MB.
x-amz-server-side-encryption-customer-algorithm
string
Specifies the algorithm to use to when encrypting the object (AES256).
x-amz-server-side-encryption-customer-key
password
Specifies the customer-provided encryption key for IBM COS to use in encrypting data. This value is used to store the object and then it is discarded; IBM COS 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. This must be the same encryption key specified in the initiate multipart upload request.
x-amz-server-side-encryption-customer-key-MD5
string
Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. IBM COS 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-algorithm
string
Specifies the algorithm to use when decrypting the source object (AES256).
x-amz-copy-source-server-side-encryption-customer-key
password
Specifies the customer-provided encryption key for IBM COS 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-MD5
string
Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. IBM COS uses this header for a message integrity check to ensure that the encryption key was transmitted without error.

Path Parameters

Bucket
Required*
string
The bucket name.
Key
Required*
string
Object key for which the multipart upload was initiated.

Possible values: length ≥ 1

Query Parameters

partNumber
Required*
integer
Part number of part being copied. This is a positive integer between 1 and 10,000.
uploadId
Required*
string
Upload ID identifying the multipart upload whose part is being copied.

Response

Response Body

UploadPartCopyOutput

Status Code

200
Success

Example responses

Status 200

{
  "CopyPartResult": {
    "ETag": "\"65d16d19e65a7508a51f043180edcc36\"",
    "LastModified": "2016-12-29T21:44:28.000Z"
  }
}
Copy to clipboard

Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration. You specify the lifecycle configuration in your request body. The lifecycle configuration is specified as XML consisting of one or more rules. Each rule consists of the following:

Filter identifying a subset of objects to which the rule applies. The filter can be based on a key name prefix, object tags, or a combination of both.
Status whether the rule is in effect.
One or more lifecycle transition and expiration actions that you want IBM COS to perform on the objects identified by the filter. Note that there can only be one Transistion rule, and filters are not supported for Transition rules.

PUT /{Bucket}?lifecycle

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.put_lifecycle

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-lifecycle.create

Request

Path Parameters

Bucket
Required*
string
The name of the bucket for which to set the configuration.

Query Parameters

lifecycle
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Request Body

Required*

text/xmlobject

Response

Status Code

200
Success

No Sample Response

This method does not specify any sample responses.

Returns the lifecycle configuration information set on the bucket.

GET /{Bucket}?lifecycle

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.get_lifecycle

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-lifecycle.read

Request

Path Parameters

Bucket
Required*
string
The name of the bucket for which to get the lifecycle information.

Query Parameters

lifecycle
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Response Body

GetBucketLifecycleConfigurationOutput

Status Code

200
Success

Example responses

Status 200

{
  "Rules": [
    {
      "ID": "Rule for TaxDocs/",
      "Prefix": "TaxDocs",
      "Status": "Enabled",
      "Transitions": [
        {
          "Days": 365,
          "StorageClass": "STANDARD_IA"
        }
      ]
    }
  ]
}
Copy to clipboard

Deletes the lifecycle configuration from the specified bucket. IBM COS removes all the lifecycle configuration rules in the lifecycle subresource associated with the bucket. Your objects never expire, and IBM COS no longer automatically deletes any objects on the basis of rules contained in the deleted lifecycle configuration. There is usually some time lag before lifecycle configuration deletion is fully propagated across the IBM COS system.

DELETE /{Bucket}?lifecycle

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.put_lifecycle

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-lifecycle.delete

Request

Path Parameters

Bucket
Required*
string
The bucket name of the lifecycle to delete.

Query Parameters

lifecycle
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Status Code

204
Success

No Sample Response

This method does not specify any sample responses.

Restores an archived copy of an object back into IBM COS. To access an archived object, you must first initiate a restore request. This restores a temporary copy of the archived object. In a restore request, you specify the number of days that you want the restored copy to exist. After the specified period, IBM COS deletes the temporary copy but the object remains archived.

POST /{Bucket}/{Key}?restore

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.restore

Auditing

Calling this method generates the following auditing events.

cloud-object-storage.object-restore.read
cloud-object-storage.object-restore.create

Request

Path Parameters

Bucket
Required*
string
The bucket name or containing the object to restore.
Key
Required*
string
Object key for which the operation was initiated.

Possible values: length ≥ 1

Query Parameters

restore
Required*
boolean
Possible values: allows empty value

Request Body

Required*

text/xmlobject

Response

Response Body

RestoreObjectOutput

Status Code

200
Success
404
ObjectAlreadyInActiveTierError

Example responses

{}

The replication configuration is provided as XML in the body of the request.

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.

PUT /{Bucket}?replication

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.put_replication

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-replication.create

Request

Path Parameters

Bucket
Required*
string
The name of the bucket for which to set the configuration.

Query Parameters

replication
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Request Body

Required*

text/xmlobject

Create a replication configuration

curl -X "PUT" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?replication"      -H 'Authorization: bearer $TOKEN'      -H 'Content-MD5: exuBoz2kFBykNwqu64JZuA=='      -H 'Content-Type: text/plain; charset=utf-8'      -d $'<ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
            <Rule>
              <ID>SimpleReplication</ID>
              <Priority>1</Priority>
              <Status>Enabled</Status>
              <DeleteMarkerReplication>
                <Status>Disabled</Status>
              </DeleteMarkerReplication>
              <Filter/>
              <Destination>
                <Bucket>$DESTINATION_CRN</Bucket>
              </Destination>
          	</Rule>
          </ReplicationConfiguration>'
Copy to clipboard

Response

Status Code

200
Success

No Sample Response

This method does not specify any sample responses.

Returns the replication configuration information set on the bucket.

GET /{Bucket}?replication

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.get_replication

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-replication.read

Request

Path Parameters

Bucket
Required*
string
The name of the bucket for which to get the replication information.

Query Parameters

replication
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Response Body

GetBucketReplicationConfigurationOutput

Status Code

200
Success

No Sample Response

This method does not specify any sample responses.

Deletes the replication configuration from the specified bucket. IBM COS removes all the lifecycle configuration rules in the lifecycle subresource associated with the bucket. Your objects never expire, and IBM COS no longer automatically deletes any objects on the basis of rules contained in the deleted replication configuration. There is usually some time lag before replication configuration deletion is fully propagated across the IBM COS system.

DELETE /{Bucket}?replication

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.put_replication

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-replication.delete

Request

Path Parameters

Bucket
Required*
string
The bucket name of the replication to delete.

Query Parameters

replication
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Status Code

204
Success

No Sample Response

This method does not specify any sample responses.

Creates a new protection configuration (this term is interchangeable with "retention policy") for the bucket or replaces an existing protection configuration. You specify the protection configuration in your request body. The protection configuration is specified as XML.

PUT /{Bucket}?protection

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.put_protection

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-retention.create

Request

Path Parameters

Bucket
Required*
string
The name of the bucket for which to set the configuration.

Query Parameters

protection
Required*
boolean
Possible values: allows empty value

Request Body

Required*

text/xmlProtection

Specifies protection configuration for a bucket.

Response

Status Code

200
Success

No Sample Response

This method does not specify any sample responses.

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.

PUT /{Bucket}?website

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.put_website

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-website.create

Request

Custom Headers

Content-MD5
string
The base64-encoded 128-bit MD5 digest of the payload (just the request body without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the data is the same data that was originally sent. Although it is optional, it is recommended to use the Content-MD5 mechanism as an end-to-end integrity check.

Path Parameters

Bucket
Required*
string
The bucket that will serve a static website.

Query Parameters

website
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Request Body

Required*

text/xmlobject

Response

Status Code

200
Success

No Sample Response

This method does not specify any sample responses.

Returns the website configuration for a bucket.

GET /{Bucket}?website

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.get_website

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-website.read

Request

Path Parameters

Bucket
Required*
string
The bucket name for which to get the website configuration.

Query Parameters

website
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Response Body

GetBucketWebsiteOutput

Status Code

200
Success

Example responses

Status 200

{
  "ErrorDocument": {
    "Key": "error.html"
  },
  "IndexDocument": {
    "Suffix": "index.html"
  }
}
Copy to clipboard

This operation removes the website configuration for a bucket. IBM COS 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. IBM COS returns a 404 response if the bucket specified in the request does not exist.

DELETE /{Bucket}?website

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.delete_website

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-website.delete

Request

Path Parameters

Bucket
Required*
string
The bucket for which you want to remove the website configuration.

Query Parameters

website
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Status Code

204
Success

No Sample Response

This method does not specify any sample responses.

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

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 bucket at my.example.bucket.com by using XMLHttpRequest in a browser.

To enable cross-origin resource sharing (CORS) on a bucket, you create a XML configuration 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 IBM COS 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:

The request's Origin header must match AllowedOrigin elements.
The request method (for example, GET, PUT, HEAD, and so on) or the Access-Control-Request-Method header in case of a pre-flight OPTIONS request must be one of the AllowedMethod elements.
Every header specified in the Access-Control-Request-Headers request header of a pre-flight request must match an AllowedHeader element.

PUT /{Bucket}?cors

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.put_cors

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-cors.create

Request

Custom Headers

Content-MD5
string
The base64-encoded 128-bit MD5 digest of the payload (just the request body without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the data is the same data that was originally sent. Although it is optional, it is recommended to use the Content-MD5 mechanism as an end-to-end integrity check.

Path Parameters

Bucket
Required*
string
Specifies the bucket impacted by the CORS configuration.

Query Parameters

cors
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Request Body

Required*

text/xmlobject

A set of origins and methods (cross-origin access that you want to allow). You can add up to 100 rules to the configuration.

Response

Status Code

200
Success

No Sample Response

This method does not specify any sample responses.

Returns the CORS configuration information set for the bucket.

GET /{Bucket}?cors

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.get_cors

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-cors.read

Request

Path Parameters

Bucket
Required*
string
The bucket name for which to get the CORS configuration.

Query Parameters

cors
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Response Body

GetBucketCorsOutput

Status Code

200
Success

Example responses

Status 200

{
  "CORSRules": [
    {
      "AllowedHeaders": [
        "Authorization"
      ],
      "AllowedMethods": [
        "GET"
      ],
      "AllowedOrigins": [
        "*"
      ],
      "MaxAgeSeconds": 3000
    }
  ]
}
Copy to clipboard

Deletes the CORS configuration information set for the bucket.

DELETE /{Bucket}?cors

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.delete_cors

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-cors.delete

Request

Path Parameters

Bucket
Required*
string
Specifies the bucket whose CORS configuration is being deleted.

Query Parameters

cors
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Status Code

204
Success

No Sample Response

This method does not specify any sample responses.

Sets tags on an object that already exists. A tag is a key-value pair.

PUT /{Bucket}/{Key}?tagging

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.put_tagging

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object-tagging.create

Request

Custom Headers

Content-MD5
string
The base64-encoded 128-bit MD5 digest of the payload (just the request body without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the data is the same data that was originally sent. Although it is optional, it is recommended to use the Content-MD5 mechanism as an end-to-end integrity check.

Path Parameters

Bucket
Required*
string
The bucket containing the object.
Key
Required*
string
Name of the object key.

Possible values: length ≥ 1

Query Parameters

tagging
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Request Body

Required*

text/xmlobject

Response

Response Body

PutObjectTaggingOutput

Status Code

200
Success

Example responses

{ "VersionId": "null" }

Returns the tags of an object.

GET /{Bucket}/{Key}?tagging

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.get_tagging

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object-tagging.read

Request

Path Parameters

Bucket
Required*
string
The bucket containing the object.
Key
Required*
string
Object key for which to get the tagging information.

Possible values: length ≥ 1

Query Parameters

tagging
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Response Body

GetObjectTaggingOutput

Status Code

200
Success

Example responses

Status 200

{
  "TagSet": [
    {
      "Key": "Key4",
      "Value": "Value4"
    },
    {
      "Key": "Key3",
      "Value": "Value3"
    }
  ],
  "VersionId": "null"
}
Copy to clipboard

Removes the entire tag set from the specified object.

DELETE /{Bucket}/{Key}?tagging

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.delete_tagging

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object-tagging.delete

Request

Path Parameters

Bucket
Required*
string
The bucket that contains the object.
Key
Required*
string
Name of the object key.

Possible values: length ≥ 1

Query Parameters

tagging
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Response Body

DeleteObjectTaggingOutput

Status Code

204
Success

Example responses

Status 204

{
  "VersionId": "ydlaNkwWm0SfKJR.T1b1fIdPRbldTYRI"
}

Creates or modifies the PublicAccessBlock configuration for an IBM COS bucket.

PUT /{Bucket}?publicAccessBlock

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.put_public_access_block

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-public-access-block.create

Request

Custom Headers

Content-MD5
string
The base64-encoded 128-bit MD5 digest of the payload (just the request body without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the data is the same data that was originally sent. Although it is optional, it is recommended to use the Content-MD5 mechanism as an end-to-end integrity check.

Path Parameters

Bucket
Required*
string
The name of the IBM COS bucket whose PublicAccessBlock configuration you want to set.

Query Parameters

publicAccessBlock
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Request Body

Required*

text/xmlobject

Response

Status Code

200
Success

No Sample Response

This method does not specify any sample responses.

Retrieves the PublicAccessBlock configuration for an IBM COS bucket.

GET /{Bucket}?publicAccessBlock

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.get_public_access_block

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-public-access-block.read

Request

Path Parameters

Bucket
Required*
string
The name of the IBM COS bucket whose PublicAccessBlock configuration you want to retrieve.

Query Parameters

publicAccessBlock
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Response Body

GetPublicAccessBlockOutput

Status Code

200
Success

No Sample Response

This method does not specify any sample responses.

Removes the PublicAccessBlock configuration for an IBM COS bucket.

DELETE /{Bucket}?publicAccessBlock

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.delete_public_access_block

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-public-access-block.delete

Request

Path Parameters

Bucket
Required*
string
The IBM COS bucket whose PublicAccessBlock configuration you want to delete.

Query Parameters

publicAccessBlock
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Status Code

204
Success

No Sample Response

This method does not specify any sample responses.

This implementation of the GET operation uses the acl subresource to return the access control list (ACL) of a bucket.

GET /{Bucket}?acl

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.get_acl

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-acl.read

Request

Path Parameters

Bucket
Required*
string
Specifies the bucket whose ACL is being requested.

Query Parameters

acl
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Status Code

200
Success

No Sample Response

This method does not specify any sample responses.

This operation should not be used. Instead, use IAM policies to grant public access.

PUT /{Bucket}?acl

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.bucket.put_acl

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.bucket-acl.create

Request

Custom Headers

x-amz-acl
string
The canned ACL to apply to the bucket.

Allowable values: [private,public-read]

Path Parameters

Bucket
Required*
string
The bucket to which to apply the ACL.

Query Parameters

acl
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Status Code

200
Success

No Sample Response

This method does not specify any sample responses.

This operation should not be used. Instead, use IAM policies to grant public access.

GET /{Bucket}/{Key}?acl

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.get_acl

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object-acl.read

Request

Path Parameters

Bucket
Required*
string
The name of the bucket containing the object being requested.
Key
Required*
string
The key of the object for which to get the ACL information.

Possible values: length ≥ 1

Query Parameters

acl
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Response

Response Body

GetObjectAclOutput

Status Code

200
Success
404
NoSuchKey

Example responses

Status 200

{
  "Grants": [
    {
      "Grantee": {
        "DisplayName": "owner-display-name",
        "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc",
        "Type": "CanonicalUser"
      },
      "Permission": "WRITE"
    },
    {
      "Grantee": {
        "DisplayName": "owner-display-name",
        "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc",
        "Type": "CanonicalUser"
      },
      "Permission": "WRITE_ACP"
    },
    {
      "Grantee": {
        "DisplayName": "owner-display-name",
        "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc",
        "Type": "CanonicalUser"
      },
      "Permission": "READ"
    },
    {
      "Grantee": {
        "DisplayName": "owner-display-name",
        "ID": "852b113eexamplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc",
        "Type": "CanonicalUser"
      },
      "Permission": "READ_ACP"
    }
  ],
  "Owner": {
    "DisplayName": "owner-display-name",
    "ID": "examplee7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc"
  }
}
Copy to clipboard

This operation should not be used. Instead, use IAM policies to grant public access. This operation can be used to make a single object in a bucket publicly accessible, but it is discouraged. Instead, create a new bucket with a Public Access policy and copy the object to that bucket.

PUT /{Bucket}/{Key}?acl

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

cloud-object-storage.object.put_acl

Auditing

Calling this method generates the following auditing event.

cloud-object-storage.object-acl.create

Request

Custom Headers

x-amz-acl
string
The canned ACL to apply to the object.

Allowable values: [private,public-read]
Content-MD5
string
The base64-encoded 128-bit MD5 digest of the payload (just the request body without the headers) according to RFC 1864. This header can be used as a message integrity check to verify that the data is the same data that was originally sent. Although it is optional, it is recommended to use the Content-MD5 mechanism as an end-to-end integrity check.
x-amz-grant-full-control
string
Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.

This action is not supported by IBM COS on Outposts.
x-amz-grant-read
string
Allows grantee to list the objects in the bucket.

This action is not supported by IBM COS on Outposts.
x-amz-grant-read-acp
string
Allows grantee to read the bucket ACL.

This action is not supported by IBM COS on Outposts.
x-amz-grant-write
string
Allows grantee to create, overwrite, and delete any object in the bucket.
x-amz-grant-write-acp
string
Allows grantee to write the ACL for the applicable bucket.

This action is not supported by IBM COS on Outposts.

Path Parameters

Bucket
Required*
string
The bucket name that contains the object to which you want to attach the ACL.
Key
Required*
string
Key for which the PUT operation was initiated.

Possible values: length ≥ 1

Query Parameters

acl
Required*
boolean
Allowable values: [true]
Possible values: allows empty value

Request Body

Required*

text/xmlobject

Response

Response Body

PutObjectAclOutput

Status Code

200
Success
404
NoSuchKey

Example responses

{}

Introduction

Error handling

Methods

List buckets in a service instance

Authorization

Auditing

Request

Custom Headers

ibm-service-instance-id

Query Parameters

extended

Response

Response Body

owner

id

displayName

buckets

name

creationDate

Status Code

200

Create a new bucket

Authorization

Auditing

Request

Custom Headers

ibm-service-instance-id

ibm-sse-kp-encryption-algorithm

ibm-sse-kp-customer-root-key-crn

x-amz-acl

Path Parameters

Bucket

Request Body

LocationConstraint

Response

Status Code

200

409

No Sample Response

Delete a bucket

Authorization

Auditing

Request

Path Parameters

Bucket

Response

Status Code

204

No Sample Response

Read a bucket's headers

Authorization

Auditing

Request

Path Parameters

Bucket

Response

Status Code

200

404

List objects in a bucket (v1)

Authorization

Auditing

Request

Path Parameters

Bucket

Query Parameters

delimiter

encoding-type

marker

max-keys

prefix

Response

Response Body

IsTruncated

Marker

NextMarker

Contents

Name

Prefix

Delimiter