List buckets in a service instance
GET /
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.account.get_account_buckets
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.instance.list
Request
Path Parameters
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.
Response
200 - Success
PUT /{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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.bucket.put_bucket
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.bucket.create
Request
Request Body
Path Parameters
Bucket
Required *
string
The name of the bucket to create.
Query Parameters
Response
200 - Success
409 - BucketAlreadyExists
Delete a bucket
DELETE /{Bucket}
Only empty buckets may be deleted. A bucket name is returned to the available namespace approximately 10 minutes after deletion.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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.
Query Parameters
Response
204 - Success
Read a bucket's headers
HEAD /{Bucket}
This request is useful for checking whether a bucket has Key Protect enabled.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.bucket.headcloud-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.
Query Parameters
Response
200 - Success
404 - NoSuchBucket
List objects in a bucket (v1)
GET /{Bucket}
Returns some or all (up to 1,000) of the objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket. A `200 OK` response can contain valid or invalid XML. 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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
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.
Response
200 - Success
404 - NoSuchBucket
List objects in a bucket (v2)
GET /{Bucket}?list-type=2
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
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.
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-type
Required *
string
Response
200 - Success
404 - NoSuchBucket
List object versions
GET /{Bucket}?list-object=versions
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
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.
key-marker
string
Key marker specifies the starting object for listing.
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-type
Required *
string
Response
200 - Success
404 - NoSuchBucket
PUT /{Bucket}/{Key}
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.object.put
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.object.write
Request
Request Body
Path Parameters
Bucket
Required *
string
The bucket that will hold the object.
Key
Required *
string
Object key for which the PUT operation was initiated.
Query Parameters
Response
200 - OK
Read (download) an object
GET /{Bucket}/{Key}
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`
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.object.get
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.object.read
Request
Path Parameters
Bucket
Required *
string
The bucket containing the object.
Key
Required *
string
Key of the object to get.
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
string
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
200 - Success
404 - NoSuchKey
Read object metadata
HEAD /{Bucket}/{Key}
The HEAD operation retrieves metadata from an object without returning the object itself. This operation is useful if you're only interested in an object's metadata or it's existence.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.bucket.headcloud-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 bucket containing the object.
Key
Required *
string
The object key.
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
200 - Success
404 - NoSuchKey
DELETE /{Bucket}/{Key}
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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.
Query Parameters
Response
204 - Success
Copy an object
PUT /{Bucket}/{TargetKey}
Copies an object.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.object.copycloud-object-storage.object.copy_get
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.object-copy.readcloud-object-storage.object-copy.create
Request
Request Body
Path Parameters
Bucket
Required *
string
The name of the destination bucket.
TargetKey
Required *
string
The key of the destination object.
Query Parameters
Response
200 - Success
404 - ObjectNotInActiveTierError
Initiate a multipart upload
POST /{Bucket}/{Key}?uploads
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.object.post_initiate_upload
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.object-multipart.start
Request
Request Body
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.
Query Parameters
uploads
Required *
boolean
Response
200 - Success
POST /{Bucket}/{Key}?uploadId={uploadId}
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.object.post_complete_upload
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.object-multipart.complete
Request
Request Body
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.
Query Parameters
uploadId
Required *
string
ID for the initiated multipart upload.
Response
200 - Success
List parts of a multipart upload
GET /{Bucket}/{Key}?uploadId={uploadId}
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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.
Query Parameters
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.
uploadId
Required *
string
Upload ID identifying the multipart upload whose parts are being listed.
Response
200 - Success
Abort a multipart upload
DELETE /{Bucket}/{Key}?uploadId={uploadId}
Stops a current multipart upload and removes any parts of an incomplete upload, which would otherwise incur storage costs.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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.
Query Parameters
uploadId
Required *
string
Upload ID that identifies the multipart upload.
Response
204 - Success
404 - NoSuchUpload
PUT /{Bucket}?lifecycle
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.bucket.put_lifecycle
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.bucket-lifecycle.create
Request
Request Body
Path Parameters
Bucket
Required *
string
The name of the bucket for which to set the configuration.
Query Parameters
lifecycle
Required *
boolean
Response
200 - Success
Read a lifecycle configuration
GET /{Bucket}?lifecycle
Returns the lifecycle configuration information set on the bucket.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
Response
200 - Success
Delete a lifecycle configuration
DELETE /{Bucket}?lifecycle
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
Response
204 - Success
PUT /{Bucket}?replication
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`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.bucket.put_replication
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.bucket-replication.create
Request
Request Body
Path Parameters
Bucket
Required *
string
The name of the bucket for which to set the configuration.
Query Parameters
replication
Required *
boolean
Response
200 - Success
Read a replication configuration
GET /{Bucket}?replication
Returns the replication configuration information set on the bucket.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
Response
200 - Success
Delete a replication configuration
DELETE /{Bucket}?replication
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
Response
204 - Success
List replication failures in a bucket
GET /{Bucket}?ibm-replication-failures
Returns some or all (up to 1,000) of the replication failures in a source bucket. You can use the request parameters as selection criteria to return a subset of the failures and use continuation token for paging when the result is truncated.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.bucket.get_replication_failures
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.bucket-replication-failures.list
Request
Path Parameters
Bucket
Required *
string
The name of the source bucket for which to list replication failures.
Query Parameters
ibm-replication-failures
Required *
boolean
encoding-type
string
continuation-token
string
Specifies the failure at which the listing should begin, in reverse chronological order. This is used for pagination purposes if there are more entries present after the entries returned in the last listing request.
max-keys
string
Restricts the number of failures to display in the response. Default and maximum is 1,000.
first-sync-attempted-before
string
Specifies the timestamp at which the listing should begin, in reverse chronological order. The time corresponds to when the replication was originally triggered (<FirstSyncAttempted> field in the entry). Thus, the listing will contain any replication failures that are at least as old as the specified timestamp.
Response
200 - Success
PUT /{Bucket}?ibm-replication-reattempt
This schedules a re-attempt of all replication failures, including any stale failures that are older than 30 days and no longer eligible for automatic retries by the system. Long-term replication failures are processed in 24 hour cycles.
Issuing this request schedules reattempts for the stale failures in the cycle starting at the next midnight GMT. For example, if a request is issued at `2026-01-01T01:00:00Z`, the earliest time at which these failures get processed is `2026-01-02T00:00:00Z`. On successful request, this timestamp is also provided in the response header `x-ibm-replication-reattempt-scheduled-time`. Multiple requests arriving on the same day in GMT (that is, resulting in the same scheduled time) are idempotent.
Each stale failure is re-attempted once on a best-effort basis. They are executed, but no guarantees are made on their timing.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.bucket.put_replication_reattempt
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.bucket-replication-failures.update
Request
Path Parameters
Bucket
Required *
string
The name of the source bucket for which to schedule replication failure reattempts.
Query Parameters
ibm-replication-reattempt
Required *
boolean
Response
200 - Success
Temporarily restore an archived object
POST /{Bucket}/{Key}?restore
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.object.restore
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.object-restore.readcloud-object-storage.object-restore.create
Request
Request Body
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.
Query Parameters
restore
Required *
boolean
Response
200 - Success
404 - ObjectAlreadyInActiveTierError
Create a protection configuration
PUT /{Bucket}?protection
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.bucket.put_protection
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.bucket-retention.create
Request
Request Body
Path Parameters
Bucket
Required *
string
The name of the bucket for which to set the configuration.
Query Parameters
protection
Required *
boolean
Response
200 - Success
Create a website configuration
PUT /{Bucket}?website
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.bucket.put_website
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.bucket-website.create
Request
Request Body
Path Parameters
Bucket
Required *
string
The bucket that will serve a static website.
Query Parameters
website
Required *
boolean
Response
200 - Success
Read a website configuration
GET /{Bucket}?website
Returns the website configuration for a bucket.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
Response
200 - Success
Delete a website configuration
DELETE /{Bucket}?website
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
Response
204 - Success
PUT /{Bucket}?cors
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.bucket.put_cors
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.bucket-cors.create
Request
Request Body
Path Parameters
Bucket
Required *
string
Specifies the bucket impacted by the CORS configuration.
Query Parameters
cors
Required *
boolean
Response
200 - Success
Read a CORS configuration
GET /{Bucket}?cors
Returns the CORS configuration information set for the bucket.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
Response
200 - Success
Delete a CORS configuration
DELETE /{Bucket}?cors
Deletes the CORS configuration information set for the bucket.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
Response
204 - Success
Add a set of tags to an object
PUT /{Bucket}/{Key}?tagging
Sets tags on an object that already exists. A tag is a key-value pair.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.object.put_tagging
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.object-tagging.create
Request
Request Body
Path Parameters
Bucket
Required *
string
The bucket containing the object.
Key
Required *
string
Name of the object key.
Query Parameters
tagging
Required *
boolean
Response
200 - Success
Read a set of object tags
GET /{Bucket}/{Key}?tagging
Returns the tags of an object.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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.
Query Parameters
tagging
Required *
boolean
Response
200 - Success
Delete a set of object tags
DELETE /{Bucket}/{Key}?tagging
Removes the entire tag set from the specified object.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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.
Query Parameters
tagging
Required *
boolean
Response
204 - Success
Delete multiple objects
POST /{Bucket}?delete
This operation enables you to delete multiple objects from a bucket using a single HTTP request. If you know the object keys that you want to delete, then this operation provides a suitable alternative to sending individual delete requests, reducing per-request overhead. The request contains a list of up to 1000 keys that you want to delete. In the XML, you provide the object key names. 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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.object.post_multi_delete
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.object-batch.delete
Request
Request Body
Path Parameters
Bucket
Required *
string
The bucket name containing the objects to delete.
Query Parameters
delete
Required *
boolean
Response
200 - Success
Create a public ACL block configuration
PUT /{Bucket}?publicAccessBlock
Creates or modifies the `PublicAccessBlock` configuration for an IBM COS bucket.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
Request Body
Path Parameters
Bucket
Required *
string
The name of the IBM COS bucket whose `PublicAccessBlock` configuration you want to set.
Query Parameters
publicAccessBlock
Required *
boolean
Response
200 - Success
Read a public ACL block configuration
GET /{Bucket}?publicAccessBlock
Retrieves the `PublicAccessBlock` configuration for an IBM COS bucket.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
Response
200 - Success
Delete a public ACL block configuration
DELETE /{Bucket}?publicAccessBlock
Removes the `PublicAccessBlock` configuration for an IBM COS bucket.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
Response
204 - Success
Read a bucket ACL
GET /{Bucket}?acl
This implementation of the `GET` operation uses the `acl` subresource to return the access control list (ACL) of a bucket.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
Response
200 - Success
Create a bucket ACL
PUT /{Bucket}?acl
This operation should not be used. Instead, use IAM policies to grant public access.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.bucket.put_acl
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.bucket-acl.create
Request
Path Parameters
Bucket
Required *
string
The bucket to which to apply the ACL.
Query Parameters
acl
Required *
boolean
Response
200 - Success
Read an object ACL
GET /{Bucket}/{Key}?acl
This operation should not be used. Instead, use IAM policies to grant public access.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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.
Query Parameters
acl
Required *
boolean
Response
200 - Success
404 - NoSuchKey
Make an object publicly accessible
PUT /{Bucket}/{Key}?acl
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.object.put_acl
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.object-acl.create
Request
Request Body
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.
Query Parameters
acl
Required *
boolean
Response
200 - Success
404 - NoSuchKey
List active multipart uploads
GET /{Bucket}?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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
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
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
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
uploads
Required *
boolean
Response
200 - Success
PUT /{Bucket}/{Key}?partNumber={partNumber}&uploadId={uploadId}
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.object.put_part
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.object-multipart.create
Request
Request Body
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.
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.
Response
200 - Success
PUT /{Bucket}/{TargetKey}?partNumber={partNumber}&uploadId={uploadId}
Uploads a part by copying data from an existing object as data source. You specify the data source by adding the request header `x-amz-copy-source` in your request and a byte range by adding the request header `x-amz-copy-source-range` in your request. The minimum allowable part size for a multipart upload is 5 MB. Instead of using an existing object as part data, you might use the `UploadPart`operation and provide data in your request.
You must initiate a multipart upload before you can upload any part. In response to your initiate request. 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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
cloud-object-storage.object.copy_partcloud-object-storage.object.copy_part_get
Auditing
Calling this method generates the following auditing event.
cloud-object-storage.object-multipart.create
Request
Path Parameters
Bucket
Required *
string
The bucket name.
Key
Required *
string
Object key for which the multipart upload was initiated.
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.