Spaces API Reference Documentation

Spaces provides a RESTful XML API for programmatically managing the data you store through standard HTTP requests. The API is interoperable with Amazon’s AWS S3 API, allowing you to interact with the service with any S3-compatible tools.

Spaces and Spaces CDN supports HTTP/2 and HTTP/1.1 clients. Any HTTP/2 conformant client receives HTTP/2 responses, otherwise HTTP/1.1 responses are returned. Some HTTP/2 requests are downgraded to HTTP/1.1 for operational reasons, as permitted by the HTTP/2 specification.

You can use the Spaces API in the following ways:

AWS S3 Compatibility

For the full list of supported S3 API commands, see Supported S3 Commands.

The Spaces API aims to be interoperable with Amazon’s AWS S3 API. In most cases, when using a client library, setting the endpoint or base URL to ${REGION}.digitaloceanspaces.com and generating a Spaces key pair to replace your AWS IAM key pair allows you to use Spaces in place of S3.

Spaces provides support for create, read, update, and delete (CRUD) operations for both buckets (Spaces) and objects as well as the ability to define access control lists (ACLs). Some S3 features are not supported as show in the table below:

Feature Supported Notes
Bucket CRUD Yes
Object CRUD Yes
Object Copy Yes Cross region copying is not supported. For regions with multiple clusters, cross-cluster copying is not supported.
Multipart Uploads Yes
Pre-Signed URLs Yes Both v2 and v4 signature types are supported.
Bucket ACLs Yes
Object ACLs Yes
Identity and Access Management (IAM) No
Security Token Service (STS) No
Multi-factor Authentication No
Public Access Block No
Bucket Policies Yes API only
Object Policies No
Bucket Versioning Yes API only; not accessible through the control panel.
Bucket Replication No
Bucket Notifications No
Bucket Tagging No
Object Tagging Yes
Request Payment No
Bucket Lifecycle Yes Object expiration and removing incomplete multipart uploads are supported. Lifecycle policies based on object tagging are not supported.
Bucket Inventory No
Bucket Access Logging No
Bucket Metrics No
Bucket Analytics No
Bucket Accelerate No
Bucket Encryption Configuration No
Object Encryption Yes Customer-provided encryption keys (SSE-C) are supported.
Bucket Websites Yes See PutBucketWebsite command for details. CDN not supported.
Object Torrent No
Object Lock No

API requests for S3 functionality that is not supported by Spaces receive an S3-compatible, XML-formatted NotImplemented error response.

The AWS S3 API is compatible with JavaScript, Go, PHP, Python 3, and Ruby. For example, the following code returns a list of Spaces (or buckets) in your specified region:

package main

import (
    "fmt"
    "log"
    "os"

    "github.com/minio/minio-go"
)

func main() {
    accessKey := os.Getenv("SPACES_KEY")
    secKey := os.Getenv("SPACES_SECRET")
    endpoint := "nyc3.digitaloceanspaces.com"
    spaceName := "my-new-space" // Space names must be globally unique
    ssl := true

    // Initiate a client using DigitalOcean Spaces.
    client, err := minio.New(endpoint, accessKey, secKey, ssl)
    if err != nil {
        log.Fatal(err)
    }

    // Create a new Space.
    err = client.MakeBucket(spaceName, "us-east-1")
    if err != nil {
        log.Fatal(err)
    }

    // List all Spaces.
    spaces, err := client.ListBuckets()
    if err != nil {
        log.Fatal(err)
    }
    for _, space := range spaces {
        fmt.Println(space.Name)
    }
}```
import boto3
from botocore.client import Config

# Initialize a session using DigitalOcean Spaces.
session = boto3.session.Session()
client = session.client('s3',
                        region_name='nyc3',
                        endpoint_url='https://nyc3.digitaloceanspaces.com',
                        aws_access_key_id='532SZONTQ6ALKBCU94OU',
                        aws_secret_access_key='zCkY83KVDXD8u83RouEYPKEm/dhPSPB45XsfnWj8fxQ')

# Create a new Space.
client.create_bucket(Bucket='my-new-space')

# List all buckets on your account.
response = client.list_buckets()
spaces = [space['Name'] for space in response['Buckets']]
print("Spaces List: %s" % spaces)

For additional examples, see Using DigitalOcean Spaces with AWS S3 SDKs.

“Hello, World!” Program

After creating a new Space, you can upload a “Hello, World!” object to it:

// Step 1: Import the S3Client object and all necessary SDK commands.
import { PutObjectCommand, S3Client } from '@aws-sdk/client-s3';


// Step 2: The s3Client function validates your request and directs it to your Space's specified endpoint using the AWS SDK.
const s3Client = new S3Client({
    endpoint: "https://nyc3.digitaloceanspaces.com", // Find your endpoint in the control panel, under Settings. Prepend "https://".
    forcePathStyle: false, // Configures to use subdomain/virtual calling format.
    region: "us-east-1", // Must be "us-east-1" when creating new Spaces. Otherwise, use the region in your endpoint (for example, nyc3).
    credentials: {
      accessKeyId: "C58A976M583E23R1O00N", // Access key pair. You can create access key pairs using the control panel or API.
      secretAccessKey: process.env.SPACES_SECRET // Secret access key defined through an environment variable.
    }
});


// Step 3: Define the parameters for the object you want to upload.
const params = {
  Bucket: "example-space", // The path to the directory you want to upload the object to, starting with your Space name.
  Key: "folder-path/hello-world.txt", // Object key, referenced whenever you want to access this file later.
  Body: "Hello, World!", // The object's contents. This variable is an object, not a string.
  ACL: "private", // Defines ACL permissions, such as private or public.
  Metadata: { // Defines metadata tags.
    "x-amz-meta-my-key": "your-value"
  }
};


// Step 4: Define a function that uploads your object using SDK's PutObjectCommand object and catches any errors.
const uploadObject = async () => {
  try {
    const data = await s3Client.send(new PutObjectCommand(params));
    console.log(
      "Successfully uploaded object: " +
        params.Bucket +
        "/" +
        params.Key
    );
    return data;
  } catch (err) {
    console.log("Error", err);
  }
};


// Step 5: Call the uploadObject function.
uploadObject();
// Step 1: Import the all necessary libraries and SDK commands.
package main
import (
    "fmt"
    "strings"

    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/credentials"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/s3"
)


func main() {

    // Step 2: Define the parameters for the session you want to create.
    key := "C58A976M583E23R1O00N" // Access key pair. You can create access key pairs using the control panel or API.
    secret := os.Getenv("SPACES_SECRET") // Secret access key defined through an environment variable.

    s3Config := &aws.Config{
        Credentials: credentials.NewStaticCredentials(key, secret, ""), // Specifies your credentials.
        Endpoint:    aws.String("https://nyc3.digitaloceanspaces.com"), // Find your endpoint in the control panel, under Settings. Prepend "https://".
        S3ForcePathStyle: aws.Bool(false), // // Configures to use subdomain/virtual calling format. Depending on your version, alternatively use o.UsePathStyle = false
        Region:      aws.String("us-east-1"), // Must be "us-east-1" when creating new Spaces. Otherwise, use the region in your endpoint, such as "nyc3".
    }

    // Step 3: The new session validates your request and directs it to your Space's specified endpoint using the AWS SDK.
    newSession := session.New(s3Config)
    s3Client := s3.New(newSession)

    // Step 4: Define the parameters of the object you want to upload.
    object := s3.PutObjectInput{
        Bucket: aws.String("example-space-name"), // The path to the directory you want to upload the object to, starting with your Space name.
        Key:    aws.String("folder-path/hello-world.txt"), // Object key, referenced whenever you want to access this file later.
        Body:   strings.NewReader("Hello, World!"), // The object's contents.
        ACL:    aws.String("private"), // Defines Access-control List (ACL) permissions, such as private or public.
        Metadata: map[string]*string{ // Required. Defines metadata tags.
                                 "x-amz-meta-my-key": aws.String("your-value"),
                         },
    }

    // Step 5: Run the PutObject function with your parameters, catching for errors.
    _, err := s3Client.PutObject(&object)
    if err != nil {
        fmt.Println(err.Error())
    }
}
# Step 1: Import the all necessary libraries and SDK commands.
import os
import boto3

# Step 2: The new session validates your request and directs it to your Space's specified endpoint using the AWS SDK.
session = boto3.session.Session()
client = session.client('s3',
                        endpoint_url='https://nyc3.digitaloceanspaces.com', # Find your endpoint in the control panel, under Settings. Prepend "https://".
                        config=botocore.config.Config(s3={'addressing_style': 'virtual'}), # Configures to use subdomain/virtual calling format.
                        region_name='nyc3', # Use the region in your endpoint.
                        aws_access_key_id='C58A976M583E23R1O00N', # Access key pair. You can create access key pairs using the control panel or API.
                        aws_secret_access_key=os.getenv('SPACES_SECRET')) # Secret access key defined through an environment variable.

# Step 3: Call the put_object command and specify the file to upload.
client.put_object(Bucket='example-space-name', # The path to the directory you want to upload the object to, starting with your Space name.
                  Key='folder-path/hello-world.txt', # Object key, referenced whenever you want to access this file later.
                  Body=b'Hello, World!', # The object's contents.
                  ACL='private', # Defines Access-control List (ACL) permissions, such as private or public.
                  Metadata={ # Defines metadata tags.
                      'x-amz-meta-my-key': 'your-value'
                  }
                )
# Step 1: Import the S3 AWS SDK.
require 'aws-sdk-s3'

# Step 2: The s3Client function validates your request and directs it to your Space's specified endpoint using the AWS SDK.
client = Aws::S3::Client.new(
  access_key_id: 'C58A976M583E23R1O00N', # Access key pair. You can create access key pairs using the control panel or API.
  secret_access_key: ENV['SPACES_SECRET'], # Secret access key defined through an environment variable.
  endpoint: 'https://nyc3.digitaloceanspaces.com', # Find your endpoint in the control panel, under Settings. Prepend "https://".
  force_path_style: false, # Configures to use subdomain/virtual calling format.
  region: 'us-east-1' # Must be "us-east-1" when creating new Spaces. Otherwise, use the region in your endpoint, such as "nyc3".
)

# Step 3: Call the put_object command and specify the file to upload.
client.put_object({
  bucket: "example-space-name", # The path to the directory you want to upload the object to, starting with your Space name.
  key: "folder-path/hello-world.txt", # Object key, referenced whenever you want to access this file later.
  body: "Hello, World!", # The object's contents.
  acl: "private" # Defines Access-control List (ACL) permissions, such as private or public.
})
# Step 1: Define the parameters for the Space you want to upload to.
SPACE="nyc-tutorial-space" # Find your endpoint in the control panel, under Settings.
REGION="nyc3" # Must be "us-east-1" when creating new Spaces. Otherwise, use the region in your endpoint (for example, nyc3).
STORAGETYPE="STANDARD" # Storage type, can be STANDARD, REDUCED_REDUNDANCY, etc.
KEY="5SGMECSBJ6UPVC2AJ6B4" # Access key pair. You can create access key pairs using the control panel or API.
SECRET="$SECRET" # Secret access key defined through an environment variable.

# Step 2: Define a function that uploads your object via cURL.
function putS3
{
  path="." # The local path to the file you want to upload.
  file="hello-world.txt" # The file you want to upload.
  space_path="/" # The path within your Space where you want to upload the new file.
  space="${SPACE}"
  date=$(date +"%a, %d %b %Y %T %z")
  acl="x-amz-acl:private" # Defines Access-control List (ACL) permissions, such as private or public.
  content_type="text/plain" # Defines the type of content you are uploading.
  storage_type="x-amz-storage-class:${STORAGETYPE}"
  string="PUT\n\n$content_type\n$date\n$acl\n$storage_type\n/$space$space_path$file"
  signature=$(echo -en "${string}" | openssl sha1 -hmac "${SECRET}" -binary | base64)
  curl -s -X PUT -T "$path/$file" \ # The cURL command that uploads your file.
    -H "Host: $space.${REGION}.digitaloceanspaces.com" \
    -H "Date: $date" \
    -H "Content-Type: $content_type" \
    -H "$storage_type" \
    -H "$acl" \
    -H "Authorization: AWS ${KEY}:$signature" \
    "https://$space.${REGION}.digitaloceanspaces.com$space_path$file"
}

# Step 3: Run the putS3 function.
for file in "$path"/*; do
  putS3 "$path" "${file##*/}" "nyc-tutorial-space/"
done

For additional examples, see Using DigitalOcean Spaces with AWS S3 SDKs.

Authentication

Requests to the Spaces API must include an HTTP Authorization header. The AWS v4 Signature type is supported as well as the AWS v2 Signature type for compatibility with older clients. Throughout the examples below, v4 signatures are used. When making use of a client library, signatures are generated for you automatically.

You can generate the needed Access Key and Secret Key by visiting the API section of the DigitalOcean Control Panel for your account.

A v4 signature consists of several parts. The table below describes each piece of the example individually:

Signature component Description
AWS4-HMAC-SHA256 Indicates AWS Signature Version 4 (AWS4) and the signing algorithm (HMAC-SHA256).
Credential Contains your access key and information about the request in the format: ${ACCESS_KEY}/${YYYMMDD}/${REGION_SLUG}/s3/aws4_request
SignedHeaders A lower-cased list of the names of the request headers used when computing the signature. (for example, host;x-amz-acl;x-amz-content-sha256;x-amz-date)
Signature A signed hash consisting of a hash of the request body, your secret key, and information about the request (that is, the canonical request). A “pseudo-code” example is provided to demonstrate how this is calculated.

The canonical request included in the signature is made up of:

  • The HTTP request method used.
  • The path component of the request URI.
  • The query string parameters included in the request.
  • The list of request headers and their values, newline separated, lower-cased, and trimmed of whitespace.
  • The list of header names without their values, sorted alphabetically, lower-cased, and semicolon-separated.
  • The SHA256 hash of the request body.

For example, for the following request:

GET /?acl HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20170804T221549Z

This would be the canonical request:

GET
/
acl=
host:static-images.nyc3.digitaloceanspaces.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20170804T221549Z

host;x-amz-content-sha256;x-amz-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Example Authorization Header

Authorization: AWS4-HMAC-SHA256
Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,
SignedHeaders=host;x-amz-acl;x-amz-content-sha256;x-amz-date,
Signature=6cab03bef74a80a0441ab7fd33c829a2cdb46bba07e82da518cdb78ac238fda5

Signing Example (pseudo-code)

canonicalRequest = `
${HTTPMethod}\n
${canonicalURI}\n
${canonicalQueryString}\n
${canonicalHeaders}\n
${signedHeaders}\n
${hashedPayload}
`

stringToSign = "AWS4-HMAC-SHA256" + "\n" +
    date(format=ISO08601) + "\n" +
    date(format=YYYYMMDD) + "/" + ${REGION} + "/" + "s3/aws4_request" + "\n" +
    Hex(SHA256Hash(canonicalRequest))

dateKey = HMAC-SHA256("AWS4" + ${SECRET_KEY}, date(format=YYYYMMDD))
dateRegionKey = HMAC-SHA256(dateKey, ${REGION})
dateRegionServiceKey = HMAC-SHA256(dateRegionKey, "s3")
signingKey = HMAC-SHA256(dateRegionServiceKey, "aws4_request")

signature = Hex(HMAC-SHA256(signingKey, stringToSign))

Access Control Lists (ACLs)

Spaces supports a limited set of access controls for buckets and objects. They can be configured by making a PUT request with an XML body consisting of an AccessControlPolicy element. It should contain both Grantee and Permission elements. Grantee may either contain the owner’s ID or a URI element representing the AllUsers group. The available Permission values are:

Name Description
FULL_CONTROL Grants full access including read and write permissions to the object or bucket.
READ Grants read access to the object or bucket.

To make a bucket or object private, create an AccessControlPolicy only containing a FULL_CONTROL grant for the owner. To allow public read access, the AccessControlPolicy should contain both a FULL_CONTROL grant for the owner as well as READ grand for the AllUsers group. (See the full reference documentation below for more information on the specific requests.)

For convenience, you can use canned ACLs in place of uploading an AccessControlPolicy. They are a set of pre-defined access controls that can be specified through the use of the x-amz-acl header when making a request. Currently Spaces supports these values:

Name Description
private Grants full access (FULL_CONTROL) to the owner. No unauthenticated, public access is permitted.
public-read Grants full access (FULL_CONTROL) to the owner while permitting unauthenticated, public READ access.

Private ACL Example

    <AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
      <Owner>
        <ID>6174283</ID>
      </Owner>
      <AccessControlList>
        <Grant>
          <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
            <ID>6174283</ID>
          </Grantee>
          <Permission>FULL_CONTROL</Permission>
        </Grant>
      </AccessControlList>
    </AccessControlPolicy>

Public Read ACL Example

    <AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
      <Owner>
        <ID>6174283</ID>
        <DisplayName>6174283</DisplayName>
      </Owner>
      <AccessControlList>
        <Grant>
          <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
            <URI>http://acs.amazonaws.com/groups/global/AllUsers</URI>
          </Grantee>
          <Permission>READ</Permission>
        </Grant>
        <Grant>
          <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
            <ID>6174283</ID>
          </Grantee>
          <Permission>FULL_CONTROL</Permission>
        </Grant>
      </AccessControlList>
    </AccessControlPolicy>

Common Headers

There are a number of common headers that may be used in most requests.

Name Description
Authorization The authorization details for the request in either the AWS Signature Version 4 or AWS Signature Version 2 format (see Authentication for more information).
Content-Length The length in bytes of the request body. Required with PUT requests containing an XML body.
Content-Type The MIME type of the request body (for example, text/plain).
Date The current date and time date in Coordinated Universal Time (UTC) using RFC 2822 format. Example: Mon, 10 Jul 2017 19:05:09 +0000
Host The target host for the request (for example, ${REGION}.digitaloceanspaces.com or ${BUCKET}.${REGION}.digitaloceanspaces.com).
x-amz-content-sha256 The SHA256 hash of the request payload. Required when using AWS Signature Version 4 for authentication.
x-amz-date The current date and time date in Coordinated Universal Time (UTC) using the ISO 8601 format: %Y%m%dT%H%M%SZ (for example, 20170803T172753Z). When provided, it takes precedence over the “Date” header.

Likewise, these common headers may be received in most responses:

Name Description
Content-Length The length in bytes of the response body.
Content-Type The MIME type of the request body (for example, text/plain).
Connection An indicator of whether the connection to the server is open or closed.
Date The date and time date of the response in Coordinated Universal Time (UTC).
ETag The entity tag containing an MD5 hash of the object.
x-amz-request-id The unique identifier for the request.

Bucket Operations

A bucket is a container for objects, such as image files and other data, that are stored in DigitalOcean Spaces. The following methods allow you to create, delete, and manage buckets.

Create a Bucket

To create a new bucket, send a PUT request to ${BUCKET}.${REGION}.digitaloceanspaces.com

In addition to the common headers, the following headers may also be supplied:

Name Description Required
x-amz-acl A “canned” ACL specifying access rules for the bucket (for example, private or public-read). Defaults to private No

For compatibility purposes, the body of the request may contain an XML object with an element named CreateBucketConfiguration containing configuration information for the bucket, specifically its location. As the region is also specified in the hostname, including this in the request is not strictly necessary.

Name Description Required
LocationConstraint The region where the bucket will be created (for example, nyc3). No

Example Request

    PUT / HTTP/1.1

    Host: static-images.nyc3.digitaloceanspaces.com
    x-amz-acl: public-read
    x-amz-content-sha256: c6f1fc479f5f690c443b73a258aacc06ddad09eca0b001e9640ff2cd56fe5710
    x-amz-date: 20170710T173143Z
    Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-acl;x-amz-content-sha256;x-amz-date,Signature=6cab03bef74a80a0441ab7fd33c829a2cdb46bba07e82da518cdb78ac238fda5

    <CreateBucketConfiguration>
      <LocationConstraint>nyc3</LocationConstraint>
    </CreateBucketConfiguration>

Example Response

    HTTP/1.1 200 OK

    Date: Mon, 10 Jul 2017 17:31:43 GMT
    Content-Length: 0
    Content-Type: text/plain;charset=utf-8
    Connection: close

List All Buckets

To list all existing buckets in a region, send a GET request to ${REGION}.digitaloceanspaces.com

The body of the response contains an XML element named ListAllMyBucketsResult containing a list of XML objects with the following elements representing each bucket:

Name Description
Owner A container holding elements with information about the bucket’s owner.
ID An element containing the ID of the bucket’s owner as its value.
DisplayName An element containing the DisplayName of the bucket’s owner as its value. Provided for compatibility purposes, has the same value as the ID.
Buckets A container holding a list of elements describing each bucket.
Bucket A container holding elements with details about a single bucket.
Name An element containing the name of the bucket.
CreationDate An element containing the date of the bucket’s creation in the format: %Y-%m-%dT%H:%M:%S.%3NZ (for example, 2017-06-23T18:37:48.157Z)

Example Request

GET / HTTP/1.1

Host: nyc3.digitaloceanspaces.com
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20170711T183940Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170711/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=245e867a6a653b7b88cbb71a734dacf2cbb4ba927d9aa5fdce57c85ab4f2b40b

Example Response

HTTP/1.1 200 OK

x-amz-request-id: tx000000000000002ba2427-0059651b6d-1268c-nyc3a
Date: Mon, 10 Jul 2017 17:31:43 GMT
Content-Length: 523
Content-Type: text/plain
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
  <ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Owner>
      <ID>6174283</ID>
      <DisplayName>6174283</DisplayName>
    </Owner>
    <Buckets>
      <Bucket>
        <Name>static-images</Name>
        <CreationDate>2017-06-23T18:37:48.157Z</CreationDate>
      </Bucket>
    <Buckets>
      <Bucket>
        <Name>log-files</Name>
        <CreationDate>2017-06-23T18:37:48.157Z</CreationDate>
      </Bucket>
    </Buckets>
  </ListAllMyBucketsResult>

List a Bucket’s Contents

To list the contents of a bucket, send a GET request to ${BUCKET}.${REGION}.digitaloceanspaces.com/

Note
The version 2 list type is not currently supported.

The following query parameters can be included in the request in order to filter the results included in the response:

Name Description Required
delimiter A single character used to group keys. When specified, the response will only contain keys up to its first occurrence. (for example, using a slash as the delimiter can allow you to list keys as if they were folders, especially in combination with a prefix.) No
marker The key (object name) to start with when listing objects. For use with pagination (for example, when then number of objects in the result exceeds the specified max-keys). No
max-keys The maximum number of objects to return. Valid inputs of 0 to 1,000 inclusive. No
prefix A string used to group keys. When specified, the response only contains objects with keys beginning with the string. No

The body of the response contains an XML element named ListBucketResult containing a list of XML objects with the following elements representing each object in the bucket:

Name | Description Name | The name of the bucket. Prefix | The specified prefix if supplied as a query parameter. Marker | A key denoting where the list of objects begins. If empty, this indicates the beginning of the list. NextMarker | Specifies the key which should be used with the maker query parameter in subsistent requests. This is only returned if a delimiter was provided with the request and IsTruncated is true. MaxKeys | The maximum number of objects to return, based on max-keys query parameter after input validation. IsTruncated | A boolean indicating whether all objects are included in the response. Contents | A container holding elements with information about the objects in the bucket. Key | The object’s key. LastModified | The date and time that the object was last modified in the format: %Y-%m-%dT%H:%M:%S.%3NZ (for example, 2017-06-23T18:37:48.157Z) ETag | The entity tag containing an MD5 hash of the object. Size | The size of the object in bytes. StorageClass | Provided for compatibility purposes. The value is always STANDARD. Owner | A container holding elements with information about the bucket’s owner. ID | An element containing the ID of the bucket’s owner as its value. DisplayName | An element containing the DisplayName of the bucket’s owner as its value. Provided for compatibility purposes, has the same value as the ID.

Example Request

GET / HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20170714T172613Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=de1bf8931e315c0576edb81a7d8be98874e847548fc70682f6c646e1cfd9177a

Example Response

HTTP/1.1 200 OK

x-amz-request-id: tx00000000000000029ac87-0059690330-8d1a-nyc3a
Date: Mon, 10 Jul 2017 17:31:43 GMT
Content-Length: 775
Content-Type: application/xml
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>static-images</Name>
  <Prefix/>
  <MaxKeys>1000</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>example.txt</Key>
    <LastModified>2017-07-13T18:40:46.777Z</LastModified>
    <ETag>"b3a92f49e7ae64acbf6b3e76f2040f5e"</ETag>
    <Size>14</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>6174283</ID>
      <DisplayName>6174283</DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>sammy.png</Key>
    <LastModified>2017-07-14T17:44:03.597Z</LastModified>
    <ETag>"fb08934ef619f205f272b0adfd6c018c"</ETag>
    <Size>35369</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>6174283</ID>
      <DisplayName>6174283</DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>

Delete a Bucket

To delete an empty bucket, send a DELETE request to ${BUCKET}.${REGION}.digitaloceanspaces.com This API call can only be used to delete an empty bucket.

Success is indicated by receiving 204 (No Content) as the response code.

If you receive 409 (BucketNotEmpty) as the response code, it means that you have objects in the bucket. You must remove all of the objects from the bucket (move or delete) before you can delete the bucket itself.

Example Request

DELETE / HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20170710T181321Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=b0558a25e794bced1ca9b620b4318bb8eb62ddbd34e2b9c1921034bc5acd597b

Example Response

HTTP/1.1 204 No Content

Date: Mon, 10 Jul 2017 18:13:21 GMT
Connection: close

Get a Bucket’s Location

To retrieve a bucket’s location, send a GET request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?location

The body of the response contains an XML element named LocationConstraint containing the “slug” for the region where the bucket is located.

Name Description
LocationConstraint A “slug” representing the region where the bucket is located (for example, nyc3).

Example Request

    GET /?location HTTP/1.1

    Host: static-images.nyc3.digitaloceanspaces.com
    x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    x-amz-date: 20170710T174432Z
    Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=0d0a16e9c86386305e3e1a809b7d5f0042c5a702d7ff6616013beeb865f9d728

Example Response

    HTTP/1.1 200 OK

    Date: Mon, 10 Jul 2017 17:44:33 GMT
    x-amz-request-id: tx000000000000002764f2e-005963bd01-1268c-nyc3a
    Content-Length: 127
    Connection: close

    <?xml version="1.0" encoding="UTF-8"?>
      <LocationConstraint xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
        nyc3
      </LocationConstraint>

Get a Bucket’s ACLs

To retrieve a bucket’s Access Control List, send a GET request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?acl

The body of the response includes an XML element named AccessControlPolicy containing information about the ACLs applied to the bucket.

Name Description
Owner A container holding elements with information about the bucket’s owner.
ID An element containing the ID of the bucket’s owner as its value.
DisplayName An element containing the DisplayName of the bucket’s owner as its value. Provided for compatibility purposes, has the same value as the ID.
AccessControlList A container holding a list of elements describing one or more access grants.
Grant A container for an individual access grant.
Grantee A container holding information about to whom an access grant is applied. If it applies to an individual account (that is, the bucket’s owner) it will contain ID and Owner elements. If the grant applies to a group (that is, AllUsers) it will contain a URI element.
URI A URI specifying a group of users. At this time, only http://acs.amazonaws.com/groups/global/AllUsers is supported.
Permission The level of access granted. At this time, the only supported values are FULL_CONTROL and READ.

Example Request

    GET /?acl HTTP/1.1

    Host: static-images.nyc3.digitaloceanspaces.com
    x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    x-amz-date: 20170710T174434Z
    Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=71dfa4666fb740d40d05307a29321c65cc620cdb17e8a9cb83d4f0e1b1b9d236

Example Response

    HTTP/1.1 200 OK

    Date: Mon, 10 Jul 2017 17:44:35 GMT
    x-amz-request-id: tx000000000000002764fa6-005963bd03-1268c-nyc3a
    Content-Type: application/xml
    Content-Length: 621
    Connection: close

    <?xml version="1.0" encoding="UTF-8"?>
      <AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
        <Owner>
          <ID>6174283</ID>
          <DisplayName>6174283</DisplayName>
        </Owner>
        <AccessControlList>
          <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
              <URI>http://acs.amazonaws.com/groups/global/AllUsers</URI>
            </Grantee>
            <Permission>READ</Permission>
          </Grant>
          <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
              <ID>6174283</ID>
              <DisplayName>6174283</DisplayName>
            </Grantee>
            <Permission>FULL_CONTROL</Permission>
          </Grant>
        </AccessControlList>
      </AccessControlPolicy>

Set a Bucket’s ACLs

To modify a bucket’s Access Control List, send a PUT request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?acl

The body of the request should include an XML element named AccessControlPolicy containing information about the ACLs to be applied to the bucket.

Name Description
Owner A container holding elements with information about the bucket’s owner.
ID An element containing the ID of the bucket’s owner as its value.
AccessControlList A container holding a list of elements describing one or more access grants.
Grant A container for an individual access grant.
Grantee A container holding information about to whom an access grant is applied. If it applies to an individual account (that is, the bucket’s owner) it will contain ID and Owner elements. If the grant applies to a group (that is, AllUsers) it will contain a URI element.
URI A URI specifying a group of users. At this time, only http://acs.amazonaws.com/groups/global/AllUsers is supported.
Permission The level of access granted. At this time, the only supported values are FULL_CONTROL and READ.

Example Request

    PUT /?acl HTTP/1.1

    content-type:application/xml
    Host: static-images.nyc3.digitaloceanspaces.com
    x-amz-content-sha256: 724483e3830b19d6960345c484fb7904b26e8f2fb34a6c002fa779353b68c8d8
    x-amz-date: 20170710T183709Z
    Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date,Signature=1cf3f7771a4086375e5b6597026db6d55d84fbc86e3c3a86ec420ea9123e3163

    <AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
      <Owner>
        <ID>6174283</ID>
      </Owner>
      <AccessControlList>
        <Grant>
          <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
            <ID>6174283</ID>
          </Grantee>
          <Permission>FULL_CONTROL</Permission>
        </Grant>
        <Grant>
          <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
            <URI>http://acs.amazonaws.com/groups/global/AllUsers</URI>
          </Grantee>
          <Permission>READ</Permission>
        </Grant>
      </AccessControlList>
    </AccessControlPolicy>

Example Response

    HTTP/1.1 200 OK

    Date: Mon, 10 Jul 2017 18:37:10 GMT
    x-amz-request-id: tx00000000000000278ac49-005963c956-1268c-nyc3a
    Content-Type: application/xml
    Content-Length: 0
    Connection: close

Get a Bucket’s CORS

To retrieve a bucket’s Cross-Origin Resource Sharing (CORS) configuration, send a GET request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?cors

The body of the response includes an XML element named CORSConfiguration containing information about how the bucket is configured to handle cross-origin requests.

Name Description
CORSRule A container holding a list of elements describing allowed methods for a specific origin.
AllowedMethod An individual HTTP method (for example, GET) which is allowed from the specified origin.
AllowedOrigin A host from which requests using the specified methods are allowed. It may contain one wildcard (for example, http://*.example.com).
AllowedHeader A header that will be included in the CORS preflight request’s Access-Control-Request-Headers. It may contain one wildcard (for example, x-amz-*).

Example Request

GET /?cors HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20170710T185319Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=f7d7879992a9f3a06ddacd59e53ac318e99b2ed6230692b30099739e34469a91

Example Response

HTTP/1.1 200 OK

Date: Mon, 10 Jul 2017 18:53:20 GMT
x-amz-request-id: tx00000000000000279651f-005963cd20-1268c-nyc3a
Content-Type: application/xml
Content-Length: 390
Connection: close

<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <CORSRule>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>DELETE</AllowedMethod>
    <AllowedMethod>POST</AllowedMethod>
    <AllowedOrigin>http://example.com</AllowedOrigin>
    <AllowedHeader>*</AllowedHeader>
  </CORSRule>
  <CORSRule>
    <AllowedMethod>GET</AllowedMethod>
    <AllowedOrigin>*</AllowedOrigin>
  </CORSRule>
</CORSConfiguration>

Set a Bucket’s CORS

To configure Cross-Origin Resource Sharing (CORS) for a bucket, send a PUT request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?cors

The body of the request should include an XML element named CORSConfiguration containing the desired configuration information for handling cross-origin requests.

Name Description
CORSRule A container holding a list of elements describing allowed methods for a specific origin.
AllowedMethod An individual HTTP method (for example, GET) which is allowed from the specified origin.
AllowedOrigin A host from which requests using the specified methods are allowed. It may contain one wildcard (for example, http://*.example.com).
AllowedHeader A header that will be included in the CORS preflight request’s Access-Control-Request-Headers. It may contain one wildcard (for example,x-amz-*).

Example Request

PUT /?cors HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
Content-Length: 374
Content-Type: application/xml
x-amz-content-sha256: 745320970930725bd18820ec990f7334960f0a47358be189e77504cc094be77e
x-amz-date: 20170710T185043Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=content-md5;content-type;host;x-amz-content-sha256;x-amz-date,Signature=f52b2bfb6ec975c86cadd2e51a6ee9842c6151b737e46ce90a3cb3cc0d0dea97

<CORSConfiguration>
 <CORSRule>
   <AllowedOrigin>http://example.com</AllowedOrigin>

   <AllowedMethod>PUT</AllowedMethod>
   <AllowedMethod>POST</AllowedMethod>
   <AllowedMethod>DELETE</AllowedMethod>

   <AllowedHeader>*</AllowedHeader>
 </CORSRule>
 <CORSRule>
   <AllowedOrigin>*</AllowedOrigin>
   <AllowedMethod>GET</AllowedMethod>
 </CORSRule>
</CORSConfiguration>

Example Response

HTTP/1.1 200 OK

Date: Mon, 10 Jul 2017 18:50:44 GMT
x-amz-request-id: tx0000000000000027946fc-005963cc84-1268c-nyc3a
Content-Type: application/xml
Content-Length: 0
Connection: close

Delete a Bucket’s CORS

To delete a bucket’s Cross-Origin Resource Sharing (CORS) configuration, send a DELETE request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?cors

Success is indicated by receiving 204 (No Content) as the response code.

Example Request

DELETE /static-images?cors HTTP/1.1

Host: nyc3.digitaloceanspaces.com
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20170714T182537Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=content-md5;content-type;host;x-amz-content-sha256;x-amz-date,Signature=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Example Response

HTTP/1.1 204 No Content

Date: Fri, 14 Jul 2017 18:25:38 GMT
x-amz-request-id: tx0000000000000002fae1f-0059690ca2-6441-nyc3a
Connection: close

Get a Bucket’s Lifecycle Rules

To retrieve a information about the lifecycle rules configured for a Space, send a GET request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?lifecycle

The body of the response will include an XML element named LifecycleConfiguration containing a list of Rule objects.

Name Description
Rule A container holding elements with information about a singe lifecycle rule.
ID A unique string identifying the rule. It may contain up to 255 characters including spaces.
Status A string that specifies whether or not the lifecycle rule will be acted upon. The only valid values are Enabled or Disabled.
Prefix A string specifying the objects to which the rule will be applied. When provided, only objects whose keys begin with the prefix will be acted upon. If empty or not present, all object in the Space will be affected.
Expiration When present, matching objects are expired and automatically deleted. This container specifies either a Date or Days element.
Days An integer specifying the number of days after an object’s creation until the rule takes effect.
Date A date in ISO 8601 format specifying the day that the rule takes effect. The action will be run at midnight UTC.
AbortIncompleteMultipartUpload When present, incomplete multipart uploads of matching objects will be removed. This container specifies a DaysAfterInitiation element.
DaysAfterInitiation An integer specifying the number of days after an incomplete multipart upload was initiated until the rule takes effect.

Example Request

GET /?lifecycle HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20180119T001757Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=e92e48fb16dad3d9d332460adde86493b8930262d9385e002b0408e17a2781f4

Example Response

HTTP/1.1 200 OK

Date: Mon, 10 Jul 2017 17:44:35 GMT
x-amz-request-id: tx000000000000000023935-005a613936-fcf92-nyc3a
Content-Type: application/xml
Content-Length: 456
Connection: close

<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Rule>
    <ID>Expire old logs</ID>
    <Prefix>logs/</Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <Days>90</Days>
    </Expiration>
  </Rule>

  <Rule>
    <ID>Remove uncompleted uploads</ID>
    <Status>Enabled</Status>
    <Prefix/>
    <AbortIncompleteMultipartUpload>
      <DaysAfterInitiation>1</DaysAfterInitiation>
    </AbortIncompleteMultipartUpload>
  </Rule>
</LifecycleConfiguration>

Configure a Bucket’s Lifecycle Rules

Lifecycle rules can be used to perform different actions on objects in a Space over the course of their “life.” For example, a Space may be configured so that objects in it expire and are automatically deleted after a certain length of time. Lifecycle rules based on tagging are not supported.

Warning
A lifecycle rule that deletes a large amount of objects can take hours or days to finish running. During this process, you are still billed for any objects that have not been deleted yet. To delete objects faster, use the S3 DeleteObject or DeleteObjects commands.

In order to configure new lifecycle rules, send a PUT request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?lifecycle

The body of the request should include an XML element named LifecycleConfiguration containing a list of Rule objects.

Name Description Required
Rule A container holding elements with information about a singe lifecycle rule. Yes
ID A unique string identifying the rule. It may contain up to 255 characters including spaces. Yes
Status A string that specifies whether or not the lifecycle rule will be acted upon. The only valid values are Enabled or Disabled. Yes
Prefix A string specifying the objects to which the rule will be applied. When provided, only objects whose keys begin with the prefix will be acted upon. If empty or not present, all object in the Space will be affected. No
Expiration When present, matching objects are expired and automatically deleted. This container must specify either a Date or Days element. No
Days An integer specifying the number of days after an object’s creation until the rule takes effect. No
Date A date in ISO 8601 format specifying the day that the rule takes effect. The action will be run at midnight UTC. No
AbortIncompleteMultipartUpload When present, incomplete multipart uploads of matching objects will be removed. This container must specify a DaysAfterInitiation element. No
DaysAfterInitiation An integer specifying the number of days after an incomplete multipart upload was initiated until the rule takes effect. No

Example Request

PUT /?lifecycle HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
Content-Length: 456
Content-Type: application/xml
x-amz-content-sha256: 34850007f92ec3331486b48fd7db15f48315fe73c4a9b135e6d9fd629276c1e7
x-amz-date: 20180119T000345Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=content-md5;content-type;host;x-amz-content-sha256;x-amz-date,Signature=fc07a541c2acdbf7527eba358afa0a6d460c9bfec539dd29dfa6b5b854aae109

<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Rule>
    <ID>Expire old logs</ID>
    <Prefix>logs/</Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <Days>90</Days>
    </Expiration>
  </Rule>

  <Rule>
    <ID>Remove uncompleted uploads</ID>
    <Status>Enabled</Status>
    <Prefix/>
    <AbortIncompleteMultipartUpload>
      <DaysAfterInitiation>1</DaysAfterInitiation>
    </AbortIncompleteMultipartUpload>
  </Rule>
</LifecycleConfiguration>

Example Response

HTTP/1.1 200 OK

Date: Mon, 13 Dec 2017 17:31:43 GMT
x-amz-request-id: tx00000000000000010ad2b-005a6135e2-f647d-nyc3a
Content-Length: 0
Content-Type: application/xml
Connection: close

Delete a Bucket’s Lifecycle Rules

To delete a bucket’s lifecycle configuration, send a DELETE request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?lifecycle

Success is indicated by receiving 204 (No Content) as the response code.

Example Request

DELETE /?lifecycle HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20171213T204101Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20171213/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=376fe41764fe6493a33160b36055d8f617b92f9337bce0cf91bc9c5b1e7482b2

Example Response

HTTP/1.1 204 No Content

Date: Mon, 12 Dec 2017 18:13:21 GMT
Connection: close

Object Operations

Objects consist of data, such as image files or applications, that you can upload to buckets. The following methods allow you to upload, delete, and manage objects across your buckets.

Get an Object

To retrieve an object from a bucket, send a GET request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}

The body of the response contains the object itself.

Example Request

GET /example.txt HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20170710T190539Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=e912de79c88f07832558244bd867c3d834584c7f8b3d8efe4d0f0ba60b7a1dcb

Example Response

HTTP/1.1 200 OK

Date: Mon, 10 Jul 2017 19:05:39 GMT
x-amz-request-id: tx00000000000000279f46e-005963d003-1268c-nyc3a
Content-Type: text/plain
Content-Length: 14
Accept-Ranges: bytes
Last-Modified: Mon, 10 Jul 2017 19:05:09 GMT
Etag: "b3a92f49e7ae64acbf6b3e76f2040f5e"
Connection: close

Example text.

Get Information About an Object

To retrieve information about a specific object, send a HEAD request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}

The response will include headers with information about the object (for example, Content-Type, Content-Length, Last-Modified, Etag) but not the object itself. (See Common Headers for more information about the included information.)

Example Request

HEAD /example.txt HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20170714T185156Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Example Response

HTTP/1.1 200 OK

Date: Fri, 14 Jul 2017 18:51:58 GMT
x-amz-request-id: tx0000000000000002ff1c9-00596912ce-6441-nyc3a
Content-Type: text/plain
Content-Length: 14
Accept-Ranges: bytes
Last-Modified: Thu, 13 Jul 2017 18:40:46 GMT
Etag: "b3a92f49e7ae64acbf6b3e76f2040f5e"
Connection: close

Upload an Object (PUT)

To upload an object to a bucket, send a PUT request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}

The body of the request should contain the object itself. In addition to the common headers used in requests, a number of additional headers are supported:

Name Description Required
Content-Length The length in bytes of the request body. Yes
Cache-Control Directives used for specifying caching behavior (for example, max-age). No
Content-Encoding Specifies how and if an object has been compressed for transit (for example, gzip), and thus how the client should decode it in order to obtain the media-type referenced by the Content-Type. No
Content-Disposition Specifies how the object is expected to be displayed (for example, inline or attachment). No
x-amz-acl A canned ACL specifying access rules for the object (for example, private or public-read). If not set, defaults to private. No
x-amz-storage-class Allowed for compatibility purposes. Spaces only accepts the default value, STANDARD, and will reject other, unsupported storage class values. No
x-amz-meta-* Prefix used to supply arbitrary user defined metadata (for example, x-amz-meta-file-attrs: uid:1000/gname:username/uname:username/gid:1000/mode:33204). The value may not be larger than 2 KB in size. No

Example Request

PUT /example.txt HTTP/1.1

Content-Length: 14
Content-Type: text/plain
Host: static-images.nyc3.digitaloceanspaces.com
x-amz-content-sha256: 003f0e5fe338b17be8be93fec537764ce199ac50f4e50f2685a753c4cc781747
x-amz-date: 20170710T194605Z
x-amz-meta-s3cmd-attrs:uid:1000/gname:asb/uname:asb/gid:1000/mode:33204/mtime:1499727909/atime:1499727909/md5:fb08934ef619f205f272b0adfd6c018c/ctime:1499713540
x-amz-storage-class: STANDARD
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=content-length;content-type;host;x-amz-content-sha256;x-amz-date;x-amz-meta-s3cmd-attrs;x-amz-storage-class,Signature=a9a9e16da23e0b37ae8362824de77d66bba2edd702ee5f291f6ecbb9ebac6013

Example text.

Example Response

HTTP/1.1 200 OK

Date: Mon, 10 Jul 2017 19:46:06 GMT
x-amz-request-id: tx0000000000000027bd57c-005963d97e-1268c-nyc3a
Content-Length: 0
Accept-Ranges: bytes
Last-Modified: Mon, 10 Jul 2017 19:05:09 GMT
Etag: "fb08934ef619f205f272b0adfd6c018c"
Connection: close

Copy an Object

Note

Spaces does not support some object copying use cases:

  • Cross region copying is not supported
  • For regions with multiple clusters, cross-cluster copying is not supported

To copy an object from one bucket to another, send a PUT request to ${DESTINATION_BUCKET}.${REGION}.digitaloceanspaces.com/${DESTINATION_OBJECT_KEY}

In addition to the common headers used in requests, a number of additional headers are required:

Name Description Required
x-amz-copy-source Specifies the original object to be copied (for example, /${ORIGIN_BUCKET}/{$ORIGIN_OBJECT_KEY}). Yes
x-amz-metadata-directive Indicates whether to copy the object’s metadata or to replace it with values specified in the request. The only valid values are COPY or REPLACE.
    Note: An object can not be copied to itself unless `REPLACE` is specified.|Yes|

|x-amz-acl|A “canned” ACL specifying access rules for the object (for example, private or public-read). If not set, defaults to private.|No|

The body of the response includes an XML element named CopyObjectResult containing:

Name Description
LastModified The date and time that the object was last modified in the format: %Y-%m-%dT%H:%M:%S.%3NZ (for example, 2017-06-23T18:37:48.157Z)
ETag The entity tag containing an MD5 hash of the object.

Example Request

PUT /copied-example.txt HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-copy-source: /static-images/example.txt
x-amz-date: 20170710T202253Z
x-amz-metadata-directive: COPY
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-copy-source;x-amz-date;x-amz-metadata-directive;x-amz-storage-class,Signature=0cb03470dd80bdd41a4b8fb06c1800b27a5059b61b0303fe589578835531c877

Example Response

HTTP/1.1 200 OK


Date: Mon, 10 Jul 2017 20:22:54 GMT
x-amz-request-id: tx0000000000000027d8430-005963e21d-1268c-nyc3a
Content-Length: 183
Connection: close

<CopyObjectResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <LastModified>2017-07-10T20:22:54.167Z</LastModified>
  <ETag>7967bfe102f83fb5fc7e5a02bf05e8fc</ETag>
</CopyObjectResult>

Get an Object’s ACLs

To retrieve a object’s Access Control List, send a GET request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?acl

The body of the response includes an XML element named AccessControlPolicy containing information about the ACLs applied to the object.

Name Description
Owner A container holding elements with information about the object’s owner.
ID An element containing the ID of the object’s owner as its value.
DisplayName An element containing the DisplayName of the object’s owner as its value. Provided for compatibility purposes, has the same value as the ID.
AccessControlList A container holding a list of elements describing one or more access grants.
Grant A container for an individual access grant.
Grantee A container holding information about to whom an access grant is applied. If it applies to an individual account (that is, the object’s owner) it will contain ID and Owner elements. If the grant applies to a group (that is, AllUsers) it will contain a URI element.
URI A URI specifying a group of users. At this time, only http://acs.amazonaws.com/groups/global/AllUsers is supported.
Permission The level of access granted. At this time, the only supported values are FULL_CONTROL and READ.

Example Request

    GET /sammy.png?acl HTTP/1.1

    Host: static-images.nyc3.digitaloceanspaces.com
    x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    x-amz-date: 20170710T191224Z
    Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=950e133849cd19d626291fd2937d927957cf3e97a36707d30d51a9b61ac08a8e

Example Response

    HTTP/1.1 200 OK

    Date: Mon, 10 Jul 2017 19:12:24 GMT
    x-amz-request-id: tx0000000000000027a42dc-005963d198-1268c-nyc3a
    Content-Type: application/xml
    Content-Length: 621
    Connection: close

    <?xml version="1.0" encoding="UTF-8"?>
      <AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
        <Owner>
          <ID>6174283</ID>
          <DisplayName>6174283</DisplayName>
        </Owner>
        <AccessControlList>
          <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
              <URI>http://acs.amazonaws.com/groups/global/AllUsers</URI>
            </Grantee>
            <Permission>READ</Permission>
          </Grant>
          <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
              <ID>6174283</ID>
              <DisplayName>6174283</DisplayName>
            </Grantee>
            <Permission>FULL_CONTROL</Permission>
          </Grant>
        </AccessControlList>
      </AccessControlPolicy>

Set an Object’s ACLs

To modify an object’s Access Control List, send a PUT request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?acl

The body of the request should include an XML element named AccessControlPolicy containing information about the ACLs to be applied to the object.

Name Description
Owner A container holding elements with information about the object’s owner.
ID An element containing the ID of the object’s owner as its value.
AccessControlList A container holding a list of elements describing one or more access grants.
Grant A container for an individual access grant.
Grantee A container holding information about to whom an access grant is applied. If it applies to an individual account (that is, the object’s owner) it will contain ID and Owner elements. If the grant applies to a group (that is, AllUsers) it will contain a URI element.
URI A URI specifying a group of users. At this time, only http://acs.amazonaws.com/groups/global/AllUsers is supported.
Permission The level of access granted. At this time, the only supported values are FULL_CONTROL and READ.

Example Request

    PUT /sammy.png?acl HTTP/1.1

    content-type:application/xml
    Host: static-images.nyc3.digitaloceanspaces.com
    x-amz-content-sha256:c0bd9ba784be78d4f38bbc1e3b0da2de2e7a8f4ee259b3b840369cf00a78dad2
    x-amz-date:20170710T192142Z
    Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date,Signature=dfeeb2386f76b29097adadb35ac15f7d5f244f18cc95f082b0ac6d14ced48b10

    <AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
      <Owner>
        <ID>6174283</ID>
      </Owner>
      <AccessControlList>
        <Grant>
          <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
            <ID>6174283</ID>
          </Grantee>
          <Permission>FULL_CONTROL</Permission>
        </Grant>
      </AccessControlList>
    </AccessControlPolicy>

Example Response

    HTTP/1.1 200 OK

    Date: Mon, 10 Jul 2017 19:21:42 GMT
    x-amz-request-id: tx0000000000000027aafc9-005963d3c6-1268c-nyc3a
    Content-Type: application/xml
    Content-Length: 0
    Connection: close

Delete an Object

To delete an object, send a DELETE request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}

Success is indicated by receiving 204 (No Content) as the response code.

Example Request

    DELETE /sammy.png HTTP/1.1

    Host: static-images.nyc3.digitaloceanspaces.com
    x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    x-amz-date: 20170710T194408Z
    Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170710/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=c2a46b21e2e8589dfbfa54382030bbef8108b2504a9f1d8aaba70fb0e1c46522

Example Response

    HTTP/1.1 204 No Content

    Date: Mon, 10 Jul 2017 19:44:09 GMT
    x-amz-request-id: tx0000000000000027bbc48-005963d908-1268c-nyc3a
    Connection: close

Begin a Multi-part Upload

To initiate a multi-part upload session, send a POST request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?uploads

In addition to the common headers used in requests, a number of additional headers are supported:

Name Description Required
Cache-Control Directives used for specifying caching behavior (for example, max-age). No
Content-Encoding Specifies how and if an object has been compressed for transit (for example, gzip), and thus how the client should decode it in order to obtain the media-type referenced by the Content-Type. No
Content-Disposition Specifies how the object is expected to be displayed (for example, inline or attachment). No
x-amz-acl A “canned” ACL specifying access rules for the object (for example, private or public-read). If not set, defaults to private. No
x-amz-meta-* Prefix used to supply arbitrary user defined metadata (for example, x-amz-meta-file-attrs: uid:1000/gname:username/uname:username/gid:1000/mode:33204). The value may not be larger than 2 KB in size. No

The body of the response will include an XML element named InitiateMultipartUploadResult containing the UploadId used to identify the multi-part upload session in any following requests.

Name Description
Bucket The name of the bucket.
Key The object’s key.
UploadId The unique identifier for the multi-part upload session.

Example Request

    POST /multipart-file.tar.gz?uploads HTTP/1.1

    Host: static-images.nyc3.digitaloceanspaces.com
    x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    x-amz-date:20170814T174652Z
    Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170814/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=e356966fff5a3d49d19c0e44e0fdba294964384a58061d3e60dfd1a4a5b605ad

Example Response

    HTTP/1.1 200 OK

    Content-Length: 258
    Content-Type: application/xml
    Date: Mon, 14 Aug 2017 17:46:53 GMT
    x-amz-request-id: tx00000000000000ab66a13-005991e20d-66a8-nyc3a
    Connection: close

    <?xml version="1.0" encoding="UTF-8"?>
      <InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
        <Bucket>static-images</Bucket>
        <Key>multipart-file.tar.gz</Key>
        <UploadId>2~iCw_lDY8VoBhoRrIJbPMrUqnE3Z-3Qh</UploadId>
      </InitiateMultipartUploadResult>

List Multipart Uploads

To retrieve a list of in-progress multipart uploads, send a GET request to ${BUCKET}.${REGION}.digitaloceanspaces.com?uploads&max-uploads=${MAX_UPLOADS} where ${MAX_UPLOADS} is the maximum number of in-progress uploads to return.

Name Description Required
Bucket The name of the bucket. Yes
delimiter A single character used to group keys. When specified, the response will only contain keys up to its first occurrence. (for example, using a slash as the delimiter can allow you to list keys as if they were folders, especially in combination with a prefix.) No
encoding-type Encodes the object keys in the response and specifies the encoding method to use. Valid Values: url No
key-marker Used with the upload-id marker, you can specify where in the list of current uploads to begin returning results. You can page through the results by updating this parameter in subsequent requests. No
max-uploads The maximum number of multipart uploads to return in the response. Valid values are integer of 1 to 1000. Yes
prefix A string used to group keys. No
upload-id-marker Used with the key-marker, you can specify after which upload the return list should begin. If you don’t specify a key-marker the the upload-id-marker parameter is ignored. No

The body of the response includes an XML element named ListMultipartUploadsResult containing the UploadId used to identify the multi-part upload session in any following requests. In-progress uploads are sorted by object key and in ascending order within each key.

Name Description
ListMultipartUploadsResult Root level tag for the ListMultipartUploadsResult parameters.
Bucket Name of the bucket being uploaded to.
CommonPrefixes An array of key prefixes containing the delimiter specified in the request.
Delimiter The delimiter specified in the requests.
EncodingType If you specify encoding-type, the API returns encoded key name values in the following response elements: Delimiter, KeyMarker, Prefix, NextKeyMarker, Key.
IsTruncated Indicates if the returned list of multipart uploads has been truncated.
KeyMarker The key at or after which the listing began.
MaxUploads The maximum number of upload that could have been returned in a response. This can be changed with the request by changing the values of the max-uploads parameter.
NextKeyMarker When a list is truncated, you can page through the results by the applying the value of NextKeyMarker to the key-marker request parameter in a subsequent request.
NextUploadIdMarker When a list is truncated, you can page through the results by the applying the value of NextUploadIdMarker to the upload-id-marker request parameter in a subsequent request.
Prefix The optional prefix value specified in the request.
Upload An array of the properties about the upload.
Upload Marker The upload ID after which listing began.

Example Request

GET /?uploads&max-uploads=3 HTTP/1.1
Host: static-images.nyc3.digitaloceanspaces.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

Example Response

HTTP/1.1 200 OK

Date: Mon, 10 Jul 2017 19:12:24 GMT
x-amz-request-id: tx0000000000000027a42dc-005963d198-1268c-nyc3a
Content-Type: application/xml
Content-Length: 2035
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Bucket>bucket</Bucket>
  <KeyMarker></KeyMarker>
  <UploadIdMarker></UploadIdMarker>
  <NextKeyMarker>my-movie.m2ts</NextKeyMarker>
  <NextUploadIdMarker>YW55IGlkZWEgd2h5IGVsdmluZydzIHVwbG9hZCBmYWlsZWQ</NextUploadIdMarker>
  <MaxUploads>3</MaxUploads>
  <IsTruncated>true</IsTruncated>
  <Upload>
    <Key>my-divisor</Key>
    <UploadId>XMgbGlrZSBlbHZpbmcncyBub3QgaGF2aW5nIG11Y2ggbHVjaw</UploadId>
    <Initiator>
      <ID>arn:aws:iam::111122223333:user/user1-11111a31-17b5-4fb7-9df5-b111111f13de</ID>
      <DisplayName>user1-11111a31-17b5-4fb7-9df5-b111111f13de</DisplayName>
    </Initiator>
    <Owner>
      <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
      <DisplayName>OwnerDisplayName</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
    <Initiated>2010-11-10T20:48:33.000Z</Initiated>  
  </Upload>
  <Upload>
    <Key>my-movie.m2ts</Key>
    <UploadId>VXBsb2FkIElEIGZvciBlbHZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZA</UploadId>
    <Initiator>
      <ID>b1d16700c70b0b05597d7acd6a3f92be</ID>
      <DisplayName>InitiatorDisplayName</DisplayName>
    </Initiator>
    <Owner>
      <ID>b1d16700c70b0b05597d7acd6a3f92be</ID>
      <DisplayName>OwnerDisplayName</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
    <Initiated>2010-11-10T20:48:33.000Z</Initiated>
  </Upload>
  <Upload>
    <Key>my-movie.m2ts</Key>
    <UploadId>YW55IGlkZWEgd2h5IGVsdmluZydzIHVwbG9hZCBmYWlsZWQ</UploadId>
    <Initiator>
      <ID>arn:aws:iam::444455556666:user/user1-22222a31-17b5-4fb7-9df5-b222222f13de</ID>
      <DisplayName>user1-22222a31-17b5-4fb7-9df5-b222222f13de</DisplayName>
    </Initiator>
    <Owner>
      <ID>b1d16700c70b0b05597d7acd6a3f92be</ID>
      <DisplayName>OwnerDisplayName</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
    <Initiated>2010-11-10T20:49:33.000Z</Initiated>
  </Upload>
</ListMultipartUploadsResult>

Upload a Part

To upload part of an object in a multi-part upload session, send a PUT request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?partNumber=${PART_NUMBER}&uploadId=${UPLOAD_ID}.

The ${PART_NUMBER} specifies which piece of the object is included in the upload. The ${UPLOAD_ID} is the unique identifier returned when the multi-part upload session was initiated. The body of the request should contain the piece of the object.

Example Request

PUT /multipart-file.tar.gz?partNumber=1&uploadId=2~iCw_lDY8VoBhoRrIJbPMrUqnE3Z-3Qh HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
Content-Length: 5242880
x-amz-content-sha256: 6ab0931e613fd0cd39af0fa4733edb6ad942df0ad33e057713d44df7195b6ecf
x-amz-date: 20170814T184459Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170814/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=2e4adca0a3164af8717f340ca874b4f3036dd0294b590a70f2147427221ca1e8

Example Response

HTTP/1.1 200 OK

Content-Length: 0
Content-Type: application/xml
Date: Mon, 14 Aug 2017 18:45:01 GMT
Etag: "d8d3ed3a4de016917a814a2cf5acad3c"
x-amz-request-id: tx00000000000000ab85dab-005991efac-66a8-nyc3a
Connection: close

List Parts

To list the parts of a multi-part upload session, send a GET request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?uploadId=${UPLOAD_ID} where ${UPLOAD_ID} is the unique identifier returned when the multi-part upload session was initiated.

The body of the response contains an XML element named ListPartsResult containing information about the multi-part upload session and a list of XML objects representing each part of the upload:

Name Description
Bucket The name of the bucket.
Key The object’s key.
UploadId The unique identifier returned when the multi-part upload session was initiated.
StorageClass Provided for compatibility purposes. The value is always STANDARD.
PartNumberMarker The part number where the list begins.
NextPartNumberMarker When the list is truncated, specifies the part number indicating where the next response begins.
MaxParts The maximum number of parts to return. Defaults to 1,000.
IsTruncated A boolean indicating whether all parts are included in the response.
Part A container holding elements with information about the parts of the multi-part upload.
PartNumber A sequential identifier specifying the part of the object.
LastModified The date and time that the part of the object was last modified in the format: %Y-%m-%dT%H:%M:%S.%3NZ (for example, 2017-06-23T18:37:48.157Z)
ETag The entity tag containing an MD5 hash of the part of the object.
Size The size of the part of the object in bytes.
Owner A container holding elements with information about the bucket’s owner.
ID An element containing the ID of the bucket’s owner as its value.
DisplayName An element containing the DisplayName of the bucket’s owner as its value. Provided for compatibility purposes, has the same value as the ID.

Example Request

GET /multipart-file.tar.gz?partNumber=1&uploadId=2~iCw_lDY8VoBhoRrIJbPMrUqnE3Z-3Qh HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
Content-Length: 5242880
x-amz-content-sha256: 6ab0931e613fd0cd39af0fa4733edb6ad942df0ad33e057713d44df7195b6ecf
x-amz-date: 20170814T184459Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170814/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=2e4adca0a3164af8717f340ca874b4f3036dd0294b590a70f2147427221ca1e8

Example Response

HTTP/1.1 200 OK

Content-Length: 0
Content-Type: application/xml
Date: Mon, 14 Aug 2017 18:45:01 GMT
Etag: "d8d3ed3a4de016917a814a2cf5acad3c"
x-amz-request-id: tx00000000000000ab85dab-005991efac-66a8-nyc3a
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
  <ListPartsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Bucket>my-new-bucket</Bucket>
    <Key>multipart-file.tar.gz</Key>
    <UploadId>2~iCw_lDY8VoBhoRrIJbPMrUqnE3Z-3Qh</UploadId>
    <StorageClass>STANDARD</StorageClass>
    <PartNumberMarker>0</PartNumberMarker>
    <NextPartNumberMarker>1</NextPartNumberMarker>
    <MaxParts>1000</MaxParts>
    <IsTruncated>false</IsTruncated>
    <Owner>
      <ID>612423</ID>
      <DisplayName>612423</DisplayName>
    </Owner>
    <Part>
      <LastModified>2017-08-14T18:45:01.601Z</LastModified>
      <PartNumber>1</PartNumber>
      <ETag>"d8d3ed3a4de016917a814a2cf5acad3c"</ETag>
      <Size>5242880</Size>
    </Part>
    <Part>
      <LastModified>2017-08-14T18:45:01.601Z</LastModified>
      <PartNumber>2</PartNumber>
      <ETag>"adf5feafc0fe4632008d5cb30beb1c49"</ETag>
      <Size>5242880</Size>
    </Part>
  </ListPartsResult>

Complete a Multi-part Upload

To complete a multi-part upload session, send a POST request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?uploadId=${UPLOAD_ID} where ${UPLOAD_ID} is the unique identifier returned when the multi-part upload session was initiated.

The body of the request should include an XML element named CompleteMultipartUpload containing information about each of the parts of the upload:

Name Description Required
Part A container holding elements with information about an individual part of a multi-part upload. Yes
PartNumber A sequential identifier specifying the part of the object. Yes
ETag The entity tag containing an MD5 hash of the part of the object. Yes

The body of the response includes an XML element named CompleteMultipartUploadResult containing information about the completed upload:

Name Description
Location The location of the bucket.
Bucket The name of the bucket.
Key The object’s key.
ETag The entity tag containing an MD5 hash of the final object.

Example Request

POST /multipart-file.tar.gz?uploadId=2~iCw_lDY8VoBhoRrIJbPMrUqnE3Z-3Qh HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
Content-Length: 5242880
x-amz-content-sha256: 6ab0931e613fd0cd39af0fa4733edb6ad942df0ad33e057713d44df7195b6ecf
x-amz-date: 20170814T184459Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170814/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=2e4adca0a3164af8717f340ca874b4f3036dd0294b590a70f2147427221ca1e8

<CompleteMultipartUpload>
  <Part>
    <PartNumber>1</PartNumber>
    <ETag>"d8d3ed3a4de016917a814a2cf5acad3c"</ETag>
  </Part>
  <Part>
    <PartNumber>2</PartNumber>
    <ETag>"adf5feafc0fe4632008d5cb30beb1c49"</ETag>
  </Part>
  <Part>
    <PartNumber>3</PartNumber>
    <ETag>"363f6bb50866541d78e5f6f626592263"</ETag>
  </Part>
</CompleteMultipartUpload>

Example Response

HTTP/1.1 200 OK

Content-Length: 311
Content-Type: application/xml
Date: Mon, 14 Aug 2017 18:45:01 GMT
x-amz-request-id: tx00000000000000ab962c8-005991f6fe-66a8-nyc3a
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
  <CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Location>static-images.nyc3.digitaloceanspaces.com</Location>
    <Bucket>static-images</Bucket>
    <Key>multipart-file.tar.gz</Key>
    <ETag>f935869350d7cbfcdd219df3f377531b-3</ETag>
  </CompleteMultipartUploadResult>

Cancel a Multi-part Upload

To cancel an active multi-part upload session, send a DELETE request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?uploadId=${UPLOAD_ID} where ${UPLOAD_ID} is the unique identifier returned when the multi-part upload session was initiated.

Success is indicated by receiving 204 (No Content) as the response code.

Example Request

DELETE /multipart-file.tar.gz?uploadId=2~iCw_lDY8VoBhoRrIJbPMrUqnE3Z-3Qh HTTP/1.1

Host: static-images.nyc3.digitaloceanspaces.com
Content-Length: 5242880
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20170814T202611Z
Authorization: AWS4-HMAC-SHA256 Credential=II5JDQBAN3JYM4DNEB6C/20170814/nyc3/s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date,Signature=9e13d3f9e71ca5fb034fe66e92c60e30b3az3e177573702dd11d2b541358bf92

Example Response

HTTP/1.1 200 OK

Date: Mon, 14 Aug 2017 18:45:01 GMT
x-amz-request-id: tx00000000000000abbaefe-0059920764-66a8-nyc3a
Connection: close