Skip to main contentlogoCreated with Sketch.
  • Start for free

    • 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 covers only a subset of methods. For more information about all the methods, see About the IBM Cloud Object Storage S3 API.

    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

    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

    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

    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

    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

    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

    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

    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

    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

    Response

    Response Body

    DeleteObjectOutput

    Status Code

    • 200

      Success

    Example responses