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

Response Body

ListBucketsOutput

Status Code

  • 200

    Success

Example responses

Create a bucket

Creates a new bucket.

PUT /{Bucket}
Request

Path Parameters

  • Bucket
    string

Request Body

CreateBucketRequest
Example:
Response

Response Body

CreateBucketOutput

Status Code

  • 200

    Success

  • 480

    BucketAlreadyExists

  • 481

    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

  • Bucket
    string

Query Parameters

  • MaxKeys
    string

    Pagination limit

  • Marker
    string

    Pagination token

Request Body

ListObjectsRequest
Example:
Response

Response Body

ListObjectsOutput

Status Code

  • 200

    Success

  • 480

    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

  • Bucket
    string

Request Body

HeadBucketRequest
Example:
Response

Status Code

  • 200

    Success

  • 480

    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

  • Bucket
    string

Request Body

DeleteBucketRequest
Example:
Response

Status Code

  • 200

    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

  • Bucket
    string
  • Key
    string

Request Body

PutObjectRequest
Example:
Response

Response Body

PutObjectOutput

Status Code

  • 200

    Success

Example responses

Download an object

Retrieves objects.

GET /{Bucket}/{Key}
Request

Path Parameters

  • Bucket
    string
  • Key
    string

Request Body

GetObjectRequest
Example:
Response

Response Body

GetObjectOutput

Status Code

  • 200

    Success

  • 480

    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

  • Bucket
    string
  • Key
    string

Request Body

HeadObjectRequest
Example:
Response

Response Body

HeadObjectOutput

Status Code

  • 200

    Success

  • 480

    NoSuchKey

Example responses

Delete an object

Deletes an object from a bucket.

DELETE /{Bucket}/{Key}
Request

Path Parameters

  • Bucket
    string
  • Key
    string

Request Body

DeleteObjectRequest
Example:
Response

Response Body

DeleteObjectOutput

Status Code

  • 200

    Success

Example responses