Introduction

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.

This document only covers a small subset of operations. For comprehensive API reference Object Storage, see the IBM Cloud docs.

This guide provides examples in JSON but the API itself will return raw XML. Please see the IBM Cloud docs

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

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

GET /
Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • Success

Example responses

Create a bucket

Creates a new bucket.

PUT /{Bucket}
Request

Path Parameters

Example:
Response

Status Code

  • Success

  • BucketAlreadyExists

  • BucketAlreadyOwnedByYou

Example responses

List objects

Returns some or all (up to 1000) 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.

GET /{Bucket}
Request

Path Parameters

Query Parameters

  • Pagination limit

  • Pagination token

Example:
Response

Status Code

  • Success

  • NoSuchBucket

Example responses

Check a bucket's headers

This operation is useful to determine if a bucket exists and you have permission to access it.

HEAD /{Bucket}
Request

Path Parameters

Example:
Response

Status Code

  • Success

  • NoSuchBucket

No Sample Response

This method does not specify any sample responses.

Delete a bucket.

Deletes the bucket. All objects in the bucket must be deleted before the bucket itself can be deleted.

DELETE /{Bucket}
Request

Path Parameters

Example:
Response

Status Code

  • Success

No Sample Response

This method does not specify any sample responses.

Upload an object

Adds an object to a bucket.

PUT /{Bucket}/{Key}
Request

Path Parameters

Example:
Response

Status Code

  • Success

Example responses

Download an object

Retrieves objects.

GET /{Bucket}/{Key}
Request

Path Parameters

Example:
Response

Status Code

  • Success

  • NoSuchKey

Example responses

Check an object''s headers

The HEAD operation retrieves metadata from an object without returning the object itself. This operation is useful if you're only interested in an object's metadata. To use HEAD, you must have READ access to the object.

HEAD /{Bucket}/{Key}
Request

Path Parameters

Example:
Response

Status Code

  • Success

  • NoSuchKey

Example responses

Delete an object

Deletes an object from a bucket.

DELETE /{Bucket}/{Key}
Request

Path Parameters

Example:
Response

Status Code

  • Success

Example responses