IBM Cloud API Docs

Introduction

Last updated: 2020-03-18

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>

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.

Methods

List buckets in a service instance

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

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

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

  • 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());
  }
}
  • 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))
  • 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`);
    });
}
  • func main() {

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

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

Response

Response Body

BucketListing

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

Status Code

  • 200

    Success

Example responses

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

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

Create a new bucket

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

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

  • 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);
}
  • 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))
  • 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`);
    });
}
  • 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)
}

Response

Status Code

  • 200

    Success

  • 409

    BucketAlreadyExists

No Sample Response

This method does not specify any sample responses.

Delete a bucket

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.

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

  • 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);
}
  • 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))
  • 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`);
    });
}
  • 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)
}

Response

Status Code

  • 204

    Success

No Sample Response

This method does not specify any sample responses.

Read a bucket's headers

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.

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

  • public HeadBucketRequest(String bucketName)
  • response = client.head_bucket(
    Bucket='string',
    ExpectedBucketOwner='string'
)
  • 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
});
  • func main() {

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

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

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

Response

Status Code

  • 200

    Success

  • 404

    NoSuchBucket

List objects in a bucket (v1)

Returns some or all (up to 1,000) of the objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket. A 200 OK response can contain valid or invalid XML. 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.

  • curl -X "GET" "https://s3.$REGION.cloud-object-storage.appdomain.cloud/$BUCKET"      -H "Authorization: Bearer $IAM_TOKEN" 
  • 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());
    }
}
  • 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))
  • 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`);
    });
}
  • 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>"
}

Response

Response Body

ListObjectsOutput

Status Code

  • 200

    Success

  • 404

    NoSuchBucket

Example responses

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

List objects in a bucket (v2)

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.

  • curl -X "GET" "https://s3.$REGION.cloud-object-storage.appdomain.cloud/$BUCKET?list-type=2"      -H "Authorization: Bearer $IAM_TOKEN" 
  • 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))
  • 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
});
  • 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>"
}
Response
Response Body
ListObjectsV2Output
Status Code
  • 200
    Success
    

  • 404
    NoSuchBucket
    

Example responses
  • 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>       

Create (upload) an object
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. IBM COS does not provide object locking; if you need this, make sure to build it into your application layer.


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
  • curl -X "PUT" "https://(endpoint)/(bucket-name)/(object-key)"  -H "Authorization: bearer (token)"  -H "Content-Type: (content-type)"  -d "(object-contents)"

  • 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
);
  • cos.Object(bucket_name, item_name).put(Body=filelike_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`);
    });
}
  • 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)
}
Response
Status Code
  • 200
    OK
    

No Sample Response
This method does not specify any sample responses.
Read (download) an object
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
  • {
  "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"
}
Read object metadata
The HEAD operation retrieves metadata from an object without returning the object itself. This operation is useful if you're only interested in an object's metadata 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
    

Delete an object
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
  • {}
Copy an object
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
  • {
  "CopyObjectResult": {
    "ETag": "\"6805f2cfc46c0f04559748bb039d69ae\"",
    "LastModified": "2016-12-15T17:38:53.000Z"
  }
}
Delete multiple objects
This operation enables you to delete multiple objects from a bucket using a single HTTP request. If you know the object keys that you want to delete, then this operation provides a suitable alternative to sending individual delete requests, reducing per-request overhead. The request contains a list of up to 1000 keys that you want to delete. In the XML, you provide the object key names. 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
  • {
  "Deleted": [
    {
      "Key": "HappyFace.jpg",
      "VersionId": "yoz3HB.ZhCS_tKVEmIOr7qYyyAaZSKVd"
    },
    {
      "Key": "HappyFace.jpg",
      "VersionId": "2LWg7lQLnY41.maGB5Z6SWW.dcq0vx7b"
    }
  ]
}
Initiate a multipart upload
This operation initiates a multipart upload and returns an upload ID. This upload ID is used to associate all of the parts in the specific multipart upload. You specify this upload ID in each of your subsequent upload part requests. You also include this upload ID in the final request to either complete or abort the multipart upload request.


POST /{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
  • {
  "Bucket": "examplebucket",
  "Key": "largeobject",
  "UploadId": "ibZBv_75gd9r8lH_gqXatLdxMVpAlj6ZQjEs.OwyF3953YdwbcQnMA2BLGn8Lx12fQNICtMw5KyteFeHw.Sjng--"
}
Complete a multipart upload
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
  • {
  "Bucket": "acexamplebucket",
  "ETag": "\"4d9031c7644d8081c2829f4ea23c55f7-2\"",
  "Key": "bigobject",
  "Location": "https://examplebucket.s3.us-south.cloud-object-storage.appdomain.com/bigobject"
}
List parts of a multipart upload
Lists the parts that have been uploaded for a specific multipart upload. This operation must include the upload ID, which you obtain by sending the initiate multipart upload request. This request 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
  • {
  "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"
}
Abort a multipart upload
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
  • {}
List active multipart uploads
This operation lists in-progress multipart uploads. An in-progress multipart upload is a multipart upload that has been initiated using the Initiate Multipart Upload request, but has not yet been completed or aborted. This operation returns at most 1,000 multipart uploads in the response. 1,000 multipart uploads is the maximum number of uploads a response can include, which is also the default value. You can further limit the number of uploads in a response by specifying the max-uploads parameter in the response. If additional multipart uploads satisfy the list criteria, the response will contain an IsTruncated element with the value true. To list the additional multipart uploads, use the key-marker and upload-id-marker request parameters. In the response, the uploads are sorted by key. If your application has initiated more than one multipart upload using the same object key, then uploads in the response are first sorted by key. Additionally, uploads are sorted in ascending order within each key by the upload initiation time.


GET /{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
  • {
  "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--"
    }
  ]
}
Upload a part of an object
Uploads a part in a multipart upload. In this operation, you provide part data in your request. However, you have an option to specify your existing 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
  • {
  "ETag": "\"d8c2eafd90c266e19ab9dcacc479f8af\""
}
Use an existing object as a part of a new object
Uploads a part by copying data from an existing object as data source. You specify the data source by adding the request header x-amz-copy-source in your request and a byte range by adding the request header x-amz-copy-source-range in your request. The minimum allowable part size for a multipart upload is 5 MB. Instead of using an existing object as part data, you might use the 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 mu