0% found this document useful (0 votes)

343 views

s3 Api PDF

Uploaded by

shreyas

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

343 views

s3 Api PDF

Uploaded by

shreyas

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 1541

Amazon Simple Storage Service

API Reference
API Version 2006-03-01
Amazon Simple Storage Service API Reference

Amazon Simple Storage Service: API Reference

Amazon S3 supports the REST API.

Note
Support for SOAP over HTTP is deprecated, but it is still available over HTTPS. However, new
Amazon S3 features will not be supported for SOAP. We recommend that you use either the
REST API or the AWS SDKs.

Read the following about authentication and access control before going to speciﬁc API topics.

Requests to Amazon S3 can be authenticated or anonymous. Authenticated access requires credentials

that AWS can use to authenticate your requests. When making REST API calls directly from your code,
you create a signature using valid credentials and include the signature in your request. For information
about various authentication methods and signature calculations, see Authenticating Requests (AWS
Signature Version 4) (p. 603).

Making REST API calls directly from your code can be cumbersome. It requires you to write the necessary
code to calculate a valid signature to authenticate your requests. We recommend the following
alternatives instead:

• Use the AWS SDKs to send your requests (see Sample Code and Libraries). With this option, you
don't need to write code to calculate a signature for request authentication because the SDK clients
authenticate your requests by using access keys that you provide. Unless you have a good reason not
to, you should always use the AWS SDKs.
• Use the AWS CLI to make Amazon S3 API calls. For information about setting up the AWS CLI and
example Amazon S3 commands see the following topics:

• CreateAccessPoint (p. 372)

• CreateJob (p. 374)
• DeleteAccessPoint (p. 379)
• DeleteAccessPointPolicy (p. 380)
• DeletePublicAccessBlock (p. 381)
• DescribeJob (p. 382)
• GetAccessPoint (p. 386)
• GetAccessPointPolicy (p. 389)
• GetAccessPointPolicyStatus (p. 391)
• GetPublicAccessBlock (p. 393)
• ListAccessPoints (p. 395)
• ListJobs (p. 397)
• PutAccessPointPolicy (p. 399)
• PutPublicAccessBlock (p. 401)
• UpdateJobPriority (p. 403)
• UpdateJobStatus (p. 405)

Amazon Simple Storage Service

The following actions are supported by Amazon Simple Storage Service:

API Version 2006-03-01

4
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• DeleteBucketPolicy (p. 55)

• DeleteBucketReplication (p. 57)
• DeleteBucketTagging (p. 59)
• DeleteBucketWebsite (p. 61)
• DeleteObject (p. 63)
• DeleteObjects (p. 67)
• DeleteObjectTagging (p. 75)
• DeletePublicAccessBlock (p. 77)
• GetBucketAccelerateConfiguration (p. 79)
• GetBucketAcl (p. 82)
• GetBucketAnalyticsConfiguration (p. 85)
• GetBucketCors (p. 89)
• GetBucketEncryption (p. 92)
• GetBucketInventoryConfiguration (p. 95)
• GetBucketLifecycle (p. 99)
• GetBucketLifecycleConfiguration (p. 102)
• GetBucketLocation (p. 105)
• GetBucketLogging (p. 107)
• GetBucketMetricsConfiguration (p. 110)
• GetBucketNotification (p. 114)
• GetBucketNotificationConfiguration (p. 116)
• GetBucketPolicy (p. 119)
• GetBucketPolicyStatus (p. 121)
• GetBucketReplication (p. 123)
• GetBucketRequestPayment (p. 127)
• GetBucketTagging (p. 129)
• GetBucketVersioning (p. 132)
• GetBucketWebsite (p. 135)
• GetObject (p. 138)
• GetObjectAcl (p. 150)
• GetObjectLegalHold (p. 154)
• GetObjectLockConfiguration (p. 156)
• GetObjectRetention (p. 158)
• GetObjectTagging (p. 160)
• GetObjectTorrent (p. 163)
• GetPublicAccessBlock (p. 165)
• HeadBucket (p. 168)
• HeadObject (p. 170)
• ListBucketAnalyticsConfigurations (p. 179)
• ListBucketInventoryConfigurations (p. 183)
• ListBucketMetricsConfigurations (p. 188)
• ListBuckets (p. 192)
• ListMultipartUploads (p. 194)
• ListObjects (p. 202)
• ListObjectsV2 (p. 209)
• ListObjectVersions (p. 218)

API Version 2006-03-01

5
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• ListParts (p. 229)

• PutBucketAccelerateConfiguration (p. 234)
• PutBucketAcl (p. 237)
• PutBucketAnalyticsConfiguration (p. 243)
• PutBucketCors (p. 247)
• PutBucketEncryption (p. 250)
• PutBucketInventoryConfiguration (p. 253)
• PutBucketLifecycle (p. 258)
• PutBucketLifecycleConfiguration (p. 264)
• PutBucketLogging (p. 270)
• PutBucketMetricsConfiguration (p. 274)
• PutBucketNotification (p. 278)
• PutBucketNotificationConfiguration (p. 280)
• PutBucketPolicy (p. 286)
• PutBucketReplication (p. 289)
• PutBucketRequestPayment (p. 294)
• PutBucketTagging (p. 297)
• PutBucketVersioning (p. 300)
• PutBucketWebsite (p. 304)
• PutObject (p. 310)
• PutObjectAcl (p. 323)
• PutObjectLegalHold (p. 329)
• PutObjectLockConfiguration (p. 331)
• PutObjectRetention (p. 333)
• PutObjectTagging (p. 336)
• PutPublicAccessBlock (p. 339)
• RestoreObject (p. 343)
• SelectObjectContent (p. 352)
• UploadPart (p. 360)
• UploadPartCopy (p. 365)

API Version 2006-03-01

6
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

AbortMultipartUpload
Service: Amazon Simple Storage Service

This operation aborts a multipart upload. After a multipart upload is aborted, no additional parts can be
uploaded using that upload ID. The storage consumed by any previously uploaded parts will be freed.
However, if any part uploads are currently in progress, those part uploads might or might not succeed.
As a result, it might be necessary to abort a given multipart upload multiple times in order to completely
free all storage consumed by all parts.

To verify that all parts have been removed, so you don't get charged for the part storage, you should call
the ListParts (p. 229) operation and ensure that the parts list is empty.

For information about permissions required to use the multipart upload API, see Multipart Upload API
and Permissions.

The following operations are related to AbortMultipartUpload:

• CreateMultipartUpload (p. 32)

• UploadPart (p. 360)
• CompleteMultipartUpload (p. 10)
• ListParts (p. 229)
• ListMultipartUploads (p. 194)

Request Syntax

DELETE /Key+?UploadId=UploadId HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-request-payer: RequestPayer

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 7)

The bucket name to which the upload was taking place.

When using this API with an access point, you must direct requests to the access point
hostname. The access point hostname takes the form AccessPointName-AccountId.s3-
accesspoint.Region.amazonaws.com. When using this operation using an access point through the
AWS SDKs, you provide the access point ARN in place of the bucket name. For more information
about access point ARNs, see Using Access Points in the Amazon Simple Storage Service Developer
Guide.
Key (p. 7)

Key of the object for which the multipart upload was initiated.

Length Constraints: Minimum length of 1.

uploadId (p. 7)

Upload ID that identiﬁes the multipart upload.

x-amz-request-payer (p. 7)

Conﬁrms that the requester knows that they will be charged for the request. Bucket owners need
not specify this parameter in their requests. For information about downloading objects from

API Version 2006-03-01

7
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

requester pays buckets, see Downloading Objects in Requestor Pays Buckets in the Amazon S3
Developer Guide.

Valid Values: requester

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204
x-amz-request-charged: RequestCharged

Response Elements
If the action is successful, the service sends back an HTTP 204 response.

The response returns the following HTTP headers.

x-amz-request-charged (p. 8)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

The speciﬁed multipart upload does not exist.

Examples
Sample Request

The following request aborts a multipart upload identiﬁed by its upload ID.

DELETE /example-object?
uploadId=VXBsb2FkIElEIGZvciBlbHZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZ HTTP/1.1
Host: example-bucket.s3.<Region>.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 204 OK
x-amz-id-2: Weag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 996c76696e6727732072657175657374
Date: Mon, 1 Nov 2010 20:34:56 GMT
Content-Length: 0
Connection: keep-alive
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

API Version 2006-03-01

8
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

9
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CompleteMultipartUpload
Service: Amazon Simple Storage Service

Completes a multipart upload by assembling previously uploaded parts.

You ﬁrst initiate the multipart upload and then upload all parts using the UploadPart (p. 360)
operation. After successfully uploading all relevant parts of an upload, you call this operation to
complete the upload. Upon receiving this request, Amazon S3 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.

Processing of a Complete Multipart Upload request could take several minutes to complete. After
Amazon S3 begins processing the request, it sends an HTTP response header that speciﬁes a 200 OK
response. While processing is in progress, Amazon S3 periodically sends white space characters to keep
the connection from timing out. Because a request could fail after the initial 200 OK response has been
sent, it is important that you check the response body to determine whether the request succeeded.

Note that if CompleteMultipartUpload fails, applications should be prepared to retry the failed
requests. For more information, see Amazon S3 Error Best Practices.

For more information about multipart uploads, see Uploading Objects Using Multipart Upload.

For information about permissions required to use the multipart upload API, see Multipart Upload API
and Permissions.

GetBucketLifecycle has the following special errors:

• Error code: EntityTooSmall

• Description: Your proposed upload is smaller than the minimum allowed object size. Each part must
be at least 5 MB in size, except the last part.
• 400 Bad Request
• Error code: InvalidPart
• Description: One or more of the specified parts could not be found. The part might not have been
uploaded, or the specified entity tag might not have matched the part's entity tag.
• 400 Bad Request
• Error code: InvalidPartOrder
• Description: The list of parts was not in ascending order. The parts list must be specified in order by
part number.
• 400 Bad Request
• Error code: NoSuchUpload
• Description: The specified multipart upload does not exist. The upload ID might be invalid, or the
multipart upload might have been aborted or completed.
• 404 Not Found

The following operations are related to DeleteBucketMetricsConfiguration:

• CreateMultipartUpload (p. 32)

• UploadPart (p. 360)
• AbortMultipartUpload (p. 7)
• ListParts (p. 229)
• ListMultipartUploads (p. 194)

API Version 2006-03-01

10
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Request Syntax

POST /Key+?UploadId=UploadId HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-request-payer: RequestPayer
<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUpload xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Part>
<ETag>string</ETag>
<PartNumber>integer</PartNumber>
</Part>
...
</CompleteMultipartUpload>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 11)

Name of the bucket to which the multipart upload was initiated.

Key (p. 11)

Object key for which the multipart upload was initiated.

Length Constraints: Minimum length of 1.

uploadId (p. 11)

ID for the initiated multipart upload.

x-amz-request-payer (p. 11)

Conﬁrms that the requester knows that they will be charged for the request. Bucket owners need
not specify this parameter in their requests. For information about downloading objects from
requester pays buckets, see Downloading Objects in Requestor Pays Buckets in the Amazon S3
Developer Guide.

Valid Values: requester

Request Body
The request accepts the following data in XML format.

CompleteMultipartUpload (p. 11)

Root level tag for the CompleteMultipartUpload parameters.

Required: Yes
Part (p. 11)

Array of CompletedPart data types.

Type: Array of CompletedPart (p. 430) data types

Required: No

Response Syntax

HTTP/1.1 200

API Version 2006-03-01

11
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-expiration: Expiration
x-amz-server-side-encryption: ServerSideEncryption
x-amz-version-id: VersionId
x-amz-server-side-encryption-aws-kms-key-id: SSEKMSKeyId
x-amz-request-charged: RequestCharged
<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadOutput>
<Location>string</Location>
<Bucket>string</Bucket>
<Key>string</Key>
<ETag>string</ETag>
</CompleteMultipartUploadOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

x-amz-expiration (p. 11)

If the object expiration is conﬁgured, this will contain the expiration date (expiry-date) and rule ID
(rule-id). The value of rule-id is URL encoded.
x-amz-request-charged (p. 11)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

x-amz-server-side-encryption (p. 11)

If you speciﬁed server-side encryption either with an Amazon S3-managed encryption key or
an AWS KMS customer master key (CMK) in your initiate multipart upload request, the response
includes this header. It conﬁrms the encryption algorithm that Amazon S3 used to encrypt the
object.

Valid Values: AES256 | aws:kms

x-amz-server-side-encryption-aws-kms-key-id (p. 11)

If present, speciﬁes the ID of the AWS Key Management Service (AWS KMS) symmetric customer
managed customer master key (CMK) that was used for the object.
x-amz-version-id (p. 11)

Version ID of the newly created object, in case the bucket has versioning turned on.

The following data is returned in XML format by the service.

CompleteMultipartUploadOutput (p. 11)

Root level tag for the CompleteMultipartUploadOutput parameters.

Required: Yes
Bucket (p. 11)

The name of the bucket that contains the newly created object.

Type: String
ETag (p. 11)

Entity tag that identifies the newly created object's data. Objects with different object data will have
different entity tags. The entity tag is an opaque string. The entity tag may or may not be an MD5

API Version 2006-03-01

12
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

digest of the object data. If the entity tag is not an MD5 digest of the object data, it will contain one
or more nonhexadecimal characters and/or will consist of less than 32 or more than 32 hexadecimal
digits.

Type: String
Key (p. 11)

The object key of the newly created object.

Type: String

Length Constraints: Minimum length of 1.

Location (p. 11)

The URI that identiﬁes the newly created object.

Type: String

Examples
Sample Request
The following Complete Multipart Upload request speciﬁes three parts in the
CompleteMultipartUpload element.

POST /example-object?
uploadId=AAAsb2FkIElEIGZvciBlbHZpbmcncyWeeS1tb3ZpZS5tMnRzIRRwbG9hZA HTTP/1.1
Host: example-bucket.s3.<Region>.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Content-Length: 391
Authorization: authorization string

15
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CopyObject
Service: Amazon Simple Storage Service

Creates a copy of an object that is already stored in Amazon S3.

Note
You can store individual objects of up to 5 TB in Amazon S3. You create a copy of your object
up to 5 GB in size in a single atomic operation using this API. However, for copying an object
greater than 5 GB, you must use the multipart upload Upload Part - Copy API. For more
information, see Copy Object Using the REST Multipart Upload API.

When copying an object, you can preserve all metadata (default) or specify new metadata. However, the
ACL is not preserved and is set to private for the user making the request. To override the default ACL
setting, specify a new ACL when generating a copy request. For more information, see Using ACLs.
Important
Amazon S3 transfer acceleration does not support cross-region copies. If you request a cross-
region copy using a transfer acceleration endpoint, you get a 400 Bad Request error. For more
information about transfer acceleration, see Transfer Acceleration.

All copy requests must be authenticated. Additionally, you must have read access to the source object
and write access to the destination bucket. For more information, see REST Authentication. Both the
Region that you want to copy the object from and the Region that you want to copy the object to must
be enabled for your account.

To only copy an object under certain conditions, such as whether the Etag matches or whether the
object was modified before or after a specified date, use the request parameters x-amz-copy-source-
if-match, x-amz-copy-source-if-none-match, x-amz-copy-source-if-unmodified-since,
or x-amz-copy-source-if-modified-since.
Note
All headers with the x-amz- prefix, including x-amz-copy-source, must be signed.

You can use this operation to change the storage class of an object that is already stored in Amazon S3
using the StorageClass parameter. For more information, see Storage Classes.

The source object that you are copying can be encrypted or unencrypted. If the source object is
encrypted, it can be encrypted by server-side encryption using AWS managed encryption keys or by
using a customer-provided encryption key. When copying an object, you can request that Amazon
S3 encrypt the target object by using either the AWS managed encryption keys or by using your own
encryption key. You can do this regardless of the form of server-side encryption that was used to encrypt
the source, or even if the source object was not encrypted. For more information about server-side
encryption, see Using Server-Side Encryption.

A copy request might return an error when Amazon S3 receives the copy request or while Amazon S3
is copying the ﬁles. If the error occurs before the copy operation starts, you receive a standard Amazon
S3 error. If the error occurs during the copy operation, the error response is embedded in the 200 OK
response. This means that a 200 OK response can contain either a success or an error. Design your
application to parse the contents of the response and handle it appropriately.

If the copy is successful, you receive a response with information about the copied object.
Note
If the request is an HTTP 1.1 request, the response is chunk encoded. If it were not, it would not
contain the content-length, and you would need to read the entire body.

Consider the following when using request headers:

• Consideration 1 – If both the x-amz-copy-source-if-match and x-amz-copy-source-if-

unmodified-since headers are present in the request and evaluate as follows, Amazon S3 returns
200 OK and copies the data:

API Version 2006-03-01

16
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• x-amz-copy-source-if-match condition evaluates to true

• x-amz-copy-source-if-unmodified-since condition evaluates to false
• Consideration 2 – 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 and evaluate as follows, Amazon S3 returns
the 412 Precondition Failed response code:
• x-amz-copy-source-if-none-match condition evaluates to false
• x-amz-copy-source-if-modified-since condition evaluates to true

The copy request charge is based on the storage class and Region you specify for the destination object.
For pricing information, see Amazon S3 Pricing.

Following are other considerations when using CopyObject:

Versioning

By default, x-amz-copy-source identiﬁes the current version of an object to copy. (If the current
version is a delete marker, Amazon S3 behaves as if the object was deleted.) To copy a diﬀerent
version, use the versionId subresource.

If you enable versioning on the target bucket, Amazon S3 generates a unique version ID for the
object being copied. This version ID is diﬀerent from the version ID of the source object. Amazon
S3 returns the version ID of the copied object in the x-amz-version-id response header in the
response.

If you do not enable versioning or suspend it on the target bucket, the version ID that Amazon S3
generates is always null.

If the source object's storage class is GLACIER, you must restore a copy of this object before you can
use it as a source object for the copy operation. For more information, see RestoreObject (p. 343).
Access Permissions

When copying an object, you can optionally specify the accounts or groups that should be granted
speciﬁc permissions on the new object. There are two ways to grant the permissions using the
request headers:
• Specify a canned ACL with the x-amz-acl request header. For more information, see Canned ACL.
• Specify access permissions explicitly with the x-amz-grant-read, x-amz-grant-read-acp, x-
amz-grant-write-acp, and x-amz-grant-full-control headers. These parameters map
to the set of permissions that Amazon S3 supports in an ACL. For more information, see Access
Control List (ACL) Overview.

You can use either a canned ACL or specify access permissions explicitly. You cannot do both.
Server-Side- Encryption-Speciﬁc Request Headers

To encrypt the target object, you must provide the appropriate encryption-related request headers.
The one you use depends on whether you want to use AWS managed encryption keys or provide
your own encryption key.
• To encrypt the target object using server-side encryption with an AWS managed encryption key,
provide the following request headers, as appropriate.
• x-amz-server-side-encryption
• x-amz-server-side-encryption-aws-kms-key-id
• x-amz-server-side-encryption-context
Note
If you specify x-amz-server-side-encryption:aws:kms, but don't provide x-amz-
server-side-encryption-aws-kms-key-id, Amazon S3 uses the AWS managed

API Version 2006-03-01

17
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CMK in AWS KMS to protect the data. If you want to use a customer managed AWS KMS
CMK, you must provide the x-amz-server-side-encryption-aws-kms-key-id of
the symmetric customer managed CMK. Amazon S3 only supports symmetric CMKs and
not asymmetric CMKs. For more information, see Using Symmetric and Asymmetric Keys
in the AWS Key Management Service Developer Guide.
Important
All GET and PUT requests for an object protected by AWS KMS fail if you don't make them
with SSL or by using SigV4.

For more information about server-side encryption with CMKs stored in AWS KMS (SSE-KMS), see
Protecting Data Using Server-Side Encryption with CMKs stored in KMS.
• To encrypt the target object using server-side encryption with an encryption key that you provide,
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
• If the source object is encrypted using server-side encryption with customer-provided encryption
keys, you must use the following headers.
• x-amz-copy-source-server-side-encryption-customer-algorithm
• x-amz-copy-source-server-side-encryption-customer-key
• x-amz-copy-source-server-side-encryption-customer-key-MD5

For more information about server-side encryption with CMKs stored in AWS KMS (SSE-KMS), see
Protecting Data Using Server-Side Encryption with CMKs stored in Amazon KMS.
Access-Control-List (ACL)-Speciﬁc Request Headers

You also can use the following access control–related headers with this operation. By default, all
objects are private. Only the owner has full access control. When adding a new object, you can
grant permissions to individual AWS accounts or to predefined groups defined by Amazon S3. These
permissions are then added to the access control list (ACL) on the object. For more information, see
Using ACLs. With this operation, you can grant access permissions using one of the following two
methods:
• Specify a canned ACL (x-amz-acl) — Amazon S3 supports a set of predefined ACLs, known
as canned ACLs. Each canned ACL has a predefined set of grantees and permissions. For more
information, see Canned ACL.
• Specify access permissions explicitly — To explicitly grant access permissions to specific AWS
accounts or groups, use the following headers. Each header maps to specific permissions that
Amazon S3 supports in an ACL. For more information, see Access Control List (ACL) Overview. In
the header, you specify a list of grantees who get the specific permission. To grant permissions
explicitly, use:
• x-amz-grant-read
• x-amz-grant-write
• x-amz-grant-read-acp
• x-amz-grant-write-acp
• x-amz-grant-full-control

You specify each grantee as a type=value pair, where the type is one of the following:
• emailAddress – if the value specified is the email address of an AWS account
• id – if the value specified is the canonical user ID of an AWS account
• uri – if you are granting permissions to a predefined group

For example, the following x-amz-grant-read header grants the AWS accounts identiﬁed by
email addresses permissions to read object data and its metadata:

API Version 2006-03-01

18
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-grant-read: emailAddress="[email protected]",
emailAddress="[email protected]"

The following operations are related to CopyObject:

• PutObject (p. 310)

• GetObject (p. 138)

For more information, see Copying Objects.

Request Syntax

PUT /Key+ HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-acl: ACL
Cache-Control: CacheControl
Content-Disposition: ContentDisposition
Content-Encoding: ContentEncoding
Content-Language: ContentLanguage
Content-Type: ContentType
x-amz-copy-source: CopySource
x-amz-copy-source-if-match: CopySourceIfMatch
x-amz-copy-source-if-modified-since: CopySourceIfModifiedSince
x-amz-copy-source-if-none-match: CopySourceIfNoneMatch
x-amz-copy-source-if-unmodified-since: CopySourceIfUnmodifiedSince
Expires: Expires
x-amz-grant-full-control: GrantFullControl
x-amz-grant-read: GrantRead
x-amz-grant-read-acp: GrantReadACP
x-amz-grant-write-acp: GrantWriteACP
x-amz-metadata-directive: MetadataDirective
x-amz-tagging-directive: TaggingDirective
x-amz-server-side-encryption: ServerSideEncryption
x-amz-storage-class: StorageClass
x-amz-website-redirect-location: WebsiteRedirectLocation
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key: SSECustomerKey
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
x-amz-server-side-encryption-aws-kms-key-id: SSEKMSKeyId
x-amz-server-side-encryption-context: SSEKMSEncryptionContext
x-amz-copy-source-server-side-encryption-customer-algorithm: CopySourceSSECustomerAlgorithm
x-amz-copy-source-server-side-encryption-customer-key: CopySourceSSECustomerKey
x-amz-copy-source-server-side-encryption-customer-key-MD5: CopySourceSSECustomerKeyMD5
x-amz-request-payer: RequestPayer
x-amz-tagging: Tagging
x-amz-object-lock-mode: ObjectLockMode
x-amz-object-lock-retain-until-date: ObjectLockRetainUntilDate
x-amz-object-lock-legal-hold: ObjectLockLegalHoldStatus

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 19)

The name of the destination bucket.

Cache-Control (p. 19)

Speciﬁes caching behavior along the request/reply chain.

API Version 2006-03-01

19
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Content-Disposition (p. 19)

Speciﬁes presentational information for the object.

Content-Encoding (p. 19)

The language the content is in.

Content-Type (p. 19)

A standard MIME type describing the format of the object data.

Expires (p. 19)

The date and time at which the object is no longer cacheable.

Key (p. 19)

The key of the destination object.

Length Constraints: Minimum length of 1.

x-amz-acl (p. 19)

The canned ACL to apply to the object.

Valid Values: private | public-read | public-read-write | authenticated-read |

aws-exec-read | bucket-owner-read | bucket-owner-full-control
x-amz-copy-source (p. 19)

The name of the source bucket and key name of the source object, separated by a slash (/). Must be
URL-encoded.

Pattern: \/.+\/.+
x-amz-copy-source-if-match (p. 19)

Copies the object if its entity tag (ETag) matches the speciﬁed tag.
x-amz-copy-source-if-modiﬁed-since (p. 19)

Copies the object if it has been modiﬁed since the speciﬁed time.
x-amz-copy-source-if-none-match (p. 19)

Copies the object if its entity tag (ETag) is different than the specified ETag.
x-amz-copy-source-if-unmodified-since (p. 19)

Copies the object if it hasn't been modiﬁed since the speciﬁed time.
x-amz-copy-source-server-side-encryption-customer-algorithm (p. 19)

Speciﬁes the algorithm to use when decrypting the source object (for example, AES256).
x-amz-copy-source-server-side-encryption-customer-key (p. 19)

Speciﬁes the customer-provided encryption key for Amazon S3 to use to decrypt the source object.
The encryption key provided in this header must be one that was used when the source object was
created.
x-amz-copy-source-server-side-encryption-customer-key-MD5 (p. 19)

Speciﬁes the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this
header for a message integrity check to ensure that the encryption key was transmitted without
error.

API Version 2006-03-01

20
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-grant-full-control (p. 19)

Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
x-amz-grant-read (p. 19)

Allows grantee to read the object data and its metadata.

x-amz-grant-read-acp (p. 19)

Allows grantee to read the object ACL.

x-amz-grant-write-acp (p. 19)

Allows grantee to write the ACL for the applicable object.

x-amz-metadata-directive (p. 19)

Speciﬁes whether the metadata is copied from the source object or replaced with metadata provided
in the request.

Valid Values: COPY | REPLACE

x-amz-object-lock-legal-hold (p. 19)

Speciﬁes whether you want to apply a Legal Hold to the copied object.

Valid Values: ON | OFF

x-amz-object-lock-mode (p. 19)

The Object Lock mode that you want to apply to the copied object.

Valid Values: GOVERNANCE | COMPLIANCE

x-amz-object-lock-retain-until-date (p. 19)

The date and time when you want the copied object's Object Lock to expire.
x-amz-request-payer (p. 19)

Valid Values: requester

x-amz-server-side-encryption (p. 19)

The server-side encryption algorithm used when storing this object in Amazon S3 (for example,
AES256, aws:kms).

Valid Values: AES256 | aws:kms

x-amz-server-side-encryption-aws-kms-key-id (p. 19)

Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an
object protected by AWS KMS will fail if not made via SSL or using SigV4. For information about
configuring using any of the officially supported AWS SDKs and AWS CLI, see Specifying the
Signature Version in Request Authentication in the Amazon S3 Developer Guide.
x-amz-server-side-encryption-context (p. 19)

Speciﬁes the AWS KMS Encryption Context to use for object encryption. The value of this header is a
base64-encoded UTF-8 string holding JSON with the encryption context key-value pairs.
x-amz-server-side-encryption-customer-algorithm (p. 19)

Speciﬁes the algorithm to use to when encrypting the object (for example, AES256).

API Version 2006-03-01

21
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-server-side-encryption-customer-key (p. 19)

Speciﬁes the customer-provided encryption key for Amazon S3 to use in encrypting data. This value
is used to store the object and then it is discarded; Amazon S3 does not store the encryption key.
The key must be appropriate for use with the algorithm speciﬁed in the x-amz-server-side-
encryption-customer-algorithm header.
x-amz-server-side-encryption-customer-key-MD5 (p. 19)

The type of storage to use for the object. Defaults to 'STANDARD'.

Valid Values: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA |

INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE
x-amz-tagging (p. 19)

The tag-set for the object destination object this value must be used in conjunction with the
TaggingDirective. The tag-set must be encoded as URL Query parameters.
x-amz-tagging-directive (p. 19)

Speciﬁes whether the object tag-set are copied from the source object or replaced with tag-set
provided in the request.

Valid Values: COPY | REPLACE

x-amz-website-redirect-location (p. 19)

If the bucket is conﬁgured as a website, redirects requests for this object to another object in
the same bucket or to an external URL. Amazon S3 stores the value of this header in the object
metadata.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
x-amz-expiration: Expiration
x-amz-copy-source-version-id: CopySourceVersionId
x-amz-version-id: VersionId
x-amz-server-side-encryption: ServerSideEncryption
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
x-amz-server-side-encryption-aws-kms-key-id: SSEKMSKeyId
x-amz-server-side-encryption-context: SSEKMSEncryptionContext
x-amz-request-charged: RequestCharged
<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
<ETag>string</ETag>
<LastModified>timestamp</LastModified>
</CopyObjectResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

API Version 2006-03-01

22
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

The response returns the following HTTP headers.

x-amz-copy-source-version-id (p. 22)

Version of the copied object in the destination bucket.

x-amz-expiration (p. 22)

If the object expiration is conﬁgured, the response includes this header.

x-amz-request-charged (p. 22)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

x-amz-server-side-encryption (p. 22)

The server-side encryption algorithm used when storing this object in Amazon S3 (for example,
AES256, aws:kms).

Valid Values: AES256 | aws:kms

x-amz-server-side-encryption-aws-kms-key-id (p. 22)

If present, speciﬁes the ID of the AWS Key Management Service (AWS KMS) symmetric customer
managed customer master key (CMK) that was used for the object.
x-amz-server-side-encryption-context (p. 22)

If present, speciﬁes the AWS KMS Encryption Context to use for object encryption. The value of this
header is a base64-encoded UTF-8 string holding JSON with the encryption context key-value pairs.
x-amz-server-side-encryption-customer-algorithm (p. 22)

If server-side encryption with a customer-provided encryption key was requested, the response will
include this header conﬁrming the encryption algorithm used.
x-amz-server-side-encryption-customer-key-MD5 (p. 22)

If server-side encryption with a customer-provided encryption key was requested, the response will
include this header to provide round-trip message integrity veriﬁcation of the customer-provided
encryption key.
x-amz-version-id (p. 22)

Version ID of the newly created copy.

The following data is returned in XML format by the service.

CopyObjectResult (p. 22)

Root level tag for the CopyObjectResult parameters.

Required: Yes
ETag (p. 22)

Returns the ETag of the new object. The ETag reﬂects only changes to the contents of an object, not
its metadata. The source and destination ETag is identical for a successfully copied object.

Type: String
LastModiﬁed (p. 22)

Returns the date that the object was last modiﬁed.

API Version 2006-03-01

23
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Type: Timestamp

The source object of the COPY operation is not in the active tier and is only stored in Amazon S3 Glacier.

Examples
Sample Request

This example copies my-image.jpg into the bucket bucket, with the key name my-second-
image.jpg.

PUT /my-second-image.jpg HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-amz-copy-source: /bucket/my-image.jpg
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
x-amz-copy-source-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
x-amz-version-id: QUpfdndhfd8438MNFDN93jdnJFkdmqnh893
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: AmazonS3

Sample Request: Copying a speciﬁed version of an object

The following request copies the my-image.jpg key with the speciﬁed version ID, copies it into the
bucket bucket, and gives it the my-second-image.jpg key.

PUT /my-second-image.jpg HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-amz-copy-source: /bucket/my-image.jpg?versionId=3/L4kqtJlcpXroDTDmJ
+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
Authorization: authorization string

Success Response: Copying a versioned object into a version-enabled bucket

The following response shows that an object was copied into a target bucket where versioning is
enabled.

HTTP/1.1 200 OK

API Version 2006-03-01

24
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-id-2:
eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
x-amz-version-id: QUpfdndhfd8438MNFDN93jdnJFkdmqnh893
x-amz-copy-source-version-id: 09df8234529fjs0dfi0w52935029wefdj
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

Success Response: Copying a versioned object into a version-suspended bucket

The following response shows that an object was copied into a target bucket where versioning is
suspended. The parameter VersionId does not appear.

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
x-amz-copy-source-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

Example: Copy from unencrypted object to an object encrypted with server-side encryption with
customer-provided encryption keys

The following example speciﬁes the HTTP PUT header to copy an unencrypted object to an object
encrypted with server-side encryption with customer-provided encryption keys (SSE-C).

PUT /exampleDestinationObject HTTP/1.1

Host: example-destination-bucket.s3.<Region>.amazonaws.com
x-amz-server-side-encryption-customer-algorithm: AES256
x-amz-server-side-encryption-customer-key: Base64(YourKey)
x-amz-server-side-encryption-customer-key-MD5 : Base64(MD5(YourKey))
x-amz-metadata-directive: metadata_directive
x-amz-copy-source: /example_source_bucket/exampleSourceObject
x-amz-copy-source-if-match: etag
x-amz-copy-source-if-none-match: etag
x-amz-copy-source-if-unmodified-since: time_stamp
x-amz-copy-source-if-modified-since: time_stamp

<request metadata>
Authorization: authorization string (see Authenticating Requests (AWS
Signature Version 4))
Date: date

API Version 2006-03-01

25
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Example: Copy from an object encrypted with SSE-C to an object encrypted with SSE-C

The following example speciﬁes the HTTP PUT header to copy an object encrypted with server-side
encryption with customer-provided encryption keys to an object encrypted with server-side encryption
with customer-provided encryption keys for key rotation.

PUT /exampleDestinationObject HTTP/1.1

Host: example-destination-bucket.s3.<Region>.amazonaws.com
x-amz-server-side-encryption-customer-algorithm: AES256
x-amz-server-side-encryption-customer-key: Base64(NewKey)
x-amz-server-side-encryption-customer-key-MD5: Base64(MD5(NewKey))
x-amz-metadata-directive: metadata_directive
x-amz-copy-source: /source_bucket/sourceObject
x-amz-copy-source-if-match: etag
x-amz-copy-source-if-none-match: etag
x-amz-copy-source-if-unmodified-since: time_stamp
x-amz-copy-source-if-modified-since: time_stamp
x-amz-copy-source-server-side-encryption-customer-algorithm: AES256
x-amz-copy-source-server-side-encryption-customer-key: Base64(OldKey)
x-amz-copy-source-server-side-encryption-customer-key-MD5:
Base64(MD5(OldKey))

<request metadata>
Authorization: authorization string (see Authenticating Requests (AWS
Signature Version 4))
Date: date

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

26
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CreateBucket
Service: Amazon Simple Storage Service

Creates a new bucket. To create a bucket, you must register with Amazon S3 and have a valid AWS Access
Key ID to authenticate requests. Anonymous requests are never allowed to create buckets. By creating
the bucket, you become the bucket owner.

Not every string is an acceptable bucket name. For information on bucket naming restrictions, see
Working with Amazon S3 Buckets.

By default, the bucket is created in the US East (N. Virginia) Region. You can optionally specify a
Region in the request body. You might choose a Region to optimize latency, minimize costs, or address
regulatory requirements. For example, if you reside in Europe, you will probably ﬁnd it advantageous
to create buckets in the EU (Ireland) Region. For more information, see How to Select a Region for Your
Buckets.
Note
If you send your create bucket request to the s3.amazonaws.com endpoint, the request goes
to the us-east-1 Region. Accordingly, the signature calculations in Signature Version 4 must use
us-east-1 as the Region, even if the location constraint in the request speciﬁes another Region
where the bucket is to be created. If you create a bucket in a Region other than US East (N.
Virginia), your application must be able to handle 307 redirect. For more information, see Virtual
Hosting of Buckets.

When creating a bucket using this operation, you can optionally specify the accounts or groups that
should be granted speciﬁc permissions on the bucket. There are two ways to grant the appropriate
permissions using the request headers.

• Specify a canned ACL using the x-amz-acl request header. Amazon S3 supports a set of predeﬁned
ACLs, known as canned ACLs. Each canned ACL has a predeﬁned set of grantees and permissions. For
more information, see Canned ACL.
• Specify access permissions explicitly using the x-amz-grant-read, x-amz-grant-write, x-amz-
grant-read-acp, x-amz-grant-write-acp, and x-amz-grant-full-control headers. These
headers map to the set of permissions Amazon S3 supports in an ACL. For more information, see
Access Control List (ACL) Overview.

For example, the following x-amz-grant-read header grants the AWS accounts identiﬁed by email
addresses permissions to read object data and its metadata:

x-amz-grant-read: emailAddress="[email protected]",
emailAddress="[email protected]"

Note
You can use either a canned ACL or specify access permissions explicitly. You cannot do both.

The following operations are related to CreateBucket:

• PutObject (p. 310)

• DeleteBucket (p. 41)

API Version 2006-03-01

27
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Request Syntax

PUT / HTTP/1.1
Host: Bucket.s3.amazonaws.com
x-amz-acl: ACL
x-amz-grant-full-control: GrantFullControl
x-amz-grant-read: GrantRead
x-amz-grant-read-acp: GrantReadACP
x-amz-grant-write: GrantWrite
x-amz-grant-write-acp: GrantWriteACP
x-amz-bucket-object-lock-enabled: ObjectLockEnabledForBucket
<?xml version="1.0" encoding="UTF-8"?>
<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<LocationConstraint>string</LocationConstraint>
</CreateBucketConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 28)

The name of the bucket to create.

x-amz-acl (p. 28)

The canned ACL to apply to the bucket.

Valid Values: private | public-read | public-read-write | authenticated-read

x-amz-bucket-object-lock-enabled (p. 28)

Speciﬁes whether you want S3 Object Lock to be enabled for the new bucket.
x-amz-grant-full-control (p. 28)

Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
x-amz-grant-read (p. 28)

Allows grantee to list the objects in the bucket.

x-amz-grant-read-acp (p. 28)

Allows grantee to read the bucket ACL.

x-amz-grant-write (p. 28)

Allows grantee to create, overwrite, and delete any object in the bucket.
x-amz-grant-write-acp (p. 28)

Allows grantee to write the ACL for the applicable bucket.

Request Body
The request accepts the following data in XML format.

CreateBucketConﬁguration (p. 28)

Root level tag for the CreateBucketConﬁguration parameters.

Required: Yes

API Version 2006-03-01

28
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

LocationConstraint (p. 28)

Speciﬁes the Region where the bucket will be created. If you don't specify a Region, the bucket is
created in the US East (N. Virginia) Region (us-east-1).

Type: String

Valid Values: EU | eu-west-1 | us-west-1 | us-west-2 | ap-south-1 | ap-

Required: No

Response Syntax

HTTP/1.1 200
Location: Location

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

Location (p. 29)

Speciﬁes the Region where the bucket will be created. If you are creating a bucket on the US East (N.
Virginia) Region (us-east-1), you do not need to specify the location.

The requested bucket name is not available. The bucket namespace is shared by all users of the system.
Please select a diﬀerent name and try again. The bucket you tried to create already exists, and you
own it. Amazon S3 returns this error in all AWS Regions except in the North Virginia Region. For legacy
compatibility, if you re-create an existing bucket that you already own in the North Virginia Region,
Amazon S3 returns 200 OK and resets the bucket access control lists (ACLs).

Examples
Sample Request

This request creates a bucket named colorpictures.

PUT / HTTP/1.1
Host: colorpictures.s3.<Region>.amazonaws.com
Content-Length: 0
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT

API Version 2006-03-01

29
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Location: /colorpictures
Content-Length: 0
Connection: close
Server: AmazonS3

Sample Request: Setting the Region of a bucket

The following request sets the Region for the bucket to EU.

PUT / HTTP/1.1
Host: bucketName.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 124

Sample Request: Creating a bucket and conﬁguring access permission using a canned ACL

This request creates a bucket named colorpictures and sets the ACL to private.

PUT / HTTP/1.1
Host: colorpictures.s3.<Region>.amazonaws.com
Content-Length: 0
x-amz-acl: private
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT

Location: /colorpictures
Content-Length: 0
Connection: close
Server: AmazonS3

Sample Request: Creating a bucket and conﬁguring access permissions explicitly

This request creates a bucket named colorpictures and grants WRITE permission to the AWS account
identiﬁed by an email address.

PUT HTTP/1.1
Host: colorpictures.s3.<Region>.amazonaws.com
x-amz-date: Sat, 07 Apr 2012 00:54:40 GMT
Authorization: authorization string

API Version 2006-03-01

30
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-grant-write: emailAddress="[email protected]", emailAddress="[email protected]"

Sample Response

HTTP/1.1 200 OK

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

31
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CreateMultipartUpload
Service: Amazon Simple Storage Service

This operation initiates a multipart upload and returns an upload ID. This upload ID is used to associate
all of the parts in the speciﬁc multipart upload. You specify this upload ID in each of your subsequent
upload part requests (see UploadPart (p. 360)). You also include this upload ID in the ﬁnal request to
either complete or abort the multipart upload request.

For more information about multipart uploads, see Multipart Upload Overview.

If you have configured a lifecycle rule to abort incomplete multipart uploads, the upload must complete
within the number of days specified in the bucket lifecycle configuration. Otherwise, the incomplete
multipart upload becomes eligible for an abort operation and Amazon S3 aborts the multipart upload.
For more information, see Aborting Incomplete Multipart Uploads Using a Bucket Lifecycle Policy.

For information about the permissions required to use the multipart upload API, see Multipart Upload
API and Permissions.

For request signing, multipart upload is just a series of regular requests. You initiate a multipart upload,
send one or more requests to upload parts, and then complete the multipart upload process. You sign
each request individually. There is nothing special about signing multipart upload requests. For more
information about signing, see Authenticating Requests (AWS Signature Version 4).
Note
After you initiate a multipart upload and upload one or more parts, to stop being charged for
storing the uploaded parts, you must either complete or abort the multipart upload. Amazon S3
frees up the space used to store the parts and stop charging you for storing them only after you
either complete or abort a multipart upload.

You can optionally request server-side encryption. For server-side encryption, Amazon S3 encrypts your
data as it writes it to disks in its data centers and decrypts it when you access it. You can provide your
own encryption key, or use AWS Key Management Service (AWS KMS) customer master keys (CMKs) or
Amazon S3-managed encryption keys. If you choose to provide your own encryption key, the request
headers you provide in UploadPart (p. 360)) and UploadPartCopy (p. 365)) requests must match the
headers you used in the request to initiate the upload by using CreateMultipartUpload.

To perform a multipart upload with encryption using an AWS KMS CMK, the requester must have
permission to the kms:Encrypt, kms:Decrypt, kms:ReEncrypt*, kms:GenerateDataKey*, and
kms:DescribeKey actions on the key. These permissions are required because Amazon S3 must decrypt
and read data from the encrypted ﬁle parts before it completes the multipart upload.

If your AWS Identity and Access Management (IAM) user or role is in the same AWS account as the AWS
KMS CMK, then you must have these permissions on the key policy. If your IAM user or role belongs to a
diﬀerent account than the key, then you must have the permissions on both the key policy and your IAM
user or role.

For more information, see Protecting Data Using Server-Side Encryption.

Access Permissions

You can use either a canned ACL or specify access permissions explicitly. You cannot do both.

API Version 2006-03-01

32
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Server-Side- Encryption-Speciﬁc Request Headers

You can optionally tell Amazon S3 to encrypt data at rest using server-side encryption. Server-side
encryption is for data encryption at rest. Amazon S3 encrypts your data as it writes it to disks in its
data centers and decrypts it when you access it. The option you use depends on whether you want to
use AWS managed encryption keys or provide your own encryption key.
• Use encryption keys managed by Amazon S3 or customer master keys (CMKs) stored in AWS Key
Management Service (AWS KMS) – If you want AWS to manage the keys used to encrypt data,
specify the following headers in the request.
• x-amz-server-side-encryption
• x-amz-server-side-encryption-aws-kms-key-id
• x-amz-server-side-encryption-context
Note
If you specify x-amz-server-side-encryption:aws:kms, but don't provide x-amz-
server-side-encryption-aws-kms-key-id, Amazon S3 uses the AWS managed
CMK in AWS KMS to protect the data.
Important
All GET and PUT requests for an object protected by AWS KMS fail if you don't make them
with SSL or by using SigV4.

For more information about server-side encryption with CMKs stored in AWS KMS (SSE-KMS), see
Protecting Data Using Server-Side Encryption with CMKs stored in AWS KMS.
• Use customer-provided encryption keys – If you want to manage your own encryption keys,
provide all the following headers in the request.
• x-amz-server-side-encryption-customer-algorithm
• x-amz-server-side-encryption-customer-key
• x-amz-server-side-encryption-customer-key-MD5

For more information about server-side encryption with CMKs stored in AWS KMS (SSE-KMS), see
Protecting Data Using Server-Side Encryption with CMKs stored in AWS KMS.
Access-Control-List (ACL)-Speciﬁc Request Headers

You specify each grantee as a type=value pair, where the type is one of the following:

API Version 2006-03-01

33
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• emailAddress – if the value speciﬁed is the email address of an AWS account

• id – if the value speciﬁed is the canonical user ID of an AWS account
• uri – if you are granting permissions to a predeﬁned group

For example, the following x-amz-grant-read header grants the AWS accounts identiﬁed by
email addresses permissions to read object data and its metadata:

x-amz-grant-read: emailAddress="[email protected]",
emailAddress="[email protected]"

The following operations are related to CreateMultipartUpload:

• UploadPart (p. 360)

• CompleteMultipartUpload (p. 10)
• AbortMultipartUpload (p. 7)
• ListParts (p. 229)
• ListMultipartUploads (p. 194)

Request Syntax

POST /{Key+}?uploads HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-acl: ACL
Cache-Control: CacheControl
Content-Disposition: ContentDisposition
Content-Encoding: ContentEncoding
Content-Language: ContentLanguage
Content-Type: ContentType
Expires: Expires
x-amz-grant-full-control: GrantFullControl
x-amz-grant-read: GrantRead
x-amz-grant-read-acp: GrantReadACP
x-amz-grant-write-acp: GrantWriteACP
x-amz-server-side-encryption: ServerSideEncryption
x-amz-storage-class: StorageClass
x-amz-website-redirect-location: WebsiteRedirectLocation
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key: SSECustomerKey
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
x-amz-server-side-encryption-aws-kms-key-id: SSEKMSKeyId
x-amz-server-side-encryption-context: SSEKMSEncryptionContext
x-amz-request-payer: RequestPayer
x-amz-tagging: Tagging
x-amz-object-lock-mode: ObjectLockMode
x-amz-object-lock-retain-until-date: ObjectLockRetainUntilDate
x-amz-object-lock-legal-hold: ObjectLockLegalHoldStatus

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 34)

The name of the bucket to which to initiate the upload

Cache-Control (p. 34)

Speciﬁes caching behavior along the request/reply chain.

API Version 2006-03-01

34
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Content-Disposition (p. 34)

Speciﬁes presentational information for the object.

Content-Encoding (p. 34)

The language the content is in.

Content-Type (p. 34)

A standard MIME type describing the format of the object data.

Expires (p. 34)

The date and time at which the object is no longer cacheable.

Key (p. 34)

Object key for which the multipart upload is to be initiated.

Length Constraints: Minimum length of 1.

x-amz-acl (p. 34)

The canned ACL to apply to the object.

Valid Values: private | public-read | public-read-write | authenticated-read |

aws-exec-read | bucket-owner-read | bucket-owner-full-control
x-amz-grant-full-control (p. 34)

Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
x-amz-grant-read (p. 34)

Allows grantee to read the object data and its metadata.

x-amz-grant-read-acp (p. 34)

Allows grantee to read the object ACL.

x-amz-grant-write-acp (p. 34)

Allows grantee to write the ACL for the applicable object.

x-amz-object-lock-legal-hold (p. 34)

Speciﬁes whether you want to apply a Legal Hold to the uploaded object.

Valid Values: ON | OFF

x-amz-object-lock-mode (p. 34)

Speciﬁes the Object Lock mode that you want to apply to the uploaded object.

Valid Values: GOVERNANCE | COMPLIANCE

x-amz-object-lock-retain-until-date (p. 34)

Speciﬁes the date and time when you want the Object Lock to expire.
x-amz-request-payer (p. 34)

Conﬁrms that the requester knows that they will be charged for the request. Bucket owners need
not specify this parameter in their requests. For information about downloading objects from

API Version 2006-03-01

35
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

requester pays buckets, see Downloading Objects in Requestor Pays Buckets in the Amazon S3
Developer Guide.

Valid Values: requester

x-amz-server-side-encryption (p. 34)

The server-side encryption algorithm used when storing this object in Amazon S3 (for example,
AES256, aws:kms).

Valid Values: AES256 | aws:kms

x-amz-server-side-encryption-aws-kms-key-id (p. 34)

Specifies the ID of the symmetric customer managed AWS KMS CMK to use for object encryption.
All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using
SigV4. For information about configuring using any of the officially supported AWS SDKs and AWS
CLI, see Specifying the Signature Version in Request Authentication in the Amazon S3 Developer
Guide.
x-amz-server-side-encryption-context (p. 34)

Speciﬁes the algorithm to use to when encrypting the object (for example, AES256).
x-amz-server-side-encryption-customer-key (p. 34)

The type of storage to use for the object. Defaults to 'STANDARD'.

Valid Values: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA |

INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE
x-amz-tagging (p. 34)

The tag-set for the object. The tag-set must be encoded as URL Query parameters.
x-amz-website-redirect-location (p. 34)

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200

API Version 2006-03-01

36
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-abort-date: AbortDate
x-amz-abort-rule-id: AbortRuleId
x-amz-server-side-encryption: ServerSideEncryption
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
x-amz-server-side-encryption-aws-kms-key-id: SSEKMSKeyId
x-amz-server-side-encryption-context: SSEKMSEncryptionContext
x-amz-request-charged: RequestCharged
<?xml version="1.0" encoding="UTF-8"?>
<CreateMultipartUploadOutput>
<Bucket>string</Bucket>
<Key>string</Key>
<UploadId>string</UploadId>
</CreateMultipartUploadOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

x-amz-abort-date (p. 36)

If the bucket has a lifecycle rule conﬁgured with an action to abort incomplete multipart uploads
and the preﬁx in the lifecycle rule matches the object name in the request, the response includes
this header. The header indicates when the initiated multipart upload becomes eligible for an
abort operation. For more information, see Aborting Incomplete Multipart Uploads Using a Bucket
Lifecycle Policy.

The response also includes the x-amz-abort-rule-id header that provides the ID of the lifecycle
conﬁguration rule that deﬁnes this action.
x-amz-abort-rule-id (p. 36)

This header is returned along with the x-amz-abort-date header. It identifies the applicable
lifecycle configuration rule that defines the action to abort incomplete multipart uploads.
x-amz-request-charged (p. 36)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

x-amz-server-side-encryption (p. 36)

The server-side encryption algorithm used when storing this object in Amazon S3 (for example,
AES256, aws:kms).

Valid Values: AES256 | aws:kms

x-amz-server-side-encryption-aws-kms-key-id (p. 36)

If server-side encryption with a customer-provided encryption key was requested, the response will
include this header conﬁrming the encryption algorithm used.

API Version 2006-03-01

37
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-server-side-encryption-customer-key-MD5 (p. 36)

The following data is returned in XML format by the service.

CreateMultipartUploadOutput (p. 36)

Root level tag for the CreateMultipartUploadOutput parameters.

Required: Yes
Bucket (p. 36)

Name of the bucket to which the multipart upload was initiated.

Type: String
Key (p. 36)

Object key for which the multipart upload was initiated.

Type: String

Length Constraints: Minimum length of 1.

UploadId (p. 36)

ID for the initiated multipart upload.

Type: String

Examples
Sample Request

This operation initiates a multipart upload for the example-object object.

POST /example-object?uploads HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732072657175657374

API Version 2006-03-01

38
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Date: Mon, 1 Nov 2010 20:34:56 GMT

Content-Length: 197
Connection: keep-alive
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Bucket>example-bucket</Bucket>
<Key>example-object</Key>
<UploadId>VXBsb2FkIElEIGZvciA2aWWpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZA</
UploadId>
</InitiateMultipartUploadResult>

Example: Initiate a multipart upload using server-side encryption with customer-provided

encryption keys

This example, which initiates a multipart upload request, speciﬁes server-side encryption with customer-
provided encryption keys by adding relevant headers.

POST /example-object?uploads HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
Authorization:authorization string
Date: Wed, 28 May 2014 19:34:57 +0000
x-amz-server-side-encryption-customer-key:
g0lCfA3Dv40jZz5SQJ1ZukLRFqtI5WorC/8SEEXAMPLE
x-amz-server-side-encryption-customer-key-MD5: ZjQrne1X/iTcskbY2example
x-amz-server-side-encryption-customer-algorithm: AES256

Sample Response

In the response, Amazon S3 returns an UploadId. In addition, Amazon S3 returns the encryption
algorithm and the MD5 digest of the encryption key that you provided in the request.

HTTP/1.1 200 OK
x-amz-id-2: 36HRCaIGp57F1FvWvVRrvd3hNn9WoBGfEaCVHTCt8QWf00qxdHazQUgfoXAbhFWD
x-amz-request-id: 50FA1D691B62CA43
Date: Wed, 28 May 2014 19:34:58 GMT
x-amz-server-side-encryption-customer-algorithm: AES256
x-amz-server-side-encryption-customer-key-MD5: ZjQrne1X/iTcskbY2m3tFg==
Transfer-Encoding: chunked

<?xml version="1.0" encoding="UTF-8"?>

<InitiateMultipartUploadResult
xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Bucket>example-bucket</Bucket>
<Key>example-object</Key>

<UploadId>EXAMPLEJZ6e0YupT2h66iePQCc9IEbYbDUy4RTpMeoSMLPRp8Z5o1u8feSRonpvnWsKKG35tI2LB9VDPiCgTy.Gq2VxQ
</UploadId>
</InitiateMultipartUploadResult>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

API Version 2006-03-01

39
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

40
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteBucket
Service: Amazon Simple Storage Service

Deletes the bucket. All objects (including all object versions and delete markers) in the bucket must be
deleted before the bucket itself can be deleted.

Related Resources

• CreateBucket (p. 27)

• DeleteObject (p. 63)

Request Syntax

DELETE / HTTP/1.1
Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 41)

Speciﬁes the bucket being deleted.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Examples
Sample Request

This request deletes the bucket named quotes.

DELETE / HTTP/1.1
Host: quotes.s3.<Region>.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 204 No Content

x-amz-id-2: JuKZqmXuiwFeDQxhD7M8KtsKobSzWA1QEjLbTMTagkKdBX2z7Il/jGhDeJ3j6s80

API Version 2006-03-01

41
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-request-id: 32FE2CEB32F5EE25
Date: Wed, 01 Mar 2006 12:00:00 GMT
Connection: close
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

42
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteBucketAnalyticsConﬁguration
Service: Amazon Simple Storage Service

Deletes an analytics configuration for the bucket (specified by the analytics configuration ID).

To use this operation, you must have permissions to perform the s3:PutAnalyticsConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources.

For information about the Amazon S3 analytics feature, see Amazon S3 Analytics – Storage Class
Analysis.

The following operations are related to DeleteBucketAnalyticsConfiguration:

• GetBucketAnalyticsConﬁguration (p. 85)

• ListBucketAnalyticsConﬁgurations (p. 179)
• PutBucketAnalyticsConﬁguration (p. 243)

Request Syntax

DELETE /?analytics&Id=Id HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 43)

The name of the bucket from which an analytics conﬁguration is deleted.

id (p. 43)

The ID that identiﬁes the analytics conﬁguration.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Examples
Sample Request

The following DELETE request deletes the analytics conﬁguration with the ID list1.

API Version 2006-03-01

43
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DELETE ?/analytics&id=list1 HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Wed, 14 May 2014 02:11:22 GMT
Authorization: signatureValue

Sample Response

The following successful response shows Amazon S3 returning a 204 No Content response. The analytics
conﬁguration with the ID list1 for the bucket has been removed.

HTTP/1.1 204 No Content

x-amz-id-2: 0FmFIWsh/PpBuzZ0JFRC55ZGVmQW4SHJ7xVDqKwhEdJmf3q63RtrvH8ZuxW1Bol5
x-amz-request-id: 0CF038E9BCF63097
Date: Wed, 14 May 2014 02:11:22 GMT
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

44
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteBucketCors
Service: Amazon Simple Storage Service

Deletes the cors conﬁguration information set for the bucket.

To use this operation, you must have permission to perform the s3:PutBucketCORS action. The bucket
owner has this permission by default and can grant this permission to others.

For information about cors, see Enabling Cross-Origin Resource Sharing in the Amazon Simple Storage
Service Developer Guide.

Related Resources:

• PutBucketCors (p. 247)

• Appendix: OPTIONS object (p. 730)

Request Syntax

DELETE /?cors HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 45)

Speciﬁes the bucket whose cors conﬁguration is being deleted.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Examples
Retrieve cors subresource

The following DELETE request deletes the cors subresource from the speciﬁed bucket. This action
removes cors conﬁguration that is stored in the subresource.

Sample Request

DELETE /?cors HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com

API Version 2006-03-01

45
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Date: Tue, 13 Dec 2011 19:14:42 GMT

Authorization: signatureValue

Sample Response

DELETE /?cors HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Tue, 13 Dec 2011 19:14:42 GMT
Authorization: signatureValue

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

46
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteBucketEncryption
Service: Amazon Simple Storage Service

This implementation of the DELETE operation removes default encryption from the bucket. For
information about the Amazon S3 default encryption feature, see Amazon S3 Default Bucket Encryption
in the Amazon Simple Storage Service Developer Guide.

To use this operation, you must have permissions to perform the s3:PutEncryptionConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to your Amazon S3 Resources in the Amazon Simple
Storage Service Developer Guide.

Related Resources

• PutBucketEncryption (p. 250)

• GetBucketEncryption (p. 92)

Request Syntax

DELETE /?encryption HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 47)

The name of the bucket containing the server-side encryption conﬁguration to delete.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Examples
Sample Request

The following DELETE request deletes default encryption from the bucket.

DELETE ?/encryption HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Wed, 06 Sep 2017 12:00:00 GMT
Authorization: signatureValue

API Version 2006-03-01

47
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Sample Response

The following successful response shows Amazon S3 returning a 204 No Content response conﬁrming
that default encryption has been removed from the bucket.

HTTP/1.1 204 No Content

x-amz-id-2: 0FmFIWsh/PpBuzZ0JFRC55ZGVmQW4SHJ7xVDqKwhEdJmf3q63RtrvH8ZuxW1Bol5
x-amz-request-id: 0CF038E9BCF63097
Date: Wed, 06 Sep 2017 12:00:00 GMT
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

48
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteBucketInventoryConﬁguration
Service: Amazon Simple Storage Service

Deletes an inventory conﬁguration (identiﬁed by the inventory ID) from the bucket.

To use this operation, you must have permissions to perform the s3:PutInventoryConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources.

For information about the Amazon S3 inventory feature, see Amazon S3 Inventory.

Operations related to DeleteBucketInventoryConfiguration include:

• GetBucketInventoryConﬁguration (p. 95)

• PutBucketInventoryConﬁguration (p. 253)
• ListBucketInventoryConﬁgurations (p. 183)

Request Syntax

DELETE /?inventory&Id=Id HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 49)

The name of the bucket containing the inventory conﬁguration to delete.

id (p. 49)

The ID used to identify the inventory conﬁguration.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Examples
Sample Request

The following DELETE request deletes the inventory conﬁguration with the ID list1.

DELETE ?/inventory&id=list1 HTTP/1.1

API Version 2006-03-01

49
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Wed, 14 May 2014 02:11:22 GMT
Authorization: signatureValue

Sample Response

The following successful response shows Amazon S3 returning a 204 No Content response. The
inventory conﬁguration with the ID list1 for the bucket has been removed.

HTTP/1.1 204 No Content

x-amz-id-2: 0FmFIWsh/PpBuzZ0JFRC55ZGVmQW4SHJ7xVDqKwhEdJmf3q63RtrvH8ZuxW1Bol5
x-amz-request-id: 0CF038E9BCF63097
Date: Wed, 14 May 2014 02:11:22 GMT
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

50
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteBucketLifecycle
Service: Amazon Simple Storage Service

Deletes the lifecycle configuration from the specified bucket. Amazon S3 removes all the lifecycle
configuration rules in the lifecycle subresource associated with the bucket. Your objects never expire, and
Amazon S3 no longer automatically deletes any objects on the basis of rules contained in the deleted
lifecycle configuration.

To use this operation, you must have permission to perform the s3:PutLifecycleConfiguration
action. By default, the bucket owner has this permission and the bucket owner can grant this permission
to others.

There is usually some time lag before lifecycle conﬁguration deletion is fully propagated to all the
Amazon S3 systems.

For more information about the object expiration, see Elements to Describe Lifecycle Actions.

Related actions include:

• PutBucketLifecycleConﬁguration (p. 264)

• GetBucketLifecycleConﬁguration (p. 102)

Request Syntax

DELETE /?lifecycle HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 51)

The bucket name of the lifecycle to delete.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Examples
Sample Request

The following DELETE request deletes the lifecycle subresource from the speciﬁed bucket. This removes
lifecycle conﬁguration stored in the subresource.

API Version 2006-03-01

51
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DELETE /?lifecycle HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Wed, 14 Dec 2011 05:37:16 GMT
Authorization: signatureValue

Sample Response

The following successful response shows Amazon S3 returning a 204 No Content response. Objects in
your bucket no longer expire.

HTTP/1.1 204 No Content

x-amz-id-2: Uuag1LuByRx9e6j5OnimrSAMPLEtRPfTaOAa==
x-amz-request-id: 656c76696e672SAMPLE5657374
Date: Wed, 14 Dec 2011 05:37:16 GMT
Connection: keep-alive
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

52
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteBucketMetricsConﬁguration
Service: Amazon Simple Storage Service

Deletes a metrics configuration for the Amazon CloudWatch request metrics (specified by the metrics
configuration ID) from the bucket. Note that this doesn't include the daily storage metrics.

To use this operation, you must have permissions to perform the s3:PutMetricsConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources.

For information about CloudWatch request metrics for Amazon S3, see Monitoring Metrics with Amazon
CloudWatch.

The following operations are related to DeleteBucketMetricsConfiguration:

• GetBucketMetricsConﬁguration (p. 110)

• PutBucketMetricsConﬁguration (p. 274)
• ListBucketMetricsConﬁgurations (p. 188)
• Monitoring Metrics with Amazon CloudWatch

Request Syntax

DELETE /?metrics&Id=Id HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 53)

The name of the bucket containing the metrics conﬁguration to delete.

id (p. 53)

The ID used to identify the metrics conﬁguration.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Examples
Sample Request
Delete the metric conﬁguration with a speciﬁed ID, which disables the CloudWatch metrics with the
ExampleMetrics value for the FilterId dimension.

API Version 2006-03-01

53
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DELETE /?metrics&id=ExampleMetrics HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT
Authorization: signatureValue

Sample Response

Delete the metric conﬁguration with a speciﬁed ID, which disables the CloudWatch metrics with the
ExampleMetrics value for the FilterId dimension.

HTTP/1.1 204 No Content

x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

54
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteBucketPolicy
Service: Amazon Simple Storage Service

This implementation of the DELETE operation uses the policy subresource to delete the policy of a
speciﬁed bucket. If you are using an identity other than the root user of the AWS account that owns the
bucket, the calling identity must have the DeleteBucketPolicy permissions on the speciﬁed bucket
and belong to the bucket owner's account to use this operation.

If you don't have DeleteBucketPolicy permissions, Amazon S3 returns a 403 Access Denied error.
If you have the correct permissions, but you're not using an identity that belongs to the bucket owner's
account, Amazon S3 returns a 405 Method Not Allowed error.
Important
As a security precaution, the root user of the AWS account that owns a bucket can always use
this operation, even if the policy explicitly denies the root user the ability to perform this action.

For more information about bucket policies, see Using Bucket Policies and UserPolicies.

The following operations are related to DeleteBucketPolicy

• CreateBucket (p. 27)

• DeleteObject (p. 63)

Request Syntax

DELETE /?policy HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 55)

The bucket name.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Examples
Sample Request

This request deletes the bucket named BucketName.

API Version 2006-03-01

55
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DELETE /?policy HTTP/1.1

Host: BucketName.s3.<Region>.amazonaws.com
Date: Tue, 04 Apr 2010 20:34:56 GMT
Authorization: signatureValue

Sample Response

HTTP/1.1 204 No Content

x-amz-id-2: Uuag1LuByRx9e6j5OnimrSAMPLEtRPfTaOFg==
x-amz-request-id: 656c76696e672SAMPLE5657374
Date: Tue, 04 Apr 2010 20:34:56 GMT
Connection: keep-alive
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

56
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteBucketReplication
Service: Amazon Simple Storage Service

Deletes the replication conﬁguration from the bucket.

To use this operation, you must have permissions to perform the s3:PutReplicationConfiguration
action. The bucket owner has these permissions by default and can grant it to others. For more
information about permissions, see Permissions Related to Bucket Subresource Operations and
Managing Access Permissions to Your Amazon S3 Resources.
Note
It can take a while for the deletion of a replication conﬁguration to fully propagate.

For information about replication conﬁguration, see Replication in the Amazon S3 Developer Guide.

The following operations are related to DeleteBucketReplication:

• PutBucketReplication (p. 289)

• GetBucketReplication (p. 123)

Request Syntax

DELETE /?replication HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 57)

The bucket name.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Examples
Sample Request

The following DELETE request deletes the replication subresource from the speciﬁed bucket. This
removes the replication conﬁguration that is set for the bucket.

DELETE /?replication HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com

API Version 2006-03-01

57
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Date: Wed, 11 Feb 2015 05:37:16 GMT

20150211T171320Z

Authorization: authorization string

Sample Response

When the replication subresource has been deleted, Amazon S3 returns a 204 No Content
response. It will not replicate new objects that are stored in the examplebucket bucket.

HTTP/1.1 204 No Content

x-amz-id-2: Uuag1LuByRx9e6j5OnimrSAMPLEtRPfTaOAa==
x-amz-request-id: 656c76696e672example
Date: Wed, 11 Feb 2015 05:37:16 GMT
Connection: keep-alive
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

58
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteBucketTagging
Service: Amazon Simple Storage Service

Deletes the tags from the bucket.

To use this operation, you must have permission to perform the s3:PutBucketTagging action. By
default, the bucket owner has this permission and can grant this permission to others.

The following operations are related to DeleteBucketTagging:

• GetBucketTagging (p. 129)

• PutBucketTagging (p. 297)

Request Syntax

DELETE /?tagging HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 59)

The bucket that has the tag set to be removed.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Examples
Sample Request

The following DELETE request deletes the tag set from the speciﬁed bucket.

DELETE /?tagging HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Wed, 14 Dec 2011 05:37:16 GMT
Authorization: signatureValue

Sample Response

The following successful response shows Amazon S3 returning a 204 No Content response. The tag set
for the bucket has been removed.

API Version 2006-03-01

59
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

HTTP/1.1 204 No Content

Date: Wed, 25 Nov 2009 12:00:00 GMT
Connection: close
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

60
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteBucketWebsite
Service: Amazon Simple Storage Service

This operation removes the website configuration for a bucket. Amazon S3 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. Amazon S3
returns a 404 response if the bucket specified in the request does not exist.

This DELETE operation requires the S3:DeleteBucketWebsite permission. By default, only the bucket
owner can delete the website conﬁguration attached to a bucket. However, bucket owners can grant
other users permission to delete the website conﬁguration by writing a bucket policy granting them the
S3:DeleteBucketWebsite permission.

For more information about hosting websites, see Hosting Websites on Amazon S3.

The following operations are related to DeleteBucketWebsite:

• GetBucketWebsite (p. 135)

• PutBucketWebsite (p. 304)

Request Syntax

DELETE /?website HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 61)

The bucket name for which you want to remove the website conﬁguration.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

Examples
Sample Request

This request deletes the website conﬁguration on the speciﬁed bucket.

DELETE ?website HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
Date: Thu, 27 Jan 2011 12:00:00 GMT

API Version 2006-03-01

61
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Authorization: signatureValue

Sample Response

HTTP/1.1 204 No Content

x-amz-id-2: aws-s3integ-s3ws-31008.sea31.amazon.com
x-amz-request-id: AF1DD829D3B49707
Date: Thu, 03 Feb 2011 22:10:26 GMT
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

62
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteObject
Service: Amazon Simple Storage Service

Removes the null version (if there is one) of an object and inserts a delete marker, which becomes the
latest version of the object. If there isn't a null version, Amazon S3 does not remove any objects.

To remove a speciﬁc version, you must be the bucket owner and you must use the version Id subresource.
Using this subresource permanently deletes the version. If the object deleted is a delete marker, Amazon
S3 sets the response header, x-amz-delete-marker, to true.

If the object you want to delete is in a bucket where the bucket versioning conﬁguration is MFA Delete
enabled, you must include the x-amz-mfa request header in the DELETE versionId request. Requests
that include x-amz-mfa must use HTTPS.

For more information about MFA Delete, see Using MFA Delete. To see sample requests that use
versioning, see Sample Request.

You can delete objects by explicitly calling the DELETE Object API or conﬁgure its lifecycle
(PutBucketLifecycle (p. 258)) to enable Amazon S3 to remove them for you. If you want to block
users or accounts from removing or deleting objects from your bucket, you must deny them the
s3:DeleteObject, s3:DeleteObjectVersion, and s3:PutLifeCycleConfiguration actions.

The following operation is related to DeleteObject:

• PutObject (p. 310)

Request Syntax

DELETE /Key+?VersionId=VersionId HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-mfa: MFA
x-amz-request-payer: RequestPayer
x-amz-bypass-governance-retention: BypassGovernanceRetention

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 63)

The bucket name of the bucket containing the object.

Key name of the object to delete.

Length Constraints: Minimum length of 1.

versionId (p. 63)

VersionId used to reference a speciﬁc version of the object.

API Version 2006-03-01

63
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-bypass-governance-retention (p. 63)

Indicates whether S3 Object Lock should bypass Governance-mode restrictions to process this
operation.
x-amz-mfa (p. 63)

The concatenation of the authentication device's serial number, a space, and the value that is
displayed on your authentication device. Required to permanently delete a versioned object if
versioning is conﬁgured with MFA delete enabled.
x-amz-request-payer (p. 63)

Valid Values: requester

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204
x-amz-delete-marker: DeleteMarker
x-amz-version-id: VersionId
x-amz-request-charged: RequestCharged

Response Elements
If the action is successful, the service sends back an HTTP 204 response.

The response returns the following HTTP headers.

x-amz-delete-marker (p. 64)

Speciﬁes whether the versioned object that was permanently deleted was (true) or was not (false) a
delete marker.
x-amz-request-charged (p. 64)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

x-amz-version-id (p. 64)

Returns the version ID of the delete marker created as a result of the DELETE operation.

Examples
Sample Request

The following request deletes the object my-second-image.jpg.

API Version 2006-03-01

64
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DELETE /my-second-image.jpg HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain

Sample Response

HTTP/1.1 204 NoContent

x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
Date: Wed, 12 Oct 2009 17:50:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3

Sample Request: Deleting a speciﬁed version of an object

The following request deletes the speciﬁed version of the object my-third-image.jpg.

DELETE /my-third-image.jpg?
versionId=UIORUnfndfiufdisojhr398493jfdkjFJjkndnqUifhnw89493jJFJ HTTP/1.1
Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 0

Sample Response

HTTP/1.1 204 NoContent

x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
x-amz-version-id: UIORUnfndfiufdisojhr398493jfdkjFJjkndnqUifhnw89493jJFJ
Date: Wed, 12 Oct 2009 17:50:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3

Sample Response: If the object deleted is a delete marker

HTTP/1.1 204 NoContent

x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
x-amz-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
x-amz-delete-marker: true
Date: Wed, 12 Oct 2009 17:50:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3

API Version 2006-03-01

65
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Sample Request: Deleting a speciﬁed version of an object in an MFA-enabled bucket

The following request deletes the speciﬁed version of the object my-third-image.jpg, which is stored
in an MFA-enabled bucket.

DELETE /my-third-image.jpg?versionId=UIORUnfndfiuf HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
x-amz-mfa:[SerialNumber] [AuthenticationCode]
Authorization: authorization string
Content-Type: text/plain
Content-Length: 0

Sample Response

HTTP/1.1 204 NoContent

x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
x-amz-version-id: UIORUnfndfiuf
Date: Wed, 12 Oct 2009 17:50:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

66
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteObjects
Service: Amazon Simple Storage Service

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, and optionally, version IDs if you want to delete a speciﬁc version of the object from a
versioning-enabled bucket. For each key, Amazon S3 performs a delete operation and returns the result
of that delete, success, or failure, in the response. Note that if the object speciﬁed in the request is not
found, Amazon S3 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.

When performing this operation on an MFA Delete enabled bucket, that attempts to delete any
versioned objects, you must include an MFA token. If you do not provide one, the entire request will
fail, even if there are non-versioned objects you are trying to delete. If you provide an invalid token,
whether there are versioned keys in the request or not, the entire Multi-Object Delete request will fail.
For information about MFA Delete, see MFA Delete.

Finally, the Content-MD5 header is required for all Multi-Object Delete requests. Amazon S3 uses the
header value to ensure that your request body has not been altered in transit.

The following operations are related to DeleteObjects:

• CreateMultipartUpload (p. 32)

• UploadPart (p. 360)
• CompleteMultipartUpload (p. 10)
• ListParts (p. 229)
• AbortMultipartUpload (p. 7)

Request Syntax

POST /?delete HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-mfa: MFA
x-amz-request-payer: RequestPayer
x-amz-bypass-governance-retention: BypassGovernanceRetention
<?xml version="1.0" encoding="UTF-8"?>
<Delete xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Object>
<Key>string</Key>
<VersionId>string</VersionId>
</Object>
...
<Quiet>boolean</Quiet>
</Delete>

URI Request Parameters

The request requires the following URI parameters.

API Version 2006-03-01

67
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Bucket (p. 67)

The bucket name containing the objects to delete.

Speciﬁes whether you want to delete this object even if it has a Governance-type Object Lock in
place. You must have suﬃcient permissions to perform this operation.
x-amz-mfa (p. 67)

Valid Values: requester

Request Body
The request accepts the following data in XML format.

Delete (p. 67)

Root level tag for the Delete parameters.

Required: Yes
Object (p. 67)

The objects to delete.

Type: Array of ObjectIdentiﬁer (p. 503) data types

Required: Yes
Quiet (p. 67)

Element to enable quiet mode for the request. When you add this element, you must set its value to
true.

Type: Boolean

Required: No

Response Syntax

HTTP/1.1 200

API Version 2006-03-01

68
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-request-charged: RequestCharged
<?xml version="1.0" encoding="UTF-8"?>
<DeleteObjectsOutput>
<Deleted>
<DeleteMarker>boolean</DeleteMarker>
<DeleteMarkerVersionId>string</DeleteMarkerVersionId>
<Key>string</Key>
<VersionId>string</VersionId>
</Deleted>
...
<Error>
<Code>string</Code>
<Key>string</Key>
<Message>string</Message>
<VersionId>string</VersionId>
</Error>
...
</DeleteObjectsOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

x-amz-request-charged (p. 68)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

The following data is returned in XML format by the service.

DeleteObjectsOutput (p. 68)

Root level tag for the DeleteObjectsOutput parameters.

Required: Yes
Deleted (p. 68)

Container element for a successful delete. It identiﬁes the object that was successfully deleted.

Type: Array of DeletedObject (p. 444) data types

Error (p. 68)

Container for a failed delete operation that describes the object that Amazon S3 attempted to
delete and the error it encountered.

Type: Array of Error (p. 452) data types

Examples
Sample Request: Multi-object delete resulting in mixed success/error response

This example illustrates a Multi-Object Delete request to delete objects that result in mixed success and
errors response. The following request deletes two objects from a bucket (bucketname). In this example,
the requester does not have permission to delete the sample2.txt object.

API Version 2006-03-01

69
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

POST /?delete HTTP/1.1

Host: bucketname.s3.<Region>.amazonaws.com
Accept: */*
x-amz-date: Wed, 30 Nov 2011 03:39:05 GMT
Content-MD5: p5/WA/oEr30qrEEl21PAqw==
Authorization: AWS AKIAIOSFODNN7EXAMPLE:W0qPYCLe6JwkZAD1ei6hp9XZIee=
Content-Length: 125
Connection: Keep-Alive

<Delete>
<Object>
<Key>sample1.txt</Key>
</Object>
<Object>
<Key>sample2.txt</Key>
</Object>
</Delete>

Sample Response

The response includes a DeleteResult element that includes a Deleted element for the item that
Amazon S3 successfully deleted and an Error element that Amazon S3 did not delete because you
didn't have permission to delete the object.

HTTP/1.1 200 OK
x-amz-id-2: 5h4FxSNCUS7wP5z92eGCWDshNpMnRuXvETa4HH3LvvH6VAIr0jU7tH9kM7X+njXx
x-amz-request-id: A437B3B641629AEE
Date: Fri, 02 Dec 2011 01:53:42 GMT
Content-Type: application/xml
Server: AmazonS3
Content-Length: 251

<?xml version="1.0" encoding="UTF-8"?>

<DeleteResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Deleted>
<Key>sample1.txt</Key>
</Deleted>
<Error>
<Key>sample2.txt</Key>
<Code>AccessDenied</Code>
<Message>Access Denied</Message>
</Error>
</DeleteResult>

Sample Request: Deleting an object from a versioned bucket

If you delete an item from a versioning enabled bucket, all versions of that object remain in the bucket;
however, Amazon S3 inserts a delete marker. For more information, see Object Versioning.

The following scenarios describe the behavior of a multi-object Delete request when versioning is
enabled for your bucket.

Case 1 - Simple Delete: In the following sample request, the multi-object delete request speciﬁes only
one key.

POST /?delete HTTP/1.1

Host: bucketname.s3.<Region>.amazonaws.com

API Version 2006-03-01

70
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Accept: */*
x-amz-date: Wed, 30 Nov 2011 03:39:05 GMT
Content-MD5: p5/WA/oEr30qrEEl21PAqw==
Authorization: AWS AKIAIOSFODNN7EXAMPLE:W0qPYCLe6JwkZAD1ei6hp9XZIee=
Content-Length: 79
Connection: Keep-Alive

<Delete>
<Object>
<Key>SampleDocument.txt</Key>
</Object>
</Delete>

Sample Response

Because versioning is enabled on the bucket, Amazon S3 does not delete the object. Instead, it adds
a delete marker for this object. The following response indicates that a delete marker was added (the
DeleteMarker element in the response as a value of true) and the version number of the delete marker
it added.

HTTP/1.1 200 OK
x-amz-id-2: P3xqrhuhYxlrefdw3rEzmJh8z5KDtGzb+/FB7oiQaScI9Yaxd8olYXc7d1111ab+
x-amz-request-id: 264A17BF16E9E80A
Date: Wed, 30 Nov 2011 03:39:32 GMT
Content-Type: application/xml
Server: AmazonS3
Content-Length: 276

<?xml version="1.0" encoding="UTF-8"?>

<DeleteResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Deleted>
<Key>SampleDocument.txt</Key>
<DeleteMarker>true</DeleteMarker>
<DeleteMarkerVersionId>NeQt5xeFTfgPJD8B4CGWnkSLtluMr11s</
DeleteMarkerVersionId>
</Deleted>
</DeleteResult>

Case 2 - Versioned Delete

The following request attempts to delete a speciﬁc version of an object.

POST /?delete HTTP/1.1

<Delete>
<Object>
<Key>SampleDocument.txt</Key>
<VersionId>OYcLXagmS.WaD..oyH4KRguB95_YhLs7</VersionId>
</Object>
</Delete>

API Version 2006-03-01

71
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Sample Response

In this case, Amazon S3 deletes the speciﬁc object version from the bucket and returns the following
response. In the response, Amazon S3 returns the key and version ID of the object deleted.

HTTP/1.1 200 OK
x-amz-id-2: P3xqrhuhYxlrefdw3rEzmJh8z5KDtGzb+/
FB7oiQaScI9Yaxd8olYXc7d1111xx+
x-amz-request-id: 264A17BF16E9E80A
Date: Wed, 30 Nov 2011 03:39:32 GMT
Content-Type: application/xml
Server: AmazonS3
Content-Length: 219

<?xml version="1.0" encoding="UTF-8"?>

<DeleteResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Deleted>
<Key>SampleDocument.txt</Key>
<VersionId>OYcLXagmS.WaD..oyH4KRguB95_YhLs7</VersionId>
</Deleted>
</DeleteResult>

Case 3 - Versioned delete of a delete marker

In the preceding example, the request refers to a delete marker (instead of an object), then Amazon S3
deletes the delete marker. The eﬀect of this operation is to make your object reappear in your bucket.
Amazon S3 returns a response that indicates the delete marker it deleted (DeleteMarker element with
value true) and the version ID of the delete marker.

HTTP/1.1 200 OK
x-amz-id-2: IIPUZrtolxDEmWsKOae9JlSZe6yWfTye3HQ3T2iAe0ZE4XHa6NKvAJcPp51zZaBr
x-amz-request-id: D6B284CEC9B05E4E
Date: Wed, 30 Nov 2011 03:43:25 GMT
Content-Type: application/xml
Server: AmazonS3
Content-Length: 331

<?xml version="1.0" encoding="UTF-8"?>

<DeleteResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Deleted>
<Key>SampleDocument.txt</Key>
<VersionId>NeQt5xeFTfgPJD8B4CGWnkSLtluMr11s</VersionId>
<DeleteMarker>true</DeleteMarker>
<DeleteMarkerVersionId>NeQt5xeFTfgPJD8B4CGWnkSLtluMr11s</
DeleteMarkerVersionId>
</Deleted>
</DeleteResult>

Sample Response

In general, when a multi-object Delete request results in Amazon S3 either adding a delete marker or
removing a delete marker, the response returns the following elements.

<DeleteMarker>true</DeleteMarker>
<DeleteMarkerVersionId>NeQt5xeFTfgPJD8B4CGWnkSLtluMr11s</
DeleteMarkerVersionId>

API Version 2006-03-01

72
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Sample Request: Malformed XML in the request

This example shows how Amazon S3 responds to a request that includes a malformed XML document.
The following request sends a malformed XML document (missing the Delete end element).

POST /?delete HTTP/1.1

Sample Response

The response returns the error messages that describe the error.

<?xml version="1.0" encoding="UTF-8"?>

<Error>
<Code>MalformedXML</Code>
<Message>The XML you provided was not well-formed or did not
validate against our published schema</Message>
<RequestId>264A17BF16E9E80A</RequestId>
<HostId>P3xqrhuhYxlrefdw3rEzmJh8z5KDtGzb+/FB7oiQaScI9Yaxd8olYXc7d1111ab+</
HostId>
</Error>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java

API Version 2006-03-01

73
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for JavaScript

• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

74
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteObjectTagging
Service: Amazon Simple Storage Service

Removes the entire tag set from the speciﬁed object. For more information about managing object tags,
see Object Tagging.

To use this operation, you must have permission to perform the s3:DeleteObjectTagging action.

To delete tags of a speciﬁc object version, add the versionId query parameter in the request. You will
need permission for the s3:DeleteObjectVersionTagging action.

The following operations are related to DeleteBucketMetricsConfiguration:

• PutObjectTagging (p. 336)

• GetObjectTagging (p. 160)

Request Syntax

DELETE /{Key+}?tagging&VersionId=VersionId HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 75)

The bucket name containing the objects from which to remove the tags.

Name of the tag.

Length Constraints: Minimum length of 1.

versionId (p. 75)

The versionId of the object that the tag-set will be removed from.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204
x-amz-version-id: VersionId

Response Elements
If the action is successful, the service sends back an HTTP 204 response.

API Version 2006-03-01

75
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

The response returns the following HTTP headers.

x-amz-version-id (p. 75)

The versionId of the object the tag-set was removed from.

Examples
Sample Request

The following DELETE request deletes the tag set from the speciﬁed object.

DELETE /exampleobject?tagging HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Wed, 25 Nov 2016 12:00:00 GMT
Authorization: signatureValue

Sample Response

The following successful response shows Amazon S3 returning a 204 No Content response. The tag set
for the object has been removed.

HTTP/1.1 204 No Content

Date: Wed, 25 Nov 2016 12:00:00 GMT
Connection: close
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

76
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeletePublicAccessBlock
Service: Amazon Simple Storage Service

Removes the PublicAccessBlock conﬁguration for an Amazon S3 bucket. To use this operation,
you must have the s3:PutBucketPublicAccessBlock permission. For more information about
permissions, see Permissions Related to Bucket Subresource Operations and Managing Access
Permissions to Your Amazon S3 Resources.

The following operations are related to DeleteBucketMetricsConfiguration:

• Using Amazon S3 Block Public Access

• GetPublicAccessBlock (p. 165)
• PutPublicAccessBlock (p. 339)
• GetBucketPolicyStatus (p. 121)

Request Syntax

DELETE /?publicAccessBlock HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 77)

The Amazon S3 bucket whose PublicAccessBlock conﬁguration you want to delete.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 204

Response Elements
If the action is successful, the service sends back an HTTP 204 response with an empty HTTP body.

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

API Version 2006-03-01

77
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for Ruby V2

API Version 2006-03-01

78
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketAccelerateConﬁguration
Service: Amazon Simple Storage Service

This implementation of the GET operation uses the accelerate subresource to return the Transfer
Acceleration state of a bucket, which is either Enabled or Suspended. Amazon S3 Transfer Acceleration
is a bucket-level feature that enables you to perform faster data transfers to and from Amazon S3.

To use this operation, you must have permission to perform the s3:GetAccelerateConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to your Amazon S3 Resources in the Amazon Simple
Storage Service Developer Guide.

You set the Transfer Acceleration state of an existing bucket to Enabled or Suspended by using the
PutBucketAccelerateConﬁguration (p. 234) operation.

A GET accelerate request does not return a state value for a bucket that has no transfer acceleration
state. A bucket has no Transfer Acceleration state if a state has never been set on the bucket.

For more information about transfer acceleration, see Transfer Acceleration in the Amazon Simple
Storage Service Developer Guide.

Related Resources

• PutBucketAccelerateConﬁguration (p. 234)

Request Syntax

GET /?accelerate HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 79)

Name of the bucket for which the accelerate conﬁguration is retrieved.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetBucketAccelerateConfigurationOutput>
<Status>string</Status>
</GetBucketAccelerateConfigurationOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

API Version 2006-03-01

79
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketAccelerateConﬁgurationOutput (p. 79)

Root level tag for the GetBucketAccelerateConﬁgurationOutput parameters.

Required: Yes
Status (p. 79)

The accelerate conﬁguration of the bucket.

Type: String

Valid Values: Enabled | Suspended

Examples
This implementation of the GET operation returns the following responses.

If the transfer acceleration state is set to Enabled on a bucket, the response is as follows:

<AccelerateConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
</AccelerateConfiguration>

If the transfer acceleration state is set to Suspended on a bucket, the response is as follows:

<AccelerateConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Suspended</Status>
</AccelerateConfiguration>

If the transfer acceleration state on a bucket has never been set to Enabled or Suspended, the response
is as follows:

<AccelerateConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/" />

Retrieve the transfer acceleration conﬁguration for a bucket

The following example shows a GET /?accelerate request to retrieve the transfer acceleration state of
the bucket named examplebucket.

<AccelerateConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
</AccelerateConfiguration>

The following is a sample of the response body (only) that shows bucket transfer acceleration is enabled.

API Version 2006-03-01

80
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GET /?accelerate HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Mon, 11 Apr 2016 12:00:00 GMT
Authorization: authorization string
Content-Type: text/plain

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

81
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketAcl
Service: Amazon Simple Storage Service

This implementation of the GET operation uses the acl subresource to return the access control list
(ACL) of a bucket. To use GET to return the ACL of the bucket, you must have READ_ACP access to the
bucket. If READ_ACP permission is granted to the anonymous user, you can return the ACL of the bucket
without using an authorization header.

Related Resources

• ListObjects (p. 202)

Request Syntax

GET /?acl HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 82)

Speciﬁes the S3 bucket whose ACL is being requested.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetBucketAclOutput>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
<AccessControlList>
<Grant>
<Grantee>
<DisplayName>string</DisplayName>
<EmailAddress>string</EmailAddress>
<ID>string</ID>
<xsi:type>string</xsi:type>
<URI>string</URI>
</Grantee>
<Permission>string</Permission>
</Grant>
</AccessControlList>
</GetBucketAclOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

API Version 2006-03-01

82
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketAclOutput (p. 82)

Root level tag for the GetBucketAclOutput parameters.

Required: Yes
Grants (p. 82)

A list of grants.

Type: Array of Grant (p. 466) data types

Owner (p. 82)

Container for the bucket owner's display name and ID.

Type: Owner (p. 512) data type

Examples
Sample Request

The following request returns the ACL of the speciﬁed bucket.

GET ?acl HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
Content-Length: 124
Content-Type: text/plain
Connection: close
Server: AmazonS3
<AccessControlPolicy>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser">
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

API Version 2006-03-01

83
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

84
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketAnalyticsConﬁguration
Service: Amazon Simple Storage Service

This implementation of the GET operation returns an analytics configuration (identified by the analytics
configuration ID) from the bucket.

To use this operation, you must have permissions to perform the s3:GetAnalyticsConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple
Storage Service Developer Guide.

For information about Amazon S3 analytics feature, see Amazon S3 Analytics – Storage Class Analysis in
the Amazon Simple Storage Service Developer Guide.

Related Resources

• DeleteBucketAnalyticsConﬁguration (p. 43)

• ListBucketAnalyticsConﬁgurations (p. 179)
• PutBucketAnalyticsConﬁguration (p. 243)

Request Syntax

GET /?analytics&Id=Id HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 85)

The name of the bucket from which an analytics conﬁguration is retrieved.

id (p. 85)

The ID that identiﬁes the analytics conﬁguration.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<AnalyticsConfiguration>
<Id>string</Id>
<Filter>
<And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
...
</And>

API Version 2006-03-01

85
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</Filter>
<StorageClassAnalysis>
<DataExport>
<Destination>
<S3BucketDestination>
<Bucket>string</Bucket>
<BucketAccountId>string</BucketAccountId>
<Format>string</Format>
<Prefix>string</Prefix>
</S3BucketDestination>
</Destination>
<OutputSchemaVersion>string</OutputSchemaVersion>
</DataExport>
</StorageClassAnalysis>
</AnalyticsConfiguration>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

AnalyticsConﬁguration (p. 85)

Root level tag for the AnalyticsConﬁguration parameters.

Required: Yes
Filter (p. 85)

The filter used to describe a set of objects for analyses. A filter must have exactly one prefix, one tag,
or one conjunction (AnalyticsAndOperator). If no filter is provided, all objects will be considered in
any analysis.

Type: AnalyticsFilter (p. 421) data type

Id (p. 85)

The ID that identiﬁes the analytics conﬁguration.

Type: String
StorageClassAnalysis (p. 85)

Contains data related to access patterns to be collected and made available to analyze the tradeoﬀs
between diﬀerent storage classes.

Type: StorageClassAnalysis (p. 557) data type

Examples
Conﬁgure an Analytics Report

The following GET request for the bucket examplebucket returns the inventory conﬁguration with the
ID list1:

API Version 2006-03-01

86
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GET /?analytics&id=list1 HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Mon, 31 Oct 2016 12:00:00 GMT
Authorization: authorization string

Example

The following is a sample response to the preceding GET request.

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A02
Date: Mon, 31 Oct 2016 12:00:00 GMT
Server: AmazonS3
Content-Length: length

<?xml version="1.0" encoding="UTF-8"?>

<AnalyticsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>list1</Id>
<Filter>
<And>
<Prefix>images/</Prefix>
<Tag>
<Key>dog</Key>
<Value>corgi</Value>
</Tag>
</And>
</Filter>
<StorageClassAnalysis>
<DataExport>
<OutputSchemaVersion>V_1</OutputSchemaVersion>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<BucketAccountId>123456789012</BucketAccountId>
<Bucket>arn:aws:s3:::destination-bucket</Bucket>
<Prefix>destination-prefix</Prefix>
</S3BucketDestination>
</Destination>
</DataExport>
</StorageClassAnalysis>
</AnalyticsConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

87
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

API Version 2006-03-01

88
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketCors
Service: Amazon Simple Storage Service

Returns the cors conﬁguration information set for the bucket.

To use this operation, you must have permission to perform the s3:GetBucketCORS action. By default,
the bucket owner has this permission and can grant it to others.

For more information about cors, see Enabling Cross-Origin Resource Sharing.

The following operations are related to GetBucketCors:

• PutBucketCors (p. 247)

• DeleteBucketCors (p. 45)

Request Syntax

GET /?cors HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 89)

The bucket name for which to get the cors conﬁguration.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetBucketCorsOutput>
<CORSRule>
<AllowedHeader>string</AllowedHeader>
...
<AllowedMethod>string</AllowedMethod>
...
<AllowedOrigin>string</AllowedOrigin>
...
<ExposeHeader>string</ExposeHeader>
...
<MaxAgeSeconds>integer</MaxAgeSeconds>
</CORSRule>
...
</GetBucketCorsOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

API Version 2006-03-01

89
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketCorsOutput (p. 89)

Root level tag for the GetBucketCorsOutput parameters.

Required: Yes
CORSRule (p. 89)

A set of origins and methods (cross-origin access that you want to allow). You can add up to 100
rules to the conﬁguration.

Type: Array of CORSRule (p. 436) data types

Examples
Conﬁgure cors Sample Request
The following PUT request adds the cors subresource to a bucket (examplebucket).

PUT /?cors HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Tue, 21 Aug 2012 17:54:50 GMT
Content-MD5: 8dYiLewFWZyGgV2Q5FNI4W==
Authorization: authorization string
Content-Length: 216

<CORSConfiguration>
<CORSRule>
<AllowedOrigin>http://www.example.com</AllowedOrigin>
<AllowedMethod>PUT</AllowedMethod>
<AllowedMethod>POST</AllowedMethod>
<AllowedMethod>DELETE</AllowedMethod>
<AllowedHeader>*</AllowedHeader>
<MaxAgeSeconds>3000</MaxAgeSec>
<ExposeHeader>x-amz-server-side-encryption</ExposeHeader>
</CORSRule>
<CORSRule>
<AllowedOrigin>*</AllowedOrigin>
<AllowedMethod>GET</AllowedMethod>
<AllowedHeader>*</AllowedHeader>
<MaxAgeSeconds>3000</MaxAgeSeconds>
</CORSRule>
</CORSConfiguration>

This is the sample response to the preceding request.

HTTP/1.1 200 OK
x-amz-id-2: CCshOvbOPfxzhwOADyC4qHj/Ck3F9Q0viXKw3rivZ+GcBoZSOOahvEJfPisZB7B
x-amz-request-id: BDC4B83DF5096BBE
Date: Tue, 21 Aug 2012 17:54:50 GMT
Server: AmazonS3

Sample Request: Retrieve cors subresource

The following example gets the cors subresource of a bucket.

API Version 2006-03-01

90
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GET /?cors HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Tue, 13 Dec 2011 19:14:42 GMT
Authorization: signatureValue

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: 0FmFIWsh/PpBuzZ0JFRC55ZGVmQW4SHJ7xVDqKwhEdJmf3q63RtrvH8ZuxW1Bol5
x-amz-request-id: 0CF038E9BCF63097
Date: Tue, 13 Dec 2011 19:14:42 GMT
Server: AmazonS3
Content-Length: 280
<CORSConfiguration>
<CORSRule>
<AllowedOrigin>http://www.example.com</AllowedOrigin>
<AllowedMethod>GET</AllowedMethod>
<MaxAgeSeconds>3000</MaxAgeSec>
<ExposeHeader>x-amz-server-side-encryption</ExposeHeader>
</CORSRule>
</CORSConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

91
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketEncryption
Service: Amazon Simple Storage Service

Returns the default encryption conﬁguration for an Amazon S3 bucket. For information about the
Amazon S3 default encryption feature, see Amazon S3 Default Bucket Encryption.

To use this operation, you must have permission to perform the s3:GetEncryptionConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources.

The following operations are related to GetBucketEncryption:

• PutBucketEncryption (p. 250)

• DeleteBucketEncryption (p. 47)

Request Syntax

GET /?encryption HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 92)

The name of the bucket from which the server-side encryption conﬁguration is retrieved.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ServerSideEncryptionConfiguration>
<Rule>
<ApplyServerSideEncryptionByDefault>
<KMSMasterKeyID>string</KMSMasterKeyID>
<SSEAlgorithm>string</SSEAlgorithm>
</ApplyServerSideEncryptionByDefault>
</Rule>
...
</ServerSideEncryptionConfiguration>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ServerSideEncryptionConﬁguration (p. 92)

Root level tag for the ServerSideEncryptionConﬁguration parameters.

API Version 2006-03-01

92
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Required: Yes
Rule (p. 92)

Container for information about a particular server-side encryption conﬁguration rule.

Type: Array of ServerSideEncryptionRule (p. 550) data types

Examples
Sample Request: Retrieve the encryption conﬁguration for an S3 bucket

The following example shows a GET /?encryption request.

GET /?encryption HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Wed, 06 Sep 2017 12:00:00 GMT
Authorization: authorization string
Content-Length: length

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: kDmqsuw5FDmgLmxQaUkd9A4NJ/PIiE0c1rAU/ue2Yp60toXs4I5k5fqlwZsA6fV
+wJQCzRRwygQ=
x-amz-request-id: 5D8706FCB2673B7D
Date: Wed, 06 Sep 2017 12:00:00 GMT
Transfer-Encoding: chunked
Server: AmazonS3

<ServerSideEncryptionConfiguration xmlns="http://s3.amazonaws.com/
doc/2006-03-01/">
<Rule>
<ApplyServerSideEncryptionByDefault>
<SSEAlgorithm>aws:kms</SSEAlgorithm>
<KMSMasterKeyID>arn:aws:kms:us-east-1:1234/5678example</KMSMasterKeyID>
</ApplyServerSideEncryptionByDefault>
</Rule>
</ServerSideEncryptionConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

93
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

API Version 2006-03-01

94
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketInventoryConﬁguration
Service: Amazon Simple Storage Service

Returns an inventory configuration (identified by the inventory configuration ID) from the bucket.

To use this operation, you must have permissions to perform the s3:GetInventoryConfiguration
action. The bucket owner has this permission by default and can grant this permission to others. For
more information about permissions, see Permissions Related to Bucket Subresource Operations and
Managing Access Permissions to Your Amazon S3 Resources.

For information about the Amazon S3 inventory feature, see Amazon S3 Inventory.

The following operations are related to GetBucketInventoryConfiguration:

• DeleteBucketInventoryConﬁguration (p. 49)

• ListBucketInventoryConﬁgurations (p. 183)
• PutBucketInventoryConﬁguration (p. 253)

Request Syntax

GET /?inventory&Id=Id HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 95)

The name of the bucket containing the inventory conﬁguration to retrieve.

id (p. 95)

The ID used to identify the inventory conﬁguration.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<InventoryConfiguration>
<Destination>
<S3BucketDestination>
<AccountId>string</AccountId>
<Bucket>string</Bucket>
<Encryption>
<SSE-KMS>
<KeyId>string</KeyId>
</SSE-KMS>
<SSE-S3>
</SSE-S3>
</Encryption>
<Format>string</Format>
<Prefix>string</Prefix>
</S3BucketDestination>

API Version 2006-03-01

95
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

</Destination>
<IsEnabled>boolean</IsEnabled>
<Filter>
<Prefix>string</Prefix>
</Filter>
<Id>string</Id>
<IncludedObjectVersions>string</IncludedObjectVersions>
<OptionalFields>
<Field>string</Field>
</OptionalFields>
<Schedule>
<Frequency>string</Frequency>
</Schedule>
</InventoryConfiguration>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

InventoryConﬁguration (p. 95)

Root level tag for the InventoryConﬁguration parameters.

Required: Yes
Destination (p. 95)

Contains information about where to publish the inventory results.

Type: InventoryDestination (p. 473) data type

Filter (p. 95)

Specifies an inventory filter. The inventory only includes objects that meet the filter's criteria.

Type: InventoryFilter (p. 475) data type

Id (p. 95)

The ID used to identify the inventory conﬁguration.

Type: String
IncludedObjectVersions (p. 95)

Object versions to include in the inventory list. If set to All, the list includes all the object versions,
which adds the version-related ﬁelds VersionId, IsLatest, and DeleteMarker to the list. If set
to Current, the list does not contain these version-related ﬁelds.

Type: String

Valid Values: All | Current

IsEnabled (p. 95)

Speciﬁes whether the inventory is enabled or disabled. If set to True, an inventory list is generated.
If set to False, no inventory list is generated.

Type: Boolean
OptionalFields (p. 95)

Contains the optional ﬁelds that are included in the inventory results.

API Version 2006-03-01

96
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Type: Array of strings

Valid Values: Size | LastModifiedDate | StorageClass | ETag |

Speciﬁes the schedule for generating inventory results.

Type: InventorySchedule (p. 477) data type

Examples
Sample Request: Conﬁgure an inventory report

The following GET request for the bucket examplebucket returns the inventory conﬁguration with the
ID list1.

GET /?inventory&id=list1 HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Mon, 31 Oct 2016 12:00:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A02
Date: Mon, 31 Oct 2016 12:00:00 GMT
Server: AmazonS3
Content-Length: length

<?xml version="1.0" encoding="UTF-8"?>

<InventoryConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>report1</Id>
<IsEnabled>true</IsEnabled>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<AccountId>123456789012</AccountId>
<Bucket>arn:aws:s3:::destination-bucket</Bucket>
<Prefix>prefix1</Prefix>
<SSE-S3/>
</S3BucketDestination>
</Destination>
<Schedule>
<Frequency>Daily</Frequency>
</Schedule>
<Filter>
<Prefix>myprefix/</Prefix>
</Filter>
<IncludedObjectVersions>All</IncludedObjectVersions>
<OptionalFields>
<Field>Size</Field>
<Field>LastModifiedDate</Field>
<Field>ETag</Field>
<Field>StorageClass</Field>

API Version 2006-03-01

97
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<Field>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
<Field>ObjectLockRetainUntilDate</Field>
<Field>ObjectLockMode</Field>
<Field>ObjectLockLegalHoldStatus</Field>
</OptionalFields>
</InventoryConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

98
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketLifecycle
Service: Amazon Simple Storage Service
Important
For an updated version of this API, see GetBucketLifecycleConﬁguration (p. 102). If you
conﬁgured a bucket lifecycle using the filter element, you should see the updated version of
this topic. This topic is provided for backward compatibility.

Returns the lifecycle conﬁguration information set on the bucket. For information about lifecycle
conﬁguration, see Object Lifecycle Management.

To use this operation, you must have permission to perform the s3:GetLifecycleConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources.

GetBucketLifecycle has the following special error:

• Error code: NoSuchLifecycleConfiguration

• Description: The lifecycle conﬁguration does not exist.
• HTTP Status Code: 404 Not Found
• SOAP Fault Code Preﬁx: Client

The following operations are related to GetBucketLifecycle:

• GetBucketLifecycleConﬁguration (p. 102)

• PutBucketLifecycle (p. 258)
• DeleteBucketLifecycle (p. 51)

Request Syntax

GET /?lifecycle HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 99)

The name of the bucket for which to get the lifecycle information.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetBucketLifecycleOutput>
<Rule>
<AbortIncompleteMultipartUpload>
<DaysAfterInitiation>integer</DaysAfterInitiation>

API Version 2006-03-01

99
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

</AbortIncompleteMultipartUpload>
<Expiration>
<Date>timestamp</Date>
<Days>integer</Days>
<ExpiredObjectDeleteMarker>boolean</ExpiredObjectDeleteMarker>
</Expiration>
<ID>string</ID>
<NoncurrentVersionExpiration>
<NoncurrentDays>integer</NoncurrentDays>
</NoncurrentVersionExpiration>
<NoncurrentVersionTransition>
<NoncurrentDays>integer</NoncurrentDays>
<StorageClass>string</StorageClass>
</NoncurrentVersionTransition>
<Prefix>string</Prefix>
<Status>string</Status>
<Transition>
<Date>timestamp</Date>
<Days>integer</Days>
<StorageClass>string</StorageClass>
</Transition>
</Rule>
...
</GetBucketLifecycleOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

GetBucketLifecycleOutput (p. 99)

Root level tag for the GetBucketLifecycleOutput parameters.

Required: Yes
Rule (p. 99)

Container for a lifecycle rule.

Type: Array of Rule (p. 540) data types

Examples
Sample Request: Retrieve a lifecycle subresource

This example is a GET request to retrieve the lifecycle subresource from the speciﬁed bucket, and an
example response with the returned lifecycle conﬁguration.

GET /?lifecycle HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Thu, 15 Nov 2012 00:17:21 GMT
Authorization: signatureValue

Sample Response

HTTP/1.1 200 OK

API Version 2006-03-01

100
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-id-2: ITnGT1y4RyTmXa3rPi4hklTXouTf0hccUjo0iCPjz6FnfIutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991C342C575321
Date: Thu, 15 Nov 2012 00:17:23 GMT
Server: AmazonS3
Content-Length: 358

<?xml version="1.0" encoding="UTF-8"?>

<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<ID>Archive and then delete rule</ID>
<Prefix>projectdocs/</Prefix>
<Status>Enabled</Status>
<Transition>
<Days>30</Days>
<StorageClass>STANDARD_IA</StorageClass>
</Transition>
<Transition>
<Days>365</Days>
<StorageClass>GLACIER</StorageClass>
</Transition>
<Expiration>
<Days>3650</Days>
</Expiration>
</Rule>
</LifecycleConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

101
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketLifecycleConfiguration
Service: Amazon Simple Storage Service
Note
Bucket lifecycle configuration now supports specifying a lifecycle rule using an object key name
prefix, one or more object tags, or a combination of both. Accordingly, this section describes the
latest API. The response describes the new filter element that you can use to specify a filter to
select a subset of objects to which the rule applies. If you are still using previous version of the
lifecycle configuration, it works. For the earlier API description, see GetBucketLifecycle (p. 99).

Returns the lifecycle conﬁguration information set on the bucket. For information about lifecycle
conﬁguration, see Object Lifecycle Management.

To use this operation, you must have permission to perform the s3:GetLifecycleConfiguration
action. The bucket owner has this permission, by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources.

GetBucketLifecycleConfiguration has the following special error:

• Error code: NoSuchLifecycleConfiguration

• Description: The lifecycle conﬁguration does not exist.
• HTTP Status Code: 404 Not Found
• SOAP Fault Code Preﬁx: Client

The following operations are related to DeleteBucketMetricsConfiguration:

• GetBucketLifecycle (p. 99)

• PutBucketLifecycle (p. 258)
• DeleteBucketLifecycle (p. 51)

Request Syntax

GET /?lifecycle HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 102)

The name of the bucket for which to get the lifecycle information.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetBucketLifecycleConfigurationOutput>
<Rule>
<AbortIncompleteMultipartUpload>

API Version 2006-03-01

102
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<DaysAfterInitiation>integer</DaysAfterInitiation>
</AbortIncompleteMultipartUpload>
<Expiration>
<Date>timestamp</Date>
<Days>integer</Days>
<ExpiredObjectDeleteMarker>boolean</ExpiredObjectDeleteMarker>
</Expiration>
<Filter>
<And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
...
</And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</Filter>
<ID>string</ID>
<NoncurrentVersionExpiration>
<NoncurrentDays>integer</NoncurrentDays>
</NoncurrentVersionExpiration>
<NoncurrentVersionTransition>
<NoncurrentDays>integer</NoncurrentDays>
<StorageClass>string</StorageClass>
</NoncurrentVersionTransition>
...
<Prefix>string</Prefix>
<Status>string</Status>
<Transition>
<Date>timestamp</Date>
<Days>integer</Days>
<StorageClass>string</StorageClass>
</Transition>
...
</Rule>
...
</GetBucketLifecycleConfigurationOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

GetBucketLifecycleConﬁgurationOutput (p. 102)

Root level tag for the GetBucketLifecycleConﬁgurationOutput parameters.

Required: Yes
Rule (p. 102)

Container for a lifecycle rule.

Type: Array of LifecycleRule (p. 484) data types

Examples
Sample Request

API Version 2006-03-01

103
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GET /?lifecycle HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Thu, 15 Nov 2012 00:17:21 GMT
Authorization: signatureValue

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4RyTmXa3rPi4hklTXouTf0hccUjo0iCPjz6FnfIutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991C342C575321
Date: Thu, 15 Nov 2012 00:17:23 GMT
Server: AmazonS3
Content-Length: 358

<?xml version="1.0" encoding="UTF-8"?>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

104
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketLocation
Service: Amazon Simple Storage Service

Returns the Region the bucket resides in. You set the bucket's Region using the LocationConstraint
request parameter in a CreateBucket request. For more information, see CreateBucket (p. 27).

To use this implementation of the operation, you must be the bucket owner.

The following operations are related to GetBucketLocation:

• GetObject (p. 138)

• CreateBucket (p. 27)

Request Syntax

GET /?location HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 105)

The name of the bucket for which to get the location.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetBucketLocationOutput>
<LocationConstraint>string</LocationConstraint>
</GetBucketLocationOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

GetBucketLocationOutput (p. 105)

Root level tag for the GetBucketLocationOutput parameters.

Required: Yes
LocationConstraint (p. 105)

Speciﬁes the Region where the bucket resides. For a list of all the Amazon S3 supported location
constraints by Region, see Regions and Endpoints.

Type: String

API Version 2006-03-01

105
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Valid Values: EU | eu-west-1 | us-west-1 | us-west-2 | ap-south-1 | ap-

Examples
Sample Request

The following request returns the Region of the speciﬁed bucket.

GET /?location HTTP/1.1

Host: myBucket.s3.amazonaws.com
Date: Tue, 09 Oct 2007 20:26:04 +0000
Authorization: signatureValue

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

106
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketLogging
Service: Amazon Simple Storage Service

Returns the logging status of a bucket and the permissions users have to view and modify that status. To
use GET, you must be the bucket owner.

The following operations are related to GetBucketLogging:

• CreateBucket (p. 27)

• PutBucketLogging (p. 270)

Request Syntax

GET /?logging HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 107)

The bucket name for which to get the logging information.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetBucketLoggingOutput>
<LoggingEnabled>
<TargetBucket>string</TargetBucket>
<TargetGrants>
<Grant>
<Grantee>
<DisplayName>string</DisplayName>
<EmailAddress>string</EmailAddress>
<ID>string</ID>
<xsi:type>string</xsi:type>
<URI>string</URI>
</Grantee>
<Permission>string</Permission>
</Grant>
</TargetGrants>
<TargetPrefix>string</TargetPrefix>
</LoggingEnabled>
</GetBucketLoggingOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

API Version 2006-03-01

107
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketLoggingOutput (p. 107)

Root level tag for the GetBucketLoggingOutput parameters.

Required: Yes
LoggingEnabled (p. 107)

Describes where logs are stored and the preﬁx that Amazon S3 assigns to all log object keys for a
bucket. For more information, see PUT Bucket logging in the Amazon Simple Storage Service API
Reference.

Type: LoggingEnabled (p. 488) data type

Examples
Sample Request

The following request returns the logging status for mybucket.

GET ?logging HTTP/1.1

Host: mybucket.s3.<Region>.amazonaws.com
Date: Wed, 25 Nov 2009 12:00:00 GMT
Authorization: authorization string

Sample Response: Showing an enabled logging status

HTTP/1.1 200 OK
Date: Wed, 25 Nov 2009 12:00:00 GMT
Connection: close
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<LoggingEnabled>
<TargetBucket>mybucketlogs</TargetBucket>
<TargetPrefix>mybucket-access_log-/</TargetPrefix>
<TargetGrants>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="AmazonCustomerByEmail">
<EmailAddress>[email protected]</EmailAddress>
</Grantee>
<Permission>READ</Permission>
</Grant>
</TargetGrants>
</LoggingEnabled>
</BucketLoggingStatus>

Sample Response: Showing a disabled logging status

HTTP/1.1 200 OK
Date: Wed, 25 Nov 2009 12:00:00 GMT
Connection: close
Server: AmazonS3

API Version 2006-03-01

108
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<?xml version="1.0" encoding="UTF-8"?>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

109
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketMetricsConﬁguration
Service: Amazon Simple Storage Service

Gets a metrics configuration (specified by the metrics configuration ID) from the bucket. Note that this
doesn't include the daily storage metrics.

To use this operation, you must have permissions to perform the s3:GetMetricsConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources.

For information about CloudWatch request metrics for Amazon S3, see Monitoring Metrics with Amazon
CloudWatch.

The following operations are related to GetBucketMetricsConfiguration:

• PutBucketMetricsConﬁguration (p. 274)

• DeleteBucketMetricsConﬁguration (p. 53)
• ListBucketMetricsConﬁgurations (p. 188)
• Monitoring Metrics with Amazon CloudWatch

Request Syntax

GET /?metrics&Id=Id HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 110)

The name of the bucket containing the metrics conﬁguration to retrieve.

id (p. 110)

The ID used to identify the metrics conﬁguration.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<MetricsConfiguration>
<Id>string</Id>
<Filter>
<And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
...
</And>

API Version 2006-03-01

110
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</Filter>
</MetricsConfiguration>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

MetricsConﬁguration (p. 110)

Root level tag for the MetricsConﬁguration parameters.

Required: Yes
Filter (p. 110)

Specifies a metrics configuration filter. The metrics configuration will only include objects that meet
the filter's criteria. A filter must be a prefix, a tag, or a conjunction (MetricsAndOperator).

Type: MetricsFilter (p. 493) data type

Id (p. 110)

The ID used to identify the metrics conﬁguration.

Type: String

Examples
First Sample Request

Retrieve a metrics configuration that filters metrics based on a specified prefix.

GET /?metrics&id=Documents HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT
Authorization: signatureValue

First Sample Response

HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 180

<?xml version="1.0" encoding="UTF-8"?>

<MetricsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>Documents</Id>
<Filter>
<Prefix>documents/</Prefix>

API Version 2006-03-01

111
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

</Filter>
</MetricsConfiguration>

Second Sample Request

Retrieve a metrics configuration that enables metrics for objects that start with a particular prefix and
also have specific tags applied.

GET /?metrics&id=ImportantBlueDocuments HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT
Authorization: signatureValue

Second Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<MetricsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>ImportantBlueDocuments</Id>
<Filter>
<And>
<Prefix>documents/</Prefix>
<Tag>
<Key>priority</Key>
<Value>high</Value>
</Tag>
<Tag>
<Key>class</Key>
<Value>blue</Value>
</Tag>
</And>
</Filter>
</MetricsConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

112
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

API Version 2006-03-01

113
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketNotiﬁcation
Service: Amazon Simple Storage Service

No longer used, see GetBucketNotiﬁcationConﬁguration (p. 116).

Request Syntax

GET /?notification HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 114)

Name of the bucket for which to get the notiﬁcation conﬁguration

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<NotificationConfigurationDeprecated>
<TopicConfiguration>
<Event>string</Event>
<Event>string</Event>
...
<Id>string</Id>
<Topic>string</Topic>
</TopicConfiguration>
<QueueConfiguration>
<Event>string</Event>
<Event>string</Event>
...
<Id>string</Id>
<Queue>string</Queue>
</QueueConfiguration>
<CloudFunctionConfiguration>
<CloudFunction>string</CloudFunction>
<Event>string</Event>
<Event>string</Event>
...
<Id>string</Id>
<InvocationRole>string</InvocationRole>
</CloudFunctionConfiguration>
</NotificationConfigurationDeprecated>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

NotiﬁcationConﬁgurationDeprecated (p. 114)

Root level tag for the NotiﬁcationConﬁgurationDeprecated parameters.

API Version 2006-03-01

114
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Required: Yes
CloudFunctionConﬁguration (p. 114)

Container for specifying the AWS Lambda notiﬁcation conﬁguration.

Type: CloudFunctionConﬁguration (p. 426) data type

QueueConﬁguration (p. 114)

This data type is deprecated. This data type specifies the configuration for publishing messages to
an Amazon Simple Queue Service (Amazon SQS) queue when Amazon S3 detects specified events.

Type: QueueConﬁgurationDeprecated (p. 522) data type

TopicConﬁguration (p. 114)

This data type is deprecated. A container for specifying the configuration for publication of
messages to an Amazon Simple Notification Service (Amazon SNS) topic when Amazon S3 detects
specified events.

Type: TopicConﬁgurationDeprecated (p. 564) data type

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

115
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketNotiﬁcationConﬁguration
Service: Amazon Simple Storage Service

Returns the notiﬁcation conﬁguration of a bucket.

If notiﬁcations are not enabled on the bucket, the operation returns an empty
NotificationConfiguration element.

By default, you must be the bucket owner to read the notification configuration of a bucket. However,
the bucket owner can use a bucket policy to grant permission to other users to read this configuration
with the s3:GetBucketNotification permission.

For more information about setting and reading the notification configuration on a bucket, see Setting
Up Notification of Bucket Events. For more information about bucket policies, see Using Bucket Policies.

The following operation is related to GetBucketNotification:

• PutBucketNotiﬁcation (p. 278)

Request Syntax

GET /?notification HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 116)

Name of the bucket for which to get the notiﬁcation conﬁguration

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<NotificationConfiguration>
<TopicConfiguration>
<Event>string</Event>
...
<Filter>
<S3Key>
<FilterRule>
<Name>string</Name>
<Value>string</Value>
</FilterRule>
...
</S3Key>
</Filter>
<Id>string</Id>
<Topic>string</Topic>
</TopicConfiguration>
...

API Version 2006-03-01

116
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<QueueConfiguration>
<Event>string</Event>
...
<Filter>
<S3Key>
<FilterRule>
<Name>string</Name>
<Value>string</Value>
</FilterRule>
...
</S3Key>
</Filter>
<Id>string</Id>
<Queue>string</Queue>
</QueueConfiguration>
...
<CloudFunctionConfiguration>
<Event>string</Event>
...
<Filter>
<S3Key>
<FilterRule>
<Name>string</Name>
<Value>string</Value>
</FilterRule>
...
</S3Key>
</Filter>
<Id>string</Id>
<CloudFunction>string</CloudFunction>
</CloudFunctionConfiguration>
...
</NotificationConfiguration>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

NotiﬁcationConﬁguration (p. 116)

Root level tag for the NotiﬁcationConﬁguration parameters.

Required: Yes
CloudFunctionConﬁguration (p. 116)

Describes the AWS Lambda functions to invoke and the events for which to invoke them.

Type: Array of LambdaFunctionConﬁguration (p. 480) data types

QueueConﬁguration (p. 116)

The Amazon Simple Queue Service queues to publish messages to and the events for which to
publish messages.

Type: Array of QueueConﬁguration (p. 520) data types

TopicConﬁguration (p. 116)

The topic to which notiﬁcations are sent and the events for which notiﬁcations are generated.

Type: Array of TopicConﬁguration (p. 562) data types

API Version 2006-03-01

117
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Examples
Sample Request

This request returns the notiﬁcation conﬁguration on the bucket

quotes.s3.<Region>.amazonaws.com.

GET ?notification HTTP/1.1

Host: quotes.s3.<Region>.amazonaws.com
Date: Wed, 15 Oct 2014 16:59:03 GMT
Authorization: authorization string

Sample Response

This response returns that the notification configuration for the specified bucket.

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A02
Date: Wed, 15 Oct 2014 16:59:04 GMT
Server: AmazonS3
<?xml version="1.0" encoding="UTF-8"?>

<NotificationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<TopicConfiguration>
<Id>YjVkM2Y0YmUtNGI3NC00ZjQyLWEwNGItNDIyYWUxY2I0N2M4</Id>
<Topic>arn:aws:sns:us-east-1:account-id:s3notificationtopic2</Topic>
<Event>s3:ReducedRedundancyLostObject</Event>
<Event>s3:ObjectCreated:*</Event>
</TopicConfiguration>
</NotificationConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

118
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketPolicy
Service: Amazon Simple Storage Service

Returns the policy of a speciﬁed bucket. If you are using an identity other than the root user of the AWS
account that owns the bucket, the calling identity must have the GetBucketPolicy permissions on the
speciﬁed bucket and belong to the bucket owner's account in order to use this operation.

If you don't have GetBucketPolicy permissions, Amazon S3 returns a 403 Access Denied error. If
you have the correct permissions, but you're not using an identity that belongs to the bucket owner's
account, Amazon S3 returns a 405 Method Not Allowed error.
Important
As a security precaution, the root user of the AWS account that owns a bucket can always use
this operation, even if the policy explicitly denies the root user the ability to perform this action.

For more information about bucket policies, see Using Bucket Policies and User Policies.

The following operation is related to GetBucketPolicy:

• GetObject (p. 138)

Request Syntax

GET /?policy HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 119)

The bucket name for which to get the bucket policy.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200

{ Policy in JSON format }

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

<varlistentry> Policy (p. 119) </varlistentry>

Examples
Sample Request

The following request returns the policy of the speciﬁed bucket.

API Version 2006-03-01

119
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GET ?policy HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: Uuag1LuByru9pO4SAMPLEAtRPfTaOFg==
x-amz-request-id: 656c76696e67SAMPLE57374
Date: Tue, 04 Apr 2010 20:34:56 GMT
Connection: keep-alive
Server: AmazonS3

{
"Version":"2008-10-17",
"Id":"aaaa-bbbb-cccc-dddd",
"Statement" : [
{
"Effect":"Deny",
"Sid":"1",
"Principal" : {
"AWS":["111122223333","444455556666"]
},
"Action":["s3:*"],
"Resource":"arn:aws:s3:::bucket/*"
}
]
}

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

120
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketPolicyStatus
Service: Amazon Simple Storage Service

Retrieves the policy status for an Amazon S3 bucket, indicating whether the bucket is public. In order to
use this operation, you must have the s3:GetBucketPolicyStatus permission. For more information
about Amazon S3 permissions, see Specifying Permissions in a Policy.

For more information about when Amazon S3 considers a bucket public, see The Meaning of "Public".

The following operations are related to GetBucketPolicyStatus:

• Using Amazon S3 Block Public Access

• GetPublicAccessBlock (p. 165)
• PutPublicAccessBlock (p. 339)
• DeletePublicAccessBlock (p. 77)

Request Syntax

GET /?policyStatus HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 121)

The name of the Amazon S3 bucket whose policy status you want to retrieve.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<PolicyStatus>
<IsPublic>boolean</IsPublic>
</PolicyStatus>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

PolicyStatus (p. 121)

Root level tag for the PolicyStatus parameters.

Required: Yes
IsPublic (p. 121)

The policy status for this bucket. TRUE indicates that this bucket is public. FALSE indicates that the
bucket is not public.

API Version 2006-03-01

121
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Type: Boolean

Examples
Sample Request

The following request gets a bucket policy status.

GET /<bucket-name>?policyStatus HTTP/1.1

Host: <bucket-name>.s3.<Region>.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <signatureValue>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

122
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketReplication
Service: Amazon Simple Storage Service

Returns the replication conﬁguration of a bucket.

Note
It can take a while to propagate the put or delete a replication conﬁguration to all Amazon S3
systems. Therefore, a get request soon after put or delete can return a wrong result.

For information about replication conﬁguration, see Replication in the Amazon Simple Storage Service
Developer Guide.

This operation requires permissions for the s3:GetReplicationConfiguration action. For more
information about permissions, see Using Bucket Policies and User Policies.

If you include the Filter element in a replication conﬁguration, you must also include the
DeleteMarkerReplication and Priority elements. The response also returns those elements.

For information about GetBucketReplication errors, see List of Replication-Related Error

Codes (p. 699)

The following operations are related to GetBucketReplication:

• PutBucketReplication (p. 289)

• DeleteBucketReplication (p. 57)

Request Syntax

GET /?replication HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 123)

The bucket name for which to get the replication information.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ReplicationConfiguration>
<Role>string</Role>
<Rule>
<DeleteMarkerReplication>
<Status>string</Status>
</DeleteMarkerReplication>
<Destination>
<AccessControlTranslation>
<Owner>string</Owner>
</AccessControlTranslation>
<Account>string</Account>
<Bucket>string</Bucket>

API Version 2006-03-01

123
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<EncryptionConfiguration>
<ReplicaKmsKeyID>string</ReplicaKmsKeyID>
</EncryptionConfiguration>
<Metrics>
<EventThreshold>
<Minutes>integer</Minutes>
</EventThreshold>
<Status>string</Status>
</Metrics>
<ReplicationTime>
<Status>string</Status>
<Time>
<Minutes>integer</Minutes>
</Time>
</ReplicationTime>
<StorageClass>string</StorageClass>
</Destination>
<ExistingObjectReplication>
<Status>string</Status>
</ExistingObjectReplication>
<Filter>
<And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
...
</And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</Filter>
<ID>string</ID>
<Prefix>string</Prefix>
<Priority>integer</Priority>
<SourceSelectionCriteria>
<SseKmsEncryptedObjects>
<Status>string</Status>
</SseKmsEncryptedObjects>
</SourceSelectionCriteria>
<Status>string</Status>
</Rule>
...
</ReplicationConfiguration>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ReplicationConﬁguration (p. 123)

Root level tag for the ReplicationConﬁguration parameters.

Required: Yes
Role (p. 123)

The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) role that
Amazon S3 assumes when replicating objects. For more information, see How to Set Up Replication
in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

124
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Type: String
Rule (p. 123)

A container for one or more replication rules. A replication conﬁguration must have at least one rule
and can contain a maximum of 1,000 rules.

Type: Array of ReplicationRule (p. 529) data types

Examples
Sample Request: Retrieve replication conﬁguration information

The following GET request retrieves information about the replication conﬁguration set for the
examplebucket bucket:

GET /?replication HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Tue, 10 Feb 2015 00:17:21 GMT
Authorization: authorization string

Sample Response

The following response shows that replication is enabled on the bucket. The empty preﬁx indicates that
Amazon S3 will replicate all objects that are created in the examplebucket bucket. The Destination
element identiﬁes the target bucket where Amazon S3 creates the object replicas, and the storage class
(STANDARD_IA) that Amazon S3 uses when creating replicas.

Amazon S3 assumes the speciﬁed IAM role to replicate objects on behalf of the bucket owner, which is
the AWS account that created the bucket.

HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4RyTmXa3rPi4hklTXouTf0hccUjo0iCPjz6FnfIutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991C342example
Date: Tue, 10 Feb 2015 00:17:23 GMT
Server: AmazonS3
Content-Length: contentlength

<?xml version="1.0" encoding="UTF-8"?>

<ReplicationConfiguration>
<Role>arn:aws:iam::35667example:role/CrossRegionReplicationRoleForS3</Role>
<Rule>
<ID>rule1</ID>
<Status>Enabled</Status>
<Priority>1</Priority>
<DeleteMarkerReplication>
<Status>Disabled</Status>
</DeleteMarkerReplication>
<Filter>
<And>
<Prefix>TaxDocs</Prefix>
<Tag>
<Key>key1</Key>
<Value>value1</Value>
</Tag>
<Tag>
<Key>key1</Key>
<Value>value1</Value>

API Version 2006-03-01

125
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

</Tag>
</And>
</Filter>
<Destination>
<Bucket>arn:aws:s3:::exampletargetbucket</Bucket>
</Destination>
</Rule>
</ReplicationConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

126
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketRequestPayment
Service: Amazon Simple Storage Service

Returns the request payment conﬁguration of a bucket. To use this version of the operation, you must be
the bucket owner. For more information, see Requester Pays Buckets.

The following operations are related to GetBucketRequestPayment:

• ListObjects (p. 202)

Request Syntax

GET /?requestPayment HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 127)

The name of the bucket for which to get the payment request conﬁguration

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetBucketRequestPaymentOutput>
<Payer>string</Payer>
</GetBucketRequestPaymentOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

GetBucketRequestPaymentOutput (p. 127)

Root level tag for the GetBucketRequestPaymentOutput parameters.

Required: Yes
Payer (p. 127)

Speciﬁes who pays for the download and request fees.

Type: String

Valid Values: Requester | BucketOwner

API Version 2006-03-01

127
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Examples
Sample Request

The following request returns the payer for the bucket, colorpictures.

GET ?requestPayment HTTP/1.1

Host: colorpictures.s3.<Region>.amazonaws.com
Date: Wed, 01 Mar 2009 12:00:00 GMT
Authorization: authorization string

Sample Response

This response shows that the bucket is a Requester Pays bucket, meaning the person requesting a
download from this bucket pays the transfer fees.

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2009 12:00:00 GMT
Content-Type: [type]
Content-Length: 0
Connection: close
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

<RequestPaymentConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Payer>Requester</Payer>
</RequestPaymentConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

128
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketTagging
Service: Amazon Simple Storage Service

Returns the tag set associated with the bucket.

To use this operation, you must have permission to perform the s3:GetBucketTagging action. By
default, the bucket owner has this permission and can grant this permission to others.

GetBucketTagging has the following special error:

• Error code: NoSuchTagSetError

• Description: There is no tag set associated with the bucket.

The following operations are related to GetBucketTagging:

• PutBucketTagging (p. 297)

• DeleteBucketTagging (p. 59)

Request Syntax

GET /?tagging HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 129)

The name of the bucket for which to get the tagging information.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetBucketTaggingOutput>
<TagSet>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</TagSet>
</GetBucketTaggingOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

API Version 2006-03-01

129
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketTaggingOutput (p. 129)

Root level tag for the GetBucketTaggingOutput parameters.

Required: Yes
TagSet (p. 129)

Contains the tag set.

Type: Array of Tag (p. 559) data types

Examples
Sample Request

The following request returns the tag set of the speciﬁed bucket.

GET ?tagging HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response

Delete the metric conﬁguration with a speciﬁed ID, which disables the CloudWatch metrics with the
ExampleMetrics value for the FilterId dimension.

HTTP/1.1 200 OK
Date: Wed, 25 Nov 2009 12:00:00 GMT
Connection: close
Server: AmazonS3

<Tagging>
<TagSet>
<Tag>
<Key>Project</Key>
<Value>Project One</Value>
</Tag>
<Tag>
<Key>User</Key>
<Value>jsmith</Value>
</Tag>
</TagSet>
</Tagging>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java

API Version 2006-03-01

130
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for JavaScript

• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

131
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketVersioning
Service: Amazon Simple Storage Service

Returns the versioning state of a bucket.

To retrieve the versioning state of a bucket, you must be the bucket owner.

This implementation also returns the MFA Delete status of the versioning state. If the MFA Delete status
is enabled, the bucket owner must use an authentication device to change the versioning state of the
bucket.

The following operations are related to GetBucketVersioning:

• GetObject (p. 138)

• PutObject (p. 310)
• DeleteObject (p. 63)

Request Syntax

GET /?versioning HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 132)

The name of the bucket for which to get the versioning information.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetBucketVersioningOutput>
<Status>string</Status>
<MfaDelete>string</MfaDelete>
</GetBucketVersioningOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

GetBucketVersioningOutput (p. 132)

Root level tag for the GetBucketVersioningOutput parameters.

Required: Yes

API Version 2006-03-01

132
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

MFADelete (p. 132)

Specifies whether MFA delete is enabled in the bucket versioning configuration. This element is
only returned if the bucket has been configured with MFA delete. If the bucket has never been so
configured, this element is not returned.

Type: String

Valid Values: Enabled | Disabled

Status (p. 132)

The versioning state of the bucket.

Type: String

Valid Values: Enabled | Suspended

Examples
Example

This example returns the versioning state of myBucket.

GET /?versioning HTTP/1.1

Host: myBucket.s3.<Region>.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain

Example

There are three versioning states:

If you enabled versioning on a bucket, the response is:

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
</VersioningConfiguration>

Example

If you suspended versioning on a bucket, the response is:

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Suspended</Status>
</VersioningConfiguration>

Example

If you never enabled (or suspended) versioning on a bucket, the response is:

API Version 2006-03-01

133
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

134
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetBucketWebsite
Service: Amazon Simple Storage Service

Returns the website configuration for a bucket. To host website on Amazon S3, you can configure a
bucket as website by adding a website configuration. For more information about hosting websites, see
Hosting Websites on Amazon S3.

This GET operation requires the S3:GetBucketWebsite permission. By default, only the bucket owner
can read the bucket website conﬁguration. However, bucket owners can allow other users to read the
website conﬁguration by writing a bucket policy granting them the S3:GetBucketWebsite permission.

The following operations are related to DeleteBucketWebsite:

• DeleteBucketWebsite (p. 61)

• PutBucketWebsite (p. 304)

Request Syntax

GET /?website HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 135)

The bucket name for which to get the website conﬁguration.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetBucketWebsiteOutput>
<RedirectAllRequestsTo>
<HostName>string</HostName>
<Protocol>string</Protocol>
</RedirectAllRequestsTo>
<IndexDocument>
<Suffix>string</Suffix>
</IndexDocument>
<ErrorDocument>
<Key>string</Key>
</ErrorDocument>
<RoutingRules>
<RoutingRule>
<Condition>
<HttpErrorCodeReturnedEquals>string</HttpErrorCodeReturnedEquals>
<KeyPrefixEquals>string</KeyPrefixEquals>
</Condition>
<Redirect>
<HostName>string</HostName>
<HttpRedirectCode>string</HttpRedirectCode>
<Protocol>string</Protocol>

API Version 2006-03-01

135
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<ReplaceKeyPrefixWith>string</ReplaceKeyPrefixWith>
<ReplaceKeyWith>string</ReplaceKeyWith>
</Redirect>
</RoutingRule>
</RoutingRules>
</GetBucketWebsiteOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

GetBucketWebsiteOutput (p. 135)

Root level tag for the GetBucketWebsiteOutput parameters.

Required: Yes
ErrorDocument (p. 135)

The name of the error document for the website.

Type: ErrorDocument (p. 462) data type

IndexDocument (p. 135)

The name of the index document for the website.

Type: IndexDocument (p. 468) data type

RedirectAllRequestsTo (p. 135)

Speciﬁes the redirect behavior of all requests to a website endpoint of an Amazon S3 bucket.

Type: RedirectAllRequestsTo (p. 527) data type

RoutingRules (p. 135)

Rules that deﬁne when a redirect is applied and the redirect behavior.

Type: Array of RoutingRule (p. 539) data types

Examples
Sample Request

This request retrieves website conﬁguration on the speciﬁed bucket.

GET ?website HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
Date: Thu, 27 Jan 2011 00:49:20 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:n0Nhek72Ufg/u7Sm5C1dqRLs8XX=

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo

API Version 2006-03-01

136
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-request-id: 3848CD259D811111
Date: Thu, 27 Jan 2011 00:49:26 GMT
Content-Length: 240
Content-Type: application/xml
Transfer-Encoding: chunked
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

<WebsiteConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<IndexDocument>
<Suffix>index.html</Suffix>
</IndexDocument>
<ErrorDocument>
<Key>404.html</Key>
</ErrorDocument>
</WebsiteConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

137
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetObject
Service: Amazon Simple Storage Service

Retrieves objects from Amazon S3. To use GET, you must have READ access to the object. If you grant
READ access to the anonymous user, you can return the object without using an authorization header.

An Amazon S3 bucket has no directory hierarchy such as you would ﬁnd in a typical computer ﬁle
system. You can, however, create a logical hierarchy by using object key names that imply a folder
structure. For example, instead of naming an object sample.jpg, you can name it photos/2006/
February/sample.jpg.

To get an object from such a logical hierarchy, specify the full key name for the object in the GET
operation. For a virtual hosted-style request example, if you have the object photos/2006/February/
sample.jpg, specify the resource as /photos/2006/February/sample.jpg. For a path-style
request example, if you have the object photos/2006/February/sample.jpg in the bucket named
examplebucket, specify the resource as /examplebucket/photos/2006/February/sample.jpg.
For more information about request types, see HTTP Host Header Bucket Speciﬁcation.

To distribute large ﬁles to many people, you can save bandwidth costs by using BitTorrent. For more
information, see Amazon S3 Torrent. For more information about returning the ACL of an object, see
GetObjectAcl (p. 150).

If the object you are retrieving is stored in the GLACIER or DEEP_ARCHIVE storage classes, before you can
retrieve the object you must ﬁrst restore a copy using RestoreObject (p. 343). Otherwise, this operation
returns an InvalidObjectStateError error. For information about restoring archived objects, see
Restoring Archived Objects.

Encryption request headers, like x-amz-server-side-encryption, should not be sent for GET
requests if your object uses server-side encryption with CMKs stored in AWS KMS (SSE-KMS) or server-
side encryption with Amazon S3–managed encryption keys (SSE-S3). If your object does use these types
of keys, you’ll get an HTTP 400 BadRequest error.

• x-amz-server-side-encryption-customer-algorithm
• x-amz-server-side-encryption-customer-key
• x-amz-server-side-encryption-customer-key-MD5

For more information about SSE-C, see Server-Side Encryption (Using Customer-Provided Encryption
Keys).

Assuming you have permission to read object tags (permission for the s3:GetObjectVersionTagging
action), the response also returns the x-amz-tagging-count header that provides the count of
number of tags associated with the object. You can use GetObjectTagging (p. 160) to retrieve the tag
set associated with an object.

Permissions

You need the s3:GetObject permission for this operation. For more information, see Specifying
Permissions in a Policy. If the object you request does not exist, the error Amazon S3 returns depends on
whether you also have the s3:ListBucket permission.

API Version 2006-03-01

138
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Versioning

By default, the GET operation returns the current version of an object. To return a diﬀerent version, use
the versionId subresource.
Note
If the current version of the object is a delete marker, Amazon S3 behaves as if the object was
deleted and includes x-amz-delete-marker: true in the response.

For more information about versioning, see PutBucketVersioning (p. 300).

Overriding Response Header Values

There are times when you want to override certain response header values in a GET response. For
example, you might override the Content-Disposition response header value in your GET request.

You can override values for a set of response headers using the following query parameters. These
response header values are sent only on a successful request, that is, when status code 200 OK is
returned. The set of headers you can override using these parameters is a subset of the headers that
Amazon S3 accepts when you create an object. The response headers that you can override for the
GET response are Content-Type, Content-Language, Expires, Cache-Control, Content-
Disposition, and Content-Encoding. To override these header values in the GET response, you use
the following request parameters.
Note
You must sign the request, either using an Authorization header or a presigned URL, when using
these parameters. They cannot be used with an unsigned (anonymous) request.

• response-content-type
• response-content-language
• response-expires
• response-cache-control
• response-content-disposition
• response-content-encoding

Additional Considerations about Request Headers

If both of the If-Match and If-Unmodified-Since headers are present in the request as follows: If-
Match condition evaluates to true, and; If-Unmodified-Since condition evaluates to false; then,
S3 returns 200 OK and the data requested.

If both of the If-None-Match and If-Modified-Since headers are present in the request as follows:
If-None-Match condition evaluates to false, and; If-Modified-Since condition evaluates to true;
then, S3 returns 304 Not Modiﬁed response code.

For more information about conditional requests, see RFC 7232.

The following operations are related to GetObject:

• ListBuckets (p. 192)

• GetObjectAcl (p. 150)

Request Syntax

GET /Key+?
PartNumber=PartNumber&ResponseCacheControl=ResponseCacheControl&ResponseContentDisposition=ResponseCont
HTTP/1.1

API Version 2006-03-01

139
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Host: Bucket.s3.amazonaws.com
If-Match: IfMatch
If-Modified-Since: IfModifiedSince
If-None-Match: IfNoneMatch
If-Unmodified-Since: IfUnmodifiedSince
Range: Range
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key: SSECustomerKey
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
x-amz-request-payer: RequestPayer

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 139)

The bucket name containing the object.

Return the object only if its entity tag (ETag) is the same as the one speciﬁed, otherwise return a 412
(precondition failed).
If-Modiﬁed-Since (p. 139)

Return the object only if it has been modified since the specified time, otherwise return a 304 (not
modified).
If-None-Match (p. 139)

Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a
304 (not modified).
If-Unmodified-Since (p. 139)

Return the object only if it has not been modiﬁed since the speciﬁed time, otherwise return a 412
(precondition failed).
Key (p. 139)

Key of the object to get.

Length Constraints: Minimum length of 1.

partNumber (p. 139)

Part number of the object being read. This is a positive integer between 1 and 10,000. Eﬀectively
performs a 'ranged' GET request for the part speciﬁed. Useful for downloading just a part of an
object.
Range (p. 139)

Downloads the speciﬁed range bytes of an object. For more information about the HTTP Range
header, see https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
response-cache-control (p. 139)

Sets the Cache-Control header of the response.

API Version 2006-03-01

140
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

response-content-disposition (p. 139)

Sets the Content-Disposition header of the response

response-content-encoding (p. 139)

Sets the Content-Encoding header of the response.

response-content-language (p. 139)

Sets the Content-Language header of the response.

response-content-type (p. 139)

Sets the Content-Type header of the response.

response-expires (p. 139)

Sets the Expires header of the response.

versionId (p. 139)

VersionId used to reference a speciﬁc version of the object.

x-amz-request-payer (p. 139)

Valid Values: requester

x-amz-server-side-encryption-customer-algorithm (p. 139)

Speciﬁes the algorithm to use to when encrypting the object (for example, AES256).
x-amz-server-side-encryption-customer-key (p. 139)

Request Body
The request does not have a request body.

Response Syntax

API Version 2006-03-01

141
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-version-id: VersionId
Cache-Control: CacheControl
Content-Disposition: ContentDisposition
Content-Encoding: ContentEncoding
Content-Language: ContentLanguage
Content-Range: ContentRange
Content-Type: ContentType
Expires: Expires
x-amz-website-redirect-location: WebsiteRedirectLocation
x-amz-server-side-encryption: ServerSideEncryption
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
x-amz-server-side-encryption-aws-kms-key-id: SSEKMSKeyId
x-amz-storage-class: StorageClass
x-amz-request-charged: RequestCharged
x-amz-replication-status: ReplicationStatus
x-amz-mp-parts-count: PartsCount
x-amz-tagging-count: TagCount
x-amz-object-lock-mode: ObjectLockMode
x-amz-object-lock-retain-until-date: ObjectLockRetainUntilDate
x-amz-object-lock-legal-hold: ObjectLockLegalHoldStatus

Body

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

accept-ranges (p. 141)

Indicates that a range of bytes was speciﬁed.

Cache-Control (p. 141)

Speciﬁes caching behavior along the request/reply chain.

Content-Disposition (p. 141)

Speciﬁes presentational information for the object.

Content-Encoding (p. 141)

The language the content is in.

Content-Length (p. 141)

Size of the body in bytes.

Content-Range (p. 141)

The portion of the object returned in the response.

Content-Type (p. 141)

A standard MIME type describing the format of the object data.

ETag (p. 141)

An ETag is an opaque identiﬁer assigned by a web server to a speciﬁc version of a resource found at
a URL.

API Version 2006-03-01

142
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Expires (p. 141)

The date and time at which the object is no longer cacheable.

Last-Modiﬁed (p. 141)

Last modiﬁed date of the object

x-amz-delete-marker (p. 141)

Speciﬁes whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this
response header does not appear in the response.
x-amz-expiration (p. 141)

If the object expiration is conﬁgured (see PUT Bucket lifecycle), the response includes this header.
It includes the expiry-date and rule-id key-value pairs providing object expiration information. The
value of the rule-id is URL encoded.
x-amz-missing-meta (p. 141)

This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen
if you create metadata using an API like SOAP that supports more ﬂexible metadata than the REST
API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
x-amz-mp-parts-count (p. 141)

The count of parts this object has.

x-amz-object-lock-legal-hold (p. 141)

Indicates whether this object has an active legal hold. This ﬁeld is only returned if you have
permission to view an object's legal hold status.

Valid Values: ON | OFF

x-amz-object-lock-mode (p. 141)

The Object Lock mode currently in place for this object.

Valid Values: GOVERNANCE | COMPLIANCE

x-amz-object-lock-retain-until-date (p. 141)

The date and time when this object's Object Lock will expire.
x-amz-replication-status (p. 141)

Amazon S3 can return this if your request involves a bucket that is either a source or destination in a
replication rule.

Valid Values: COMPLETE | PENDING | FAILED | REPLICA

x-amz-request-charged (p. 141)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

x-amz-restore (p. 141)

Provides information about object restoration operation and expiration time of the restored object
copy.
x-amz-server-side-encryption (p. 141)

The server-side encryption algorithm used when storing this object in Amazon S3 (for example,
AES256, aws:kms).

Valid Values: AES256 | aws:kms

API Version 2006-03-01

143
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-server-side-encryption-aws-kms-key-id (p. 141)

Provides storage class information of the object. Amazon S3 returns this header for all objects
except for Standard storage class objects.

Valid Values: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA |

INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE
x-amz-tagging-count (p. 141)

The number of tags, if any, on the object.

x-amz-version-id (p. 141)

Version of the object.

x-amz-website-redirect-location (p. 141)

The following data is returned in binary format by the service.

<varlistentry> Body (p. 141) </varlistentry>
The speciﬁed key does not exist.

Examples
Sample Request

The following request returns the object my-image.jpg.

GET /my-image.jpg HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Mon, 3 Oct 2016 22:32:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
Date: Mon, 3 Oct 2016 22:32:00 GMT
Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT

API Version 2006-03-01

144
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234

[434234 bytes of object data]

Sample Response: Object with associated tags

If the object had tags associated with it, Amazon S3 returns the x-amz-tagging-count header with
tag count.

[434234 bytes of object data]

Sample Response: Object with an expiration

If the object had expiration set using lifecycle conﬁguration, you get the following response with the x-
amz-expiration header.

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT
x-amz-expiration: expiry-date="Fri, 23 Dec 2012 00:00:00 GMT", rule-
id="picture-deletion-rule"
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234
Content-Type: text/plain

[434234 bytes of object data]

Sample Response if an Object Is Archived in Glacier

An object archived in Amazon S3 Glacier must ﬁrst be restored before you can access it. If you attempt to
access a Glacier object without restoring it, Amazon S3 returns the following error.

HTTP/1.1 403 Forbidden

x-amz-request-id: CD4BD8A1310A11B3
x-amz-id-2: m9RDbQU0+RRBTjOUN1ChQ1eqMUnr9dv8b+KP6I2gHfRJZSTSrMCoRP8RtPRzX9mb
Content-Type: application/xml
Date: Mon, 12 Nov 2012 23:53:21 GMT
Server: AmazonS3
Content-Length: 231

<Error>
<Code>InvalidObjectState</Code>
<Message>The operation is not valid for the object's storage class</Message>

API Version 2006-03-01

145
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<RequestId>9FEFFF118E15B86F</RequestId>
<HostId>WVQ5kzhiT+oiUfDCOiOYv8W4Tk9eNcxWi/MK+hTS/av34Xy4rBU3zsavf0aaaaa</
HostId>
</Error>

Sample Response if the Latest Object Is a Delete Marker

Notice that the delete marker returns a 404 Not Found error.

HTTP/1.1 404 Not Found

x-amz-request-id: 318BC8BC148832E5
x-amz-id-2: eftixk72aD6Ap51Tnqzj7UDNEHGran
x-amz-version-id: 3GL4kqtJlcpXroDTDm3vjVBH40Nr8X8g
x-amz-delete-marker: true
Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Type: text/plain
Connection: close
Server: AmazonS3

Sample Request: Getting a speciﬁed version of an object

The following request returns the speciﬁed version of an object.

GET /myObject?versionId=3/L4kqtJlcpXroDTDmpUMLUo HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response: To a versioned object GET request

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap54OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
x-amz-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3QBpUMLUo
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234
Content-Type: text/plain
Connection: close
Server: AmazonS3
[434234 bytes of object data]

Sample Request: Parameters altering response header values

The following request speciﬁes all the query string parameters in a GET request overriding the response
header values.

API Version 2006-03-01

146
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-date: Sun, 19 Dec 2010 01:53:44 GMT

Accept: */*
Authorization: AWS AKIAIOSFODNN7EXAMPLE:aaStE6nKnw8ihhiIdReoXYlMamW=

Sample Response: With overridden response header values

The following request speciﬁes all the query string parameters in a GET request overriding the response
header values.

HTTP/1.1 200 OK
x-amz-id-2: SIidWAK3hK+Il3/Qqiu1ZKEuegzLAAspwsgwnwygb9GgFseeFHL5CII8NXSrfWW2
x-amz-request-id: 881B1CBD9DF17WA1
Date: Sun, 19 Dec 2010 01:54:01 GMT
x-amz-meta-param1: value 1
x-amz-meta-param2: value 2
Cache-Control: No-cache
Content-Language: mi, en
Expires: Thu, 01 Dec 1994 16:00:00 GMT
Content-Disposition: attachment; filename=testing.txt
Content-Encoding: x-gzip
Last-Modified: Fri, 17 Dec 2010 18:10:41 GMT
ETag: "0332bee1a7bf845f176c5c0d1ae7cf07"
Accept-Ranges: bytes
Content-Type: text/plain
Content-Length: 22
Server: AmazonS3

[object data not shown]

Sample Request: Range header

The following request speciﬁes the HTTP Range header to retrieve the ﬁrst 10 bytes of an object. For
more information about the HTTP Range header, see https://www.w3.org/Protocols/rfc2616/rfc2616-
sec14.html#sec14.35.

Amazon S3 doesn't support retrieving multiple ranges of data per GET request.

GET /example-object HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
x-amz-date: Fri, 28 Jan 2011 21:32:02 GMT
Range: bytes=0-9
Authorization: AWS AKIAIOSFODNN7EXAMPLE:Yxg83MZaEgh3OZ3l0rLo5RTX11o=
Sample Response with Specified Range of the Object Bytes

Sample Response

In the following sample response, note that the header values are set to the values speciﬁed in the true
request.

HTTP/1.1 206 Partial Content

API Version 2006-03-01

147
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ETag: "b2419b1e3fd45d596ee22bdf62aaaa2f"
Accept-Ranges: bytes
Content-Range: bytes 0-9/443
Content-Type: text/plain
Content-Length: 10
Server: AmazonS3

[10 bytes of object data]

Sample: Get an object stored using server-side encryption with customer-provided encryption
keys

If an object is stored in Amazon S3 using server-side encryption with customer-provided encryption

keys, Amazon S3 needs encryption information so that it can decrypt the object before sending it to
you in response to a GET request. You provide the encryption information in your GET request using the
relevant headers, as shown in the following example request.

GET /example-object HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com

Accept: */*
Authorization:authorization string
Date: Wed, 28 May 2014 19:24:44 +0000
x-amz-server-side-encryption-customer-
key:g0lCfA3Dv40jZz5SQJ1ZukLRFqtI5WorC/8SEKEXAMPLE
x-amz-server-side-encryption-customer-key-MD5:ZjQrne1X/iTcskbY2m3example
x-amz-server-side-encryption-customer-algorithm:AES256

Sample Response

The following sample response shows some of the response headers Amazon S3 returns. Note that it
includes the encryption information in the response.

HTTP/1.1 200 OK
x-amz-id-2: ka5jRm8X3N12ZiY29Z989zg2tNSJPMcK+to7jNjxImXBbyChqc6tLAv+sau7Vjzh
x-amz-request-id: 195157E3E073D3F9
Date: Wed, 28 May 2014 19:24:45 GMT
Last-Modified: Wed, 28 May 2014 19:21:01 GMT
ETag: "c12022c9a3c6d3a28d29d90933a2b096"
x-amz-server-side-encryption-customer-algorithm: AES256
x-amz-server-side-encryption-customer-key-MD5: ZjQrne1X/iTcskbY2m3example

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3

API Version 2006-03-01

148
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for Python

• AWS SDK for Ruby V2

API Version 2006-03-01

149
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetObjectAcl
Service: Amazon Simple Storage Service

Returns the access control list (ACL) of an object. To use this operation, you must have READ_ACP access
to the object.

Versioning

By default, GET returns ACL information about the current version of an object. To return ACL
information about a diﬀerent version, use the versionId subresource.

The following operations are related to GetObjectAcl:

• GetObject (p. 138)

• DeleteObject (p. 63)
• PutObject (p. 310)

Request Syntax

GET /{Key+}?acl&VersionId=VersionId HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-request-payer: RequestPayer

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 150)

The bucket name that contains the object for which to get the ACL information.

The key of the object for which to get the ACL information.

Length Constraints: Minimum length of 1.

versionId (p. 150)

VersionId used to reference a speciﬁc version of the object.

x-amz-request-payer (p. 150)

Valid Values: requester

Request Body
The request does not have a request body.

API Version 2006-03-01

150
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Response Syntax
HTTP/1.1 200
x-amz-request-charged: RequestCharged
<?xml version="1.0" encoding="UTF-8"?>
<GetObjectAclOutput>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
<AccessControlList>
<Grant>
<Grantee>
<DisplayName>string</DisplayName>
<EmailAddress>string</EmailAddress>
<ID>string</ID>
<xsi:type>string</xsi:type>
<URI>string</URI>
</Grantee>
<Permission>string</Permission>
</Grant>
</AccessControlList>
</GetObjectAclOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

x-amz-request-charged (p. 151)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

The following data is returned in XML format by the service.

GetObjectAclOutput (p. 151)

Root level tag for the GetObjectAclOutput parameters.

Required: Yes
Grants (p. 151)

A list of grants.

Type: Array of Grant (p. 466) data types

Owner (p. 151)

Container for the bucket owner's display name and ID.

Type: Owner (p. 512) data type

The speciﬁed key does not exist.

Examples
Sample Request
The following request returns information, including the ACL, of the object my-image.jpg.

API Version 2006-03-01

151
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GET /my-image.jpg?acl HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
x-amz-version-id: 4HL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nrjfkd
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
Content-Length: 124
Content-Type: text/plain
Connection: close
Server: AmazonS3

<AccessControlPolicy>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser">
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</
ID>
<DisplayName>[email protected]</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>

Sample Request: Getting the ACL of the speciﬁc version of an object

The following request returns information, including the ACL, of the speciﬁed version of the object, my-
image.jpg.

GET /my-image.jpg?versionId=3/L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo&acl HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response: Showing the ACL of the speciﬁc version

API Version 2006-03-01

152
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
Content-Length: 124
Content-Type: text/plain
Connection: close
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

153
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetObjectLegalHold
Service: Amazon Simple Storage Service

Gets an object's current Legal Hold status. For more information, see Locking Objects.

Request Syntax

GET /{Key+}?legal-hold&VersionId=VersionId HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-request-payer: RequestPayer

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 154)

The bucket name containing the object whose Legal Hold status you want to retrieve.

The key name for the object whose Legal Hold status you want to retrieve.

Length Constraints: Minimum length of 1.

versionId (p. 154)

The version ID of the object whose Legal Hold status you want to retrieve.
x-amz-request-payer (p. 154)

Valid Values: requester

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<LegalHold>
<Status>string</Status>
</LegalHold>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

API Version 2006-03-01

154
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

The following data is returned in XML format by the service.

LegalHold (p. 154)

Root level tag for the LegalHold parameters.

Required: Yes
Status (p. 154)

Indicates whether the speciﬁed object has a Legal Hold in place.

Type: String

Valid Values: ON | OFF

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

155
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetObjectLockConﬁguration
Service: Amazon Simple Storage Service

Gets the Object Lock configuration for a bucket. The rule specified in the Object Lock configuration
will be applied by default to every new object placed in the specified bucket. For more information, see
Locking Objects.

Request Syntax

GET /?object-lock HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 156)

The bucket whose Object Lock conﬁguration you want to retrieve.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ObjectLockConfiguration>
<ObjectLockEnabled>string</ObjectLockEnabled>
<Rule>
<DefaultRetention>
<Days>integer</Days>
<Mode>string</Mode>
<Years>integer</Years>
</DefaultRetention>
</Rule>
</ObjectLockConfiguration>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ObjectLockConﬁguration (p. 156)

Root level tag for the ObjectLockConﬁguration parameters.

Required: Yes
ObjectLockEnabled (p. 156)

Indicates whether this bucket has an Object Lock conﬁguration enabled.

Type: String

Valid Values: Enabled

API Version 2006-03-01

156
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Rule (p. 156)

The Object Lock rule in place for the speciﬁed object.

Type: ObjectLockRule (p. 507) data type

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

157
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetObjectRetention
Service: Amazon Simple Storage Service

Retrieves an object's retention settings. For more information, see Locking Objects.

Request Syntax

GET /{Key+}?retention&VersionId=VersionId HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-request-payer: RequestPayer

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 158)

The bucket name containing the object whose retention settings you want to retrieve.

The key name for the object whose retention settings you want to retrieve.

Length Constraints: Minimum length of 1.

versionId (p. 158)

The version ID for the object whose retention settings you want to retrieve.
x-amz-request-payer (p. 158)

Valid Values: requester

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<Retention>
<Mode>string</Mode>
<RetainUntilDate>timestamp</RetainUntilDate>
</Retention>

API Version 2006-03-01

158
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

Retention (p. 158)

Root level tag for the Retention parameters.

Required: Yes
Mode (p. 158)

Indicates the Retention mode for the speciﬁed object.

Type: String

Valid Values: GOVERNANCE | COMPLIANCE

RetainUntilDate (p. 158)

The date on which this Object Lock Retention will expire.

Type: Timestamp

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

159
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetObjectTagging
Service: Amazon Simple Storage Service

Returns the tag-set of an object. You send the GET request against the tagging subresource associated
with the object.

To use this operation, you must have permission to perform the s3:GetObjectTagging action. By
default, the GET operation returns information about current version of an object. For a versioned
bucket, you can have multiple versions of an object in your bucket. To retrieve tags of any other version,
use the versionId query parameter. You also need permission for the s3:GetObjectVersionTagging
action.

By default, the bucket owner has this permission and can grant this permission to others.

For information about the Amazon S3 object tagging feature, see Object Tagging.

The following operation is related to GetObjectTagging:

• PutObjectTagging (p. 336)

Request Syntax

GET /{Key+}?tagging&VersionId=VersionId HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 160)

The bucket name containing the object for which to get the tagging information.

Object key for which to get the tagging information.

Length Constraints: Minimum length of 1.

versionId (p. 160)

The versionId of the object for which to get the tagging information.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
x-amz-version-id: VersionId

API Version 2006-03-01

160
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<?xml version="1.0" encoding="UTF-8"?>

<GetObjectTaggingOutput>
<TagSet>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</TagSet>
</GetObjectTaggingOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

x-amz-version-id (p. 160)

The versionId of the object for which you got the tagging information.

The following data is returned in XML format by the service.

GetObjectTaggingOutput (p. 160)

Root level tag for the GetObjectTaggingOutput parameters.

Required: Yes
TagSet (p. 160)

Contains the tag set.

Type: Array of Tag (p. 559) data types

Examples
Sample Request

The following request returns the tag set of the speciﬁed object.

GET /example-object?tagging HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Thu, 22 Sep 2016 21:33:08 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
Date: Thu, 22 Sep 2016 21:33:08 GMT
Connection: close
Server: AmazonS3
<?xml version="1.0" encoding="UTF-8"?>
<Tagging xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<TagSet>
<Tag>
<Key>tag1</Key>
<Value>val1</Value>

API Version 2006-03-01

161
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

</Tag>
<Tag>
<Key>tag2</Key>
<Value>val2</Value>
</Tag>
</TagSet>
</Tagging>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

162
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetObjectTorrent
Service: Amazon Simple Storage Service

Return torrent ﬁles from a bucket. BitTorrent can save you bandwidth when you're distributing large
ﬁles. For more information about BitTorrent, see Amazon S3 Torrent.
Note
You can get torrent only for objects that are less than 5 GB in size and that are not encrypted
using server-side encryption with customer-provided encryption key.

To use GET, you must have READ access to the object.

The following operation is related to GetObjectTorrent:

• GetObject (p. 138)

Request Syntax

GET /{Key+}?torrent HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-request-payer: RequestPayer

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 163)

The name of the bucket containing the object for which to get the torrent ﬁles.
Key (p. 163)

The object key for which to get the information.

Length Constraints: Minimum length of 1.

x-amz-request-payer (p. 163)

Valid Values: requester

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
x-amz-request-charged: RequestCharged

Body

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

API Version 2006-03-01

163
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

The response returns the following HTTP headers.

x-amz-request-charged (p. 163)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

The following data is returned in binary format by the service.

Examples
Getting torrent ﬁles in a bucket

This example retrieves the Torrent ﬁle for the Nelson object in the quotes bucket.

GET /quotes/Nelson?torrent HTTP/1.0

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-request-id: 7CD745EBB7AB5ED9
Date: Wed, 25 Nov 2009 12:00:00 GMT
Content-Disposition: attachment; filename=Nelson.torrent;
Content-Type: application/x-bittorrent
Content-Length: 537
Server: AmazonS3

<body: a Bencoded dictionary as defined by the BitTorrent specification>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

164
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GetPublicAccessBlock
Service: Amazon Simple Storage Service

Retrieves the PublicAccessBlock configuration for an Amazon S3 bucket. To use this operation, you
must have the s3:GetBucketPublicAccessBlock permission. For more information about Amazon
S3 permissions, see Specifying Permissions in a Policy.
Important
When Amazon S3 evaluates the PublicAccessBlock configuration for a bucket or an object, it
checks the PublicAccessBlock configuration for both the bucket (or the bucket that contains
the object) and the bucket owner's account. If the PublicAccessBlock settings are different
between the bucket and the account, Amazon S3 uses the most restrictive combination of the
bucket-level and account-level settings.

For more information about when Amazon S3 considers a bucket or an object public, see The Meaning of
"Public".

The following operations are related to GetPublicAccessBlock:

• Using Amazon S3 Block Public Access

• PutPublicAccessBlock (p. 339)
• GetPublicAccessBlock (p. 165)
• DeletePublicAccessBlock (p. 77)

Request Syntax

GET /?publicAccessBlock HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 165)

The name of the Amazon S3 bucket whose PublicAccessBlock conﬁguration you want to
retrieve.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<PublicAccessBlockConfiguration>
<BlockPublicAcls>boolean</BlockPublicAcls>
<IgnorePublicAcls>boolean</IgnorePublicAcls>
<BlockPublicPolicy>boolean</BlockPublicPolicy>
<RestrictPublicBuckets>boolean</RestrictPublicBuckets>
</PublicAccessBlockConfiguration>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

API Version 2006-03-01

165
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

The following data is returned in XML format by the service.

PublicAccessBlockConﬁguration (p. 165)

Root level tag for the PublicAccessBlockConﬁguration parameters.

Required: Yes
BlockPublicAcls (p. 165)

Speciﬁes whether Amazon S3 should block public access control lists (ACLs) for this bucket and
objects in this bucket. Setting this element to TRUE causes the following behavior:
• PUT Bucket acl and PUT Object acl calls fail if the speciﬁed ACL is public.
• PUT Object calls fail if the request includes a public ACL.
• PUT Bucket calls fail if the request includes a public ACL.

Enabling this setting doesn't aﬀect existing policies or ACLs.

Type: Boolean
BlockPublicPolicy (p. 165)

Speciﬁes whether Amazon S3 should block public bucket policies for this bucket. Setting this
element to TRUE causes Amazon S3 to reject calls to PUT Bucket policy if the speciﬁed bucket policy
allows public access.

Enabling this setting doesn't aﬀect existing bucket policies.

Type: Boolean
IgnorePublicAcls (p. 165)

Speciﬁes whether Amazon S3 should ignore public ACLs for this bucket and objects in this bucket.
Setting this element to TRUE causes Amazon S3 to ignore all public ACLs on this bucket and objects
in this bucket.

Enabling this setting doesn't aﬀect the persistence of any existing ACLs and doesn't prevent new
public ACLs from being set.

Type: Boolean
RestrictPublicBuckets (p. 165)

Speciﬁes whether Amazon S3 should restrict public bucket policies for this bucket. Setting this
element to TRUE restricts access to this bucket to only AWS services and authorized users within this
account if the bucket has a public policy.

Enabling this setting doesn't aﬀect previously stored bucket policies, except that public and cross-
account access within any public bucket policy, including non-public delegation to speciﬁc accounts,
is blocked.

Type: Boolean

Examples
Sample Request

The following request gets a bucket PublicAccessBlock conﬁguration.

GET /<bucket-name>?publicAccessBlock HTTP/1.1

API Version 2006-03-01

166
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Host: <bucket-name>.s3.<Region>.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <signatureValue>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0

<PublicAccessBlockConfiguration>
<BlockPublicAcls>TRUE</BlockPublicAcls>
<IgnorePublicAcls>FALSE</IgnorePublicAcls>
<BlockPublicPolicy>FALSE</BlockPublicPolicy>
<RestrictPublicBuckets>FALSE</RestrictPublicBuckets>
</PublicAccessBlockConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

167
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

HeadBucket
Service: Amazon Simple Storage Service

This operation is useful to determine if a bucket exists and you have permission to access it. The
operation returns a 200 OK if the bucket exists and you have permission to access it. Otherwise, the
operation might return responses such as 404 Not Found and 403 Forbidden.

To use this operation, you must have permissions to perform the s3:ListBucket action. The bucket
owner has this permission by default and can grant this permission to others. For more information
about permissions, see Permissions Related to Bucket Subresource Operations and Managing Access
Permissions to Your Amazon S3 Resources.

Request Syntax

HEAD / HTTP/1.1
Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 168)

The bucket name.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
The speciﬁed bucket does not exist.

Examples
Sample Request

HEAD / HTTP/1.1
Date: Fri, 10 Feb 2012 21:34:55 GMT
Authorization: authorization string
Host: myawsbucket.s3.amazonaws.com
Connection: Keep-Alive

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: JuKZqmXuiwFeDQxhD7M8KtsKobSzWA1QEjLbTMTagkKdBX2z7Il/jGhDeJ3j6s80

API Version 2006-03-01

168
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-request-id: 32FE2CEB32F5EE25
Date: Fri, 10 2012 21:34:56 GMT
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

169
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

HeadObject
Service: Amazon Simple Storage Service

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.

A HEAD request has the same options as a GET operation on an object. The response is identical to the
GET response except that there is no response body.

If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-
C) when you store the object in Amazon S3, then when you retrieve the metadata from 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

For more information about SSE-C, see Server-Side Encryption (Using Customer-Provided Encryption
Keys).
Note
Encryption request headers, like x-amz-server-side-encryption, should not be sent for
GET requests if your object uses server-side encryption with CMKs stored in AWS KMS (SSE-KMS)
or server-side encryption with Amazon S3–managed encryption keys (SSE-S3). If your object
does use these types of keys, you’ll get an HTTP 400 BadRequest error.

Request headers are limited to 8 KB in size. For more information, see Common Request Headers.

Consider the following when using request headers:

• Consideration 1 – If both of the If-Match and If-Unmodified-Since headers are present in the
request as follows:
• If-Match condition evaluates to true, and;
• If-Unmodified-Since condition evaluates to false;

Then Amazon S3 returns 200 OK and the data requested.

• Consideration 2 – If both of the If-None-Match and If-Modified-Since headers are present in
the request as follows:
• If-None-Match condition evaluates to false, and;
• If-Modified-Since condition evaluates to true;

Then Amazon S3 returns the 304 Not Modified response code.

For more information about conditional requests, see RFC 7232.

Permissions

• If you have the s3:ListBucket permission on the bucket, Amazon S3 returns an HTTP status code
404 ("no such key") error.
• If you don’t have the s3:ListBucket permission, Amazon S3 returns an HTTP status code 403
("access denied") error.

API Version 2006-03-01

170
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

The following operation is related to HeadObject:

• GetObject (p. 138)

Request Syntax

HEAD /Key+?PartNumber=PartNumber&VersionId=VersionId HTTP/1.1

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 171)

The name of the bucket containing the object.

If-Match (p. 171)

Return the object only if its entity tag (ETag) is the same as the one speciﬁed, otherwise return a 412
(precondition failed).
If-Modiﬁed-Since (p. 171)

Return the object only if it has been modified since the specified time, otherwise return a 304 (not
modified).
If-None-Match (p. 171)

Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a
304 (not modified).
If-Unmodified-Since (p. 171)

Return the object only if it has not been modiﬁed since the speciﬁed time, otherwise return a 412
(precondition failed).
Key (p. 171)

The object key.

Length Constraints: Minimum length of 1.

partNumber (p. 171)

Part number of the object being read. This is a positive integer between 1 and 10,000. Eﬀectively
performs a 'ranged' HEAD request for the part speciﬁed. Useful querying about the size of the part
and the number of parts in this object.
Range (p. 171)

Downloads the speciﬁed range bytes of an object. For more information about the HTTP Range
header, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.

API Version 2006-03-01

171
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

versionId (p. 171)

VersionId used to reference a speciﬁc version of the object.

x-amz-request-payer (p. 171)

Valid Values: requester

x-amz-server-side-encryption-customer-algorithm (p. 171)

Speciﬁes the algorithm to use to when encrypting the object (for example, AES256).
x-amz-server-side-encryption-customer-key (p. 171)

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
x-amz-delete-marker: DeleteMarker
accept-ranges: AcceptRanges
x-amz-expiration: Expiration
x-amz-restore: Restore
Last-Modified: LastModified
Content-Length: ContentLength
ETag: ETag
x-amz-missing-meta: MissingMeta
x-amz-version-id: VersionId
Cache-Control: CacheControl
Content-Disposition: ContentDisposition
Content-Encoding: ContentEncoding
Content-Language: ContentLanguage
Content-Type: ContentType
Expires: Expires
x-amz-website-redirect-location: WebsiteRedirectLocation
x-amz-server-side-encryption: ServerSideEncryption
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
x-amz-server-side-encryption-aws-kms-key-id: SSEKMSKeyId
x-amz-storage-class: StorageClass
x-amz-request-charged: RequestCharged
x-amz-replication-status: ReplicationStatus
x-amz-mp-parts-count: PartsCount
x-amz-object-lock-mode: ObjectLockMode
x-amz-object-lock-retain-until-date: ObjectLockRetainUntilDate

API Version 2006-03-01

172
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-object-lock-legal-hold: ObjectLockLegalHoldStatus

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

accept-ranges (p. 172)

Indicates that a range of bytes was speciﬁed.

Cache-Control (p. 172)

Speciﬁes caching behavior along the request/reply chain.

Content-Disposition (p. 172)

Speciﬁes presentational information for the object.

Content-Encoding (p. 172)

The language the content is in.

Content-Length (p. 172)

Size of the body in bytes.

Content-Type (p. 172)

A standard MIME type describing the format of the object data.

ETag (p. 172)

An ETag is an opaque identiﬁer assigned by a web server to a speciﬁc version of a resource found at
a URL.
Expires (p. 172)

The date and time at which the object is no longer cacheable.

Last-Modiﬁed (p. 172)

Last modiﬁed date of the object

x-amz-delete-marker (p. 172)

Speciﬁes whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this
response header does not appear in the response.
x-amz-expiration (p. 172)

The count of parts this object has.

API Version 2006-03-01

173
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-object-lock-legal-hold (p. 172)

Specifies whether a legal hold is in effect for this object. This header is only returned if the requester
has the s3:GetObjectLegalHold permission. This header is not returned if the specified version
of this object has never had a legal hold applied. For more information about S3 Object Lock, see
Object Lock.

Valid Values: ON | OFF

x-amz-object-lock-mode (p. 172)

The Object Lock mode, if any, that's in eﬀect for this object. This header is only returned if the
requester has the s3:GetObjectRetention permission. For more information about S3 Object
Lock, see Object Lock.

Valid Values: GOVERNANCE | COMPLIANCE

x-amz-object-lock-retain-until-date (p. 172)

The date and time when the Object Lock retention period expires. This header is only returned if the
requester has the s3:GetObjectRetention permission.
x-amz-replication-status (p. 172)

Amazon S3 can return this header if your request involves a bucket that is either a source or
destination in a replication rule.

In replication, you have a source bucket on which you conﬁgure replication and destination bucket
where Amazon S3 stores object replicas. When you request an object (GetObject) or object
metadata (HeadObject) from these buckets, Amazon S3 will return the x-amz-replication-
status header in the response as follows:
• If requesting an object from the source bucket — Amazon S3 will return the x-amz-
replication-status header if the object in your request is eligible for replication.

For example, suppose that in your replication configuration, you specify object prefix TaxDocs
requesting Amazon S3 to replicate objects with key prefix TaxDocs. Any objects you upload with
this key name prefix, for example TaxDocs/document1.pdf, are eligible for replication. For
any object request with this key name prefix, Amazon S3 will return the x-amz-replication-
status header with value PENDING, COMPLETED or FAILED indicating object replication status.
• If requesting an object from the destination bucket — Amazon S3 will return the x-amz-
replication-status header with value REPLICA if the object in your request is a replica that
Amazon S3 created.

For more information, see Replication.

Valid Values: COMPLETE | PENDING | FAILED | REPLICA

x-amz-request-charged (p. 172)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

x-amz-restore (p. 172)

If the object is an archived object (an object whose storage class is GLACIER), the response includes
this header if either the archive restoration is in progress (see RestoreObject (p. 343) or an archive
copy is already restored.

If an archive copy is already restored, the header value indicates when Amazon S3 is scheduled to
delete the object copy. For example:

x-amz-restore: ongoing-request="false", expiry-date="Fri, 23 Dec 2012

00:00:00 GMT"

API Version 2006-03-01

174
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

If the object restoration is in progress, the header returns the value ongoing-request="true".

For more information about archiving objects, see Transitioning Objects: General Considerations.
x-amz-server-side-encryption (p. 172)

If the object is stored using server-side encryption either with an AWS KMS customer master key
(CMK) or an Amazon S3-managed encryption key, the response includes this header with the value
of the server-side encryption algorithm used when storing this object in Amazon S3 (for example,
AES256, aws:kms).

Valid Values: AES256 | aws:kms

x-amz-server-side-encryption-aws-kms-key-id (p. 172)

Provides storage class information of the object. Amazon S3 returns this header for all objects
except for Standard storage class objects.

For more information, see Storage Classes.

Valid Values: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA |

INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE
x-amz-version-id (p. 172)

Version of the object.

x-amz-website-redirect-location (p. 172)

The speciﬁed key does not exist.

Examples
Sample Request

The following request returns the metadata of an object.

HEAD /my-image.jpg HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:02236Q3V0RonhpaBX5sCYVf1bNRuU=

API Version 2006-03-01

175
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Sample Response
Delete the metric conﬁguration with a speciﬁed ID, which disables theCloudWatch metrics with the
ExampleMetrics value for the FilterId dimension.

HTTP/1.1 200 OK
x-amz-id-2: ef8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC143432E5
x-amz-version-id: 3HL4kqtJlcpXroDTDmjVBH40Nrjfkd
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234
Content-Type: text/plain
Connection: close
Server: AmazonS3

Sample Response: With an expiration tag

If the object is scheduled to expire according to a lifecycle conﬁguration set on the bucket, the response
returns the x-amz-expiration tag with information about when Amazon S3 will delete the object. For
more information, see Transitioning Objects: General Considerations.

HTTP/1.1 200 OK
x-amz-id-2: azQRZtQJ2m1P8R+TIsG9h0VuC/DmiSJmjXUMq7snk+LKSJeurtmfzSlGhR46GzSJ
x-amz-request-id: 0EFF61CCE3F24A26
Date: Mon, 17 Dec 2012 02:26:39 GMT
Last-Modified: Mon, 17 Dec 2012 02:14:10 GMT
x-amz-expiration: expiry-date="Fri, 21 Dec 2012 00:00:00 GMT", rule-id="Rule
for testfile.txt"
ETag: "54b0c58c7ce9f2a8b551351102ee0938"
Accept-Ranges: bytes
Content-Type: text/plain
Content-Length: 14
Server: AmazonS3

Sample Request: Getting metadata from a speciﬁed version of an object

The following request returns the metadata of the speciﬁed version of an object.

HEAD /my-image.jpg?versionId=3HL4kqCxf3vjVBH40Nrjfkd HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:02236Q3V0WpaBX5sCYVf1bNRuU=

Sample Response: To a versioned HEAD request

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8epIszj7UDNEHGran
x-amz-request-id: 318BC8BC143432E5
x-amz-version-id: 3HL4kqtJlcpXrof3vjVBH40Nrjfkd
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"

API Version 2006-03-01

176
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Content-Length: 434234
Content-Type: text/plain
Connection: close
Server: AmazonS3

Sample Request: For a Glacier object

For an archived object, the x-amz-restore header provides the date when the restored copy expires,
as shown in the following response. Even if the object is stored in Glacier, all object metadata is still
available.

HEAD /my-image.jpg HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: 13 Nov 2012 00:28:38 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:02236Q3V0RonhpaBX5sCYVf1bNRuU=

Sample Response: Glacier object

If the object is already restored, the x-amz-restore header provides the date when the restored copy
will expire, as shown in the following response.

HTTP/1.1 200 OK
x-amz-id-2: FSVaTMjrmBp3Izs1NnwBZeu7M19iI8UbxMbi0A8AirHANJBo+hEftBuiESACOMJp
x-amz-request-id: E5CEFCB143EB505A
Date: Tue, 13 Nov 2012 00:28:38 GMT
Last-Modified: Mon, 15 Oct 2012 21:58:07 GMT
x-amz-restore: ongoing-request="false", expiry-date="Wed, 07 Nov 2012 00:00:00
GMT"
ETag: "1accb31fcf202eba0c0f41fa2f09b4d7"
Accept-Ranges: bytes
Content-Type: binary/octet-stream
Content-Length: 300
Server: AmazonS3

Sample Response: In-progress restoration

If the restoration is in progress, the x-amz-restore header returns a message accordingly.

HTTP/1.1 200 OK
x-amz-id-2: b+V2mDiMHTdy1myoUBpctvmJl95H9U/OSUm/jRtHxjh0+pCk5SvByL4xu2TDv4GM
x-amz-request-id: E2E7B6AEE4E9BD2B
Date: Tue, 13 Nov 2012 00:43:32 GMT
Last-Modified: Sat, 20 Oct 2012 21:28:27 GMT
x-amz-restore: ongoing-request="true"
ETag: "1accb31fcf202eba0c0f41fa2f09b4d7"
Accept-Ranges: bytes
Content-Type: binary/octet-stream
Content-Length: 300
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

API Version 2006-03-01

177
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

178
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ListBucketAnalyticsConﬁgurations
Service: Amazon Simple Storage Service

Lists the analytics conﬁgurations for the bucket. You can have up to 1,000 analytics conﬁgurations per
bucket.

This operation supports list pagination and does not return more than 100 configurations at a time. You
should always check the IsTruncated element in the response. If there are no more configurations to
list, IsTruncated is set to false. If there are more configurations to list, IsTruncated is set to true,
and there will be a value in NextContinuationToken. You use the NextContinuationToken value to
continue the pagination of the list by passing the value in continuation-token in the request to GET the
next page.

For information about Amazon S3 analytics feature, see Amazon S3 Analytics – Storage Class Analysis.

The following operations are related to ListBucketAnalyticsConfigurations:

• GetBucketAnalyticsConﬁguration (p. 85)

• DeleteBucketAnalyticsConﬁguration (p. 43)
• PutBucketAnalyticsConﬁguration (p. 243)

Request Syntax

GET /?analytics&ContinuationToken=ContinuationToken HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 179)

The name of the bucket from which analytics conﬁgurations are retrieved.
continuation-token (p. 179)

The ContinuationToken that represents a placeholder from where this request should begin.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketAnalyticsConfigurationsOutput>
<IsTruncated>boolean</IsTruncated>
<ContinuationToken>string</ContinuationToken>
<NextContinuationToken>string</NextContinuationToken>
<AnalyticsConfiguration>

API Version 2006-03-01

179
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<Filter>
<And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
...
</And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</Filter>
<Id>string</Id>
<StorageClassAnalysis>
<DataExport>
<Destination>
<S3BucketDestination>
<Bucket>string</Bucket>
<BucketAccountId>string</BucketAccountId>
<Format>string</Format>
<Prefix>string</Prefix>
</S3BucketDestination>
</Destination>
<OutputSchemaVersion>string</OutputSchemaVersion>
</DataExport>
</StorageClassAnalysis>
</AnalyticsConfiguration>
...
</ListBucketAnalyticsConfigurationsOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ListBucketAnalyticsConﬁgurationsOutput (p. 179)

Root level tag for the ListBucketAnalyticsConﬁgurationsOutput parameters.

Required: Yes
AnalyticsConﬁguration (p. 179)

The list of analytics conﬁgurations for a bucket.

Type: Array of AnalyticsConﬁguration (p. 419) data types

ContinuationToken (p. 179)

The marker that is used as a starting point for this analytics conﬁguration list response. This value is
present if it was sent in the request.

Type: String
IsTruncated (p. 179)

Indicates whether the returned list of analytics conﬁgurations is complete. A value of true indicates
that the list is not complete and the NextContinuationToken will be provided for a subsequent
request.

Type: Boolean

API Version 2006-03-01

180
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

NextContinuationToken (p. 179)

NextContinuationToken is sent when isTruncated is true, which indicates that there are more
analytics conﬁgurations to list. The next request must include this NextContinuationToken. The
token is obfuscated and is not a usable value.

Type: String

Examples
Sample Request
Delete the metric conﬁguration with a speciﬁed ID, which disables the CloudWatch metrics with the
ExampleMetrics value for the FilterId dimension.

GET /?analytics HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
x-amz-date: 20160430T233541Z
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: gyB+3jRPnrkN98ZajxHXr3u7EFM67bNgSAxexeEHndCX/7GRnfTXxReKUQF28IfP
x-amz-request-id: 3B3C7C725673C630
Date: Sat, 30 Apr 2016 23:29:37 GMT
Content-Length: length
Server: AmazonS3

<ListBucketAnalyticsConfigurationResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<AnalyticsConfiguration>
<Id>list1</Id>
<Filter>
<And>
<Prefix>images/</Prefix>
<Tag>
<Key>dog</Key>
<Value>corgi</Value>
</Tag>
</And>
</Filter>
<StorageClassAnalysis>
<DataExport>
<OutputSchemaVersion>V_1</OutputSchemaVersion>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<BucketAccountId>123456789012</BucketAccountId>
<Bucket>arn:aws:s3:::destination-bucket</Bucket>
<Prefix>destination-prefix</Prefix>
</S3BucketDestination>
</Destination>
</DataExport>
</StorageClassAnalysis>
</AnalyticsConfiguration>

<AnalyticsConfiguration>
<Id>report1</Id>
<Filter>

API Version 2006-03-01

181
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<And>
<Prefix>images/</Prefix>
<Tag>
<Key>dog</Key>
<Value>bulldog</Value>
</Tag>
</And>
</Filter>
<StorageClassAnalysis>
<DataExport>
<OutputSchemaVersion>V_1</OutputSchemaVersion>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<BucketAccountId>123456789012</BucketAccountId>
<Bucket>arn:aws:s3:::destination-bucket</Bucket>
<Prefix>destination-prefix</Prefix>
</S3BucketDestination>
</Destination>
</DataExport>
</StorageClassAnalysis>
</AnalyticsConfiguration>
...
<IsTruncated>false</IsTruncated>

<ContinuationToken>...</ContinuationToken>

<IsTruncated>true</IsTruncated>
<NextContinuationToken>...</NextContinuationToken>
</ListBucketAnalyticsConfigurationResult>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

182
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ListBucketInventoryConﬁgurations
Service: Amazon Simple Storage Service

Returns a list of inventory conﬁgurations for the bucket. You can have up to 1,000 analytics
conﬁgurations per bucket.

This operation supports list pagination and does not return more than 100 configurations at a time.
Always check the IsTruncated element in the response. If there are no more configurations to list,
IsTruncated is set to false. If there are more configurations to list, IsTruncated is set to true, and
there is a value in NextContinuationToken. You use the NextContinuationToken value to continue
the pagination of the list by passing the value in continuation-token in the request to GET the next page.

To use this operation, you must have permissions to perform the s3:GetInventoryConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources.

For information about the Amazon S3 inventory feature, see Amazon S3 Inventory

The following operations are related to ListBucketInventoryConfigurations:

• GetBucketInventoryConﬁguration (p. 95)

• DeleteBucketInventoryConﬁguration (p. 49)
• PutBucketInventoryConﬁguration (p. 253)

Request Syntax

GET /?inventory&ContinuationToken=ContinuationToken HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 183)

The name of the bucket containing the inventory conﬁgurations to retrieve.

continuation-token (p. 183)

The marker used to continue an inventory conﬁguration listing that has been truncated. Use the
NextContinuationToken from a previously truncated list response to continue the listing. The
continuation token is an opaque value that Amazon S3 understands.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketInventoryConfigurationsOutput>
<ContinuationToken>string</ContinuationToken>
<InventoryConfiguration>

API Version 2006-03-01

183
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<Destination>
<S3BucketDestination>
<AccountId>string</AccountId>
<Bucket>string</Bucket>
<Encryption>
<SSE-KMS>
<KeyId>string</KeyId>
</SSE-KMS>
<SSE-S3>
</SSE-S3>
</Encryption>
<Format>string</Format>
<Prefix>string</Prefix>
</S3BucketDestination>
</Destination>
<Filter>
<Prefix>string</Prefix>
</Filter>
<Id>string</Id>
<IncludedObjectVersions>string</IncludedObjectVersions>
<IsEnabled>boolean</IsEnabled>
<OptionalFields>
<Field>string</Field>
</OptionalFields>
<Schedule>
<Frequency>string</Frequency>
</Schedule>
</InventoryConfiguration>
...
<IsTruncated>boolean</IsTruncated>
<NextContinuationToken>string</NextContinuationToken>
</ListBucketInventoryConfigurationsOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ListBucketInventoryConﬁgurationsOutput (p. 183)

Root level tag for the ListBucketInventoryConﬁgurationsOutput parameters.

Required: Yes
ContinuationToken (p. 183)

If sent in the request, the marker that is used as a starting point for this inventory conﬁguration list
response.

Type: String
InventoryConﬁguration (p. 183)

The list of inventory conﬁgurations for a bucket.

Type: Array of InventoryConﬁguration (p. 471) data types

IsTruncated (p. 183)

Tells whether the returned list of inventory conﬁgurations is complete. A value of true indicates that
the list is not complete and the NextContinuationToken is provided for a subsequent request.

Type: Boolean

API Version 2006-03-01

184
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

NextContinuationToken (p. 183)

The marker used to continue this inventory conﬁguration listing. Use the NextContinuationToken
from this response to continue the listing in a subsequent request. The continuation token is an
opaque value that Amazon S3 understands.

Type: String

Examples
Sample Request

The following request returns the inventory conﬁgurations in example-bucket.

GET /?inventory HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
x-amz-date: 20160430T233541Z
Authorization: authorization string
Content-Type: text/plain

Sample Response

Delete the metric conﬁguration with a speciﬁed ID, which disables the CloudWatch metrics with the
ExampleMetrics value for the FilterId dimension.

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

185
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<Field>StorageClass</Field>
<Field>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
</OptionalFields>
</InventoryConfiguration>
<InventoryConfiguration>
<Id>report2</Id>
<IsEnabled>true</IsEnabled>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<AccountId>123456789012</AccountId>
<Bucket>arn:aws:s3:::bucket2</Bucket>
<Prefix>prefix2</Prefix>
</S3BucketDestination>
</Destination>
<Schedule>
<Frequency>Daily</Frequency>
</Schedule>
<Filter>
<Prefix>prefix/Two</Prefix>
</Filter>
<IncludedObjectVersions>All</IncludedObjectVersions>
<OptionalFields>
<Field>Size</Field>
<Field>LastModifiedDate</Field>
<Field>ETag</Field>
<Field>StorageClass</Field>
<Field>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
<Field>ObjectLockRetainUntilDate</Field>
<Field>ObjectLockMode</Field>
<Field>ObjectLockLegalHoldStatus</Field>
</OptionalFields>
</InventoryConfiguration>
<InventoryConfiguration>
<Id>report3</Id>
<IsEnabled>true</IsEnabled>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<AccountId>123456789012</AccountId>
<Bucket>arn:aws:s3:::bucket3</Bucket>
<Prefix>prefix3</Prefix>
</S3BucketDestination>
</Destination>
<Schedule>
<Frequency>Daily</Frequency>
</Schedule>
<Filter>
<Prefix>prefix/Three</Prefix>
</Filter>
<IncludedObjectVersions>All</IncludedObjectVersions>
<OptionalFields>
<Field>Size</Field>
<Field>LastModifiedDate</Field>
<Field>ETag</Field>
<Field>StorageClass</Field>
<Field>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
</OptionalFields>
</InventoryConfiguration>
...
<IsTruncated>false</IsTruncated>

<ContinuationToken>...</ContinuationToken>

API Version 2006-03-01

186
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

187
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ListBucketMetricsConﬁgurations
Service: Amazon Simple Storage Service

Lists the metrics configurations for the bucket. The metrics configurations are only for the request
metrics of the bucket and do not provide information on daily storage metrics. You can have up to 1,000
configurations per bucket.

For more information about metrics conﬁgurations and CloudWatch request metrics, see Monitoring
Metrics with Amazon CloudWatch.

The following operations are related to ListBucketMetricsConfigurations:

• PutBucketMetricsConﬁguration (p. 274)

• GetBucketMetricsConﬁguration (p. 110)
• DeleteBucketMetricsConﬁguration (p. 53)

Request Syntax

GET /?metrics&ContinuationToken=ContinuationToken HTTP/1.1

Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 188)

The name of the bucket containing the metrics conﬁgurations to retrieve.

continuation-token (p. 188)

The marker that is used to continue a metrics conﬁguration listing that has been truncated. Use
the NextContinuationToken from a previously truncated list response to continue the listing. The
continuation token is an opaque value that Amazon S3 understands.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketMetricsConfigurationsOutput>

API Version 2006-03-01

188
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<IsTruncated>boolean</IsTruncated>
<ContinuationToken>string</ContinuationToken>
<NextContinuationToken>string</NextContinuationToken>
<MetricsConfiguration>
<Filter>
<And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
...
</And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</Filter>
<Id>string</Id>
</MetricsConfiguration>
...
</ListBucketMetricsConfigurationsOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ListBucketMetricsConﬁgurationsOutput (p. 188)

Root level tag for the ListBucketMetricsConﬁgurationsOutput parameters.

Required: Yes
ContinuationToken (p. 188)

The marker that is used as a starting point for this metrics conﬁguration list response. This value is
present if it was sent in the request.

Type: String
IsTruncated (p. 188)

Indicates whether the returned list of metrics conﬁgurations is complete. A value of true indicates
that the list is not complete and the NextContinuationToken will be provided for a subsequent
request.

Type: Boolean
MetricsConﬁguration (p. 188)

The list of metrics conﬁgurations for a bucket.

Type: Array of MetricsConﬁguration (p. 492) data types

NextContinuationToken (p. 188)

The marker used to continue a metrics conﬁguration listing that has been truncated. Use the
NextContinuationToken from a previously truncated list response to continue the listing. The
continuation token is an opaque value that Amazon S3 understands.

Type: String

API Version 2006-03-01

189
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Examples
Sample Request

Delete the metric conﬁguration with a speciﬁed ID, which disables theCloudWatch metrics with the
ExampleMetrics value for the FilterId dimension.

GET /?metrics HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT
Authorization: signatureValue

Sample Response

Delete the metric conﬁguration with a speciﬁed ID, which disables theCloudWatch metrics with the
ExampleMetrics value for the FilterId dimension.

<?xml version="1.0" encoding="UTF-8"?>

<ListMetricsConfigurationsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<MetricsConfiguration>
<Id>EntireBucket</Id>
</MetricsConfiguration>
<MetricsConfiguration>
<Id>Documents</Id>
<Filter>
<Prefix>documents/</Prefix>
</Filter>
</MetricsConfiguration>
<MetricsConfiguration>
<Id>BlueDocuments</Id>
<Filter>
<And>
<Prefix>documents/</Prefix>
<Tag>
<Key>class</Key>
<Value>blue</Value>
</Tag>
</And>
</Filter>
</MetricsConfiguration>
<IsTruncated>false</IsTruncated>
</ListMetricsConfigurationsResult>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++

API Version 2006-03-01

190
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for Go

• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

191
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ListBuckets
Service: Amazon Simple Storage Service

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

Request Syntax

GET / HTTP/1.1

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketsOutput>
<Buckets>
<Bucket>
<CreationDate>timestamp</CreationDate>
<Name>string</Name>
</Bucket>
</Buckets>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
</ListBucketsOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ListBucketsOutput (p. 192)

Root level tag for the ListBucketsOutput parameters.

Required: Yes
Buckets (p. 192)

The list of buckets owned by the requestor.

Type: Array of Bucket (p. 423) data types

Owner (p. 192)

The owner of the buckets listed.

Type: Owner (p. 512) data type

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

API Version 2006-03-01

192
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

193
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ListMultipartUploads
Service: Amazon Simple Storage Service

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 ﬁrst sorted by key. Additionally,
uploads are sorted in ascending order within each key by the upload initiation time.

For more information on multipart uploads, see Uploading Objects Using Multipart Upload.

For information on permissions required to use the multipart upload API, see Multipart Upload API and
Permissions.

The following operations are related to ListMultipartUploads:

• CreateMultipartUpload (p. 32)

• UploadPart (p. 360)
• CompleteMultipartUpload (p. 10)
• ListParts (p. 229)
• AbortMultipartUpload (p. 7)

Request Syntax

GET /?
uploads&Delimiter=Delimiter&EncodingType=EncodingType&KeyMarker=KeyMarker&MaxUploads=MaxUploads&Prefix=
HTTP/1.1
Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 194)

Name of the bucket to which the multipart upload was initiated.

Character you use to group keys.

API Version 2006-03-01

194
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

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 (p. 194)

Requests Amazon S3 to encode the object keys in the response and speciﬁes the encoding method
to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse
some characters, such as characters with an ASCII value from 0 to 10. For characters that are not
supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the
response.

Valid Values: url

key-marker (p. 194)

Together with upload-id-marker, this parameter speciﬁes the multipart upload after which listing
should begin.

If upload-id-marker is not speciﬁed, only the keys lexicographically greater than the speciﬁed
key-marker will be included in the list.

If upload-id-marker is speciﬁed, 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 speciﬁed upload-id-marker.
max-uploads (p. 194)

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.
preﬁx (p. 194)

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 (p. 194)

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.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsOutput>
<Bucket>string</Bucket>
<KeyMarker>string</KeyMarker>
<UploadIdMarker>string</UploadIdMarker>
<NextKeyMarker>string</NextKeyMarker>
<Prefix>string</Prefix>
<Delimiter>string</Delimiter>
<NextUploadIdMarker>string</NextUploadIdMarker>
<MaxUploads>integer</MaxUploads>
<IsTruncated>boolean</IsTruncated>

API Version 2006-03-01

195
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<Upload>
<Initiated>timestamp</Initiated>
<Initiator>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Initiator>
<Key>string</Key>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
<StorageClass>string</StorageClass>
<UploadId>string</UploadId>
</Upload>
...
<CommonPrefixes>
<Prefix>string</Prefix>
</CommonPrefixes>
...
<EncodingType>string</EncodingType>
</ListMultipartUploadsOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ListMultipartUploadsOutput (p. 195)

Root level tag for the ListMultipartUploadsOutput parameters.

Required: Yes
Bucket (p. 195)

Name of the bucket to which the multipart upload was initiated.

Type: String
CommonPreﬁxes (p. 195)

If you specify a delimiter in the request, then the result returns each distinct key preﬁx containing
the delimiter in a CommonPrefixes element. The distinct key preﬁxes are returned in the Prefix
child element.

Type: Array of CommonPreﬁx (p. 428) data types

Delimiter (p. 195)

Contains the delimiter you speciﬁed in the request. If you don't specify a delimiter in your request,
this element is absent from the response.

Type: String
EncodingType (p. 195)

Encoding type used by Amazon S3 to encode object keys in the response.

If you specify encoding-type request parameter, Amazon S3 includes this element in the response,
and returns encoded key name values in the following response elements:

Delimiter, KeyMarker, Prefix, NextKeyMarker, Key.

Type: String

API Version 2006-03-01

196
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Valid Values: url

IsTruncated (p. 195)

Indicates whether the returned list of multipart uploads is truncated. A value of true indicates that
the list was truncated. The list can be truncated if the number of multipart uploads exceeds the limit
allowed or speciﬁed by max uploads.

Type: Boolean
KeyMarker (p. 195)

The key at or after which the listing began.

Type: String
MaxUploads (p. 195)

Maximum number of multipart uploads that could have been included in the response.

Type: Integer
NextKeyMarker (p. 195)

When a list is truncated, this element speciﬁes the value that should be used for the key-marker
request parameter in a subsequent request.

Type: String
NextUploadIdMarker (p. 195)

When a list is truncated, this element speciﬁes the value that should be used for the upload-id-
marker request parameter in a subsequent request.

Type: String
Preﬁx (p. 195)

When a prefix is provided in the request, this field contains the specified prefix. The result contains
only keys starting with the specified prefix.

Type: String
Upload (p. 195)

Container for elements related to a particular multipart upload. A response can contain zero or more
Upload elements.

Type: Array of MultipartUpload (p. 494) data types

UploadIdMarker (p. 195)

Upload ID after which listing began.

Type: String

Examples
Sample Request

The following request lists three multipart uploads. The request speciﬁes the max-uploads request
parameter to set the maximum number of multipart uploads to return in the response body.

GET /?uploads&max-uploads=3 HTTP/1.1

API Version 2006-03-01

197
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Host: example-bucket.s3.<Region>.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

Sample Response

The following sample response indicates that the multipart upload list was truncated and provides
the NextKeyMarker and the NextUploadIdMarker elements. You specify these values in
your subsequent requests to read the next set of multipart uploads. That is, send a subsequent
request specifying key-marker=my-movie2.m2ts (value of the NextKeyMarker element) and
upload-id-marker=YW55IGlkZWEgd2h5IGVsdmluZydzIHVwbG9hZCBmYWlsZWQ (value of the
NextUploadIdMarker).

The sample response also shows a case of two multipart uploads in progress with the same key (my-
movie.m2ts). That is, the response shows two uploads with the same key. This response shows the
uploads sorted by key, and within each key the uploads are sorted in ascending order by the time the
multipart upload was initiated.

<?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>

API Version 2006-03-01

198
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<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>

Sample Request: Using the delimiter and the preﬁx parameters

Assume you have a multipart upload in progress for the following keys in your bucket, example-
bucket.

• photos/2006/January/sample.jpg
• photos/2006/February/sample.jpg
• photos/2006/March/sample.jpg
• videos/2006/March/sample.wmv
• sample.jpg

The following list multipart upload request speciﬁes the delimiter parameter with value "/".

GET /?uploads&delimiter=/ HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

Sample Response

The following sample response lists multipart uploads on the speciﬁed bucket, example-bucket.

The response returns multipart upload for the sample.jpg key in an <Upload> element.

However, because all the other keys contain the specified delimiter, a distinct substring, from the
beginning of the key to the first occurrence of the delimiter, from each of these keys is returned in a
<CommonPrefixes> element. The key substrings, photos/ and videos/ in the <CommonPrefixes>
element, indicate that there are one or more in-progress multipart uploads with these key prefixes.

This is a useful scenario if you use key preﬁxes for your objects to create a logical folder like structure. In
this case, you can interpret the result as the folders photos/ and videos/ have one or more multipart
uploads in progress.

<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Bucket>example-bucket</Bucket>
<KeyMarker/>
<UploadIdMarker/>

API Version 2006-03-01

199
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<NextKeyMarker>sample.jpg</NextKeyMarker>

<NextUploadIdMarker>Xgw4MJT6ZPAVxpY0SAuGN7q4uWJJM22ZYg1W99trdp4tpO88.PT6.MhO0w2E17eutfAvQfQWoajgE_W2gp
</NextUploadIdMarker>
<Delimiter>/</Delimiter>
<Prefix/>
<MaxUploads>1000</MaxUploads>
<IsTruncated>false</IsTruncated>
<Upload>
<Key>sample.jpg</Key>

<UploadId>Agw4MJT6ZPAVxpY0SAuGN7q4uWJJM22ZYg1N99trdp4tpO88.PT6.MhO0w2E17eutfAvQfQWoajgE_W2gpcxQw--
</UploadId>
<Initiator>
<ID>314133b66967d86f031c7249d1d9a80249109428335cd0ef1cdc487b4566cb1b</ID>
<DisplayName>s3-nickname</DisplayName>
</Initiator>
<Owner>
<ID>314133b66967d86f031c7249d1d9a80249109428335cd0ef1cdc487b4566cb1b</ID>
<DisplayName>s3-nickname</DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
<Initiated>2010-11-26T19:24:17.000Z</Initiated>
</Upload>
<CommonPrefixes>
<Prefix>photos/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>videos/</Prefix>
</CommonPrefixes>
</ListMultipartUploadsResult>

Sample Request
In addition to the delimiter parameter, you can ﬁlter results by adding a preﬁx parameter as shown in the
following request.

GET /?uploads&delimiter=/&prefix=photos/2006/ HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

Sample Response
In this case, the response will include only multipart uploads for keys that start with the specified prefix.
The value returned in the <CommonPrefixes> element is a substring from the beginning of the key to the
first occurrence of the specified delimiter after the prefix.

<?xml version="1.0" encoding="UTF-8"?>

<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Bucket>example-bucket</Bucket>
<KeyMarker/>
<UploadIdMarker/>
<NextKeyMarker/>
<NextUploadIdMarker/>
<Delimiter>/</Delimiter>
<Prefix>photos/2006/</Prefix>
<MaxUploads>1000</MaxUploads>
<IsTruncated>false</IsTruncated>

API Version 2006-03-01

200
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<CommonPrefixes>
<Prefix>photos/2006/February/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/January/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/March/</Prefix>
</CommonPrefixes>
</ListMultipartUploadsResult>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

201
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ListObjects
Service: Amazon Simple Storage Service

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. Be sure to design your application to parse the contents of the response and handle it
appropriately.
Important
This API has been revised. We recommend that you use the newer version,
ListObjectsV2 (p. 209), when developing applications. For backward compatibility, Amazon S3
continues to support ListObjects.

The following operations are related to ListObjects:

• ListObjectsV2 (p. 209)

• GetObject (p. 138)
• PutObject (p. 310)
• CreateBucket (p. 27)
• ListBuckets (p. 192)

Request Syntax

GET /?
Delimiter=Delimiter&EncodingType=EncodingType&Marker=Marker&MaxKeys=MaxKeys&Prefix=Prefix
HTTP/1.1
Host: Bucket.s3.amazonaws.com
x-amz-request-payer: RequestPayer

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 202)

The name of the bucket containing the objects.

delimiter (p. 202)

A delimiter is a character you use to group keys.

encoding-type (p. 202)

Valid Values: url

marker (p. 202)

Speciﬁes the key to start with when listing objects in a bucket.

max-keys (p. 202)

Sets the maximum number of keys returned in the response. The response might contain fewer keys
but will never contain more.

API Version 2006-03-01

202
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

preﬁx (p. 202)

Limits the response to keys that begin with the speciﬁed preﬁx.
x-amz-request-payer (p. 202)

Conﬁrms that the requester knows that she or he will be charged for the list objects request. Bucket
owners need not specify this parameter in their requests.

Valid Values: requester

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListObjectsOutput>
<IsTruncated>boolean</IsTruncated>
<Marker>string</Marker>
<NextMarker>string</NextMarker>
<Contents>
<ETag>string</ETag>
<Key>string</Key>
<LastModified>timestamp</LastModified>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
<Size>integer</Size>
<StorageClass>string</StorageClass>
</Contents>
...
<Name>string</Name>
<Prefix>string</Prefix>
<Delimiter>string</Delimiter>
<MaxKeys>integer</MaxKeys>
<CommonPrefixes>
<Prefix>string</Prefix>
</CommonPrefixes>
...
<EncodingType>string</EncodingType>
</ListObjectsOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ListObjectsOutput (p. 203)

Root level tag for the ListObjectsOutput parameters.

Required: Yes
CommonPreﬁxes (p. 203)

All of the keys rolled up in a common preﬁx count as a single return when calculating the number of
returns.

API Version 2006-03-01

203
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

A response can contain CommonPreﬁxes only if you specify a delimiter.

CommonPrefixes contains all (if there are any) keys between Prefix and the next occurrence of the
string specified by the delimiter.

CommonPrefixes lists keys that act like subdirectories in the directory specified by Prefix.

For example, if the prefix is notes/ and the delimiter is a slash (/) as in notes/summer/july, the
common prefix is notes/summer/. All of the keys that roll up into a common prefix count as a single
return when calculating the number of returns.

Type: Array of CommonPreﬁx (p. 428) data types

Contents (p. 203)

Metadata about each object returned.

Type: Array of Object (p. 501) data types

Delimiter (p. 203)

Causes keys that contain the same string between the preﬁx and the ﬁrst occurrence of the delimiter
to be rolled up into a single result element in the CommonPrefixes collection. These rolled-up keys
are not returned elsewhere in the response. Each rolled-up result counts as only one return against
the MaxKeys value.

Type: String
EncodingType (p. 203)

Encoding type used by Amazon S3 to encode object keys in the response.

Type: String

Valid Values: url

IsTruncated (p. 203)

A ﬂag that indicates whether Amazon S3 returned all of the results that satisﬁed the search criteria.

Type: Boolean
Marker (p. 203)

Indicates where in the bucket listing begins. Marker is included in the response if it was sent with the
request.

Type: String
MaxKeys (p. 203)

The maximum number of keys returned in the response body.

Type: Integer
Name (p. 203)

Bucket name.

Type: String
NextMarker (p. 203)

When response is truncated (the IsTruncated element value in the response is true), you can use the
key name in this ﬁeld as marker in the subsequent request to get next set of objects. Amazon S3
lists objects in alphabetical order Note: This element is returned only if you have delimiter request
parameter speciﬁed. If response does not include the NextMaker and it is truncated, you can use the

API Version 2006-03-01

204
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

value of the last Key in the response as the marker in the subsequent request to get the next set of
object keys.

Type: String
Preﬁx (p. 203)

Keys that begin with the indicated preﬁx.

Type: String

The speciﬁed bucket does not exist.

Examples
Sample Request

This request returns the objects in BucketName.

GET / HTTP/1.1
Host: BucketName.s3.<Region>.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>bucket</Name>
<Prefix/>
<Marker/>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>my-image.jpg</Key>
<LastModified>2009-10-12T17:50:30.000Z</LastModified>
<ETag>"fba9dede5f27731c9771645a39863328"</ETag>
<Size>434234</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
</Contents>
<Contents>
<Key>my-third-image.jpg</Key>
<LastModified>2009-10-12T17:50:30.000Z</LastModified>
<ETag>"1b2cf535f27731c974343645a3985328"</ETag>
<Size>64994</Size>
<StorageClass>STANDARD_IA</StorageClass>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
</Contents>
</ListBucketResult>

API Version 2006-03-01

205
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Sample Request: Using request parameters

This example lists up to 40 keys in the quotes bucket that start with N and occur lexicographically after
Ned.

GET /?prefix=N&marker=Ned&max-keys=40 HTTP/1.1

Host: quotes.s3.<Region>.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: gyB+3jRPnrkN98ZajxHXr3u7EFM67bNgSAxexeEHndCX/7GRnfTXxReKUQF28IfP
x-amz-request-id: 3B3C7C725673C630
Date: Wed, 01 Mar 2006 12:00:00 GMT
Content-Type: application/xml
Content-Length: 302
Connection: close
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>quotes</Name>
<Prefix>N</Prefix>
<Marker>Ned</Marker>
<MaxKeys>40</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>Nelson</Key>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
<Size>5</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>bcaf161ca5fb16fd081034f</ID>
<DisplayName>webfile</DisplayName>
</Owner>
</Contents>
<Contents>
<Key>Neo</Key>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
<Size>4</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>bcaf1ffd86a5fb16fd081034f</ID>
<DisplayName>webfile</DisplayName>
</Owner>
</Contents>
</ListBucketResult>

Sample Request: Using a preﬁx and delimiter

For this example, we assume that you have the following keys in your bucket:

• sample.jpg

API Version 2006-03-01

206
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• photos/2006/January/sample.jpg
• photos/2006/February/sample2.jpg
• photos/2006/February/sample3.jpg
• photos/2006/February/sample4.jpg

The following GET request speciﬁes the delimiter parameter with value /.

GET /?delimiter=/ HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

Sample Response

The key sample.jpg does not contain the delimiter character, and Amazon S3 returns it in the Contents
element in the response. However, all other keys contain the delimiter character. Amazon S3 groups
these keys and returns a single CommonPrefixes element with prefix value photos/ that is a substring
from the beginning of these keys to the first occurrence of the specified delimiter.

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>example-bucket</Name>
<Prefix></Prefix>
<Marker></Marker>
<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>sample.jpg</Key>
<LastModified>2011-02-26T01:56:20.000Z</LastModified>
<ETag>"bf1d737a4d46a19f3bced6905cc8b902"</ETag>
<Size>142863</Size>
<Owner>
<ID>canonical-user-id</ID>
<DisplayName>display-name</DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Contents>
<CommonPrefixes>
<Prefix>photos/</Prefix>
</CommonPrefixes>
</ListBucketResult>

Sample Request

The following GET request speciﬁes the delimiter parameter with the value /, and the preﬁx parameter
with the value photos/2006/.

GET /?prefix=photos/2006/&delimiter=/ HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

API Version 2006-03-01

207
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Sample Response

In response, Amazon S3 returns only the keys that start with the specified prefix. It uses the delimiter
character to group keys that contain the same substring until the first occurrence of the delimiter
character after the specified prefix. For each such key group, Amazon S3 returns one <CommonPrefixes>
element in the response. The keys grouped under this CommonPrefixes element are not returned
elsewhere in the response. The value returned in the CommonPrefixes element is a substring that starts
at the beginning of the key and ends at the first occurrence of the specified delimiter after the prefix.

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>example-bucket</Name>
<Prefix>photos/2006/</Prefix>
<Marker></Marker>
<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>

<CommonPrefixes>
<Prefix>photos/2006/February/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/January/</Prefix>
</CommonPrefixes>
</ListBucketResult>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

208
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ListObjectsV2
Service: Amazon Simple Storage Service

To use this operation, you must have READ access to the bucket.

To use this operation in an AWS Identity and Access Management (IAM) policy, you must have
permissions to perform the s3:ListBucket action. The bucket owner has this permission by default
and can grant this permission to others. For more information about permissions, see Permissions
Related to Bucket Subresource Operations and Managing Access Permissions to Your Amazon S3
Resources.
Important
This section describes the latest revision of the API. We recommend that you use this revised API
for application development. For backward compatibility, Amazon S3 continues to support the
prior version of this API, ListObjects (p. 202).

To get a list of your buckets, see ListBuckets (p. 192).

The following operations are related to ListObjectsV2:

• GetObject (p. 138)

• PutObject (p. 310)
• CreateBucket (p. 27)

Request Syntax

GET /?list-
type=2&ContinuationToken=ContinuationToken&Delimiter=Delimiter&EncodingType=EncodingType&FetchOwner=Fet
HTTP/1.1
Host: Bucket.s3.amazonaws.com
x-amz-request-payer: RequestPayer

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 209)

Bucket name to list.

ContinuationToken indicates Amazon S3 that the list is being continued on this bucket with a token.
ContinuationToken is obfuscated and is not a real key.
delimiter (p. 209)

A delimiter is a character you use to group keys.

API Version 2006-03-01

209
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

encoding-type (p. 209)

Encoding type used by Amazon S3 to encode object keys in the response.

Valid Values: url

fetch-owner (p. 209)

The owner field is not present in listV2 by default, if you want to return owner field with each key in
the result then set the fetch owner field to true.
max-keys (p. 209)

Sets the maximum number of keys returned in the response. The response might contain fewer keys
but will never contain more.
preﬁx (p. 209)

Limits the response to keys that begin with the speciﬁed preﬁx.
start-after (p. 209)

StartAfter is where you want Amazon S3 to start listing from. Amazon S3 starts listing after this
speciﬁed key. StartAfter can be any key in the bucket.
x-amz-request-payer (p. 209)

Conﬁrms that the requester knows that she or he will be charged for the list objects request in V2
style. Bucket owners need not specify this parameter in their requests.

Valid Values: requester

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListObjectsV2Output>
<IsTruncated>boolean</IsTruncated>
<Contents>
<ETag>string</ETag>
<Key>string</Key>
<LastModified>timestamp</LastModified>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
<Size>integer</Size>
<StorageClass>string</StorageClass>
</Contents>
...
<Name>string</Name>
<Prefix>string</Prefix>
<Delimiter>string</Delimiter>
<MaxKeys>integer</MaxKeys>
<CommonPrefixes>
<Prefix>string</Prefix>
</CommonPrefixes>
...
<EncodingType>string</EncodingType>
<KeyCount>integer</KeyCount>
<ContinuationToken>string</ContinuationToken>

API Version 2006-03-01

210
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<NextContinuationToken>string</NextContinuationToken>
<StartAfter>string</StartAfter>
</ListObjectsV2Output>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ListObjectsV2Output (p. 210)

Root level tag for the ListObjectsV2Output parameters.

Required: Yes
CommonPreﬁxes (p. 210)

All of the keys rolled up into a common preﬁx count as a single return when calculating the number
of returns.

A response can contain CommonPrefixes only if you specify a delimiter.

CommonPrefixes contains all (if there are any) keys between Prefix and the next occurrence of
the string speciﬁed by a delimiter.

CommonPrefixes lists keys that act like subdirectories in the directory speciﬁed by Prefix.

For example, if the prefix is notes/ and the delimiter is a slash (/) as in notes/summer/july,
the common prefix is notes/summer/. All of the keys that roll up into a common prefix count as a
single return when calculating the number of returns.

Type: Array of CommonPreﬁx (p. 428) data types

Contents (p. 210)

Metadata about each object returned.

Type: Array of Object (p. 501) data types

ContinuationToken (p. 210)

If ContinuationToken was sent with the request, it is included in the response.

Type: String
Delimiter (p. 210)

Causes keys that contain the same string between the prefix and the first occurrence of the delimiter
to be rolled up into a single result element in the CommonPrefixes collection. These rolled-up keys
are not returned elsewhere in the response. Each rolled-up result counts as only one return against
the MaxKeys value.

Type: String
EncodingType (p. 210)

Encoding type used by Amazon S3 to encode object key names in the XML response.

If you specify the encoding-type request parameter, Amazon S3 includes this element in the
response, and returns encoded key name values in the following response elements:

Delimiter, Prefix, Key, and StartAfter.

Type: String

API Version 2006-03-01

211
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Valid Values: url

IsTruncated (p. 210)

Set to false if all of the results were returned. Set to true if more keys are available to return. If the
number of results exceeds that speciﬁed by MaxKeys, all of the results might not be returned.

Type: Boolean
KeyCount (p. 210)

KeyCount is the number of keys returned with this request. KeyCount will always be less than equals
to MaxKeys ﬁeld. Say you ask for 50 keys, your result will include less than equals 50 keys

Type: Integer
MaxKeys (p. 210)

Sets the maximum number of keys returned in the response. The response might contain fewer keys
but will never contain more.

Type: Integer
Name (p. 210)

Bucket name.

Type: String
NextContinuationToken (p. 210)

NextContinuationToken is sent when isTruncated is true, which means there are more keys
in the bucket that can be listed. The next list requests to Amazon S3 can be continued with this
NextContinuationToken. NextContinuationToken is obfuscated and is not a real key

Type: String
Preﬁx (p. 210)

Keys that begin with the indicated preﬁx.

Type: String
StartAfter (p. 210)

If StartAfter was sent with the request, it is included in the response.

Type: String

The speciﬁed bucket does not exist.

Examples
Sample Request: Listing keys

This request returns the objects in BucketName. The request speciﬁes the list-type parameter, which
indicates version 2 of the API.

API Version 2006-03-01

212
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GET /?list-type=2 HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
x-amz-date: 20160430T233541Z
Authorization: authorization string
Content-Type: text/plain

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>bucket</Name>
<Prefix/>
<KeyCount>205</KeyCount>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>my-image.jpg</Key>
<LastModified>2009-10-12T17:50:30.000Z</LastModified>
<ETag>"fba9dede5f27731c9771645a39863328"</ETag>
<Size>434234</Size>
<StorageClass>STANDARD</StorageClass>
</Contents>
<Contents>
...
</Contents>
...
</ListBucketResult>

Sample Request: Listing keys using the max-keys, preﬁx, and start-after parameters

In addition to the list-type parameter that indicates version 2 of the API, the request also speciﬁes
additional parameters to retrieve up to three keys in the quotes bucket that start with E and occur
lexicographically after ExampleGuide.pdf.

GET /?list-type=2&max-keys=3&prefix=E&start-after=ExampleGuide.pdf HTTP/1.1

Host: quotes.s3.<Region>.amazonaws.com
x-amz-date: 20160430T232933Z
Authorization: authorization string

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>quotes</Name>

API Version 2006-03-01

213
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<Prefix>E</Prefix>
<StartAfter>ExampleGuide.pdf</StartAfter>
<KeyCount>1</KeyCount>
<MaxKeys>3</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>ExampleObject.txt</Key>
<LastModified>2013-09-17T18:07:53.000Z</LastModified>
<ETag>"599bab3ed2c697f1d26842727561fd94"</ETag>
<Size>857</Size>
<StorageClass>REDUCED_REDUNDANCY</StorageClass>
</Contents>
</ListBucketResult>

Sample Request: Listing keys using the preﬁx and delimiter parameters

This example illustrates the use of the preﬁx and the delimiter parameters in the request. For this
example, we assume that you have the following keys in your bucket:

• sample.jpg
• photos/2006/January/sample.jpg
• photos/2006/February/sample2.jpg
• photos/2006/February/sample3.jpg
• photos/2006/February/sample4.jpg

The following GET request speciﬁes the delimiter parameter with value /.

GET /?list-type=2&delimiter=/ HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
x-amz-date: 20160430T235931Z
Authorization: authorization string

Sample Response

The key sample.jpg does not contain the delimiter character, and Amazon S3 returns it in the
Contents element in the response. However, all other keys contain the delimiter character. Amazon S3
groups these keys and returns a single CommonPrefixes element with the prefix value photos/. The
element is a substring that starts at the beginning of these keys and ends at the first occurrence of the
specified delimiter.

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>example-bucket</Name>
<Prefix></Prefix>
<KeyCount>2</KeyCount>
<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>sample.jpg</Key>
<LastModified>2011-02-26T01:56:20.000Z</LastModified>
<ETag>"bf1d737a4d46a19f3bced6905cc8b902"</ETag>
<Size>142863</Size>
<StorageClass>STANDARD</StorageClass>
</Contents>

API Version 2006-03-01

214
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<CommonPrefixes>
<Prefix>photos/</Prefix>
</CommonPrefixes>
</ListBucketResult>

Sample Request

The following request speciﬁes the delimiter parameter with value /, and the preﬁx parameter with value
photos/2006/.

GET /?list-type=2&prefix=photos/2006/&delimiter=/ HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
x-amz-date: 20160501T000433Z
Authorization: authorization string

Sample Response

In response, Amazon S3 returns only the keys that start with the specified prefix. Further, it uses
the delimiter character to group keys that contain the same substring until the first occurrence of
the delimiter character after the specified prefix. For each such key group Amazon S3 returns one
CommonPrefixes element in the response. The keys grouped under this CommonPrefixes element
are not returned elsewhere in the response. The value returned in the CommonPrefixes element is
a substring that starts at the beginning of the key and ends at the first occurrence of the specified
delimiter after the prefix.

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>example-bucket</Name>
<Prefix>photos/2006/</Prefix>
<KeyCount>3</KeyCount>
<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>photos/2006/</Key>
<LastModified>2016-04-30T23:51:29.000Z</LastModified>
<ETag>"d41d8cd98f00b204e9800998ecf8427e"</ETag>
<Size>0</Size>
<StorageClass>STANDARD</StorageClass>
</Contents>

<CommonPrefixes>
<Prefix>photos/2006/February/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/January/</Prefix>
</CommonPrefixes>
</ListBucketResult>

Sample Request: Using a continuation token

In this example, the initial request returns more than 1,000 keys. In response to this request, Amazon
S3 returns the IsTruncated element with the value set to true and with a NextContinuationToken
element.

API Version 2006-03-01

215
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GET /?list-type=2 HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Mon, 02 May 2016 23:17:07 GMT
Authorization: authorization string

Sample Response: Using a continuation token

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>bucket</Name>
<Prefix></Prefix>
<NextContinuationToken>1ueGcxLPRx1Tr/XYExHnhbYLgveDs2J/wm36Hy4vbOwM=</
NextContinuationToken>
<KeyCount>1000</KeyCount>
<MaxKeys>1000</MaxKeys>
<IsTruncated>true</IsTruncated>
<Contents>
<Key>happyface.jpg</Key>
<LastModified>2014-11-21T19:40:05.000Z</LastModified>
<ETag>"70ee1738b6b21e2c8a43f3a5ab0eee71"</ETag>
<Size>11</Size>
<StorageClass>STANDARD</StorageClass>
</Contents>
...
</ListBucketResult>

In the following subsequent request, we include a continuation-token query parameter in the request
with value of the <NextContinuationToken> from the preceding response.

GET /?list-type=2 HTTP/1.1

GET /?list-type=2&continuation-token=1ueGcxLPRx1Tr/XYExHnhbYLgveDs2J/wm36Hy4vbOwM= HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Mon, 02 May 2016 23:17:07 GMT
Authorization: authorization string

Amazon S3 returns a list of the next set of keys starting where the previous request ended.

HTTP/1.1 200 OK
x-amz-id-2: gyB+3jRPnrkN98ZajxHXr3u7EFM67bNgSAxexeEHndCX/7GRnfTXxReKUQF28IfP
x-amz-request-id: 3B3C7C725673C630
Date: Sat, 30 Apr 2016 23:29:37 GMT

API Version 2006-03-01

216
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Content-Type: application/xml
Content-Length: length
Connection: close
Server: AmazonS3

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>bucket</Name>
<Prefix></Prefix>
<ContinuationToken>1ueGcxLPRx1Tr/XYExHnhbYLgveDs2J/wm36Hy4vbOwM=</ContinuationToken>
<KeyCount>112</KeyCount>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>happyfacex.jpg</Key>
<LastModified>2014-11-21T19:40:05.000Z</LastModified>
<ETag>"70ee1738b6b21e2c8a43f3a5ab0eee71"</ETag>
<Size>1111</Size>
<StorageClass>STANDARD</StorageClass>
</Contents>
...
</ListBucketResult>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

217
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ListObjectVersions
Service: Amazon Simple Storage Service

Returns metadata about all of the versions of objects in a bucket. You can also use request parameters as
selection criteria to return metadata about a subset of all the object versions.
Note
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.

To use this operation, you must have READ access to the bucket.

The following operations are related to ListObjectVersions:

• ListObjectsV2 (p. 209)

• GetObject (p. 138)
• PutObject (p. 310)
• DeleteObject (p. 63)

Request Syntax

GET /?
versions&Delimiter=Delimiter&EncodingType=EncodingType&KeyMarker=KeyMarker&MaxKeys=MaxKeys&Prefix=Prefi
HTTP/1.1
Host: Bucket.s3.amazonaws.com

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 218)

The bucket name that contains the objects.

A delimiter is a character that you specify to group keys. All keys that contain the same string
between the prefix and the ﬁrst occurrence of the delimiter are grouped under a single result
element in CommonPreﬁxes. These groups are counted as one result against the max-keys
limitation. These keys are not returned elsewhere in the response.
encoding-type (p. 218)

Valid Values: url

API Version 2006-03-01

218
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

key-marker (p. 218)

Speciﬁes the key to start with when listing objects in a bucket.

max-keys (p. 218)

Sets the maximum number of keys returned in the response. The response might contain fewer
keys but will never contain more. If additional keys satisfy the search criteria, but were not returned
because max-keys was exceeded, the response contains <isTruncated>true</isTruncated>. To return
the additional keys, see key-marker and version-id-marker.
preﬁx (p. 218)

Use this parameter to select only those keys that begin with the specified prefix. You can use
prefixes to separate a bucket into different groupings of keys. (You can think of using prefix to make
groups in the same way you'd use a folder in a file system.) You can use prefix with delimiter to roll
up numerous objects into a single result under CommonPrefixes.
version-id-marker (p. 218)

Speciﬁes the object version you want to start listing from.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListObjectVersionsOutput>
<IsTruncated>boolean</IsTruncated>
<KeyMarker>string</KeyMarker>
<VersionIdMarker>string</VersionIdMarker>
<NextKeyMarker>string</NextKeyMarker>
<NextVersionIdMarker>string</NextVersionIdMarker>
<Version>
<ETag>string</ETag>
<IsLatest>boolean</IsLatest>
<Key>string</Key>
<LastModified>timestamp</LastModified>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
<Size>integer</Size>
<StorageClass>string</StorageClass>
<VersionId>string</VersionId>
</Version>
...
<DeleteMarker>
<IsLatest>boolean</IsLatest>
<Key>string</Key>
<LastModified>timestamp</LastModified>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
<VersionId>string</VersionId>
</DeleteMarker>
...
<Name>string</Name>
<Prefix>string</Prefix>
<Delimiter>string</Delimiter>

API Version 2006-03-01

219
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<MaxKeys>integer</MaxKeys>
<CommonPrefixes>
<Prefix>string</Prefix>
</CommonPrefixes>
...
<EncodingType>string</EncodingType>
</ListObjectVersionsOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ListObjectVersionsOutput (p. 219)

Root level tag for the ListObjectVersionsOutput parameters.

Required: Yes
CommonPreﬁxes (p. 219)

All of the keys rolled up into a common preﬁx count as a single return when calculating the number
of returns.

Type: Array of CommonPreﬁx (p. 428) data types

DeleteMarker (p. 219)

Container for an object that is a delete marker.

Type: Array of DeleteMarkerEntry (p. 445) data types

Delimiter (p. 219)

The delimiter grouping the included keys. A delimiter is a character that you specify to group keys.
All keys that contain the same string between the preﬁx and the ﬁrst occurrence of the delimiter are
grouped under a single result element in CommonPrefixes. These groups are counted as one result
against the max-keys limitation. These keys are not returned elsewhere in the response.

Type: String
EncodingType (p. 219)

Encoding type used by Amazon S3 to encode object key names in the XML response.

If you specify encoding-type request parameter, Amazon S3 includes this element in the response,
and returns encoded key name values in the following response elements:

KeyMarker, NextKeyMarker, Prefix, Key, and Delimiter.

Type: String

Valid Values: url

IsTruncated (p. 219)

A ﬂag that indicates whether Amazon S3 returned all of the results that satisﬁed the search criteria.
If your results were truncated, you can make a follow-up paginated request using the NextKeyMarker
and NextVersionIdMarker response parameters as a starting place in another request to return the
rest of the results.

Type: Boolean
KeyMarker (p. 219)

Marks the last key returned in a truncated response.

API Version 2006-03-01

220
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Type: String
MaxKeys (p. 219)

Speciﬁes the maximum number of objects to return.

Type: Integer
Name (p. 219)

Bucket name.

Type: String
NextKeyMarker (p. 219)

When the number of responses exceeds the value of MaxKeys, NextKeyMarker specifies the
first key not returned that satisfies the search criteria. Use this value for the key-marker request
parameter in a subsequent request.

Type: String
NextVersionIdMarker (p. 219)

When the number of responses exceeds the value of MaxKeys, NextVersionIdMarker specifies
the first object version not returned that satisfies the search criteria. Use this value for the version-
id-marker request parameter in a subsequent request.

Type: String
Preﬁx (p. 219)

Selects objects that start with the value supplied by this parameter.

Type: String
Version (p. 219)

Container for version information.

Type: Array of ObjectVersion (p. 508) data types

VersionIdMarker (p. 219)

Marks the last version of the key returned in a truncated response.

Type: String

Examples
Sample Request

The following request returns all of the versions of all of the objects in the speciﬁed bucket.

GET /?versions HTTP/1.1

Host: BucketName.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 +0000
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Sample Response

API Version 2006-03-01

221
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<?xml version="1.0" encoding="UTF-8"?>

<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<Name>bucket</Name>
<Prefix>my</Prefix>
<KeyMarker/>
<VersionIdMarker/>
<MaxKeys>5</MaxKeys>
<IsTruncated>false</IsTruncated>
<Version>
<Key>my-image.jpg</Key>
<VersionId>3/L4kqtJl40Nr8X8gdRQBpUMLUo</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2009-10-12T17:50:30.000Z</LastModified>
<ETag>"fba9dede5f27731c9771645a39863328"</ETag>
<Size>434234</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
</Version>
<DeleteMarker>
<Key>my-second-image.jpg</Key>
<VersionId>03jpff543dhffds434rfdsFDN943fdsFkdmqnh892</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2009-11-12T17:50:30.000Z</LastModified>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
</DeleteMarker>
<Version>
<Key>my-second-image.jpg</Key>
<VersionId>QUpfdndhfd8438MNFDN93jdnJFkdmqnh893</VersionId>
<IsLatest>false</IsLatest>
<LastModified>2009-10-10T17:50:30.000Z</LastModified>
<ETag>"9b2cf535f27731c974343645a3985328"</ETag>
<Size>166434</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
</Version>
<DeleteMarker>
<Key>my-third-image.jpg</Key>
<VersionId>03jpff543dhffds434rfdsFDN943fdsFkdmqnh892</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2009-10-15T17:50:30.000Z</LastModified>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
</DeleteMarker>
<Version>
<Key>my-third-image.jpg</Key>
<VersionId>UIORUnfndfhnw89493jJFJ</VersionId>
<IsLatest>false</IsLatest>
<LastModified>2009-10-11T12:50:30.000Z</LastModified>
<ETag>"772cf535f27731c974343645a3985328"</ETag>
<Size>64</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>

API Version 2006-03-01

222
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

</Owner>
</Version>
</ListVersionsResult>

Sample Request

The following request returns objects in the order they were stored, returning the most recently stored
object ﬁrst starting with the value for key-marker.

GET /?versions&key-marker=key2 HTTP/1.1

Host: s3.amazonaws.com
Pragma: no-cache
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
Date: Thu, 10 Dec 2009 22:46:32 +0000
Authorization: signatureValue

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>mtp-versioning-fresh</Name>
<Prefix/>
<KeyMarker>key2</KeyMarker>
<VersionIdMarker/>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Version>
<Key>key3</Key>
<VersionId>I5VhmK6CDDdQ5Pwfe1gcHZWmHDpcv7gfmfc29UBxsKU.</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2009-12-09T00:19:04.000Z</LastModified>
<ETag>"396fefef536d5ce46c7537ecf978a360"</ETag>
<Size>217</Size>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>
<DeleteMarker>
<Key>sourcekey</Key>
<VersionId>qDhprLU80sAlCFLu2DWgXAEDgKzWarn-HS_JU0TvYqs.</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2009-12-10T16:38:11.000Z</LastModified>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
</DeleteMarker>
<Version>
<Key>sourcekey</Key>
<VersionId>wxxQ7ezLaL5JN2Sislq66Syxxo0k7uHTUpb9qiiMxNg.</VersionId>
<IsLatest>false</IsLatest>
<LastModified>2009-12-10T16:37:44.000Z</LastModified>
<ETag>"396fefef536d5ce46c7537ecf978a360"</ETag>
<Size>217</Size>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
<StorageClass>STANDARD</StorageClass>

API Version 2006-03-01

223
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

</Version>
</ListVersionsResult>

Sample Request Using preﬁx

This example returns objects whose keys begin with source.

GET /?versions&prefix=source HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 +0000
Authorization: authorization string

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>mtp-versioning-fresh</Name>
<Prefix>source</Prefix>
<KeyMarker/>
<VersionIdMarker/>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<DeleteMarker>
<Key>sourcekey</Key>
<VersionId>qDhprLU80sAlCFLu2DWgXAEDgKzWarn-HS_JU0TvYqs.</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2009-12-10T16:38:11.000Z</LastModified>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
</DeleteMarker>
<Version>
<Key>sourcekey</Key>
<VersionId>wxxQ7ezLaL5JN2Sislq66Syxxo0k7uHTUpb9qiiMxNg.</VersionId>
<IsLatest>false</IsLatest>
<LastModified>2009-12-10T16:37:44.000Z</LastModified>
<ETag>"396fefef536d5ce46c7537ecf978a360"</ETag>
<Size>217</Size>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>
</ListVersionsResult>

Sample Request: Using key-marker and version-id-marker parameters

The following example returns objects starting at the speciﬁed key (key-marker) and version ID (version-
id-marker).

GET /?versions&key-marker=key3&version-id-marker=t46ZenlYTZBnj HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 +0000
Authorization: signatureValue

API Version 2006-03-01

224
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>mtp-versioning-fresh</Name>
<Prefix/>
<KeyMarker>key3</KeyMarker>
<VersionIdMarker>t46ZenlYTZBnj</VersionIdMarker>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<DeleteMarker>
<Key>sourcekey</Key>
<VersionId>qDhprLU80sAlCFLu2DWgXAEDgKzWarn-HS_JU0TvYqs.</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2009-12-10T16:38:11.000Z</LastModified>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
</DeleteMarker>
<Version>
<Key>sourcekey</Key>
<VersionId>wxxQ7ezLaL5JN2Sislq66Syxxo0k7uHTUpb9qiiMxNg.</VersionId>
<IsLatest>false</IsLatest>
<LastModified>2009-12-10T16:37:44.000Z</LastModified>
<ETag>"396fefef536d5ce46c7537ecf978a360"</ETag>
<Size>217</Size>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>
</ListVersionsResult>

Sample Request: Using key-marker, version-id-marker, and max-keys

The following request returns up to three (the value of max-keys) objects starting with the key speciﬁed
by key-marker and the version ID speciﬁed by version-id-marker.

GET /?versions&key-marker=key3&version-id-marker=t46Z0menlYTZBnj&max-keys=3
Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 +0000
Authorization: authorization string

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>mtp-versioning-fresh</Name>
<Prefix/>
<KeyMarker>key3</KeyMarker>
<VersionIdMarker>null</VersionIdMarker>
<NextKeyMarker>key3</NextKeyMarker>
<NextVersionIdMarker>d-d309mfjFrUmoQ0DBsVqmcMV15OI.</NextVersionIdMarker>
<MaxKeys>3</MaxKeys>
<IsTruncated>true</IsTruncated>

API Version 2006-03-01

225
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<Version>
<Key>key3</Key>
<VersionId>8XECiENpj8pydEDJdd-_VRrvaGKAHOaGMNW7tg6UViI.</VersionId>
<IsLatest>false</IsLatest>
<LastModified>2009-12-09T00:18:23.000Z</LastModified>
<ETag>"396fefef536d5ce46c7537ecf978a360"</ETag>
<Size>217</Size>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>
<Version>
<Key>key3</Key>
<VersionId>d-d309mfjFri40QYukDozqBt3UmoQ0DBsVqmcMV15OI.</VersionId>
<IsLatest>false</IsLatest>
<LastModified>2009-12-09T00:18:08.000Z</LastModified>
<ETag>"396fefef536d5ce46c7537ecf978a360"</ETag>
<Size>217</Size>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>
</ListVersionsResult>

Sample Request: Using the delimiter and preﬁx parameters

Assume you have the following keys in your bucket, example-bucket.

photos/2006/January/sample.jpg

photos/2006/February/sample.jpg

photos/2006/March/sample.jpg

videos/2006/March/sample.wmv

sample.jpg

The following GET versions request speciﬁes the delimiter parameter with value "/".

GET /?versions&delimiter=/ HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
Date: Wed, 02 Feb 2011 20:34:56 GMT
Authorization: authorization string

Sample Response

The list of keys from the speciﬁed bucket is shown in the following response.

The response returns the sample.jpg key in a <Version> element. However, because all the other keys
contain the specified delimiter, a distinct substring, from the beginning of the key to the first occurrence
of the delimiter, from each of these keys is returned in a <CommonPrefixes> element. The key substrings,
photos/ and videos/, in the <CommonPrefixes> element indicate that there are one or more keys with
these key prefixes.

This is a useful scenario if you use key preﬁxes for your objects to create a logical folder-like structure. In
this case, you can interpret the result as the folders photos/ and videos/ have one or more objects.

API Version 2006-03-01

226
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>mvbucketwithversionon1</Name>
<Prefix></Prefix>
<KeyMarker></KeyMarker>
<VersionIdMarker></VersionIdMarker>
<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>

<Version>
<Key>Sample.jpg</Key>
<VersionId>toxMzQlBsGyGCz1YuMWMp90cdXLzqOCH</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2011-02-02T18:46:20.000Z</LastModified>
<ETag>"3305f2cfc46c0f04559748bb039d69ae"</ETag>
<Size>3191</Size>
<Owner>
<ID>852b113e7a2f25102679df27bb0ae12b3f85be6f290b936c4393484be31bebcc</ID>
<DisplayName>display-name</DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>

<CommonPrefixes>
<Prefix>photos/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>videos/</Prefix>
</CommonPrefixes>
</ListVersionsResult>

In addition to the delimiter parameter, you can ﬁlter results by adding a preﬁx parameter as shown in
the following request.

GET /?versions&prefix=photos/2006/&delimiter=/ HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
Date: Wed, 02 Feb 2011 19:34:02 GMT
Authorization: authorization string

In this case, the response will include only objects keys that start with the specified prefix. The value
returned in the <CommonPrefixes> element is a substring from the beginning of the key to the first
occurrence of the specified delimiter after the prefix.

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

227
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<IsLatest>true</IsLatest>
<LastModified>2011-02-02T18:47:27.000Z</LastModified>
<ETag>"d41d8cd98f00b204e9800998ecf8427e"</ETag>
<Size>0</Size>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>display-name</DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>
<CommonPrefixes>
<Prefix>photos/2006/February/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/January/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/March/</Prefix>
</CommonPrefixes>
</ListVersionsResult>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

228
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ListParts
Service: Amazon Simple Storage Service

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 (see
CreateMultipartUpload (p. 32)). This request returns a maximum of 1,000 uploaded parts. The default
number of parts returned is 1,000 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.

For more information on multipart uploads, see Uploading Objects Using Multipart Upload.

For information on permissions required to use the multipart upload API, see Multipart Upload API and
Permissions.

The following operations are related to ListParts:

• CreateMultipartUpload (p. 32)

• UploadPart (p. 360)
• CompleteMultipartUpload (p. 10)
• AbortMultipartUpload (p. 7)
• ListMultipartUploads (p. 194)

Request Syntax

GET /Key+?MaxParts=MaxParts&PartNumberMarker=PartNumberMarker&UploadId=UploadId HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-request-payer: RequestPayer

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 229)

Name of the bucket to which the parts are being uploaded.

Object key for which the multipart upload was initiated.

Length Constraints: Minimum length of 1.

max-parts (p. 229)

Sets the maximum number of parts to return.

part-number-marker (p. 229)

Speciﬁes the part after which listing should begin. Only parts with higher part numbers will be
listed.

API Version 2006-03-01

229
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

uploadId (p. 229)

Upload ID identifying the multipart upload whose parts are being listed.
x-amz-request-payer (p. 229)

Valid Values: requester

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
x-amz-abort-date: AbortDate
x-amz-abort-rule-id: AbortRuleId
x-amz-request-charged: RequestCharged
<?xml version="1.0" encoding="UTF-8"?>
<ListPartsOutput>
<Bucket>string</Bucket>
<Key>string</Key>
<UploadId>string</UploadId>
<PartNumberMarker>integer</PartNumberMarker>
<NextPartNumberMarker>integer</NextPartNumberMarker>
<MaxParts>integer</MaxParts>
<IsTruncated>boolean</IsTruncated>
<Part>
<ETag>string</ETag>
<LastModified>timestamp</LastModified>
<PartNumber>integer</PartNumber>
<Size>integer</Size>
</Part>
...
<Initiator>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Initiator>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
<StorageClass>string</StorageClass>
</ListPartsOutput>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

x-amz-abort-date (p. 230)

If the bucket has a lifecycle rule conﬁgured with an action to abort incomplete multipart uploads
and the preﬁx in the lifecycle rule matches the object name in the request, then the response
includes this header indicating when the initiated multipart upload will become eligible for abort

API Version 2006-03-01

230
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

operation. For more information, see Aborting Incomplete Multipart Uploads Using a Bucket
Lifecycle Policy.

The response will also include the x-amz-abort-rule-id header that will provide the ID of the
lifecycle conﬁguration rule that deﬁnes this action.
x-amz-abort-rule-id (p. 230)

This header is returned along with the x-amz-abort-date header. It identifies applicable lifecycle
configuration rule that defines the action to abort incomplete multipart uploads.
x-amz-request-charged (p. 230)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

The following data is returned in XML format by the service.

ListPartsOutput (p. 230)

Root level tag for the ListPartsOutput parameters.

Required: Yes
Bucket (p. 230)

Name of the bucket to which the multipart upload was initiated.

Type: String
Initiator (p. 230)

Container element that identiﬁes who initiated the multipart upload. If the initiator is an AWS
account, this element provides the same information as the Owner element. If the initiator is an IAM
User, this element provides the user ARN and display name.

Type: Initiator (p. 469) data type

IsTruncated (p. 230)

Indicates whether the returned list of parts is truncated. A true value indicates that the list was
truncated. A list can be truncated if the number of parts exceeds the limit returned in the MaxParts
element.

Type: Boolean
Key (p. 230)

Object key for which the multipart upload was initiated.

Type: String

Length Constraints: Minimum length of 1.

MaxParts (p. 230)

Maximum number of parts that were allowed in the response.

Type: Integer
NextPartNumberMarker (p. 230)

When a list is truncated, this element speciﬁes the last part in the list, as well as the value to use for
the part-number-marker request parameter in a subsequent request.

API Version 2006-03-01

231
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Type: Integer
Owner (p. 230)

Container element that identiﬁes the object owner, after the object is created. If multipart upload is
initiated by an IAM user, this element provides the parent account ID and display name.

Type: Owner (p. 512) data type

Part (p. 230)

Container for elements related to a particular part. A response can contain zero or more Part
elements.

Type: Array of Part (p. 514) data types

PartNumberMarker (p. 230)

When a list is truncated, this element speciﬁes the last part in the list, as well as the value to use for
the part-number-marker request parameter in a subsequent request.

Type: Integer
StorageClass (p. 230)

Class of storage (STANDARD or REDUCED_REDUNDANCY) used to store the uploaded object.

Type: String

Valid Values: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA |

INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE
UploadId (p. 230)

Upload ID identifying the multipart upload whose parts are being listed.

Type: String

Examples
Sample Request

Assume you have uploaded parts with sequential part numbers starting with 1. The following List Parts
request speciﬁes max-parts and part-number-marker query parameters. The request lists the ﬁrst
two parts that follow part number 1, that is, you will get parts 2 and 3 in the response. If more parts
exist, the result is a truncated result and therefore the response will return an IsTruncated element
with the value true. The response will also return the NextPartNumberMarker element with the value
3, which should be used for the value of the part-number-marker request query string parameter in
the next ListParts request.

GET /example-object?
uploadId=XXBsb2FkIElEIGZvciBlbHZpbmcncyVcdS1tb3ZpZS5tMnRzEEEwbG9hZA&max-parts=2&part-
number-marker=1 HTTP/1.1
Host: example-bucket.s3.<Region>.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

Sample Response

API Version 2006-03-01

232
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<?xml version="1.0" encoding="UTF-8"?>

<ListPartsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Bucket>example-bucket</Bucket>
<Key>example-object</Key>
<UploadId>XXBsb2FkIElEIGZvciBlbHZpbmcncyVcdS1tb3ZpZS5tMnRzEEEwbG9hZA</UploadId>
<Initiator>
<ID>arn:aws:iam::111122223333:user/some-user-11116a31-17b5-4fb7-9df5-b288870f11xx</
ID>
<DisplayName>umat-user-11116a31-17b5-4fb7-9df5-b288870f11xx</DisplayName>
</Initiator>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>someName</DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
<PartNumberMarker>1</PartNumberMarker>
<NextPartNumberMarker>3</NextPartNumberMarker>
<MaxParts>2</MaxParts>
<IsTruncated>true</IsTruncated>
<Part>
<PartNumber>2</PartNumber>
<LastModified>2010-11-10T20:48:34.000Z</LastModified>
<ETag>"7778aef83f66abc1fa1e8477f296d394"</ETag>
<Size>10485760</Size>
</Part>
<Part>
<PartNumber>3</PartNumber>
<LastModified>2010-11-10T20:48:33.000Z</LastModified>
<ETag>"aaaa18db4cc2f85cedef654fccc4a4x8"</ETag>
<Size>10485760</Size>
</Part>
</ListPartsResult>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

233
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketAccelerateConﬁguration
Service: Amazon Simple Storage Service

Sets the accelerate conﬁguration of an existing bucket. Amazon S3 Transfer Acceleration is a bucket-level
feature that enables you to perform faster data transfers to Amazon S3.

To use this operation, you must have permission to perform the s3:PutAccelerateConﬁguration action.
The bucket owner has this permission by default. The bucket owner can grant this permission to others.
For more information about permissions, see Permissions Related to Bucket Subresource Operations and
Managing Access Permissions to Your Amazon S3 Resources.

The Transfer Acceleration state of a bucket can be set to one of the following two values:

• Enabled – Enables accelerated data transfers to the bucket.

• Suspended – Disables accelerated data transfers to the bucket.

The GetBucketAccelerateConﬁguration (p. 79) operation returns the transfer acceleration state of a
bucket.

After setting the Transfer Acceleration state of a bucket to Enabled, it might take up to thirty minutes
before the data transfer rates to the bucket increase.

The name of the bucket used for Transfer Acceleration must be DNS-compliant and must not contain
periods (".").

For more information about transfer acceleration, see Transfer Acceleration.

The following operations are related to PutBucketAccelerateConfiguration:

• GetBucketAccelerateConﬁguration (p. 79)

• CreateBucket (p. 27)

Request Syntax

PUT /?accelerate HTTP/1.1

Host: Bucket.s3.amazonaws.com
<?xml version="1.0" encoding="UTF-8"?>
<AccelerateConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>string</Status>
</AccelerateConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 234)

Name of the bucket for which the accelerate conﬁguration is set.

Request Body
The request accepts the following data in XML format.

AccelerateConﬁguration (p. 234)

Root level tag for the AccelerateConﬁguration parameters.

API Version 2006-03-01

234
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Required: Yes
Status (p. 234)

Speciﬁes the transfer acceleration status of the bucket.

Type: String

Valid Values: Enabled | Suspended

Required: No

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
Sample Request: Add transfer acceleration conﬁguration to set acceleration status

The following is an example of a PUT /?accelerate request that enables transfer acceleration for the
bucket named examplebucket.

PUT /?accelerate HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Mon, 11 Apr 2016 12:00:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: length

<AccelerateConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
</AccelerateConfiguration>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Mon, 11 Apr 2016 12:00:00 GMT
Content-Length: 0
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++

API Version 2006-03-01

235
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for Go

• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

236
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketAcl
Service: Amazon Simple Storage Service

Sets the permissions on an existing bucket using access control lists (ACL). For more information, see
Using ACLs. To set the ACL of a bucket, you must have WRITE_ACP permission.

You can use one of the following two ways to set a bucket's permissions:

• Specify the ACL in the request body

• Specify permissions using request headers

Note
You cannot specify access permission using both the body and the request headers.

Depending on your application needs, you may choose to set the ACL on a bucket using either the
request body or the headers. For example, if you have an existing application that updates a bucket ACL
using the request body, then you can continue to use that approach.

Access Permissions

You can set access permissions using one of the following methods:

• Specify a canned ACL with the x-amz-acl request header. Amazon S3 supports a set of predefined
ACLs, known as canned ACLs. Each canned ACL has a predefined set of grantees and permissions.
Specify the canned ACL name as the value of x-amz-acl. If you use this header, you cannot use other
access control-specific headers in your request. For more information, see Canned ACL.
• Specify access permissions explicitly with the x-amz-grant-read, x-amz-grant-read-acp, x-
amz-grant-write-acp, and x-amz-grant-full-control headers. When using these headers,
you specify explicit access permissions and grantees (AWS accounts or Amazon S3 groups) who will
receive the permission. If you use these ACL-specific headers, you cannot use the x-amz-acl header
to set a canned ACL. These parameters map to the set of permissions that Amazon S3 supports in an
ACL. For more information, see Access Control List (ACL) Overview.

For example, the following x-amz-grant-write header grants create, overwrite, and delete objects
permission to LogDelivery group predeﬁned by Amazon S3 and two AWS accounts identiﬁed by their
email addresses.

x-amz-grant-write: uri="http://acs.amazonaws.com/groups/s3/LogDelivery",
emailAddress="[email protected]", emailAddress="[email protected]"

You can use either a canned ACL or specify access permissions explicitly. You cannot do both.

Grantee Values

You can specify the person (grantee) to whom you're assigning access rights (using request elements) in
the following ways:

• By Email address:

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="AmazonCustomerByEmail"><EmailAddress><>[email protected]<></
EmailAddress>lt;/Grantee>

API Version 2006-03-01

237
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

The grantee is resolved to the CanonicalUser and, in a response to a GET Object acl request, appears as
the CanonicalUser.
• By the person's ID:

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser"><ID><>ID<></ID><DisplayName><>GranteesEmail<></
DisplayName> </Grantee>

DisplayName is optional and ignored in the request

• By URI:

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="Group"><URI><>http://acs.amazonaws.com/groups/global/
AuthenticatedUsers<></URI></Grantee>

Related Resources

• CreateBucket (p. 27)

• DeleteBucket (p. 41)
• GetObjectAcl (p. 150)

Request Syntax

PUT /?acl HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-acl: ACL
Content-MD5: ContentMD5
x-amz-grant-full-control: GrantFullControl
x-amz-grant-read: GrantRead
x-amz-grant-read-acp: GrantReadACP
x-amz-grant-write: GrantWrite
x-amz-grant-write-acp: GrantWriteACP
<?xml version="1.0" encoding="UTF-8"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<AccessControlList>
<Grant>
<Grantee>
<DisplayName>string</DisplayName>
<EmailAddress>string</EmailAddress>
<ID>string</ID>
<xsi:type>string</xsi:type>
<URI>string</URI>
</Grantee>
<Permission>string</Permission>
</Grant>
</AccessControlList>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
</AccessControlPolicy>

URI Request Parameters

The request requires the following URI parameters.

API Version 2006-03-01

238
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Bucket (p. 238)

The bucket to which to apply the ACL.

Content-MD5 (p. 238)

The base64-encoded 128-bit MD5 digest of the data. This header must be used as a message
integrity check to verify that the request body was not corrupted in transit. For more information, go
to RFC 1864.
x-amz-acl (p. 238)

The canned ACL to apply to the bucket.

Valid Values: private | public-read | public-read-write | authenticated-read

x-amz-grant-full-control (p. 238)

Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
x-amz-grant-read (p. 238)

Allows grantee to list the objects in the bucket.

x-amz-grant-read-acp (p. 238)

Allows grantee to read the bucket ACL.

x-amz-grant-write (p. 238)

Allows grantee to create, overwrite, and delete any object in the bucket.
x-amz-grant-write-acp (p. 238)

Allows grantee to write the ACL for the applicable bucket.

Request Body
The request accepts the following data in XML format.

AccessControlPolicy (p. 238)

Root level tag for the AccessControlPolicy parameters.

Required: Yes
Grants (p. 238)

A list of grants.

Type: Array of Grant (p. 466) data types

Required: No
Owner (p. 238)

Container for the bucket owner's display name and ID.

Type: Owner (p. 512) data type

Required: No

Response Syntax

HTTP/1.1 200

API Version 2006-03-01

239
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
Sample Request: Access permissions speciﬁed in the body

The following request grants access permission to the existing examplebucket bucket. The request
speciﬁes the ACL in the body. In addition to granting full control to the bucket owner, the XML speciﬁes
the following grants.

• Grant the AllUsers group READ permission on the bucket.

• Grant the LogDelivery group WRITE permission on the bucket.
• Grant an AWS account, identiﬁed by email address, WRITE_ACP permission.
• Grant an AWS account, identiﬁed by canonical user ID, READ_ACP permission.

PUT ?acl HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Content-Length: 1660
x-amz-date: Thu, 12 Apr 2012 20:04:21 GMT
Authorization: authorization string

<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Owner>
<ID>852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID</ID>
<DisplayName>OwnerDisplayName</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser">
<ID>852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID</ID>
<DisplayName>OwnerDisplayName</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
<URI xmlns="">http://acs.amazonaws.com/groups/global/AllUsers</URI>
</Grantee>
<Permission xmlns="">READ</Permission>
</Grant>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
<URI xmlns="">http://acs.amazonaws.com/groups/s3/LogDelivery</URI>
</Grantee>
<Permission xmlns="">WRITE</Permission>
</Grant>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="AmazonCustomerByEmail">
<EmailAddress xmlns="">[email protected]</EmailAddress>
</Grantee>
<Permission xmlns="">WRITE_ACP</Permission>
</Grant>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser">

API Version 2006-03-01

240
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<ID xmlns="">f30716ab7115dcb44a5ef76e9d74b8e20567f63TestAccountCanonicalUserID</ID>
</Grantee>
<Permission xmlns="">READ_ACP</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: NxqO3PNiMHXXGwjgv15LLgUoAmPVmG0xtZw2sxePXLhpIvcyouXDrcQUaWWXcOK0
x-amz-request-id: C651BC9B4E1BD401
Date: Thu, 12 Apr 2012 20:04:28 GMT
Content-Length: 0
Server: AmazonS3

Sample Request: Access permissions speciﬁed using headers

The following request uses ACL-speciﬁc request headers to grant the following permissions:

• Write permission to the Amazon S3 LogDelivery group and an AWS account identiﬁed by the email
[email protected].
• Read permission to the Amazon S3 AllUsers group

PUT ?acl HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Sun, 29 Apr 2012 22:00:57 GMT
x-amz-grant-write: uri="http://acs.amazonaws.com/groups/s3/LogDelivery",
emailAddress="[email protected]"
x-amz-grant-read: uri="http://acs.amazonaws.com/groups/global/AllUsers"
Accept: */*
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: 0w9iImt23VF9s6QofOTDzelF7mrryz7d04Mw23FQCi4O205Zw28Zn+d340/RytoQ
x-amz-request-id: A6A8F01A38EC7138
Date: Sun, 29 Apr 2012 22:01:10 GMT
Content-Length: 0
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

API Version 2006-03-01

241
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

242
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketAnalyticsConﬁguration
Service: Amazon Simple Storage Service

Sets an analytics configuration for the bucket (specified by the analytics configuration ID). You can have
up to 1,000 analytics configurations per bucket.

You can choose to have storage class analysis export analysis reports sent to a comma-separated values
(CSV) flat file. See the DataExport request element. Reports are updated daily and are based on the
object filters that you configure. When selecting data export, you specify a destination bucket and an
optional destination prefix where the file is written. You can export the data to a destination bucket in
a different account. However, the destination bucket must be in the same Region as the bucket that you
are making the PUT analytics configuration to. For more information, see Amazon S3 Analytics – Storage
Class Analysis.
Important
You must create a bucket policy on the destination bucket where the exported file is written
to grant permissions to Amazon S3 to write objects to the bucket. For an example policy, see
Granting Permissions for Amazon S3 Inventory and Storage Class Analysis.

Special Errors

• • HTTP Error: HTTP 400 Bad Request

• Code: InvalidArgument
• Cause: Invalid argument.
• • HTTP Error: HTTP 400 Bad Request
• Code: TooManyConfigurations
• Cause: You are attempting to create a new configuration but have already reached the 1,000-
configuration limit.
• • HTTP Error: HTTP 403 Forbidden
• Code: AccessDenied
• Cause: You are not the owner of the specified bucket, or you do not have the
s3:PutAnalyticsConfiguration bucket permission to set the configuration on the bucket.

Related Resources

• GetBucketAnalyticsConﬁguration (p. 85)

• DeleteBucketAnalyticsConﬁguration (p. 43)
• ListBucketAnalyticsConﬁgurations (p. 179)

Request Syntax

PUT /?analytics&Id=Id HTTP/1.1

Host: Bucket.s3.amazonaws.com
<?xml version="1.0" encoding="UTF-8"?>
<AnalyticsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>string</Id>
<Filter>
<And>
<Prefix>string</Prefix>
<Tag>

API Version 2006-03-01

243
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<Key>string</Key>
<Value>string</Value>
</Tag>
...
</And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</Filter>
<StorageClassAnalysis>
<DataExport>
<Destination>
<S3BucketDestination>
<Bucket>string</Bucket>
<BucketAccountId>string</BucketAccountId>
<Format>string</Format>
<Prefix>string</Prefix>
</S3BucketDestination>
</Destination>
<OutputSchemaVersion>string</OutputSchemaVersion>
</DataExport>
</StorageClassAnalysis>
</AnalyticsConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 243)

The name of the bucket to which an analytics conﬁguration is stored.

id (p. 243)

The ID that identiﬁes the analytics conﬁguration.

Request Body
The request accepts the following data in XML format.

AnalyticsConﬁguration (p. 243)

Root level tag for the AnalyticsConﬁguration parameters.

Required: Yes
Filter (p. 243)

Type: AnalyticsFilter (p. 421) data type

Required: No
Id (p. 243)

The ID that identiﬁes the analytics conﬁguration.

Type: String

API Version 2006-03-01

244
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Required: Yes
StorageClassAnalysis (p. 243)

Contains data related to access patterns to be collected and made available to analyze the tradeoﬀs
between diﬀerent storage classes.

Type: StorageClassAnalysis (p. 557) data type

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
Example 1: Creating an analytics conﬁguration

The following PUT request for the bucket examplebucket creates a new or replaces an existing
analytics configuration with the ID report1. The configuration is defined in the request body.

PUT /?analytics&id=report1 HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Mon, 31 Oct 2016 12:00:00 GMT
Authorization: authorization string
Content-Length: length

<?xml version="1.0" encoding="UTF-8"?>

<AnalyticsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>report1</Id>
<Filter>
<And>
<Prefix>images/</Prefix>
<Tag>
<Key>dog</Key>
<Value>corgi</Value>
</Tag>
</And>
</Filter>
<StorageClassAnalysis>
<DataExport>
<OutputSchemaVersion>V_1</OutputSchemaVersion>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<BucketAccountId>123456789012</BucketAccountId>
<Bucket>arn:aws:s3:::destination-bucket</Bucket>
<Prefix>destination-prefix</Prefix>
</S3BucketDestination>
</Destination>
</DataExport>
</StorageClassAnalysis>
</AnalyticsConfiguration>

Sample Response

API Version 2006-03-01

245
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Mon, 31 Oct 2016 12:00:00 GMT
Content-Length: 0
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

246
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketCors
Service: Amazon Simple Storage Service

Sets the cors conﬁguration for your bucket. If the conﬁguration exists, Amazon S3 replaces it.

To use this operation, you must be allowed to perform the s3:PutBucketCORS action. By default, the
bucket owner has this permission and can grant it to others.

You set this conﬁguration 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 Amazon
S3 bucket at my.example.bucket.com by using the browser's XMLHttpRequest capability.

To enable cross-origin resource sharing (CORS) on a bucket, you add the cors subresource to the bucket.
The cors subresource is an XML document in which you conﬁgure 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 Amazon S3 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.

For more information about CORS, go to Enabling Cross-Origin Resource Sharing in the Amazon Simple
Storage Service Developer Guide.

Related Resources

• GetBucketCors (p. 89)

• DeleteBucketCors (p. 45)
• Appendix: OPTIONS object (p. 730)

Request Syntax

PUT /?cors HTTP/1.1

Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<CORSRule>
<AllowedHeader>string</AllowedHeader>
...
<AllowedMethod>string</AllowedMethod>
...
<AllowedOrigin>string</AllowedOrigin>
...
<ExposeHeader>string</ExposeHeader>
...
<MaxAgeSeconds>integer</MaxAgeSeconds>
</CORSRule>
...
</CORSConfiguration>

API Version 2006-03-01

247
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 247)

Speciﬁes the bucket impacted by the corsconﬁguration.

Content-MD5 (p. 247)

Request Body
The request accepts the following data in XML format.

CORSConﬁguration (p. 247)

Root level tag for the CORSConﬁguration parameters.

Required: Yes
CORSRule (p. 247)

A set of origins and methods (cross-origin access that you want to allow). You can add up to 100
rules to the conﬁguration.

Type: Array of CORSRule (p. 436) data types

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
Example: Cors conﬁguration on a bucket with two rules

• The first CORSRule allows cross-origin PUT, POST, and DELETE requests whose origin is http://
www.example.com origins. The rule also allows all headers in a pre-flight OPTIONS request through
the Access-Control-Request-Headers header. Therefore, in response to any pre-flight OPTIONS
request, Amazon S3 will return any requested headers.
• The second rule allows cross-origin GET requests from all the origins. The '*' wildcard character refers
to all origins.

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

API Version 2006-03-01

248
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

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

Example: Cors conﬁguration allows cross-origin PUT and POST requests from http://
www.example.com

The cors configuration also allows additional optional configuration parameters as shown in the
following cors configuration on a bucket. For example,

In the preceding conﬁguration, CORSRule includes the following additional optional parameters:

• MaxAgeSeconds—Specifies the time in seconds that the browser will cache an Amazon S3 response
to a pre-flight OPTIONS request for the specified resource. In this example, this parameter is 3000
seconds. Caching enables the browsers to avoid sending pre-flight OPTIONS request to Amazon S3 for
repeated requests.
• ExposeHeader—Identifies the response header (in this case x-amz-server-side-encryption)
that you want customers to be able to access from their applications (for example, from a JavaScript
XMLHttpRequest object).

<CORSConfiguration>
<CORSRule>
<AllowedOrigin>http://www.example.com</AllowedOrigin>
<AllowedMethod>PUT</AllowedMethod>
<AllowedMethod>POST</AllowedMethod>
<AllowedMethod>DELETE</AllowedMethod>
<AllowedHeader>*</AllowedHeader>
<MaxAgeSeconds>3000</MaxAgeSeconds>
<ExposeHeader>x-amz-server-side-encryption</ExposeHeader>
</CORSRule>
</CORSConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

249
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketEncryption
Service: Amazon Simple Storage Service

This implementation of the PUT operation uses the encryption subresource to set the default
encryption state of an existing bucket.

This implementation of the PUT operation sets default encryption for a bucket using server-side
encryption with Amazon S3-managed keys SSE-S3 or AWS KMS customer master keys (CMKs) (SSE-
KMS). For information about the Amazon S3 default encryption feature, see Amazon S3 Default Bucket
Encryption.
Important
This operation requires AWS Signature Version 4. For more information, see Authenticating
Requests (AWS Signature Version 4).

To use this operation, you must have permissions to perform the s3:PutEncryptionConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple
Storage Service Developer Guide.

Related Resources

• GetBucketEncryption (p. 92)

• DeleteBucketEncryption (p. 47)

Request Syntax

PUT /?encryption HTTP/1.1

Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<ServerSideEncryptionConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<ApplyServerSideEncryptionByDefault>
<KMSMasterKeyID>string</KMSMasterKeyID>
<SSEAlgorithm>string</SSEAlgorithm>
</ApplyServerSideEncryptionByDefault>
</Rule>
...
</ServerSideEncryptionConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 250)

Speciﬁes default encryption for a bucket using server-side encryption with Amazon S3-managed
keys (SSE-S3) or customer master keys stored in AWS KMS (SSE-KMS). For information about the
Amazon S3 default encryption feature, see Amazon S3 Default Bucket Encryption in the Amazon
Simple Storage Service Developer Guide.
Content-MD5 (p. 250)

The base64-encoded 128-bit MD5 digest of the server-side encryption conﬁguration. This parameter
is auto-populated when using the command from the CLI.

API Version 2006-03-01

250
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Request Body
The request accepts the following data in XML format.

ServerSideEncryptionConﬁguration (p. 250)

Root level tag for the ServerSideEncryptionConﬁguration parameters.

Required: Yes
Rule (p. 250)

Container for information about a particular server-side encryption conﬁguration rule.

Type: Array of ServerSideEncryptionRule (p. 550) data types

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
In the request, you specify the encryption configuration in the request body. The encryption
configuration is specified as XML, as shown in the following examples that show setting encryption using
SSE-S3 or SSE-KMS.

Request Body for Setting SSE-S3

Request Body for Setting SSE-KMS

<ServerSideEncryptionConfiguration xmlns="http://s3.amazonaws.com/
doc/2006-03-01/">
<Rule>
<ApplyServerSideEncryptionByDefault>
<KMSMasterKeyID>arn:aws:kms:us-east-1:1234/5678example</
KMSMasterKeyID>
</ApplyServerSideEncryptionByDefault>
</Rule>
</ServerSideEncryptionConfiguration>

API Version 2006-03-01

251
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Set the Default Encryption Conﬁguration for an S3 Bucket

The following is an example of a PUT /? encryption request that speciﬁes to use AWS KMS encryption.

PUT /?encryption HTTP/1.1

Host: examplebucket.<Region>s3.amazonaws.com
Date: Wed, 06 Sep 2017 12:00:00 GMT
Authorization: authorization string
Content-Length: length

<ServerSideEncryptionConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<ApplyServerSideEncryptionByDefault>
<SSEAlgorithm>aws:kms</SSEAlgorithm>
<KMSMasterKeyID>arn:aws:kms:us-east-1:1234/5678example</KMSMasterKeyID>
</ApplyServerSideEncryptionByDefault>
</Rule>
</ServerSideEncryptionConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

252
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketInventoryConﬁguration
Service: Amazon Simple Storage Service

This implementation of the PUT operation adds an inventory configuration (identified by the inventory
ID) to the bucket. You can have up to 1,000 inventory configurations per bucket.

Amazon S3 inventory generates inventories of the objects in the bucket on a daily or weekly basis, and
the results are published to a flat file. The bucket that is inventoried is called the source bucket, and the
bucket where the inventory flat file is stored is called the destination bucket. The destination bucket must
be in the same AWS Region as the source bucket.

When you configure an inventory for a source bucket, you specify the destination bucket where you
want the inventory to be stored, and whether to generate the inventory daily or weekly. You can
also configure what object metadata to include and whether to inventory all object versions or only
current versions. For more information, see Amazon S3 Inventory in the Amazon Simple Storage Service
Developer Guide.
Important
You must create a bucket policy on the destination bucket to grant permissions to Amazon
S3 to write objects to the bucket in the defined location. For an example policy, see Granting
Permissions for Amazon S3 Inventory and Storage Class Analysis.

To use this operation, you must have permissions to perform the s3:PutInventoryConfiguration
action. The bucket owner has this permission by default and can grant this permission to others. For
more information about permissions, see Permissions Related to Bucket Subresource Operations and
Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple Storage Service
Developer Guide.

Special Errors

• HTTP 400 Bad Request Error

• Code: InvalidArgument
• Cause: Invalid Argument
• HTTP 400 Bad Request Error
• Code: TooManyConfigurations
• Cause: You are attempting to create a new configuration but have already reached the 1,000-
configuration limit.
• HTTP 403 Forbidden Error
• Code: AccessDenied
• Cause: You are not the owner of the specified bucket, or you do not have the
s3:PutInventoryConfiguration bucket permission to set the configuration on the bucket

Related Resources

• GetBucketInventoryConﬁguration (p. 95)

• DeleteBucketInventoryConﬁguration (p. 49)
• ListBucketInventoryConﬁgurations (p. 183)

Request Syntax

PUT /?inventory&Id=Id HTTP/1.1

Host: Bucket.s3.amazonaws.com
<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

253
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<InventoryConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Destination>
<S3BucketDestination>
<AccountId>string</AccountId>
<Bucket>string</Bucket>
<Encryption>
<SSE-KMS>
<KeyId>string</KeyId>
</SSE-KMS>
<SSE-S3>
</SSE-S3>
</Encryption>
<Format>string</Format>
<Prefix>string</Prefix>
</S3BucketDestination>
</Destination>
<IsEnabled>boolean</IsEnabled>
<Filter>
<Prefix>string</Prefix>
</Filter>
<Id>string</Id>
<IncludedObjectVersions>string</IncludedObjectVersions>
<OptionalFields>
<Field>string</Field>
</OptionalFields>
<Schedule>
<Frequency>string</Frequency>
</Schedule>
</InventoryConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 253)

The name of the bucket where the inventory conﬁguration will be stored.
id (p. 253)

The ID used to identify the inventory conﬁguration.

Request Body
The request accepts the following data in XML format.

InventoryConﬁguration (p. 253)

Root level tag for the InventoryConﬁguration parameters.

Required: Yes
Destination (p. 253)

Contains information about where to publish the inventory results.

Type: InventoryDestination (p. 473) data type

Required: Yes
Filter (p. 253)

Specifies an inventory filter. The inventory only includes objects that meet the filter's criteria.

API Version 2006-03-01

254
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Type: InventoryFilter (p. 475) data type

Required: No
Id (p. 253)

The ID used to identify the inventory conﬁguration.

Type: String

Required: Yes
IncludedObjectVersions (p. 253)

Type: String

Valid Values: All | Current

Required: Yes
IsEnabled (p. 253)

Speciﬁes whether the inventory is enabled or disabled. If set to True, an inventory list is generated.
If set to False, no inventory list is generated.

Type: Boolean

Required: Yes
OptionalFields (p. 253)

Contains the optional ﬁelds that are included in the inventory results.

Type: Array of strings

Valid Values: Size | LastModifiedDate | StorageClass | ETag |

Required: No
Schedule (p. 253)

Speciﬁes the schedule for generating inventory results.

Type: InventorySchedule (p. 477) data type

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

API Version 2006-03-01

255
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Example
Example: Create an inventory conﬁguration

The following PUT request and response for the bucket examplebucket creates a new or replaces an
existing inventory configuration with the ID report1. The configuration is defined in the request body.

PUT /?inventory&id=report1 HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Mon, 31 Oct 2016 12:00:00 GMT
Authorization: authorization string
Content-Length: length

<?xml version="1.0" encoding="UTF-8"?>

<InventoryConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>report1</Id>
<IsEnabled>true</IsEnabled>
<Filter>
<Prefix>filterPrefix</Prefix>
</Filter>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<AccountId>123456789012</AccountId>
<Bucket>arn:aws:s3:::destination-bucket</Bucket>
<Prefix>prefix1</Prefix>
<Encryption>
<SSE-KMS>
<KeyId>arn:aws:kms:us-
west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab</KeyId>
</SSE-KMS>
</Encryption>
</S3BucketDestination>
</Destination>
<Schedule>
<Frequency>Daily</Frequency>
</Schedule>
<IncludedObjectVersions>All</IncludedObjectVersions>
<OptionalFields>
<Field>Size</Field>
<Field>LastModifiedDate</Field>
<Field>ETag</Field>
<Field>StorageClass</Field>
<Field>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
<Field>EncryptionStatus</Field>
<Field>ObjectLockRetainUntilDate</Field>
<Field>ObjectLockMode</Field>
<Field>ObjectLockLegalHoldStatus</Field>
</OptionalFields>
</InventoryConfiguration>

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Mon, 31 Oct 2016 12:00:00 GMT
Content-Length: 0
Server: AmazonS3

API Version 2006-03-01

256
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

257
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketLifecycle
Service: Amazon Simple Storage Service
Important
For an updated version of this API, see PutBucketLifecycleConfiguration (p. 264). This version
has been deprecated. Existing lifecycle configurations will work. For new lifecycle configurations,
use the updated API.

Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration. For
information about lifecycle configuration, see Object Lifecycle Management in the Amazon Simple
Storage Service Developer Guide.

By default, all Amazon S3 resources, including buckets, objects, and related subresources (for
example, lifecycle conﬁguration and website conﬁguration) are private. Only the resource owner,
the AWS account that created the resource, can access it. The resource owner can optionally grant
access permissions to others by writing an access policy. For this operation, users must get the
s3:PutLifecycleConfiguration permission.

You can also explicitly deny permissions. Explicit denial also supersedes any other permissions. If you
want to prevent users or accounts from removing or deleting objects from your bucket, you must deny
them permissions for the following actions:

• s3:DeleteObject
• s3:DeleteObjectVersion
• s3:PutLifecycleConfiguration

For more information about permissions, see Managing Access Permissions to your Amazon S3 Resources
in the Amazon Simple Storage Service Developer Guide.

For more examples of transitioning objects to storage classes such as STANDARD_IA or ONEZONE_IA, see
Examples of Lifecycle Conﬁguration.

Related Resources

• GetBucketLifecycle (p. 99)(Deprecated)

• GetBucketLifecycleConﬁguration (p. 102)
• RestoreObject (p. 343)
• By default, a resource owner—in this case, a bucket owner, which is the AWS account that created the
bucket—can perform any of the operations. A resource owner can also grant others permission to
perform the operation. For more information, see the following topics in the Amazon Simple Storage
Service Developer Guide:
• Specifying Permissions in a Policy
• Managing Access Permissions to your Amazon S3 Resources

Request Syntax

PUT /?lifecycle HTTP/1.1

Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<AbortIncompleteMultipartUpload>
<DaysAfterInitiation>integer</DaysAfterInitiation>

API Version 2006-03-01

258
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 258)

Content-MD5 (p. 258)

Request Body
The request accepts the following data in XML format.

LifecycleConﬁguration (p. 258)

Root level tag for the LifecycleConﬁguration parameters.

Required: Yes
Rule (p. 258)

Speciﬁes lifecycle conﬁguration rules for an Amazon S3 bucket.

Type: Array of Rule (p. 540) data types

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

API Version 2006-03-01

259
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Examples
Sample Request: Body of a basic lifecycle conﬁguration

In the request, you specify the lifecycle configuration in the request body. The lifecycle configuration
is specified as XML. The following is an example of a basic lifecycle configuration. It specifies one rule.
The Prefix in the rule identifies objects to which the rule applies. The rule also specifies two actions
(Transition and Expiration). Each action specifies a timeline when Amazon S3 should perform the
action. The Status indicates whether the rule is enabled or disabled.

<LifecycleConfiguration>
<Rule>
<ID>sample-rule</ID>
<Prefix>key-prefix</Prefix>
<Status>rule-status</Status>
<Transition>
<Date>value</Date>
<StorageClass>storage class</StorageClass>
</Transition>
<Expiration>
<Days>value</Days>
</Expiration>
</Rule>
</LifecycleConfiguration>

Sample Request: Body of a lifecycle conﬁguration specifying noncurrent versions

If the state of your bucket is versioning-enabled or versioning-suspended, you can have many
versions of the same object: one current version and zero or more noncurrent versions. The
following lifecycle configuration specifies the actions (NoncurrentVersionTransition,
NoncurrentVersionExpiration) that are specific to noncurrent object versions.

<LifecycleConfiguration>
<Rule>
<ID>sample-rule</ID>
<Prefix>key-prefix</Prefix>
<Status>rule-status</Status>
<NoncurrentVersionTransition>
<NoncurrentDays>value</NoncurrentDays>
<StorageClass>storage class</StorageClass>
</NoncurrentVersionTransition>
<NoncurrentVersionExpiration>
<NoncurrentDays>value</NoncurrentDays>
</NoncurrentVersionExpiration>
</Rule>
</LifecycleConfiguration>

Sample Request: Body of a lifecycle conﬁguration that speciﬁes a rule with

AbortIncompleteMultipartUpload

You can use the multipart upload API to upload large objects in parts. For more information about
multipart uploads, see Multipart Upload Overview in the Amazon Simple Storage Service Developer Guide.
With lifecycle configuration, you can tell Amazon S3 to abort incomplete multipart uploads, which are
identified by the key name prefix specified in the rule, if they don't complete within a specified number
of days. When Amazon S3 aborts a multipart upload, it deletes all parts associated with the upload. This
ensures that you don't have incomplete multipart uploads that have left parts stored in Amazon S3, so

API Version 2006-03-01

260
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

you don't have to pay storage costs for them. The following is an example lifecycle conﬁguration that
speciﬁes a rule with the AbortIncompleteMultipartUpload action. This action tells Amazon S3 to
abort incomplete multipart uploads seven days after initiation.

<LifecycleConfiguration>
<Rule>
<ID>sample-rule</ID>
<Prefix>SomeKeyPrefix</Prefix>
<Status>rule-status</Status>
<AbortIncompleteMultipartUpload>
<DaysAfterInitiation>7</DaysAfterInitiation>
</AbortIncompleteMultipartUpload>
</Rule>
</LifecycleConfiguration>

Add lifecycle conﬁguration to a bucket that is not versioning-enabled

The following is a sample PUT /?lifecycle request that adds the lifecycle configuration to the
examplebucket bucket. The lifecycle configuration specifies two rules, each with one action:

• The Transition action tells Amazon S3 to transition objects with the "documents/" preﬁx to the
GLACIER storage class 30 days after creation.
• The Expiration action tells Amazon S3 to delete objects with the "logs/" preﬁx 365 days after
creation.

The sample response follows the sample request.

PUT /?lifecycle HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Wed, 14 May 2014 02:11:21 GMT
Content-MD5: q6yJDlIkcBaGGfb3QLY69A==
Authorization: authorization string
Content-Length: 415
<LifecycleConfiguration>
<Rule>
<ID>id1</ID>
<Prefix>documents/</Prefix>
<Status>Enabled</Status>
<Transition>
<Days>30</Days>
<StorageClass>GLACIER</StorageClass>
</Transition>
</Rule>
<Rule>
<ID>id2</ID>
<Prefix>logs/</Prefix>
<Status>Enabled</Status>
<Expiration>
<Days>365</Days>
</Expiration>
</Rule>
</LifecycleConfiguration>

HTTP/1.1 200 OK
x-amz-id-2: r+qR7+nhXtJDDIJ0JJYcd+1j5nM/rUFiiiZ/fNbDOsd3JUE8NWMLNHXmvPfwMpdc
x-amz-request-id: 9E26D08072A8EF9E

API Version 2006-03-01

261
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Date: Wed, 14 May 2014 02:11:22 GMT

Content-Length: 0
Server: AmazonS3

Add lifecycle conﬁguration to a bucket that is versioning-enabled

The following is a sample PUT /?lifecycle request that adds the lifecycle configuration to the
examplebucket bucket. The lifecycle configuration specifies two rules, each with one action. You
specify these actions when your bucket is versioning-enabled or versioning is suspended: :

• The NoncurrentVersionExpiration action tells Amazon S3 to expire noncurrent versions of

objects with the "logs/" preﬁx 100 days after the objects become noncurrent.
• The NoncurrentVersionTransition action tells Amazon S3 to transition noncurrent versions
of objects with the "documents/" preﬁx to the GLACIER storage class 30 days after they become
noncurrent.

The sample response follows the sample request.

PUT /?lifecycle HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Wed, 14 May 2014 02:21:48 GMT
Content-MD5: 96rxH9mDqVNKkaZDddgnw==
Authorization: authorization string
Content-Length: 598
<LifecycleConfiguration>
<Rule>
<ID>id1</ID>
<Prefix>logs/</Prefix>
<Status>Enabled</Status>
<NoncurrentVersionExpiration>
<NoncurrentDays>1</NoncurrentDays>
</NoncurrentVersionExpiration>
</Rule>
<Rule>
<ID>TransitionSoonAfterBecomingNonCurrent</ID>
<Prefix>documents/</Prefix>
<Status>Enabled</Status>
<NoncurrentVersionTransition>
<NoncurrentDays>0</NoncurrentDays>
<StorageClass>GLACIER</StorageClass>
</NoncurrentVersionTransition>
</Rule>
</LifecycleConfiguration>

HTTP/1.1 200 OK
x-amz-id-2: aXQ+KbIrmMmoO//3bMdDTw/CnjArwje+J49Hf+j44yRb/VmbIkgIO5A+PT98Cp/6k07hf+LD2mY=
x-amz-request-id: 02D7EC4C10381EB1
Date: Wed, 14 May 2014 02:21:50 GMT
Content-Length: 0
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

API Version 2006-03-01

262
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

263
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketLifecycleConﬁguration
Service: Amazon Simple Storage Service

Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration.
For information about lifecycle configuration, see Managing Access Permissions to Your Amazon S3
Resources.
Note
Bucket lifecycle configuration now supports specifying a lifecycle rule using an object key name
prefix, one or more object tags, or a combination of both. Accordingly, this section describes
the latest API. The previous version of the API supported filtering based only on an object key
name prefix, which is supported for backward compatibility. For the related API description, see
PutBucketLifecycle (p. 258).

Rules

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 Amazon S3 to perform on
the objects identified by the filter. If the state of your bucket is versioning-enabled or versioning-
suspended, you can have many versions of the same object (one current version and zero or more
noncurrent versions). Amazon S3 provides predefined actions that you can specify for current and
noncurrent object versions.

For more information, see Object Lifecycle Management and Lifecycle Conﬁguration Elements.

Permissions

By default, all Amazon S3 resources are private, including buckets, objects, and related subresources
(for example, lifecycle configuration and website configuration). Only the resource owner (that is,
the AWS account that created it) can access the resource. The resource owner can optionally grant
access permissions to others by writing an access policy. For this operation, a user must get the
s3:PutLifecycleConfiguration permission.

You can also explicitly deny permissions. Explicit deny also supersedes any other permissions. If you want
to block users or accounts from removing or deleting objects from your bucket, you must deny them
permissions for the following actions:

• s3:DeleteObject
• s3:DeleteObjectVersion
• s3:PutLifecycleConﬁguration

For more information about permissions, see Managing Access Permissions to Your Amazon S3
Resources.

The following are related to PutBucketLifecycleConfiguration:

• Examples of Lifecycle Conﬁguration

• GetBucketLifecycleConﬁguration (p. 102)
• DeleteBucketLifecycle (p. 51)

API Version 2006-03-01

264
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Request Syntax

PUT /?lifecycle HTTP/1.1

Host: Bucket.s3.amazonaws.com
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<AbortIncompleteMultipartUpload>
<DaysAfterInitiation>integer</DaysAfterInitiation>
</AbortIncompleteMultipartUpload>
<Expiration>
<Date>timestamp</Date>
<Days>integer</Days>
<ExpiredObjectDeleteMarker>boolean</ExpiredObjectDeleteMarker>
</Expiration>
<Filter>
<And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
...
</And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</Filter>
<ID>string</ID>
<NoncurrentVersionExpiration>
<NoncurrentDays>integer</NoncurrentDays>
</NoncurrentVersionExpiration>
<NoncurrentVersionTransition>
<NoncurrentDays>integer</NoncurrentDays>
<StorageClass>string</StorageClass>
</NoncurrentVersionTransition>
...
<Prefix>string</Prefix>
<Status>string</Status>
<Transition>
<Date>timestamp</Date>
<Days>integer</Days>
<StorageClass>string</StorageClass>
</Transition>
...
</Rule>
...
</LifecycleConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 265)

The name of the bucket for which to set the conﬁguration.

Request Body
The request accepts the following data in XML format.

API Version 2006-03-01

265
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

LifecycleConﬁguration (p. 265)

Root level tag for the LifecycleConﬁguration parameters.

Required: Yes
Rule (p. 265)

A lifecycle rule for individual objects in an Amazon S3 bucket.

Type: Array of LifecycleRule (p. 484) data types

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
Example 1: Add lifecycle conﬁguration - bucket not versioning-enabled

The following lifecycle conﬁguration speciﬁes two rules, each with one action.

• The Transition action requests Amazon S3 to transition objects with the "documents/" preﬁx to the
GLACIER storage class 30 days after creation.
• The Expiration action requests Amazon S3 to delete objects with the "logs/" preﬁx 365 days after
creation.

<LifecycleConfiguration>
<Rule>
<ID>id1</ID>
<Filter>
<Prefix>documents/</Prefix>
</Filter>
<Status>Enabled</Status>
<Transition>
<Days>30</Days>
<StorageClass>GLACIER</StorageClass>
</Transition>
</Rule>
<Rule>
<ID>id2</ID>
<Filter>
<Prefix>logs/</Prefix>
</Filter>
<Status>Enabled</Status>
<Expiration>
<Days>365</Days>
</Expiration>
</Rule>

API Version 2006-03-01

266
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

</LifecycleConfiguration>

The following is a sample PUT /?lifecycle request that adds the preceding lifecycle conﬁguration to
the examplebucket bucket.

PUT /?lifecycle HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Wed, 14 May 2014 02:11:21 GMT
Content-MD5: q6yJDlIkcBaGGfb3QLY69A==
Authorization: authorization string
Content-Length: 415

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: r+qR7+nhXtJDDIJ0JJYcd+1j5nM/rUFiiiZ/fNbDOsd3JUE8NWMLNHXmvPfwMpdc
x-amz-request-id: 9E26D08072A8EF9E
Date: Wed, 14 May 2014 02:11:22 GMT
Content-Length: 0
Server: AmazonS3

Example 2: Add lifecycle conﬁguration - bucket is versioning-enabled

The following lifecycle conﬁguration speciﬁes two rules, each with one action for Amazon S3 to perform.
You specify these actions when your bucket is versioning-enabled or versioning is suspended:

• The NoncurrentVersionExpiration action requests Amazon S3 to expire noncurrent versions of

objects with the "logs/" preﬁx 100 days after the objects become noncurrent.
• The NoncurrentVersionTransition action requests Amazon S3 to transition noncurrent versions
of objects with the "documents/" preﬁx to the GLACIER storage class 30 days after they become
noncurrent.

API Version 2006-03-01

267
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<LifeCycleConfiguration>
<Rule>
<ID>DeleteAfterBecomingNonCurrent</ID>
<Filter>
<Prefix>logs/</Prefix>
</Filter>
<Status>Enabled</Status>
<NoncurrentVersionExpiration>
<NoncurrentDays>100</NoncurrentDays>
</NoncurrentVersionExpiration>
</Rule>
<Rule>
<ID>TransitionAfterBecomingNonCurrent</ID>
<Filter>
<Prefix>documents/</Prefix>
</Filter>
<Status>Enabled</Status>
<NoncurrentVersionTransition>
<NoncurrentDays>30</NoncurrentDays>
<StorageClass>GLACIER</StorageClass>
</NoncurrentVersionTransition>
</Rule>
</LifeCycleConfiguration>

The following is a sample PUT /?lifecycle request that adds the preceding lifecycle conﬁguration to
the examplebucket bucket.

PUT /?lifecycle HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Wed, 14 May 2014 02:21:48 GMT
Content-MD5: 96rxH9mDqVNKkaZDddgnw==
Authorization: authorization string
Content-Length: 598

<LifeCycleConfiguration>
<Rule>
<ID>DeleteAfterBecomingNonCurrent</ID>
<Filter>
<Prefix>logs/</Prefix>
</Filter>
<Status>Enabled</Status>
<NoncurrentVersionExpiration>
<NoncurrentDays>1</NoncurrentDays>
</NoncurrentVersionExpiration>
</Rule>
<Rule>
<ID>TransitionSoonAfterBecomingNonCurrent</ID>
<Filter>
<Prefix>documents/</Prefix>
</Filter>
<Status>Enabled</Status>
<NoncurrentVersionTransition>
<NoncurrentDays>0</NoncurrentDays>
<StorageClass>GLACIER</StorageClass>
</NoncurrentVersionTransition>
</Rule>
</LifeCycleConfiguration>

API Version 2006-03-01

268
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Sample Response

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

269
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketLogging
Service: Amazon Simple Storage Service

Set the logging parameters for a bucket and to specify permissions for who can view and modify the
logging parameters. All logs are saved to buckets in the same AWS Region as the source bucket. To set
the logging status of a bucket, you must be the bucket owner.

The bucket owner is automatically granted FULL_CONTROL to all logs. You use the Grantee request
element to grant access to other people. The Permissions request element speciﬁes the kind of access
the grantee has to the logs.

Grantee Values

You can specify the person (grantee) to whom you're assigning access rights (using request elements) in
the following ways:

• By the person's ID:

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser"><ID><>ID<></ID><DisplayName><>GranteesEmail<></
DisplayName> </Grantee>

DisplayName is optional and ignored in the request.

• By Email address:

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="AmazonCustomerByEmail"><EmailAddress><>[email protected]<></
EmailAddress></Grantee>

The grantee is resolved to the CanonicalUser and, in a response to a GET Object acl request, appears as
the CanonicalUser.
• By URI:

To enable logging, you use LoggingEnabled and its children request elements. To disable logging, you
use an empty BucketLoggingStatus request element:

<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01" />

For more information about server access logging, see Server Access Logging.

For more information about creating a bucket, see CreateBucket (p. 27). For more information about
returning the logging status of a bucket, see GetBucketLogging (p. 107).

The following operations are related to PutBucketLogging:

• PutObject (p. 310)

• DeleteBucket (p. 41)
• CreateBucket (p. 27)
• GetBucketLogging (p. 107)

Request Syntax

PUT /?logging HTTP/1.1

API Version 2006-03-01

270
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<BucketLoggingStatus xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<LoggingEnabled>
<TargetBucket>string</TargetBucket>
<TargetGrants>
<Grant>
<Grantee>
<DisplayName>string</DisplayName>
<EmailAddress>string</EmailAddress>
<ID>string</ID>
<xsi:type>string</xsi:type>
<URI>string</URI>
</Grantee>
<Permission>string</Permission>
</Grant>
</TargetGrants>
<TargetPrefix>string</TargetPrefix>
</LoggingEnabled>
</BucketLoggingStatus>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 270)

The name of the bucket for which to set the logging parameters.
Content-MD5 (p. 270)

The MD5 hash of the PutBucketLogging request body.

Request Body
The request accepts the following data in XML format.

BucketLoggingStatus (p. 270)

Root level tag for the BucketLoggingStatus parameters.

Required: Yes
LoggingEnabled (p. 270)

Type: LoggingEnabled (p. 488) data type

Required: No

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

API Version 2006-03-01

271
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Examples
Sample Request

This request enables logging and gives the grantee of the bucket READ access to the logs.

PUT ?logging HTTP/1.1

Host: quotes.s3.<Region>.amazonaws.com
Content-Length: 214
Date: Wed, 25 Nov 2009 12:00:00 GMT
Authorization: authorization string

<?xml version="1.0" encoding="UTF-8"?>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT

Sample Request: Disabling logging

This request disables logging on the bucket quotes.

PUT ?logging HTTP/1.1

Host: quotes.s3.<Region>.amazonaws.com
Content-Length: 214
Date: Wed, 25 Nov 2009 12:00:00 GMT
Authorization: authorization string

<?xml version="1.0" encoding="UTF-8"?>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo

API Version 2006-03-01

272
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

273
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketMetricsConﬁguration
Service: Amazon Simple Storage Service

Sets a metrics configuration (specified by the metrics configuration ID) for the bucket. You can have up
to 1,000 metrics configurations per bucket. If you're updating an existing metrics configuration, note
that this is a full replacement of the existing metrics configuration. If you don't include the elements you
want to keep, they are erased.

For information about CloudWatch request metrics for Amazon S3, see Monitoring Metrics with Amazon
CloudWatch.

The following operations are related to PutBucketMetricsConfiguration:

• DeleteBucketMetricsConﬁguration (p. 53)

• PutBucketMetricsConﬁguration (p. 274)
• ListBucketMetricsConﬁgurations (p. 188)

GetBucketLifecycle has the following special error:

• Error code: TooManyConfigurations

• Description: You are attempting to create a new conﬁguration but have already reached the 1,000-
conﬁguration limit.
• HTTP Status Code: HTTP 400 Bad Request

Request Syntax

PUT /?metrics&Id=Id HTTP/1.1

Host: Bucket.s3.amazonaws.com
<?xml version="1.0" encoding="UTF-8"?>
<MetricsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>string</Id>
<Filter>
<And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
...
</And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</Filter>
</MetricsConfiguration>

URI Request Parameters

The request requires the following URI parameters.

API Version 2006-03-01

274
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Bucket (p. 274)

The name of the bucket for which the metrics conﬁguration is set.
id (p. 274)

The ID used to identify the metrics conﬁguration.

Request Body
The request accepts the following data in XML format.

MetricsConﬁguration (p. 274)

Root level tag for the MetricsConﬁguration parameters.

Required: Yes
Filter (p. 274)

Type: MetricsFilter (p. 493) data type

Required: No
Id (p. 274)

The ID used to identify the metrics conﬁguration.

Type: String

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
First Sample Request

Put a metric conﬁguration that enables metrics for an entire bucket.

PUT /?metrics&id=EntireBucket HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT
Authorization: signatureValue
Content-Length: 159

<?xml version="1.0" encoding="UTF-8"?>

<MetricsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>EntireBucket</Id>

API Version 2006-03-01

275
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

</MetricsConfiguration>

First Sample Response

HTTP/1.1 204 No Content

x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3

Second Sample Request

Put a metrics configuration that enables metrics for objects that start with a particular prefix and also
have specific tags applied.

PUT /?metrics&id=ImportantBlueDocuments HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-date: Thu, 15 Nov 2016 00:17:29 GMT
Authorization: signatureValue
Content-Length: 480

<?xml version="1.0" encoding="UTF-8"?>

Second Sample Response

HTTP/1.1 204 No Content

x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:29 GMT
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET

API Version 2006-03-01

276
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

277
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketNotiﬁcation
Service: Amazon Simple Storage Service

No longer used, see the PutBucketNotiﬁcationConﬁguration (p. 280) operation.

Request Syntax

PUT /?notification HTTP/1.1

Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<NotificationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<TopicConfiguration>
<Event>string</Event>
<Event>string</Event>
...
<Id>string</Id>
<Topic>string</Topic>
</TopicConfiguration>
<QueueConfiguration>
<Event>string</Event>
<Event>string</Event>
...
<Id>string</Id>
<Queue>string</Queue>
</QueueConfiguration>
<CloudFunctionConfiguration>
<CloudFunction>string</CloudFunction>
<Event>string</Event>
<Event>string</Event>
...
<Id>string</Id>
<InvocationRole>string</InvocationRole>
</CloudFunctionConfiguration>
</NotificationConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 278)

The name of the bucket.

Content-MD5 (p. 278)

The MD5 hash of the PutPublicAccessBlock request body.

Request Body
The request accepts the following data in XML format.

NotiﬁcationConﬁguration (p. 278)

Root level tag for the NotiﬁcationConﬁguration parameters.

Required: Yes
CloudFunctionConﬁguration (p. 278)

Container for specifying the AWS Lambda notiﬁcation conﬁguration.

API Version 2006-03-01

278
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Type: CloudFunctionConﬁguration (p. 426) data type

Required: No
QueueConﬁguration (p. 278)

This data type is deprecated. This data type specifies the configuration for publishing messages to
an Amazon Simple Queue Service (Amazon SQS) queue when Amazon S3 detects specified events.

Type: QueueConﬁgurationDeprecated (p. 522) data type

Required: No
TopicConﬁguration (p. 278)

Type: TopicConﬁgurationDeprecated (p. 564) data type

Required: No

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

279
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketNotiﬁcationConﬁguration
Service: Amazon Simple Storage Service

Enables notifications of specified events for a bucket. For more information about event notifications,
see Configuring Event Notifications.

Using this API, you can replace an existing notification configuration. The configuration is an XML file
that defines the event types that you want Amazon S3 to publish and the destination where you want
Amazon S3 to publish an event notification when it detects an event of the specified type.

By default, your bucket has no event notifications configured. That is, the notification configuration will
be an empty NotificationConfiguration.

</NotificationConfiguration>

This operation replaces the existing notification configuration with the configuration you include in the
request body.

After Amazon S3 receives this request, it first verifies that any Amazon Simple Notification Service
(Amazon SNS) or Amazon Simple Queue Service (Amazon SQS) destination exists, and that the bucket
owner has permission to publish to it by sending a test notification. In the case of AWS Lambda
destinations, Amazon S3 verifies that the Lambda function permissions grant Amazon S3 permission to
invoke the function from the Amazon S3 bucket. For more information, see Configuring Notifications for
Amazon S3 Events.

You can disable notifications by adding the empty NotificationConfiguration element.

By default, only the bucket owner can configure notifications on a bucket. However, bucket
owners can use a bucket policy to grant permission to other users to set this configuration with
s3:PutBucketNotification permission.
Note
The PUT notification is an atomic operation. For example, suppose your notification
configuration includes SNS topic, SQS queue, and Lambda function configurations. When
you send a PUT request with this configuration, Amazon S3 sends test messages to your SNS
topic. If the message fails, the entire PUT operation will fail, and Amazon S3 will not add the
configuration to your bucket.

Responses

If the conﬁguration in the request body includes only one TopicConfiguration specifying only the
s3:ReducedRedundancyLostObject event type, the response will also include the x-amz-sns-
test-message-id header containing the message ID of the test notiﬁcation sent to the topic.

The following operation is related to PutBucketNotificationConfiguration:

• GetBucketNotiﬁcationConﬁguration (p. 116)

Request Syntax

PUT /?notification HTTP/1.1

Host: Bucket.s3.amazonaws.com
<?xml version="1.0" encoding="UTF-8"?>
<NotificationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<TopicConfiguration>
<Event>string</Event>
...
<Filter>

API Version 2006-03-01

280
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<S3Key>
<FilterRule>
<Name>string</Name>
<Value>string</Value>
</FilterRule>
...
</S3Key>
</Filter>
<Id>string</Id>
<Topic>string</Topic>
</TopicConfiguration>
...
<QueueConfiguration>
<Event>string</Event>
...
<Filter>
<S3Key>
<FilterRule>
<Name>string</Name>
<Value>string</Value>
</FilterRule>
...
</S3Key>
</Filter>
<Id>string</Id>
<Queue>string</Queue>
</QueueConfiguration>
...
<CloudFunctionConfiguration>
<Event>string</Event>
...
<Filter>
<S3Key>
<FilterRule>
<Name>string</Name>
<Value>string</Value>
</FilterRule>
...
</S3Key>
</Filter>
<Id>string</Id>
<CloudFunction>string</CloudFunction>
</CloudFunctionConfiguration>
...
</NotificationConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 280)

The name of the bucket.

Request Body
The request accepts the following data in XML format.

NotiﬁcationConﬁguration (p. 280)

Root level tag for the NotiﬁcationConﬁguration parameters.

Required: Yes

API Version 2006-03-01

281
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CloudFunctionConﬁguration (p. 280)

Describes the AWS Lambda functions to invoke and the events for which to invoke them.

Type: Array of LambdaFunctionConﬁguration (p. 480) data types

Required: No
QueueConﬁguration (p. 280)

The Amazon Simple Queue Service queues to publish messages to and the events for which to
publish messages.

Type: Array of QueueConﬁguration (p. 520) data types

Required: No
TopicConﬁguration (p. 280)

The topic to which notiﬁcations are sent and the events for which notiﬁcations are generated.

Type: Array of TopicConﬁguration (p. 562) data types

Required: No

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
Example 1: Conﬁgure notiﬁcation to invoke a cloud function in Lambda

The following notification configuration includes CloudFunctionConfiguration, which identifies the event
type for which Amazon S3 can invoke a cloud function and the name of the cloud function to invoke.

<NotificationConfiguration>
<CloudFunctionConfiguration>
<Id>ObjectCreatedEvents</Id>
<CloudFunction>arn:aws:lambda:us-west-2:35667example:function:CreateThumbnail</
CloudFunction>
<Event>s3:ObjectCreated:*</Event>
</CloudFunctionConfiguration>
</NotificationConfiguration>

The following PUT uploads the notification configuration. The operation replaces the existing
notification configuration.

PUT http://s3.<Region>.amazonaws.com/examplebucket?notification= HTTP/1.1

User-Agent: s3curl 2.0
Host: s3.amazonaws.com

API Version 2006-03-01

282
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Pragma: no-cache
Accept: */*
Proxy-Connection: Keep-Alive
Authorization: authorization string
Date: Mon, 13 Oct 2014 23:14:52 +0000
Content-Length: length

[request body]

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: 8+FlwagBSoT2qpMaGlfCUkRkFR5W3OeS7UhhoBb17j+kqvpS2cSFlgJ5coLd53d2
x-amz-request-id: E5BA4600A3937335
Date: Fri, 31 Oct 2014 01:49:50 GMT
Content-Length: 0
Server: AmazonS3

Example 2: Conﬁgure a notiﬁcation with multiple destinations

The following notification configuration includes the topic and queue configurations:

• A topic conﬁguration identifying an SNS topic for Amazon S3 to publish events of the
s3:ReducedRedundancyLostObject type.
• A queue conﬁguration identifying an SQS queue for Amazon S3 to publish events of the
s3:ObjectCreated:* type.

<NotificationConfiguration>
<TopicConfiguration>
<Topic>arn:aws:sns:us-east-1:356671443308:s3notificationtopic2</Topic>
<Event>s3:ReducedRedundancyLostObject</Event>
</TopicConfiguration>
<QueueConfiguration>
<Queue>arn:aws:sqs:us-east-1:356671443308:s3notificationqueue</Queue>
<Event>s3:ObjectCreated:*</Event>
</QueueConfiguration>
</NotificationConfiguration>

The following PUT request against the notification subresource of the examplebucket bucket sends the
preceding notification configuration in the request body. The operation replaces the existing notification
configuration on the bucket.

PUT http://s3.<Region>.amazonaws.com/examplebucket?notification= HTTP/1.1

User-Agent: s3curl 2.0
Host: s3.amazonaws.com
Pragma: no-cache
Accept: */*
Proxy-Connection: Keep-Alive
Authorization: authorization string
Date: Mon, 13 Oct 2014 22:58:43 +0000
Content-Length: 391
Expect: 100-continue

API Version 2006-03-01

283
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Example 3: Configure a notification with object key name filtering

The following notification configuration contains a queue configuration identifying an Amazon SQS
queue for Amazon S3 to publish events to of the s3:ObjectCreated:Put type. The events will be published
whenever an object that has a prefix of images/ and a .jpg suffix is PUT to a bucket. For more examples
of notification configurations that use filtering, see Configuring Event Notifications.

<NotificationConfiguration>
<QueueConfiguration>
<Id>1</Id>
<Filter>
<S3Key>
<FilterRule>
<Name>prefix</Name>
<Value>images/</Value>
</FilterRule>
<FilterRule>
<Name>suffix</Name>
<Value>.jpg</Value>
</FilterRule>
</S3Key>
</Filter>
<Queue>arn:aws:sqs:us-west-2:444455556666:s3notificationqueue</Queue>
<Event>s3:ObjectCreated:Put</Event>
</QueueConfiguration>
</NotificationConfiguration>

PUT http://s3.<Region>.amazonaws.com/examplebucket?notification= HTTP/1.1

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: SlvJLkfunoAGILZK3KqHSSUq4kwbudkrROmESoHOpDacULy+cxRoR1Svrfoyvg2A
x-amz-request-id: BB1BA8E12D6A80B7
Date: Mon, 13 Oct 2014 22:58:44 GMT
Content-Length: 0
Server: AmazonS3

API Version 2006-03-01

284
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

285
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketPolicy
Service: Amazon Simple Storage Service

Applies an Amazon S3 bucket policy to an Amazon S3 bucket. If you are using an identity other
than the root user of the AWS account that owns the bucket, the calling identity must have the
PutBucketPolicy permissions on the speciﬁed bucket and belong to the bucket owner's account in
order to use this operation.

If you don't have PutBucketPolicy permissions, Amazon S3 returns a 403 Access Denied error. If
you have the correct permissions, but you're not using an identity that belongs to the bucket owner's
account, Amazon S3 returns a 405 Method Not Allowed error.
Important
As a security precaution, the root user of the AWS account that owns a bucket can always use
this operation, even if the policy explicitly denies the root user the ability to perform this action.

For more information about bucket policies, see Using Bucket Policies and User Policies.

The following operations are related to PutBucketPolicy:

• CreateBucket (p. 27)

• DeleteBucket (p. 41)

Request Syntax

PUT /?policy HTTP/1.1

Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
x-amz-confirm-remove-self-bucket-access: ConfirmRemoveSelfBucketAccess

{ Policy in JSON format }

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 286)

The name of the bucket.

Content-MD5 (p. 286)

The MD5 hash of the request body.

x-amz-conﬁrm-remove-self-bucket-access (p. 286)

Set this parameter to true to conﬁrm that you want to remove your permissions to change this
bucket policy in the future.

Request Body
The request accepts the following data in JSON format.

Policy (p. 286)

Response Syntax

HTTP/1.1 200

API Version 2006-03-01

286
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
Sample Request

The following request shows the PUT individual policy request for the bucket.

PUT /?policy HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Tue, 04 Apr 2010 20:34:56 GMT
Authorization: authorization string

{
"Version":"2008-10-17",
"Id":"aaaa-bbbb-cccc-dddd",
"Statement" : [
{
"Effect":"Allow",
"Sid":"1",
"Principal" : {
"AWS":["111122223333","444455556666"]
},
"Action":["s3:*"],
"Resource":"arn:aws:s3:::bucket/*"
}
]
}

Sample Response

HTTP/1.1 204 No Content

x-amz-id-2: Uuag1LuByR5Onimru9SAMPLEAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732SAMPLE7374
Date: Tue, 04 Apr 2010 20:34:56 GMT
Connection: keep-alive
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

287
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

API Version 2006-03-01

288
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketReplication
Service: Amazon Simple Storage Service

Creates a replication conﬁguration or replaces an existing one. For more information, see Replication in
the Amazon S3 Developer Guide.
Note
To perform this operation, the user or role performing the operation must have the
iam:PassRole permission.

Specify the replication conﬁguration in the request body. In the replication conﬁguration, you provide
the name of the destination bucket where you want Amazon S3 to replicate objects, the IAM role that
Amazon S3 can assume to replicate objects on your behalf, and other relevant information.

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. All rules must specify the same
destination bucket.

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.

For information about enabling versioning on a bucket, see Using Versioning.

By default, a resource owner, in this case the AWS account that created the bucket, can perform this
operation. The resource owner can also grant others permissions to perform the operation. For more
information about permissions, see Specifying Permissions in a Policy and Managing Access Permissions
to Your Amazon S3 Resources.

Handling Replication of Encrypted Objects

By default, Amazon S3 doesn't replicate objects that are stored at rest using server-side encryption
with CMKs stored in AWS KMS. To replicate AWS KMS-encrypted objects, add the following:
SourceSelectionCriteria, SseKmsEncryptedObjects, Status, EncryptionConfiguration,
and ReplicaKmsKeyID. For information about replication conﬁguration, see Replicating Objects
Created with SSE Using CMKs stored in AWS KMS.

For information on PutBucketReplication errors, see List of Replication-Related Error

Codes (p. 699)

The following operations are related to PutBucketReplication:

• GetBucketReplication (p. 123)

• DeleteBucketReplication (p. 57)

Request Syntax

PUT /?replication HTTP/1.1

Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
x-amz-bucket-object-lock-token: Token
<?xml version="1.0" encoding="UTF-8"?>
<ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Role>string</Role>
<Rule>

API Version 2006-03-01

289
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<DeleteMarkerReplication>
<Status>string</Status>
</DeleteMarkerReplication>
<Destination>
<AccessControlTranslation>
<Owner>string</Owner>
</AccessControlTranslation>
<Account>string</Account>
<Bucket>string</Bucket>
<EncryptionConfiguration>
<ReplicaKmsKeyID>string</ReplicaKmsKeyID>
</EncryptionConfiguration>
<Metrics>
<EventThreshold>
<Minutes>integer</Minutes>
</EventThreshold>
<Status>string</Status>
</Metrics>
<ReplicationTime>
<Status>string</Status>
<Time>
<Minutes>integer</Minutes>
</Time>
</ReplicationTime>
<StorageClass>string</StorageClass>
</Destination>
<ExistingObjectReplication>
<Status>string</Status>
</ExistingObjectReplication>
<Filter>
<And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
...
</And>
<Prefix>string</Prefix>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</Filter>
<ID>string</ID>
<Prefix>string</Prefix>
<Priority>integer</Priority>
<SourceSelectionCriteria>
<SseKmsEncryptedObjects>
<Status>string</Status>
</SseKmsEncryptedObjects>
</SourceSelectionCriteria>
<Status>string</Status>
</Rule>
...
</ReplicationConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 289)

The name of the bucket

API Version 2006-03-01

290
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Content-MD5 (p. 289)

The base64-encoded 128-bit MD5 digest of the data. You must use this header as a message
integrity check to verify that the request body was not corrupted in transit. For more information,
see RFC 1864.
x-amz-bucket-object-lock-token (p. 289)

Request Body
The request accepts the following data in XML format.

ReplicationConﬁguration (p. 289)

Root level tag for the ReplicationConﬁguration parameters.

Required: Yes
Role (p. 289)

Type: String

Required: Yes
Rule (p. 289)

A container for one or more replication rules. A replication conﬁguration must have at least one rule
and can contain a maximum of 1,000 rules.

Type: Array of ReplicationRule (p. 529) data types

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
Sample Request: Add a replication configuration
The following is a sample PUT request that creates a replication subresource on the specified bucket and
saves the replication configuration in it. The replication configuration specifies a rule to replicate objects
to the exampletargetbucket bucket. The rule includes a filter to replicate only the objects created
with the key name prefix TaxDocs and that have two specific tags.

After you add a replication configuration to your bucket, Amazon S3 assumes the AWS Identity and
Access Management (IAM) role specified in the configuration to replicate objects on behalf of the bucket
owner. The bucket owner is the AWS account that created the bucket.

Filtering using the <Filter> element is supported in the latest XML configuration. If you are using an
earlier version of the XML configuration, you can filter only on key prefix. In that case, you add the
<Prefix> element as a child of the <Rule>.

API Version 2006-03-01

291
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

For more examples of replication conﬁguration, see Replication Conﬁguration Overview in the Amazon
S3 Developer Guide.

PUT /?replication HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Wed, 11 Feb 2015 02:11:21 GMT
Content-MD5: q6yJDlIkcBaGGfb3QLY69A==
Authorization: authorization string
Content-Length: length

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: r+qR7+nhXtJDDIJ0JJYcd+1j5nM/rUFiiiZ/fNbDOsd3JUE8NWMLNHXmvPfwMpdc
x-amz-request-id: 9E26D08072A8EF9E
Date: Wed, 11 Feb 2015 02:11:22 GMT
Content-Length: 0
Server: AmazonS3

Sample Request: Add a Replication Conﬁguration with Amazon S3 Replication Time Control
Enabled
You can use S3 Replication Time Control (S3 RTC) to replicate your data in the same AWS Region or
across diﬀerent AWS Regions in a predictable time frame. S3 RTC replicates 99.99 percent of new objects
stored in Amazon S3 within 15 minutes. For more information, see Replicating Objects Using Replication
Time Control.

PUT /?replication HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com

API Version 2006-03-01

292
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Date: Wed, 11 Feb 2015 02:11:21 GMT

Content-MD5: q6yJDlIkcBaGGfb3QLY69A==
Authorization: authorization string
Content-Length: length
x-amz-bucket-object-lock-token: Token
<?xml version="1.0" encoding="UTF-8"?>

<ReplicationConfiguration>
<Role>arn:aws:iam::35667example:role/CrossRegionReplicationRoleForS3</Role>
<Rule>
<ID>rule1</ID>
<Status>Enabled</Status>
<Priority>1</Priority>
<Filter>
<And>
<Prefix>TaxDocs</Prefix>
<Tag>
<Key>key1</Key>
<Value>value1</Value>
</Tag>
<Tag>
<Key>key1</Key>
<Value>value1</Value>
</Tag>
</And>
</Filter>
<Destination>
<Bucket>arn:aws:s3:::exampletargetbucket</Bucket>
<Metrics>
<Status>Enabled</Status>
<EventThreshold>
<Minutes>15</Minutes>
</EventThreshold>
</Metrics>
<ReplicationTime>
<Status>Enabled</Status>
<Time>
<Minutes>15</Minutes>
</Time>
</ReplicationTime>
</Destination>
</Rule>
</ReplicationConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

293
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketRequestPayment
Service: Amazon Simple Storage Service

Sets the request payment conﬁguration for a bucket. By default, the bucket owner pays for downloads
from the bucket. This conﬁguration parameter enables the bucket owner (only) to specify that the
person requesting the download will be charged for the download. For more information, see Requester
Pays Buckets.

The following operations are related to PutBucketRequestPayment:

• CreateBucket (p. 27)

• GetBucketRequestPayment (p. 127)

Request Syntax

PUT /?requestPayment HTTP/1.1

Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<RequestPaymentConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Payer>string</Payer>
</RequestPaymentConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 294)

The bucket name.

Content-MD5 (p. 294)

>The base64-encoded 128-bit MD5 digest of the data. You must use this header as a message
integrity check to verify that the request body was not corrupted in transit. For more information,
see RFC 1864.

Request Body
The request accepts the following data in XML format.

RequestPaymentConﬁguration (p. 294)

Root level tag for the RequestPaymentConﬁguration parameters.

Required: Yes
Payer (p. 294)

Speciﬁes who pays for the download and request fees.

Type: String

Valid Values: Requester | BucketOwner

Required: Yes

API Version 2006-03-01

294
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
Sample Request

This request creates a Requester Pays bucket named colorpictures.

PUT ?requestPayment HTTP/1.1

Host: colorpictures.s3.<Region>.amazonaws.com
Content-Length: 173
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

<RequestPaymentConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Payer>Requester</Payer>
</RequestPaymentConfiguration>

Sample Response

Delete the metric conﬁguration with a speciﬁed ID, which disables theCloudWatch metrics with the
ExampleMetrics value for the FilterId dimension.

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT
Location: /colorpictures
Content-Length: 0
Connection: close
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

295
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

API Version 2006-03-01

296
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketTagging
Service: Amazon Simple Storage Service

Sets the tags for a bucket.

Use tags to organize your AWS bill to reﬂect your own cost structure. To do this, sign up to get your AWS
account bill with tag key values included. Then, to see the cost of combined resources, organize your
billing information according to resources with the same tag key values. For example, you can tag several
resources with a speciﬁc application name, and then organize your billing information to see the total
cost of that application across several services. For more information, see Cost Allocation and Tagging.
Note
Within a bucket, if you add a tag that has the same key as an existing tag, the new value
overwrites the old value. For more information, see Using Cost Allocation in Amazon S3 Bucket
Tags.

To use this operation, you must have permissions to perform the s3:PutBucketTagging action.
The bucket owner has this permission by default and can grant this permission to others. For more
information about permissions, see Permissions Related to Bucket Subresource Operations and
Managing Access Permissions to Your Amazon S3 Resources.

PutBucketTagging has the following special errors:

• Error code: InvalidTagError

• Description: The tag provided was not a valid tag. This error can occur if the tag did not pass input
validation. For information about tag restrictions, see User-Deﬁned Tag Restrictions and AWS-
Generated Cost Allocation Tag Restrictions.
• Error code: MalformedXMLError
• Description: The XML provided does not match the schema.
• Error code: OperationAbortedError
• Description: A conﬂicting conditional operation is currently in progress against this resource. Please
try again.
• Error code: InternalError
• Description: The service was unable to apply the provided tag to the bucket.

The following operations are related to PutBucketTagging:

• GetBucketTagging (p. 129)

• DeleteBucketTagging (p. 59)

Request Syntax

PUT /?tagging HTTP/1.1

Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<Tagging xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<TagSet>
<Tag>
<Key>string</Key>
<Value>string</Value>
</Tag>
</TagSet>
</Tagging>

API Version 2006-03-01

297
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 297)

The bucket name.

Content-MD5 (p. 297)

Request Body
The request accepts the following data in XML format.

Tagging (p. 297)

Root level tag for the Tagging parameters.

Required: Yes
TagSet (p. 297)

A collection for a set of tags

Type: Array of Tag (p. 559) data types

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
Sample Request: Add tag set to a bucket

The following request adds a tag set to the existing examplebucket bucket.

PUT ?tagging HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Content-Length: 1660
x-amz-date: Thu, 12 Apr 2012 20:04:21 GMT
Authorization: authorization string

<Tagging>
<TagSet>
<Tag>
<Key>Project</Key>
<Value>Project One</Value>
</Tag>

API Version 2006-03-01

298
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<Tag>
<Key>User</Key>
<Value>jsmith</Value>
</Tag>
</TagSet>
</Tagging>

Sample Response

HTTP/1.1 204 No Content

x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Oct 2012 12:00:00 GMT

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

299
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketVersioning
Service: Amazon Simple Storage Service

Sets the versioning state of an existing bucket. To set the versioning state, you must be the bucket
owner.

You can set the versioning state with one of the following values:

Enabled—Enables versioning for the objects in the bucket. All objects added to the bucket receive a
unique version ID.

Suspended—Disables versioning for the objects in the bucket. All objects added to the bucket receive
the version ID null.

If the versioning state has never been set on a bucket, it has no versioning state; a
GetBucketVersioning (p. 132) request does not return a versioning state value.

If the bucket owner enables MFA Delete in the bucket versioning conﬁguration, the bucket owner must
include the x-amz-mfa request header and the Status and the MfaDelete request elements in a
request to set the versioning state of the bucket.
Important
If you have an object expiration lifecycle policy in your non-versioned bucket and you want to
maintain the same permanent delete behavior when you enable versioning, you must add a
noncurrent expiration policy. The noncurrent expiration lifecycle policy will manage the deletes
of the noncurrent object versions in the version-enabled bucket. (A version-enabled bucket
maintains one current and zero or more noncurrent object versions.) For more information, see
Lifecycle and Versioning.

Related Resources

• CreateBucket (p. 27)

• DeleteBucket (p. 41)
• GetBucketVersioning (p. 132)

Request Syntax

PUT /?versioning HTTP/1.1

Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
x-amz-mfa: MFA
<?xml version="1.0" encoding="UTF-8"?>
<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<MfaDelete>string</MfaDelete>
<Status>string</Status>
</VersioningConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 300)

The bucket name.

Content-MD5 (p. 300)

API Version 2006-03-01

300
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-mfa (p. 300)

The concatenation of the authentication device's serial number, a space, and the value that is
displayed on your authentication device.

Request Body
The request accepts the following data in XML format.

VersioningConﬁguration (p. 300)

Root level tag for the VersioningConﬁguration parameters.

Required: Yes
MFADelete (p. 300)

Type: String

Valid Values: Enabled | Disabled

Required: No
Status (p. 300)

The versioning state of the bucket.

Type: String

Valid Values: Enabled | Suspended

Required: No

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
Sample Request

The following request enables versioning for the speciﬁed bucket.

PUT /?versioning HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 124

API Version 2006-03-01

301
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
</VersioningConfiguration>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT3

Sample Request

The following request suspends versioning for the speciﬁed bucket.

PUT /?versioning HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 124

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Suspended</Status>
</VersioningConfiguration>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT

Sample Request

The following request enables versioning and MFA Delete on a bucket. Note the space between
[SerialNumber] and [TokenCode] and that you must include Status whenever you use MfaDelete.

PUT /?versioning HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
x-amz-mfa:[SerialNumber] [TokenCode]
Authorization: authorization string
Content-Type: text/plain
Content-Length: 124

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
<MfaDelete>Enabled</MfaDelete>
</VersioningConfiguration>

API Version 2006-03-01

302
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Sample Response

HTTPS/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT

Location: /colorpictures
Content-Length: 0
Connection: close
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

303
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutBucketWebsite
Service: Amazon Simple Storage Service

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. For more information, see Hosting Websites
on Amazon S3.

This PUT operation requires the S3:PutBucketWebsite permission. By default, only the bucket owner
can conﬁgure the website attached to a bucket; however, bucket owners can allow other users to set
the website conﬁguration by writing a bucket policy that grants them the S3:PutBucketWebsite
permission.

To redirect all website requests sent to the bucket's website endpoint, you add a website conﬁguration
with the following elements. Because all requests are sent to another website, you don't need to provide
index document name for the bucket.

• WebsiteConfiguration
• RedirectAllRequestsTo
• HostName
• Protocol

If you want granular control over redirects, you can use the following elements to add routing rules that
describe conditions for redirecting requests and information about the redirect destination. In this case,
the website conﬁguration must provide an index document for the bucket, because some requests might
not be redirected.

• WebsiteConfiguration
• IndexDocument
• Suffix
• ErrorDocument
• Key
• RoutingRules
• RoutingRule
• Condition
• HttpErrorCodeReturnedEquals
• KeyPrefixEquals
• Redirect
• Protocol
• HostName
• ReplaceKeyPrefixWith
• ReplaceKeyWith
• HttpRedirectCode

Request Syntax

PUT /?website HTTP/1.1

Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<WebsiteConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<ErrorDocument>

API Version 2006-03-01

304
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<Key>string</Key>
</ErrorDocument>
<IndexDocument>
<Suffix>string</Suffix>
</IndexDocument>
<RedirectAllRequestsTo>
<HostName>string</HostName>
<Protocol>string</Protocol>
</RedirectAllRequestsTo>
<RoutingRules>
<RoutingRule>
<Condition>
<HttpErrorCodeReturnedEquals>string</HttpErrorCodeReturnedEquals>
<KeyPrefixEquals>string</KeyPrefixEquals>
</Condition>
<Redirect>
<HostName>string</HostName>
<HttpRedirectCode>string</HttpRedirectCode>
<Protocol>string</Protocol>
<ReplaceKeyPrefixWith>string</ReplaceKeyPrefixWith>
<ReplaceKeyWith>string</ReplaceKeyWith>
</Redirect>
</RoutingRule>
</RoutingRules>
</WebsiteConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 304)

The bucket name.

Content-MD5 (p. 304)

Request Body
The request accepts the following data in XML format.

WebsiteConﬁguration (p. 304)

Root level tag for the WebsiteConﬁguration parameters.

Required: Yes
ErrorDocument (p. 304)

The name of the error document for the website.

Type: ErrorDocument (p. 462) data type

Required: No
IndexDocument (p. 304)

The name of the index document for the website.

Type: IndexDocument (p. 468) data type

API Version 2006-03-01

305
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Required: No
RedirectAllRequestsTo (p. 304)

The redirect behavior for every request to this bucket's website endpoint.
Important
If you specify this property, you can't specify any other property.

Type: RedirectAllRequestsTo (p. 527) data type

Required: No
RoutingRules (p. 304)

Rules that deﬁne when a redirect is applied and the redirect behavior.

Type: Array of RoutingRule (p. 539) data types

Required: No

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples
Example 1: Conﬁgure bucket as a website (add website conﬁguration)

The following request configures a bucket example.com as a website. The configuration in the
request specifies index.html as the index document. It also specifies the optional error document,
SomeErrorDocument.html.

PUT ?website HTTP/1.1

Host: example.com.s3.<Region>.amazonaws.com
Content-Length: 256
Date: Thu, 27 Jan 2011 12:00:00 GMT
Authorization: signatureValue

<WebsiteConfiguration xmlns='http://s3.amazonaws.com/doc/2006-03-01/'>
<IndexDocument>
<Suffix>index.html</Suffix>
</IndexDocument>
<ErrorDocument>
<Key>SomeErrorDocument.html</Key>
</ErrorDocument>
</WebsiteConfiguration>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 80CD4368BD211111

API Version 2006-03-01

306
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Date: Thu, 27 Jan 2011 00:00:00 GMT

Content-Length: 0
Server: AmazonS3

Example 2: Conﬁgure bucket as a website but redirect all requests

The following request configures a bucket www.example.com as a website. However, the configuration
specifies that all GET requests for the www.example.com bucket's website endpoint will be redirected
to host example.com. This redirect can be useful when you want to serve requests for both http://
www.example.com and http://example.com, but you want to maintain the website content in only
one bucket, in this case, example.com.

PUT ?website HTTP/1.1

Host: www.example.com.s3.<Region>.amazonaws.com
Content-Length: length-value
Date: Thu, 27 Jan 2011 12:00:00 GMT
Authorization: signatureValue

<WebsiteConfiguration xmlns='http://s3.amazonaws.com/doc/2006-03-01/'>
<RedirectAllRequestsTo>
<HostName>example.com</HostName>
</RedirectAllRequestsTo>
</WebsiteConfiguration>

Example 3: Conﬁgure bucket as a website and specify optional redirection rules

Example 1 is the simplest website configuration. It configures a bucket as a website by providing only an
index document and an error document. You can further customize the website configuration by adding
routing rules that redirect requests for one or more objects. For example, suppose that your bucket
contained the following objects:

• index.html
• docs/article1.html
• docs/article2.html

If you decided to rename the folder from docs/ to documents/, you would need to redirect requests
for preﬁx /docs to documents/. For example, a request for docs/article1.html will need to be
redirected to documents/article1.html.

In this case, you update the website conﬁguration and add a routing rule as shown in the following
request.

PUT ?website HTTP/1.1

Host: www.example.com.s3.<Region>.amazonaws.com
Content-Length: length-value
Date: Thu, 27 Jan 2011 12:00:00 GMT
Authorization: signatureValue

API Version 2006-03-01

307
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<RoutingRules>
<RoutingRule>
<Condition>
<KeyPrefixEquals>docs/</KeyPrefixEquals>
</Condition>
<Redirect>
<ReplaceKeyPrefixWith>documents/</ReplaceKeyPrefixWith>
</Redirect>
</RoutingRule>
</RoutingRules>
</WebsiteConfiguration>

Example 4: Conﬁgure a bucket as a website and redirect errors

You can use a routing rule to specify a condition that checks for a specific HTTP error code. When a page
request results in this error, you can optionally reroute requests. For example, you might route requests
to another host and optionally process the error. The routing rule in the following requests redirects
requests to an EC2 instance in the event of an HTTP error 404. For illustration, the redirect also inserts a
object key prefix report-404/ in the redirect. For example, if you request a page ExamplePage.html and
it results in a HTTP 404 error, the request is routed to a page report-404/testPage.html on the specified
EC2 instance. If there is no routing rule and the HTTP error 404 occurred, then Error.html would be
returned.

PUT ?website HTTP/1.1

Host: www.example.com.s3.<Region>.amazonaws.com
Content-Length: 580
Date: Thu, 27 Jan 2011 12:00:00 GMT
Authorization: signatureValue

<RoutingRules>
<RoutingRule>
<Condition>
<HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals >
</Condition>
<Redirect>
<HostName>ec2-11-22-333-44.compute-1.amazonaws.com</HostName>
<ReplaceKeyPrefixWith>report-404/</ReplaceKeyPrefixWith>
</Redirect>
</RoutingRule>
</RoutingRules>
</WebsiteConfiguration>

Example 5: Conﬁgure a Bucket as a Website and Redirect Folder Requests to a Page

Suppose you have the following pages in your bucket:

• images/photo1.jpg
• images/photo2.jpg
• images/photo3.jpg

API Version 2006-03-01

308
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Now you want to route requests for all pages with the images/ preﬁx to go to a single page,
errorpage.html. You can add a website conﬁguration to your bucket with the routing rule shown in the
following request.

PUT ?website HTTP/1.1

Host: www.example.com.s3.<Region>.amazonaws.com
Content-Length: 481
Date: Thu, 27 Jan 2011 12:00:00 GMT
Authorization: signatureValue

<RoutingRules>
<RoutingRule>
<Condition>
<KeyPrefixEquals>images/</KeyPrefixEquals>
</Condition>
<Redirect>
<ReplaceKeyWith>errorpage.html</ReplaceKeyWith>
</Redirect>
</RoutingRule>
</RoutingRules>
</WebsiteConfiguration>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

309
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutObject
Service: Amazon Simple Storage Service

Adds an object to a bucket. You must have WRITE permissions on a bucket to add an object to it.

Amazon S3 never adds partial objects; if you receive a success response, Amazon S3 added the entire
object to the bucket.

Amazon S3 is a distributed system. If it receives multiple write requests for the same object
simultaneously, it overwrites all but the last object written. Amazon S3 does not provide object locking;
if you need this, make sure to build it into your application layer or use versioning instead.

To ensure that data is not corrupted traversing the network, use the Content-MD5 header. When you
use this header, Amazon S3 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 Amazon S3 and
compare the returned ETag to the calculated MD5 value.
Note
The Content-MD5 header is required for any request to upload an object with a retention
period conﬁgured using Amazon S3 Object Lock. For more information about Amazon S3 Object
Lock, see Amazon S3 Object Lock Overview in the Amazon Simple Storage Service Developer
Guide.

You can optionally request server-side encryption. With server-side encryption, Amazon S3 encrypts
your data as it writes it to disks in its data centers and decrypts the data when you access it. You have the
option to provide your own encryption key or use AWS managed encryption keys. For more information,
see Using Server-Side Encryption.
Note
To conﬁgure your application to send the request headers before sending the request body,
use the 100-continue HTTP status code. For PUT operations, this helps you avoid sending
the message body if the message is rejected based on the headers (for example, because
authentication fails or a redirect occurs). For more information on the 100-continue HTTP
status code, see Section 8.2.3 of http://www.ietf.org/rfc/rfc2616.txt.

Access Permissions

You can optionally specify the accounts or groups that should be granted speciﬁc permissions on the
new object. There are two ways to grant the permissions using the request headers:
• Specify a canned ACL with the x-amz-acl request header. For more information, see Canned ACL.
• Specify access permissions explicitly with the x-amz-grant-read, x-amz-grant-read-acp, x-
amz-grant-write-acp, and x-amz-grant-full-control headers. These parameters map
to the set of permissions that Amazon S3 supports in an ACL. For more information, see Access
Control List (ACL) Overview.

You can use either a canned ACL or specify access permissions explicitly. You cannot do both.
Server-Side- Encryption-Speciﬁc Request Headers

API Version 2006-03-01

310
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• x-amz-server-side-encryption-aws-kms-key-id
• x-amz-server-side-encryption-context
Note
If you specify x-amz-server-side-encryption:aws:kms, but don't provide
x-amz-server-side-encryption-aws-kms-key-id, Amazon S3 uses the
AWS managed CMK in AWS KMS to protect the data. If you want to use a customer
managed AWS KMS CMK, you must provide the x-amz-server-side-encryption-
aws-kms-key-id of the symmetric customer managed CMK. For the key id,
you can provide the x-amz-server-side-encryption-aws-kms-key-id
or the Amazon Resource Name (ARN) of the CMK. For more information, see
ServerSideEncryptionByDefault:KMSMasterKeyID (p. 548). However, for cross-
account PubObject requests, you must specify the full ARN of the customer managed
CMK. Amazon S3 only supports symmetric CMKs and not asymmetric CMKs. For more
information, see Using Symmetric and Asymmetric Keys in the AWS Key Management
Service Developer Guide.
Important
All GET and PUT requests for an object protected by AWS KMS fail if you don't make them
with SSL or by using SigV4.

For more information about server-side encryption with CMKs stored in AWS KMS (SSE-KMS), see
Protecting Data Using Server-Side Encryption with CMKs stored in AWS.
• Use customer-provided encryption keys – If you want to manage your own encryption keys,
provide all the following headers in the request.
• x-amz-server-side-encryption-customer-algorithm
• x-amz-server-side-encryption-customer-key
• x-amz-server-side-encryption-customer-key-MD5

For more information about server-side encryption with CMKs stored in KMS (SSE-KMS), see
Protecting Data Using Server-Side Encryption with CMKs stored in AWS.
Access-Control-List (ACL)-Speciﬁc Request Headers

You also can use the following access control–related headers with this operation. By default, all
objects are private. Only the owner has full access control. When adding a new object, you can
grant permissions to individual AWS accounts or to predefined groups defined by Amazon S3. These
permissions are then added to the Access Control List (ACL) on the object. For more information, see
Using ACLs. With this operation, you can grant access permissions using one of the following two
methods:
• Specify a canned ACL (x-amz-acl) — Amazon S3 supports a set of predefined ACLs, known
as canned ACLs. Each canned ACL has a predefined set of grantees and permissions. For more
information, see Canned ACL.
• Specify access permissions explicitly — To explicitly grant access permissions to specific AWS
accounts or groups, use the following headers. Each header maps to specific permissions that
Amazon S3 supports in an ACL. For more information, see Access Control List (ACL) Overview. In
the header, you specify a list of grantees who get the specific permission. To grant permissions
explicitly use:
• x-amz-grant-read
• x-amz-grant-write
• x-amz-grant-read-acp
• x-amz-grant-write-acp
• x-amz-grant-full-control

You specify each grantee as a type=value pair, where the type is one of the following:
• emailAddress – if the value speciﬁed is the email address of an AWS account
API Version 2006-03-01
311
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Important
Using email addresses to specify a grantee is only supported in the following AWS
Regions:
• US East (N. Virginia)
• US West (N. California)
• US West (Oregon)
• Asia Pacific (Singapore)
• Asia Pacific (Sydney)
• Asia Pacific (Tokyo)
• EU (Ireland)
• South America (São Paulo)
For a list of all the Amazon S3 supported Regions and endpoints, see Regions and
Endpoints in the AWS General Reference
• id – if the value specified is the canonical user ID of an AWS account
• uri – if you are granting permissions to a predefined group

For example, the following x-amz-grant-read header grants the AWS accounts identiﬁed by
email addresses permissions to read object data and its metadata:

x-amz-grant-read: emailAddress="[email protected]",
emailAddress="[email protected]"
Server-Side- Encryption-Speciﬁc Request Headers

You can optionally tell Amazon S3 to encrypt data at rest using server-side encryption. Server-side
encryption is for data encryption at rest. Amazon S3 encrypts your data as it writes it to disks in its
data centers and decrypts it when you access it. The option you use depends on whether you want to
use AWS-managed encryption keys or provide your own encryption key.
• Use encryption keys managed by Amazon S3 or customer master keys (CMKs) stored in AWS Key
Management Service (AWS KMS) – If you want AWS to manage the keys used to encrypt data,
specify the following headers in the request.
• x-amz-server-side-encryption
• x-amz-server-side-encryption-aws-kms-key-id
• x-amz-server-side-encryption-context
Note
If you specify x-amz-server-side-encryption:aws:kms, but don't provide x-amz-
server-side-encryption-aws-kms-key-id, Amazon S3 uses the AWS managed
CMK in AWS KMS to protect the data. If you want to use a customer managed AWS KMS
CMK, you must provide the x-amz-server-side-encryption-aws-kms-key-id of
the symmetric customer managed CMK. Amazon S3 only supports symmetric CMKs and
not asymmetric CMKs. For more information, see Using Symmetric and Asymmetric Keys
in the AWS Key Management Service Developer Guide.
Important
All GET and PUT requests for an object protected by AWS KMS fail if you don't make them
with SSL or by using SigV4.

For more information about server-side encryption with CMKs stored in AWS KMS (SSE-KMS), see
Protecting Data Using Server-Side Encryption with CMKs stored in AWS KMS.
• Use customer-provided encryption keys – If you want to manage your own encryption keys,
provide all the following headers in the request.
Note
If you use this feature, the ETag value that Amazon S3 returns in the response is not the
MD5 of the object.

API Version 2006-03-01

312
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• x-amz-server-side-encryption-customer-algorithm
• x-amz-server-side-encryption-customer-key
• x-amz-server-side-encryption-customer-key-MD5

For more information about server-side encryption with CMKs stored in AWS KMS (SSE-KMS), see
Protecting Data Using Server-Side Encryption with CMKs stored in AWS KMS.

Storage Class Options

By default, Amazon S3 uses the Standard storage class to store newly created objects. The Standard
storage class provides high durability and high availability. You can specify other storage classes
depending on the performance needs. For more information, see Storage Classes in the Amazon Simple
Storage Service Developer Guide.

Versioning

If you enable versioning for a bucket, Amazon S3 automatically generates a unique version ID for
the object being stored. Amazon S3 returns this ID in the response using the x-amz-version-
id response header. If versioning is suspended, Amazon S3 always uses null as the version ID
for the object stored. For more information about returning the versioning state of a bucket, see
GetBucketVersioning (p. 132). If you enable versioning for a bucket, when Amazon S3 receives multiple
write requests for the same object simultaneously, it stores all of the objects.

Related Resources

• CopyObject (p. 16)

• DeleteObject (p. 63)

Request Syntax

PUT /Key+ HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-acl: ACL
Cache-Control: CacheControl
Content-Disposition: ContentDisposition
Content-Encoding: ContentEncoding
Content-Language: ContentLanguage
Content-Length: ContentLength
Content-MD5: ContentMD5
Content-Type: ContentType
Expires: Expires
x-amz-grant-full-control: GrantFullControl
x-amz-grant-read: GrantRead
x-amz-grant-read-acp: GrantReadACP
x-amz-grant-write-acp: GrantWriteACP
x-amz-server-side-encryption: ServerSideEncryption
x-amz-storage-class: StorageClass
x-amz-website-redirect-location: WebsiteRedirectLocation
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key: SSECustomerKey
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
x-amz-server-side-encryption-aws-kms-key-id: SSEKMSKeyId
x-amz-server-side-encryption-context: SSEKMSEncryptionContext
x-amz-request-payer: RequestPayer
x-amz-tagging: Tagging
x-amz-object-lock-mode: ObjectLockMode
x-amz-object-lock-retain-until-date: ObjectLockRetainUntilDate
x-amz-object-lock-legal-hold: ObjectLockLegalHoldStatus

API Version 2006-03-01

313
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Body

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 313)

Bucket name to which the PUT operation was initiated.

Can be used to specify caching behavior along the request/reply chain. For more information, see
http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9.
Content-Disposition (p. 313)

Speciﬁes presentational information for the object. For more information, see http://www.w3.org/
Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1.
Content-Encoding (p. 313)

Speciﬁes what content encodings have been applied to the object and thus what decoding
mechanisms must be applied to obtain the media-type referenced by the Content-Type header ﬁeld.
For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11.
Content-Language (p. 313)

The language the content is in.

Content-Length (p. 313)

Size of the body in bytes. This parameter is useful when the size of the body cannot be determined
automatically. For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-
sec14.html#sec14.13.
Content-MD5 (p. 313)

The base64-encoded 128-bit MD5 digest of the message (without the headers) according to RFC
1864. This header can be used as a message integrity check to verify that the data is the same data
that was originally sent. Although it is optional, we recommend using the Content-MD5 mechanism
as an end-to-end integrity check. For more information about REST request authentication, see REST
Authentication.
Content-Type (p. 313)

A standard MIME type describing the format of the contents. For more information, see http://
www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17.
Expires (p. 313)

The date and time at which the object is no longer cacheable. For more information, see http://
www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21.
Key (p. 313)

Object key for which the PUT operation was initiated.

Length Constraints: Minimum length of 1.

API Version 2006-03-01

314
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-acl (p. 313)

The canned ACL to apply to the object. For more information, see Canned ACL.

Valid Values: private | public-read | public-read-write | authenticated-read |

aws-exec-read | bucket-owner-read | bucket-owner-full-control
x-amz-grant-full-control (p. 313)

Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
x-amz-grant-read (p. 313)

Allows grantee to read the object data and its metadata.

x-amz-grant-read-acp (p. 313)

Allows grantee to read the object ACL.

x-amz-grant-write-acp (p. 313)

Allows grantee to write the ACL for the applicable object.

x-amz-object-lock-legal-hold (p. 313)

Speciﬁes whether a legal hold will be applied to this object. For more information about S3 Object
Lock, see Object Lock.

Valid Values: ON | OFF

x-amz-object-lock-mode (p. 313)

The Object Lock mode that you want to apply to this object.

Valid Values: GOVERNANCE | COMPLIANCE

x-amz-object-lock-retain-until-date (p. 313)

The date and time when you want this object's Object Lock to expire.
x-amz-request-payer (p. 313)

Valid Values: requester

x-amz-server-side-encryption (p. 313)

The server-side encryption algorithm used when storing this object in Amazon S3 (for example,
AES256, aws:kms).

Valid Values: AES256 | aws:kms

x-amz-server-side-encryption-aws-kms-key-id (p. 313)

If x-amz-server-side-encryption is present and has the value of aws:kms, this header

speciﬁes the ID of the AWS Key Management Service (AWS KMS) symmetrical customer managed
customer master key (CMK) that was used for the object.

If the value of x-amz-server-side-encryption is aws:kms, this header speciﬁes the ID of the

symmetric customer managed AWS KMS CMK that will be used for the object. If you specify x-amz-
server-side-encryption:aws:kms, but do not provide x-amz-server-side-encryption-
aws-kms-key-id, Amazon S3 uses the AWS managed CMK in AWS to protect the data.

API Version 2006-03-01

315
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-server-side-encryption-context (p. 313)

Speciﬁes the algorithm to use to when encrypting the object (for example, AES256).
x-amz-server-side-encryption-customer-key (p. 313)

If you don't specify, Standard is the default storage class. Amazon S3 supports other storage classes.

Valid Values: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA |

INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE
x-amz-tagging (p. 313)

The tag-set for the object. The tag-set must be encoded as URL Query parameters. (For example,
"Key1=Value1")
x-amz-website-redirect-location (p. 313)

In the following example, the request header sets the redirect to an object (anotherPage.html) in the
same bucket:

x-amz-website-redirect-location: /anotherPage.html

In the following example, the request header sets the object redirect to another website:

x-amz-website-redirect-location: http://www.example.com/

For more information about website hosting in Amazon S3, see Hosting Websites on Amazon S3 and
How to Conﬁgure Website Page Redirects.

Request Body
The request accepts the following binary data.

Body (p. 313)

Response Syntax

HTTP/1.1 200

API Version 2006-03-01

316
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-expiration: Expiration
ETag: ETag
x-amz-server-side-encryption: ServerSideEncryption
x-amz-version-id: VersionId
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
x-amz-server-side-encryption-aws-kms-key-id: SSEKMSKeyId
x-amz-server-side-encryption-context: SSEKMSEncryptionContext
x-amz-request-charged: RequestCharged

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

ETag (p. 316)

Entity tag for the uploaded object.

x-amz-expiration (p. 316)

If the expiration is conﬁgured for the object (see PutBucketLifecycleConﬁguration (p. 264)), the
response includes this header. It includes the expiry-date and rule-id key-value pairs that provide
information about object expiration. The value of the rule-id is URL encoded.
x-amz-request-charged (p. 316)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

x-amz-server-side-encryption (p. 316)

If you speciﬁed server-side encryption either with an AWS KMS customer master key (CMK) or
Amazon S3-managed encryption key in your PUT request, the response includes this header. It
conﬁrms the encryption algorithm that Amazon S3 used to encrypt the object.

Valid Values: AES256 | aws:kms

x-amz-server-side-encryption-aws-kms-key-id (p. 316)

If x-amz-server-side-encryption is present and has the value of aws:kms, this header

speciﬁes the ID of the AWS Key Management Service (AWS KMS) symmetric customer managed
customer master key (CMK) that was used for the object.
x-amz-server-side-encryption-context (p. 316)

Version of the object.

x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
x-amz-version-id: 43jfkodU8493jnFJD9fjj3HHNVfdsQUIFDNsidf038jfdsjGFDSIRp
Date: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "fbacf535f27731c9771645a39863328"
Content-Length: 0
Connection: close
Server: AmazonS3
Server: AmazonS3

Example 2: Specifying the Reduced Redundancy Storage Class

The following request stores the image, my-image.jpg, in the myBucket bucket. The request
speciﬁes the x-amz-storage-class header to request that the object is stored using the
REDUCED_REDUNDANCY storage class.

PUT /my-image.jpg HTTP/1.1

Host: myBucket.s3.<Region>.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: image/jpeg
Content-Length: 11434
Expect: 100-continue
x-amz-storage-class: REDUCED_REDUNDANCY

Sample Response

HTTP/1.1 100 Continue

Example 3: Uploading an object and specifying access permissions explicitly

The following request stores the TestObject.txt file in the myBucket bucket. The request specifies various
ACL headers to grant permission to AWS accounts that are specified with a canonical user ID and an
email address.

PUT TestObject.txt HTTP/1.1

Host: myBucket.s3.<Region>.amazonaws.com
x-amz-date: Fri, 13 Apr 2012 05:40:14 GMT
Authorization: authorization string
x-amz-grant-write-acp: id=8a6925ce4adf588a4532142d3f74dd8c71fa124ExampleCanonicalUserID
x-amz-grant-full-control: emailAddress="[email protected]"
x-amz-grant-write: emailAddress="[email protected]",
emailAddress="[email protected]"
Content-Length: 300
Expect: 100-continue
Connection: Keep-Alive

API Version 2006-03-01

319
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

...Object data in the body...

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: RUxG2sZJUfS+ezeAS2i0Xj6w/ST6xqF/8pFNHjTjTrECW56SCAUWGg+7QLVoj1GH
x-amz-request-id: 8D017A90827290BA
Date: Fri, 13 Apr 2012 05:40:25 GMT
ETag: "dd038b344cf9553547f8b395a814b274"
Content-Length: 0
Server: AmazonS3

Example 4: Using a canned ACL to set access permissions

The following request stores the TestObject.txt ﬁle in the myBucket bucket. The request uses an x-
amz-acl header to specify a canned ACL that grants READ permission to the public.

...Object data in the body...

PUT TestObject.txt HTTP/1.1
Host: myBucket.s3.<Region>.amazonaws.com
x-amz-date: Fri, 13 Apr 2012 05:54:57 GMT
x-amz-acl: public-read
Authorization: authorization string
Content-Length: 300
Expect: 100-continue
Connection: Keep-Alive

...Object data in the body...

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: Yd6PSJxJFQeTYJ/3dDO7miqJfVMXXW0S2Hijo3WFs4bz6oe2QCVXasxXLZdMfASd
x-amz-request-id: 80DF413BB3D28A25
Date: Fri, 13 Apr 2012 05:54:59 GMT
ETag: "dd038b344cf9553547f8b395a814b274"
Content-Length: 0
Server: AmazonS3

Example 5: Upload an object (request server-side encryption using a customer-provided

encryption key

This example of an upload object requests server-side encryption and provides an encryption key.

PUT /example-object HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
Accept: */*
Authorization:authorization string
Date: Wed, 28 May 2014 19:31:11 +0000
x-amz-server-side-encryption-customer-key:g0lCfA3Dv40jZz5SQJ1ZukLRFqtI5WorC/8SEEXAMPLE
x-amz-server-side-encryption-customer-key-MD5:ZjQrne1X/iTcskbY2example

API Version 2006-03-01

320
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-server-side-encryption-customer-algorithm:AES256

In the response, Amazon S3 returns the encryption algorithm and MD5 of the encryption key that you
speciﬁed when uploading the object. The ETag that is returned is not the MD5 of the object.

HTTP/1.1 200 OK
x-amz-id-2: 7qoYGN7uMuFuYS6m7a4lszH6in+hccE+4DXPmDZ7C9KqucjnZC1gI5mshai6fbMG
x-amz-request-id: 06437EDD40C407C7
Date: Wed, 28 May 2014 19:31:12 GMT
x-amz-server-side-encryption-customer-algorithm: AES256
x-amz-server-side-encryption-customer-key-MD5: ZjQrne1X/iTcskbY2example
ETag: "ae89237c20e759c5f479ece02c642f59"

Example 6: Upload an object and specify tags

This example of an upload object request speciﬁes the optional x-amz-tagging header to add tags to
the object.

PUT /example-object HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
Accept: */*
Authorization:authorization string
Date: Thu, 22 Sep 2016 21:58:13 GMT
x-amz-tagging: tag1=value1&tag2=value2

[... bytes of object data]

Example 6: Upload an object and specify tags

This example of an upload object request speciﬁes the optional x-amz-tagging header to add tags to
the object.

After the object is created, Amazon S3 stores the speciﬁed object tags in the tagging subresource that is
associated with the object.

PUT /example-object HTTP/1.1

Host: example-bucket.s3.<Region>.amazonaws.com
Accept: */*
Authorization:authorization string
Date: Thu, 22 Sep 2016 21:58:13 GMT
x-amz-tagging: tag1=value1&tag2=value2

[... bytes of object data]

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: 7qoYGN7uMuFuYS6m7a4lszH6in+hccE+4DXPmDZ7C9KqucjnZC1gI5mshai6fbMG
x-amz-request-id: 06437EDD40C407C7
Date: Thu, 22 Sep 2016 21:58:17 GMT

API Version 2006-03-01

321
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

322
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutObjectAcl
Service: Amazon Simple Storage Service

Uses the acl subresource to set the access control list (ACL) permissions for an object that already exists
in a bucket. You must have WRITE_ACP permission to set the ACL of an object.

Depending on your application needs, you can choose to set the ACL on an object using either the
request body or the headers. For example, if you have an existing application that updates a bucket ACL
using the request body, you can continue to use that approach.

Access Permissions

You can set access permissions using one of the following methods:

• Specify a canned ACL with the x-amz-acl request header. Amazon S3 supports a set of predefined
ACLs, known as canned ACLs. Each canned ACL has a predefined set of grantees and permissions.
Specify the canned ACL name as the value of x-amz-acl. If you use this header, you cannot use other
access control-specific headers in your request. For more information, see Canned ACL.
• Specify access permissions explicitly with the x-amz-grant-read, x-amz-grant-read-acp, x-
amz-grant-write-acp, and x-amz-grant-full-control headers. When using these headers,
you specify explicit access permissions and grantees (AWS accounts or Amazon S3 groups) who will
receive the permission. If you use these ACL-specific headers, you cannot use x-amz-acl header to set
a canned ACL. These parameters map to the set of permissions that Amazon S3 supports in an ACL.
For more information, see Access Control List (ACL) Overview.

For example, the following x-amz-grant-read header grants list objects permission to the two AWS
accounts identiﬁed by their email addresses.

x-amz-grant-read: emailAddress="[email protected]",
emailAddress="[email protected]"

You can use either a canned ACL or specify access permissions explicitly. You cannot do both.

Grantee Values

You can specify the person (grantee) to whom you're assigning access rights (using request elements) in
the following ways:

• By Email address:

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="AmazonCustomerByEmail"><EmailAddress><>[email protected]<></
EmailAddress>lt;/Grantee>

The grantee is resolved to the CanonicalUser and, in a response to a GET Object acl request, appears as
the CanonicalUser.
• By the person's ID:

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser"><ID><>ID<></ID><DisplayName><>GranteesEmail<></
DisplayName> </Grantee>

DisplayName is optional and ignored in the request.

API Version 2006-03-01

323
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• By URI:

Versioning

The ACL of an object is set at the object version level. By default, PUT sets the ACL of the current version
of an object. To set the ACL of a diﬀerent version, use the versionId subresource.

Related Resources

• CopyObject (p. 16)

• GetObject (p. 138)

Request Syntax

PUT /{Key+}?acl&VersionId=VersionId HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-acl: ACL
Content-MD5: ContentMD5
x-amz-grant-full-control: GrantFullControl
x-amz-grant-read: GrantRead
x-amz-grant-read-acp: GrantReadACP
x-amz-grant-write: GrantWrite
x-amz-grant-write-acp: GrantWriteACP
x-amz-request-payer: RequestPayer
<?xml version="1.0" encoding="UTF-8"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<AccessControlList>
<Grant>
<Grantee>
<DisplayName>string</DisplayName>
<EmailAddress>string</EmailAddress>
<ID>string</ID>
<xsi:type>string</xsi:type>
<URI>string</URI>
</Grantee>
<Permission>string</Permission>
</Grant>
</AccessControlList>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
</AccessControlPolicy>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 324)

The bucket name that contains the object to which you want to attach the ACL.

API Version 2006-03-01

324
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

AWS SDKs, you provide the access point ARN in place of the bucket name. For more information
about access point ARNs, see Using Access Points in the Amazon Simple Storage Service Developer
Guide.
Content-MD5 (p. 324)

Key for which the PUT operation was initiated.

Length Constraints: Minimum length of 1.

versionId (p. 324)

VersionId used to reference a speciﬁc version of the object.

x-amz-acl (p. 324)

The canned ACL to apply to the object. For more information, see Canned ACL.

Valid Values: private | public-read | public-read-write | authenticated-read |

aws-exec-read | bucket-owner-read | bucket-owner-full-control
x-amz-grant-full-control (p. 324)

Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
x-amz-grant-read (p. 324)

Allows grantee to list the objects in the bucket.

x-amz-grant-read-acp (p. 324)

Allows grantee to read the bucket ACL.

x-amz-grant-write (p. 324)

Allows grantee to create, overwrite, and delete any object in the bucket.
x-amz-grant-write-acp (p. 324)

Allows grantee to write the ACL for the applicable bucket.

x-amz-request-payer (p. 324)

Valid Values: requester

Request Body
The request accepts the following data in XML format.

AccessControlPolicy (p. 324)

Root level tag for the AccessControlPolicy parameters.

Required: Yes

API Version 2006-03-01

325
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Grants (p. 324)

A list of grants.

Type: Array of Grant (p. 466) data types

Required: No
Owner (p. 324)

Container for the bucket owner's display name and ID.

Type: Owner (p. 512) data type

Required: No

Response Syntax

HTTP/1.1 200
x-amz-request-charged: RequestCharged

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

x-amz-request-charged (p. 326)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

The speciﬁed key does not exist.

Examples
Sample Request

The following request grants access permission to an existing object. The request specifies the ACL in the
body. In addition to granting full control to the object owner, the XML specifies full control to an AWS
account identified by its canonical user ID.

PUT /my-image.jpg?acl HTTP/1.1

Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string
Content-Length: 124

API Version 2006-03-01

326
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeeExampleCanonicalUserID</ID>
<DisplayName>[email protected]</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>

Sample Response

The following shows a sample response when versioning on the bucket is enabled.

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51T9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
x-amz-version-id: 3/L4kqtJlcpXrof3vjVBH40Nr8X8gdRQBpUMLUo
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3

Sample Request: Setting the ACL of a speciﬁed object version

The following request sets the ACL on the speciﬁed version of the object.

PUT /my-image.jpg?acl&versionId=3HL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nrjfkd
HTTP/1.1
Host: bucket.s3.<Region>.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string
Content-Length: 124

<AccessControlPolicy>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser">
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51u8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
x-amz-version-id: 3/L4kqtJlcpXro3vjVBH40Nr8X8gdRQBpUMLUo

API Version 2006-03-01

327
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Date: Wed, 28 Oct 2009 22:32:00 GMT

Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3

Sample Request: Access permissions speciﬁed using headers

The following request sets the ACL on the speciﬁed version of the object.

PUT ExampleObject.txt?acl HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
x-amz-acl: public-read
Accept: */*
Authorization: authorization string
Host: s3.amazonaws.com
Connection: Keep-Alive

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: w5YegkbG6ZDsje4WK56RWPxNQHIQ0CjrjyRVFZhEJI9E3kbabXnBO9w5G7Dmxsgk
x-amz-request-id: C13B2827BD8455B1
Date: Sun, 29 Apr 2012 23:24:12 GMT
Content-Length: 0
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

328
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutObjectLegalHold
Service: Amazon Simple Storage Service

Applies a Legal Hold conﬁguration to the speciﬁed object.

Related Resources

• Locking Objects

Request Syntax

PUT /{Key+}?legal-hold&VersionId=VersionId HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-request-payer: RequestPayer
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<LegalHold xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>string</Status>
</LegalHold>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 329)

The bucket name containing the object that you want to place a Legal Hold on.

The MD5 hash for the request body.

Key (p. 329)

The key name for the object that you want to place a Legal Hold on.

Length Constraints: Minimum length of 1.

versionId (p. 329)

The version ID of the object that you want to place a Legal Hold on.
x-amz-request-payer (p. 329)

Valid Values: requester

Request Body
The request accepts the following data in XML format.

API Version 2006-03-01

329
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

LegalHold (p. 329)

Root level tag for the LegalHold parameters.

Required: Yes
Status (p. 329)

Indicates whether the speciﬁed object has a Legal Hold in place.

Type: String

Valid Values: ON | OFF

Required: No

Response Syntax

HTTP/1.1 200
x-amz-request-charged: RequestCharged

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

x-amz-request-charged (p. 330)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

330
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutObjectLockConﬁguration
Service: Amazon Simple Storage Service

Places an Object Lock configuration on the specified bucket. The rule specified in the Object Lock
configuration will be applied by default to every new object placed in the specified bucket.
Note
DefaultRetention requires either Days or Years. You can't specify both at the same time.

Related Resources

• Locking Objects

Request Syntax

PUT /?object-lock HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-request-payer: RequestPayer
x-amz-bucket-object-lock-token: Token
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<ObjectLockEnabled>string</ObjectLockEnabled>
<Rule>
<DefaultRetention>
<Days>integer</Days>
<Mode>string</Mode>
<Years>integer</Years>
</DefaultRetention>
</Rule>
</ObjectLockConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 331)

The bucket whose Object Lock conﬁguration you want to create or replace.
Content-MD5 (p. 331)

The MD5 hash for the request body.

x-amz-bucket-object-lock-token (p. 331)

A token to allow Object Lock to be enabled for an existing bucket.

x-amz-request-payer (p. 331)

Valid Values: requester

Request Body
The request accepts the following data in XML format.

API Version 2006-03-01

331
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ObjectLockConﬁguration (p. 331)

Root level tag for the ObjectLockConﬁguration parameters.

Required: Yes
ObjectLockEnabled (p. 331)

Indicates whether this bucket has an Object Lock conﬁguration enabled.

Type: String

Valid Values: Enabled

Required: No
Rule (p. 331)

The Object Lock rule in place for the speciﬁed object.

Type: ObjectLockRule (p. 507) data type

Required: No

Response Syntax

HTTP/1.1 200
x-amz-request-charged: RequestCharged

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

x-amz-request-charged (p. 332)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

332
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutObjectRetention
Service: Amazon Simple Storage Service

Places an Object Retention conﬁguration on an object.

Related Resources

• Locking Objects

Request Syntax

PUT /{Key+}?retention&VersionId=VersionId HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-request-payer: RequestPayer
x-amz-bypass-governance-retention: BypassGovernanceRetention
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<Retention xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Mode>string</Mode>
<RetainUntilDate>timestamp</RetainUntilDate>
</Retention>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 333)

The bucket name that contains the object you want to apply this Object Retention conﬁguration to.

The MD5 hash for the request body.

Key (p. 333)

The key name for the object that you want to apply this Object Retention conﬁguration to.

Length Constraints: Minimum length of 1.

versionId (p. 333)

The version ID for the object that you want to apply this Object Retention conﬁguration to.
x-amz-bypass-governance-retention (p. 333)

Indicates whether this operation should bypass Governance-mode restrictions.

x-amz-request-payer (p. 333)

API Version 2006-03-01

333
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Valid Values: requester

Request Body
The request accepts the following data in XML format.

Retention (p. 333)

Root level tag for the Retention parameters.

Required: Yes
Mode (p. 333)

Indicates the Retention mode for the speciﬁed object.

Type: String

Valid Values: GOVERNANCE | COMPLIANCE

Required: No
RetainUntilDate (p. 333)

The date on which this Object Lock Retention will expire.

Type: Timestamp

Required: No

Response Syntax

HTTP/1.1 200
x-amz-request-charged: RequestCharged

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

x-amz-request-charged (p. 334)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript

API Version 2006-03-01

334
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

335
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutObjectTagging
Service: Amazon Simple Storage Service

Sets the supplied tag-set to an object that already exists in a bucket

A tag is a key-value pair. You can associate tags with an object by sending a PUT request against the
tagging subresource that is associated with the object. You can retrieve tags by sending a GET request.
For more information, see GetObjectTagging (p. 160).

For tagging-related restrictions related to characters and encodings, see Tag Restrictions. Note that
Amazon S3 limits the maximum number of tags to 10 tags per object.

To use this operation, you must have permission to perform the s3:PutObjectTagging action. By
default, the bucket owner has this permission and can grant this permission to others.

To put tags of any other version, use the versionId query parameter. You also need permission for the
s3:PutObjectVersionTagging action.

For information about the Amazon S3 object tagging feature, see Object Tagging.

Special Errors

•
• Code: InvalidTagError
• Cause: The tag provided was not a valid tag. This error can occur if the tag did not pass input
validation. For more information, see Object Tagging.
•
• Code: MalformedXMLError
• Cause: The XML provided does not match the schema.
• • Code: OperationAbortedError
• Cause: A conﬂicting conditional operation is currently in progress against this resource. Please try
again.
• • Code: InternalError
• Cause: The service was unable to apply the provided tag to the object.

Related Resources

• GetObjectTagging (p. 160)

Request Syntax

PUT /{Key+}?tagging&VersionId=VersionId HTTP/1.1

URI Request Parameters

The request requires the following URI parameters.

API Version 2006-03-01

336
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Bucket (p. 336)

The bucket name containing the object.

The MD5 hash for the request body.

Key (p. 336)

Name of the tag.

Length Constraints: Minimum length of 1.

versionId (p. 336)

The versionId of the object that the tag-set will be added to.

Request Body
The request accepts the following data in XML format.

Tagging (p. 336)

Root level tag for the Tagging parameters.

Required: Yes
TagSet (p. 336)

A collection for a set of tags

Type: Array of Tag (p. 559) data types

Required: Yes

Response Syntax

HTTP/1.1 200
x-amz-version-id: VersionId

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

x-amz-version-id (p. 337)

The versionId of the object the tag-set was added to.

API Version 2006-03-01

337
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Examples
Sample Request: Add tag set to an object

The following request adds a tag set to the existing object object-key in the examplebucket bucket.

PUT object-key?tagging HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Content-Length: length
Content-MD5: pUNXr/BjKK5G2UKExample==
x-amz-date: 20160923T001956Z
Authorization: authorization string
<Tagging>
<TagSet>
<Tag>
<Key>tag1</Key>
<Value>val1</Value>
</Tag>
<Tag>
<Key>tag2</Key>
<Value>val2</Value>
</Tag>
</TagSet>
</Tagging>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Fri, 23 Sep 2016 00:20:19 GMT

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

338
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PutPublicAccessBlock
Service: Amazon Simple Storage Service

Creates or modifies the PublicAccessBlock configuration for an Amazon S3 bucket. To use this
operation, you must have the s3:PutBucketPublicAccessBlock permission. For more information
about Amazon S3 permissions, see Specifying Permissions in a Policy.
Important
When Amazon S3 evaluates the PublicAccessBlock configuration for a bucket or an object, it
checks the PublicAccessBlock configuration for both the bucket (or the bucket that contains
the object) and the bucket owner's account. If the PublicAccessBlock configurations are
different between the bucket and the account, Amazon S3 uses the most restrictive combination
of the bucket-level and account-level settings.

For more information about when Amazon S3 considers a bucket or an object public, see The Meaning of
"Public".

Related Resources

• GetPublicAccessBlock (p. 165)

• DeletePublicAccessBlock (p. 77)
• GetBucketPolicyStatus (p. 121)
• Using Amazon S3 Block Public Access

Request Syntax

PUT /?publicAccessBlock HTTP/1.1

Host: Bucket.s3.amazonaws.com
Content-MD5: ContentMD5
<?xml version="1.0" encoding="UTF-8"?>
<PublicAccessBlockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<BlockPublicAcls>boolean</BlockPublicAcls>
<IgnorePublicAcls>boolean</IgnorePublicAcls>
<BlockPublicPolicy>boolean</BlockPublicPolicy>
<RestrictPublicBuckets>boolean</RestrictPublicBuckets>
</PublicAccessBlockConfiguration>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 339)

The name of the Amazon S3 bucket whose PublicAccessBlock conﬁguration you want to set.
Content-MD5 (p. 339)

The MD5 hash of the PutPublicAccessBlock request body.

Request Body
The request accepts the following data in XML format.

PublicAccessBlockConﬁguration (p. 339)

Root level tag for the PublicAccessBlockConﬁguration parameters.

Required: Yes

API Version 2006-03-01

339
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

BlockPublicAcls (p. 339)

Enabling this setting doesn't aﬀect existing policies or ACLs.

Type: Boolean

Required: No
BlockPublicPolicy (p. 339)

Enabling this setting doesn't aﬀect existing bucket policies.

Type: Boolean

Required: No
IgnorePublicAcls (p. 339)

Enabling this setting doesn't aﬀect the persistence of any existing ACLs and doesn't prevent new
public ACLs from being set.

Type: Boolean

Required: No
RestrictPublicBuckets (p. 339)

Type: Boolean

Required: No

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

API Version 2006-03-01

340
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Examples
First Sample Request

The following request puts a bucket PublicAccessBlock conﬁguration that rejects public ACLs.

PUT /<bucket-name>?publicAccessBlock HTTP/1.1

Host: <bucket-name>.s3.<Region>.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <signatureValue>

<?xml version="1.0" encoding="UTF-8"?>

First Sample Response

HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0

Second Sample Request

The following request puts a bucket PublicAccessBlock conﬁguration that ignores public ACLs and
restricts access to public buckets.

PUT /<bucket-name>?publicAccessBlock HTTP/1.1

Host: <bucket-name>.s3.<Region>.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <signatureValue>

<?xml version="1.0" encoding="UTF-8"?>

<PublicAccessBlockConfiguration>
<BlockPublicAcls>FALSE</BlockPublicAcls>
<IgnorePublicAcls>TRUE</IgnorePublicAcls>
<BlockPublicPolicy>FALSE</BlockPublicPolicy>
<RestrictPublicBuckets>TRUE</RestrictPublicBuckets>
</PublicAccessBlockConfiguration>

Second Sample Response

HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3

API Version 2006-03-01

341
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Content-Length: 0

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

342
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

RestoreObject
Service: Amazon Simple Storage Service

Restores an archived copy of an object back into Amazon S3

This operation performs the following types of requests:

• select - Perform a select query on an archived object

• restore an archive - Restore an archived object

To use this operation, you must have permissions to perform the s3:RestoreObject and
s3:GetObject actions. The bucket owner has this permission by default and can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple
Storage Service Developer Guide.

Querying Archives with Select Requests

You use a select type of request to perform SQL queries on archived objects. The archived objects that
are being queried by the select request must be formatted as uncompressed comma-separated values
(CSV) ﬁles. You can run queries and custom analytics on your archived data without having to restore
your data to a hotter Amazon S3 tier. For an overview about select requests, see Querying Archived
Objects in the Amazon Simple Storage Service Developer Guide.

When making a select request, do the following:

• Deﬁne an output location for the select query's output. This must be an Amazon S3 bucket in the same
AWS Region as the bucket that contains the archive object that is being queried. The AWS account that
initiates the job must have permissions to write to the S3 bucket. You can specify the storage class
and encryption for the output objects stored in the bucket. For more information about output, see
Querying Archived Objects in the Amazon Simple Storage Service Developer Guide.

For more information about the S3 structure in the request body, see the following:
• PutObject (p. 310)
• Managing Access with ACLs in the Amazon Simple Storage Service Developer Guide
• Protecting Data Using Server-Side Encryption in the Amazon Simple Storage Service Developer Guide
• Deﬁne the SQL expression for the SELECT type of restoration for your query in the request body's
SelectParameters structure. You can use expressions like the following examples.
• The following expression returns all records from the speciﬁed object.

SELECT * FROM Object

• Assuming that you are not using any headers for data stored in the object, you can specify columns
with positional headers.

SELECT s._1, s._2 FROM Object s WHERE s._3 > 100

• If you have headers and you set the fileHeaderInfo in the CSV structure in the request body to
USE, you can specify headers in the query. (If you set the fileHeaderInfo ﬁeld to IGNORE, the
ﬁrst row is skipped for the query.) You cannot mix ordinal positions with header column names.

SELECT s.Id, s.FirstName, s.SSN FROM S3Object s

For more information about using SQL with Glacier Select restore, see SQL Reference for Amazon S3
Select and Glacier Select in the Amazon Simple Storage Service Developer Guide.

When making a select request, you can also do the following:

API Version 2006-03-01

343
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• To expedite your queries, specify the Expedited tier. For more information about tiers, see "Restoring
Archives," later in this topic.
• Specify details about the data serialization format of both the input object that is being queried and
the serialization of the CSV-encoded query results.

The following are additional important facts about the select feature:

• The output results are new Amazon S3 objects. Unlike archive retrievals, they are stored until explicitly
deleted-manually or through a lifecycle policy.
• You can issue more than one select request on the same Amazon S3 object. Amazon S3 doesn't
deduplicate requests, so avoid issuing duplicate requests.
• Amazon S3 accepts a select request even if the object has already been restored. A select request
doesn’t return error response 409.

Restoring Archives

Objects in the GLACIER and DEEP_ARCHIVE storage classes are archived. To access an archived object,
you must ﬁrst 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
speciﬁed period, Amazon S3 deletes the temporary copy but the object remains archived in the GLACIER
or DEEP_ARCHIVE storage class that object was restored from.

To restore a speciﬁc object version, you can provide a version ID. If you don't provide a version ID,
Amazon S3 restores the current version.

The time it takes restore jobs to ﬁnish depends on which storage class the object is being restored from
and which data access tier you specify.

When restoring an archived object (or using a select request), you can specify one of the following data
access tier options in the Tier element of the request body:

• Expedited - Expedited retrievals allow you to quickly access your data stored in the GLACIER storage
class when occasional urgent requests for a subset of archives are required. For all but the largest
archived objects (250 MB+), data accessed using Expedited retrievals are typically made available
within 1–5 minutes. Provisioned capacity ensures that retrieval capacity for Expedited retrievals is
available when you need it. Expedited retrievals and provisioned capacity are not available for the
DEEP_ARCHIVE storage class.
• Standard - Standard retrievals allow you to access any of your archived objects within several hours.
This is the default option for the GLACIER and DEEP_ARCHIVE retrieval requests that do not specify
the retrieval option. Standard retrievals typically complete within 3-5 hours from the GLACIER storage
class and typically complete within 12 hours from the DEEP_ARCHIVE storage class.
• Bulk - Bulk retrievals are Amazon S3 Glacier’s lowest-cost retrieval option, enabling you to retrieve
large amounts, even petabytes, of data inexpensively in a day. Bulk retrievals typically complete
within 5-12 hours from the GLACIER storage class and typically complete within 48 hours from the
DEEP_ARCHIVE storage class.

For more information about archive retrieval options and provisioned capacity for Expedited data
access, see Restoring Archived Objects in the Amazon Simple Storage Service Developer Guide.

You can use Amazon S3 restore speed upgrade to change the restore speed to a faster speed while it is
in progress. You upgrade the speed of an in-progress restoration by issuing another restore request to
the same object, setting a new Tier request element. When issuing a request to upgrade the restore
tier, you must choose a tier that is faster than the tier that the in-progress restore is using. You must not
change any other parameters, such as the Days request element. For more information, see Upgrading
the Speed of an In-Progress Restore in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

344
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

To get the status of object restoration, you can send a HEAD request. Operations return the x-amz-
restore header, which provides information about the restoration status, in the response. You can
use Amazon S3 event notifications to notify you when a restore is initiated or completed. For more
information, see Configuring Amazon S3 Event Notifications in the Amazon Simple Storage Service
Developer Guide.

After restoring an archived object, you can update the restoration period by reissuing the request with a
new period. Amazon S3 updates the restoration period relative to the current time and charges only for
the request-there are no data transfer charges. You cannot update the restoration period when Amazon
S3 is actively processing your current restore request for the object.

If your bucket has a lifecycle configuration with a rule that includes an expiration action, the object
expiration overrides the life span that you specify in a restore request. For example, if you restore an
object copy for 10 days, but the object is scheduled to expire in 3 days, Amazon S3 deletes the object in
3 days. For more information about lifecycle configuration, see PutBucketLifecycleConfiguration (p. 264)
and Object Lifecycle Management in Amazon Simple Storage Service Developer Guide.

Responses

A successful operation returns either the 200 OK or 202 Accepted status code.

• If the object copy is not previously restored, then Amazon S3 returns 202 Accepted in the response.
• If the object copy is previously restored, Amazon S3 returns 200 OK in the response.

Special Errors

•
• Code: RestoreAlreadyInProgress
• Cause: Object restore is already in progress. (This error does not apply to SELECT type requests.)
• HTTP Status Code: 409 Conflict
• SOAP Fault Code Prefix: Client
•
• Code: GlacierExpeditedRetrievalNotAvailable
• Cause: Glacier expedited retrievals are currently not available. Try again later. (Returned if there is
insufficient capacity to process the Expedited request. This error applies only to Expedited retrievals and
not to Standard or Bulk retrievals.)
• HTTP Status Code: 503
• SOAP Fault Code Prefix: N/A

Related Resources

• PutBucketLifecycleConﬁguration (p. 264)

• GetBucketNotiﬁcationConﬁguration (p. 116)
• SQL Reference for Amazon S3 Select and Glacier Select in the Amazon Simple Storage Service
Developer Guide

Request Syntax

POST /{Key+}?restore&VersionId=VersionId HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-request-payer: RequestPayer
<?xml version="1.0" encoding="UTF-8"?>
<RestoreRequest xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Days>integer</Days>
<GlacierJobParameters>

API Version 2006-03-01

345
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<Tier>string</Tier>
</GlacierJobParameters>
<Type>string</Type>
<Tier>string</Tier>
<Description>string</Description>
<SelectParameters>
<Expression>string</Expression>
<ExpressionType>string</ExpressionType>
<InputSerialization>
<CompressionType>string</CompressionType>
<CSV>
<AllowQuotedRecordDelimiter>boolean</AllowQuotedRecordDelimiter>
<Comments>string</Comments>
<FieldDelimiter>string</FieldDelimiter>
<FileHeaderInfo>string</FileHeaderInfo>
<QuoteCharacter>string</QuoteCharacter>
<QuoteEscapeCharacter>string</QuoteEscapeCharacter>
<RecordDelimiter>string</RecordDelimiter>
</CSV>
<JSON>
<Type>string</Type>
</JSON>
<Parquet>
</Parquet>
</InputSerialization>
<OutputSerialization>
<CSV>
<FieldDelimiter>string</FieldDelimiter>
<QuoteCharacter>string</QuoteCharacter>
<QuoteEscapeCharacter>string</QuoteEscapeCharacter>
<QuoteFields>string</QuoteFields>
<RecordDelimiter>string</RecordDelimiter>
</CSV>
<JSON>
<RecordDelimiter>string</RecordDelimiter>
</JSON>
</OutputSerialization>
</SelectParameters>
<OutputLocation>
<S3>
<AccessControlList>
<Grant>
<Grantee>
<DisplayName>string</DisplayName>
<EmailAddress>string</EmailAddress>
<ID>string</ID>
<xsi:type>string</xsi:type>
<URI>string</URI>
</Grantee>
<Permission>string</Permission>
</Grant>
</AccessControlList>
<BucketName>string</BucketName>
<CannedACL>string</CannedACL>
<Encryption>
<EncryptionType>string</EncryptionType>
<KMSContext>string</KMSContext>
<KMSKeyId>string</KMSKeyId>
</Encryption>
<Prefix>string</Prefix>
<StorageClass>string</StorageClass>
<Tagging>
<TagSet>
<Tag>
<Key>string</Key>
<Value>string</Value>

API Version 2006-03-01

346
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

</Tag>
</TagSet>
</Tagging>
<UserMetadata>
<MetadataEntry>
<Name>string</Name>
<Value>string</Value>
</MetadataEntry>
</UserMetadata>
</S3>
</OutputLocation>
</RestoreRequest>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 345)

The bucket name or containing the object to restore.

Object key for which the operation was initiated.

Length Constraints: Minimum length of 1.

versionId (p. 345)

VersionId used to reference a speciﬁc version of the object.

x-amz-request-payer (p. 345)

Valid Values: requester

Request Body
The request accepts the following data in XML format.

RestoreRequest (p. 345)

Root level tag for the RestoreRequest parameters.

Required: Yes
Days (p. 345)

Lifetime of the active copy in days. Do not use with restores that specify OutputLocation.

Type: Integer

API Version 2006-03-01

347
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Required: No
Description (p. 345)

The optional description for the job.

Type: String

Required: No
GlacierJobParameters (p. 345)

Glacier related parameters pertaining to this job. Do not use with restores that specify
OutputLocation.

Type: GlacierJobParameters (p. 465) data type

Required: No
OutputLocation (p. 345)

Describes the location where the restore job's output is stored.

Type: OutputLocation (p. 510) data type

Required: No
SelectParameters (p. 345)

Describes the parameters for Select job types.

Type: SelectParameters (p. 547) data type

Required: No
Tier (p. 345)

Glacier retrieval tier at which the restore will be processed.

Type: String

Valid Values: Standard | Bulk | Expedited

Required: No
Type (p. 345)

Type of restore request.

Type: String

Valid Values: SELECT

Required: No

Response Syntax

HTTP/1.1 200
x-amz-request-charged: RequestCharged
x-amz-restore-output-path: RestoreOutputPath

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

API Version 2006-03-01

348
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

The response returns the following HTTP headers.

x-amz-request-charged (p. 348)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

x-amz-restore-output-path (p. 348)

Indicates the path in the provided S3 output location where Select results will be restored to.

This operation is not allowed against this storage tier.

Examples
Restore an object for 2 days using the expedited retrieval option

The following restore request restores a copy of the photo1.jpg object from Glacier for a period of two
days using the expedited retrieval option.

Host: examplebucket.dummy value

Date: Mon, 22 Oct 2012 01:49:52 GMT
Authorization: authorization string
Content-Length: content length

<RestoreRequest>
<Days>2</Days>
<GlacierJobParameters>
<Tier>Expedited</Tier>
</GlacierJobParameters>
</RestoreRequest>

If the examplebucket does not have a restored copy of the object, Amazon S3 returns the following
202 Accepted response.
Note
If a copy of the object is already restored, Amazon S3 returns a 200 OK response, and updates
only the restored copy's expiry time.

HTTP/1.1 202 Accepted

x-amz-id-2: GFihv3y6+kE7KG11GEkQhU7/2/cHR3Yb2fCb2S04nxI423Dqwg2XiQ0B/UZlzYQvPiBlZNRcovw=
x-amz-request-id: 9F341CD3C4BA79E0
Date: Sat, 20 Oct 2012 23:54:05 GMT
Content-Length: 0
Server: AmazonS3

Query an archive with a SELECT request

The following is an example SELECT restore request.

POST /object-one.csv?restore HTTP/1.1

Host: examplebucket.dummy value

API Version 2006-03-01

349
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Date: Date: Sat, 20 Oct 2012 23:54:05 GMT

Authorization: <>authorization string</>
Content-Length: <>content length</>

<RestoreRequest xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Type>SELECT</Type>
<Tier>Expedited</Tier>
<Description>this is a description</Description>
<SelectParameters>
<InputSerialization>
<CSV>
<FileHeaderInfo>IGNORE</FileHeaderInfo>
<Comments>#</Comments>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
</CSV>
</InputSerialization>
<ExpressionType>SQL</ExpressionType>
<Expression>select * from object</Expression>
<OutputSerialization>
<CSV>
<QuoteFields>ALWAYS</QuoteFields>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>\t</FieldDelimiter>
<QuoteCharacter>\'</QuoteCharacter>
</CSV>
</OutputSerialization>
</SelectParameters>
<OutputLocation>
<S3>
<BucketName>example-output-bucket</BucketName>
<Prefix>test-s3</Prefix>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="AmazonCustomerByEmail">
<EmailAddress>[email protected]</EmailAddress>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
<UserMetadata>
<MetadataEntry>
<Name>test</Name>
<Value>test-value</Value>
</MetadataEntry>
<MetadataEntry>
<Name>other</Name>
<Value>something else</Value>
</MetadataEntry>
</UserMetadata>
<StorageClass>STANDARD</StorageClass>
</S3>
</OutputLocation>
</RestoreRequest>

Amazon S3 returns the following 202 Accepted response.

HTTP/1.1 202 Accepted

API Version 2006-03-01

350
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-id-2: GFihv3y6+kE7KG11GEkQhU7/2/cHR3Yb2fCb2S04nxI423Dqwg2XiQ0B/UZlzYQvPiBlZNRcovw=
x-amz-request-id: 9F341CD3C4BA79E0
x-amz-restore-output-path: js-test-s3/qE8nk5M0XIj-LuZE2HXNw6empQm3znLkHlMWInRYPS-
Orl2W0uj6LyYm-neTvm1-btz3wbBxfMhPykd3jkl-lvZE7w42/
Date: Sat, 20 Oct 2012 23:54:05 GMT
Content-Length: 0
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

351
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

SelectObjectContent
Service: Amazon Simple Storage Service

This operation ﬁlters the contents of an Amazon S3 object based on a simple structured query language
(SQL) statement. In the request, along with the SQL expression, you must also specify a data serialization
format (JSON, CSV, or Apache Parquet) of the object. Amazon S3 uses this format to parse object data
into records, and returns only records that match the speciﬁed SQL expression. You must also specify the
data serialization format for the response.

For more information about Amazon S3 Select, see Selecting Content from Objects in the Amazon
Simple Storage Service Developer Guide.

For more information about using SQL with Amazon S3 Select, see SQL Reference for Amazon S3 Select
and Glacier Select in the Amazon Simple Storage Service Developer Guide.

Permissions

You must have s3:GetObject permission for this operation. Amazon S3 Select does not support
anonymous access. For more information about permissions, see Specifying Permissions in a Policy in the
Amazon Simple Storage Service Developer Guide.

Object Data Formats

You can use Amazon S3 Select to query objects that have the following format properties:

• CSV, JSON, and Parquet - Objects must be in CSV, JSON, or Parquet format.
• UTF-8 - UTF-8 is the only encoding type Amazon S3 Select supports.
• GZIP or BZIP2 - CSV and JSON ﬁles can be compressed using GZIP or BZIP2. GZIP and BZIP2 are the
only compression formats that Amazon S3 Select supports for CSV and JSON ﬁles. Amazon S3 Select
supports columnar compression for Parquet using GZIP or Snappy. Amazon S3 Select does not support
whole-object compression for Parquet objects.
• Server-side encryption - Amazon S3 Select supports querying objects that are protected with server-
side encryption.

For objects that are encrypted with customer-provided encryption keys (SSE-C), you must use HTTPS,
and you must use the headers that are documented in the GetObject (p. 138). For more information
about SSE-C, see Server-Side Encryption (Using Customer-Provided Encryption Keys) in the Amazon
Simple Storage Service Developer Guide.

For objects that are encrypted with Amazon S3 managed encryption keys (SSE-S3) and customer
master keys (CMKs) stored in AWS Key Management Service (SSE-KMS), server-side encryption is
handled transparently, so you don't need to specify anything. For more information about server-side
encryption, including SSE-S3 and SSE-KMS, see Protecting Data Using Server-Side Encryption in the
Amazon Simple Storage Service Developer Guide.

Working with the Response Body

Given the response size is unknown, Amazon S3 Select streams the response as a series of messages
and includes a Transfer-Encoding header with chunked as its value in the response. For more
information, see Appendix: SelectObjectContent Response (p. 720) .

GetObject Support

The SelectObjectContent operation does not support the following GetObject functionality. For
more information, see GetObject (p. 138).

• Range: While you can specify a scan range for a Amazon S3 Select request, see
SelectObjectContent:ScanRange (p. 355) in the request parameters below, you cannot specify the
range of bytes of an object to return.

API Version 2006-03-01

352
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• GLACIER, DEEP_ARCHIVE and REDUCED_REDUNDANCY storage classes: You cannot specify the
GLACIER, DEEP_ARCHIVE, or REDUCED_REDUNDANCY storage classes. For more information, about
storage classes see Storage Classes in the Amazon Simple Storage Service Developer Guide.

Special Errors

For a list of special errors for this operation, see List of SELECT Object Content Error Codes (p. 693)

Related Resources

• GetObject (p. 138)

• GetBucketLifecycleConﬁguration (p. 102)
• PutBucketLifecycleConﬁguration (p. 264)

Request Syntax

POST /{Key+}?select&select-type=2 HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key: SSECustomerKey
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
<?xml version="1.0" encoding="UTF-8"?>
<SelectObjectContentRequest xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Expression>string</Expression>
<ExpressionType>string</ExpressionType>
<RequestProgress>
<Enabled>boolean</Enabled>
</RequestProgress>
<InputSerialization>
<CompressionType>string</CompressionType>
<CSV>
<AllowQuotedRecordDelimiter>boolean</AllowQuotedRecordDelimiter>
<Comments>string</Comments>
<FieldDelimiter>string</FieldDelimiter>
<FileHeaderInfo>string</FileHeaderInfo>
<QuoteCharacter>string</QuoteCharacter>
<QuoteEscapeCharacter>string</QuoteEscapeCharacter>
<RecordDelimiter>string</RecordDelimiter>
</CSV>
<JSON>
<Type>string</Type>
</JSON>
<Parquet>
</Parquet>
</InputSerialization>
<OutputSerialization>
<CSV>
<FieldDelimiter>string</FieldDelimiter>
<QuoteCharacter>string</QuoteCharacter>
<QuoteEscapeCharacter>string</QuoteEscapeCharacter>
<QuoteFields>string</QuoteFields>
<RecordDelimiter>string</RecordDelimiter>
</CSV>
<JSON>
<RecordDelimiter>string</RecordDelimiter>
</JSON>
</OutputSerialization>
<ScanRange>
<End>long</End>
<Start>long</Start>
</ScanRange>

API Version 2006-03-01

353
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

</SelectObjectContentRequest>

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 353)

The S3 bucket.
Key (p. 353)

The object key.

Length Constraints: Minimum length of 1.

x-amz-server-side-encryption-customer-algorithm (p. 353)

The SSE Algorithm used to encrypt the object. For more information, see Server-Side Encryption
(Using Customer-Provided Encryption Keys.
x-amz-server-side-encryption-customer-key (p. 353)

The SSE Customer Key. For more information, see Server-Side Encryption (Using Customer-Provided
Encryption Keys.
x-amz-server-side-encryption-customer-key-MD5 (p. 353)

The SSE Customer Key MD5. For more information, see Server-Side Encryption (Using Customer-
Provided Encryption Keys.

Request Body
The request accepts the following data in XML format.

SelectObjectContentRequest (p. 353)

Root level tag for the SelectObjectContentRequest parameters.

Required: Yes
Expression (p. 353)

The expression that is used to query the object.

Type: String

Required: Yes
ExpressionType (p. 353)

The type of the provided expression (for example, SQL).

Type: String

Valid Values: SQL

Required: Yes
InputSerialization (p. 353)

Describes the format of the data in the object that is being queried.

Type: InputSerialization (p. 470) data type

API Version 2006-03-01

354
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Required: Yes
OutputSerialization (p. 353)

Describes the format of the data that you want Amazon S3 to return in response.

Type: OutputSerialization (p. 511) data type

Required: Yes
RequestProgress (p. 353)

Speciﬁes if periodic request progress information should be enabled.

Type: RequestProgress (p. 536) data type

Required: No
ScanRange (p. 353)

Specifies the byte range of the object to get the records from. A record is processed when its first
byte is contained by the range. This parameter is optional, but when specified, it must not be empty.
See RFC 2616, Section 14.35.1 about how to specify the start and end of the range.

ScanRangemay be used in the following ways:

• <scanrange><start>50</start><end>100</end></scanrange> - process only the records
starting between the bytes 50 and 100 (inclusive, counting from zero)
• <scanrange><start>50</start></scanrange> - process only the records starting after the
byte 50
• <scanrange><end>50</end></scanrange> - process only the records within the last 50 bytes
of the ﬁle.

Type: ScanRange (p. 545) data type

Required: No

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<Payload>
<Records>
<Payload>blob</Payload>
</Records>
<Stats>
<Details>
<BytesProcessed>long</BytesProcessed>
<BytesReturned>long</BytesReturned>
<BytesScanned>long</BytesScanned>
</Details>
</Stats>
<Progress>
<Details>
<BytesProcessed>long</BytesProcessed>
<BytesReturned>long</BytesReturned>
<BytesScanned>long</BytesScanned>
</Details>
</Progress>
<Cont>
</Cont>
<End>
</End>

API Version 2006-03-01

355
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

</Payload>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

Payload (p. 355)

Root level tag for the Payload parameters.

Required: Yes
Cont (p. 355)

The Continuation Event.

Type: ContinuationEvent (p. 432) data type

End (p. 355)

The End Event.

Type: EndEvent (p. 451) data type

Progress (p. 355)

The Progress Event.

Type: ProgressEvent (p. 517) data type

Records (p. 355)

The Records Event.

Type: RecordsEvent (p. 524) data type

Stats (p. 355)

The Stats Event.

Type: StatsEvent (p. 556) data type

Examples
Example 1: CSV object

The following select request retrieves all records from an object with data stored in CSV format. The
OutputSerialization element directs Amazon S3 to return results in CSV.

You can try diﬀerent queries in the Expression element:

• Assuming that you are not using column headers, you can identify columns using positional headers:

SELECT s._1, s._2 FROM S3Object s WHERE s._3 > 100

• If you have column headers and you set the FileHeaderInfo to Use, you can identify columns by
name in the expression:

role="nocopy" language="sql">SELECT s.Id, s.FirstName, s.SSN FROM S3Object s

• You can specify functions in the SQL expression:

SELECT count(*) FROM S3Object s WHERE s._1 < 1

API Version 2006-03-01

356
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

POST /exampleobject.csv?select&select-type=2 HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Tue, 17 Oct 2017 01:49:52 GMT
Authorization: authorization string
Content-Length: content length

<?xml version="1.0" encoding="UTF-8"?>

<SelectRequest>
<Expression>Select * from S3Object</Expression>
<ExpressionType>SQL</ExpressionType>
<InputSerialization>
<CompressionType>GZIP</CompressionType>
<CSV>
<FileHeaderInfo>IGNORE</FileHeaderInfo>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
<Comments>#</Comments>
</CSV>
</InputSerialization>
<OutputSerialization>
<CSV>
<QuoteFields>ASNEEDED</QuoteFields>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
</CSV>
</OutputSerialization>
</SelectRequest>

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: GFihv3y6+kE7KG11GEkQhU7/2/cHR3Yb2fCb2S04nxI423Dqwg2XiQ0B/UZlzYQvPiBlZNRcovw=
x-amz-request-id: 9F341CD3C4BA79E0
Date: Tue, 17 Oct 2017 23:54:05 GMT

A series of messages

Example 2: JSON object

The following select request retrieves all records from an object with data stored in JSON format. The
OutputSerialization directs Amazon S3 to return results in CSV.

You can try diﬀerent queries in the Expression element:

• You can ﬁlter by string comparison using record keys:

SELECT s.country, s.city from S3Object s where s.city = 'Seattle'

• You can specify functions in the SQL expression:

SELECT count(*) FROM S3Object s

API Version 2006-03-01

357
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

POST /exampleobject.json?select&select-type=2 HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Tue, 17 Oct 2017 01:49:52 GMT
Authorization: authorization string
Content-Length: content length

<?xml version="1.0" encoding="UTF-8"?>

<SelectRequest>
<Expression>Select * from S3Object</Expression>
<ExpressionType>SQL</ExpressionType>
<InputSerialization>
<CompressionType>GZIP</CompressionType>
<JSON>
<Type>DOCUMENT</Type>
</JSON>
</InputSerialization>
<OutputSerialization>
<CSV>
<QuoteFields>ASNEEDED</QuoteFields>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
</CSV>
</OutputSerialization>
</SelectRequest>

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: GFihv3y6+kE7KG11GEkQhU7/2/cHR3Yb2fCb2S04nxI423Dqwg2XiQ0B/UZlzYQvPiBlZNRcovw=
x-amz-request-id: 9F341CD3C4BA79E0
Date: Tue, 17 Oct 2017 23:54:05 GMT

A series of messages

Example 3: Parquet object

• The InputSerialization element describes the format of the data in the object that is being
queried. It must specify CSV, JSON, or Parquet.
• The OutputSerialization element describes the format of the data that you want Amazon S3
to return in response to the query. It must specify CSV, JSON. Amazon S3 doesn't support outputting
data in the Parquet format.
• The format of the InputSerialization doesn't need to match the format of the
OutputSerialization. So, for example, you can specify JSON in the InputSerialization and
CSV in the OutputSerialization.

POST /exampleobject.parquet?select&select-type=2 HTTP/1.1

Host: examplebucket.s3.<Region>.amazonaws.com
Date: Tue, 17 Oct 2017 01:49:52 GMT
Authorization: authorization string
Content-Length: content length

API Version 2006-03-01

358
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

<?xml version="1.0" encoding="UTF-8"?>

<SelectRequest>
<Expression>Select * from S3Object</Expression>
<ExpressionType>SQL</ExpressionType>
<InputSerialization>
<CompressionType>NONE</CompressionType>
<Parquet>
</Parquet>
</InputSerialization>
<OutputSerialization>
<CSV>
<QuoteFields>ASNEEDED</QuoteFields>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
</CSV>
</OutputSerialization>
</SelectRequest>

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

359
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

UploadPart
Service: Amazon Simple Storage Service

Uploads a part in a multipart upload.

Note
In this operation, you provide part data in your request. However, you have an option to specify
your existing Amazon S3 object as a data source for the part you are uploading. To upload a part
from an existing object, you use the UploadPartCopy (p. 365) operation.

You must initiate a multipart upload (see CreateMultipartUpload (p. 32)) before you can upload any part.
In response to your initiate request, Amazon S3 returns an upload ID, a unique identiﬁer, that you must
include in your upload part request.

Part numbers can be any number from 1 to 10,000, inclusive. A part number uniquely identiﬁes a part
and also deﬁnes 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.

Note: 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, Amazon S3 frees up the parts storage and stops charging you
for the parts storage.

For more information on multipart uploads, go to Multipart Upload Overview in the Amazon Simple
Storage Service Developer Guide .

For information on the permissions required to use the multipart upload API, go to Multipart Upload API
and Permissions in the Amazon Simple Storage Service Developer Guide.

You can optionally request server-side encryption where Amazon S3 encrypts your data as it writes it to
disks in its data centers and decrypts it for you when you access it. You have the option of providing your
own encryption key, or you can use the AWS managed encryption keys. If you choose to provide your
own encryption key, the request headers you provide in the request must match the headers you used in
the request to initiate the upload by using CreateMultipartUpload (p. 32). For more information, go to
Using Server-Side Encryption in the Amazon Simple Storage Service Developer Guide.

Server-side encryption is supported by the S3 Multipart Upload actions. Unless you are using a
customer-provided encryption key, you don't need to specify the encryption parameters in each
UploadPart request. Instead, you only need to specify the server-side encryption parameters in the initial
Initiate Multipart request. For more information, see CreateMultipartUpload (p. 32).

If you requested server-side encryption using a customer-provided encryption key in your initiate
multipart upload request, you must provide identical encryption information in each part upload using
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

Special Errors

•
• Code: NoSuchUpload

API Version 2006-03-01

360
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• Cause: The speciﬁed multipart upload does not exist. The upload ID might be invalid, or the multipart
upload might have been aborted or completed.
• HTTP Status Code: 404 Not Found
• SOAP Fault Code Preﬁx: Client

Related Resources

• CreateMultipartUpload (p. 32)

• CompleteMultipartUpload (p. 10)
• AbortMultipartUpload (p. 7)
• ListParts (p. 229)
• ListMultipartUploads (p. 194)

Request Syntax
PUT /Key+?PartNumber=PartNumber&UploadId=UploadId HTTP/1.1
Host: Bucket.s3.amazonaws.com
Content-Length: ContentLength
Content-MD5: ContentMD5
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key: SSECustomerKey
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
x-amz-request-payer: RequestPayer

Body

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 361)

Name of the bucket to which the multipart upload was initiated.

Content-Length (p. 361)

Size of the body in bytes. This parameter is useful when the size of the body cannot be determined
automatically.
Content-MD5 (p. 361)

The base64-encoded 128-bit MD5 digest of the part data. This parameter is auto-populated when
using the command from the CLI. This parameter is required if object lock parameters are speciﬁed.
Key (p. 361)

Object key for which the multipart upload was initiated.

Length Constraints: Minimum length of 1.

partNumber (p. 361)

Part number of part being uploaded. This is a positive integer between 1 and 10,000.
uploadId (p. 361)

Upload ID identifying the multipart upload whose part is being uploaded.

x-amz-request-payer (p. 361)

Conﬁrms that the requester knows that they will be charged for the request. Bucket owners need
not specify this parameter in their requests. For information about downloading objects from

API Version 2006-03-01

361
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

requester pays buckets, see Downloading Objects in Requestor Pays Buckets in the Amazon S3
Developer Guide.

Valid Values: requester

x-amz-server-side-encryption-customer-algorithm (p. 361)

Speciﬁes the algorithm to use to when encrypting the object (for example, AES256).
x-amz-server-side-encryption-customer-key (p. 361)

Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value
is used to store the object and then it is discarded; Amazon S3 does not store the encryption key.
The key must be appropriate for use with the algorithm specified in the x-amz-server-side-
encryption-customer-algorithm header. This must be the same encryption key specified in
the initiate multipart upload request.
x-amz-server-side-encryption-customer-key-MD5 (p. 361)

Request Body
The request accepts the following binary data.

Body (p. 361)

Response Syntax

HTTP/1.1 200
x-amz-server-side-encryption: ServerSideEncryption
ETag: ETag
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
x-amz-server-side-encryption-aws-kms-key-id: SSEKMSKeyId
x-amz-request-charged: RequestCharged

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

ETag (p. 362)

Entity tag for the uploaded object.

x-amz-request-charged (p. 362)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

x-amz-server-side-encryption (p. 362)

The server-side encryption algorithm used when storing this object in Amazon S3 (for example,
AES256, aws:kms).

Valid Values: AES256 | aws:kms

API Version 2006-03-01

362
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-server-side-encryption-aws-kms-key-id (p. 362)

If present, speciﬁes the ID of the AWS Key Management Service (AWS KMS) symmetric customer
managed customer master key (CMK) was used for the object.
x-amz-server-side-encryption-customer-algorithm (p. 362)

Examples
Sample Request

The following PUT request uploads a part (part number 1) in a multipart upload. The request includes
the upload ID that you get in response to your Initiate Multipart Upload request.

PUT /my-movie.m2ts?
partNumber=1&uploadId=VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR HTTP/1.1
Host: example-bucket.s3.<Region>.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Content-Length: 10485760
Content-MD5: pUNXr/BjKK5G2UKvaRRrOA==
Authorization: authorization string
>>>>>>> reefconvert-joe

part data omitted

Sample Response

The response includes the ETag header. You need to retain this value for use when you send the
Complete Multipart Upload request.

HTTP/1.1 200 OK
x-amz-id-2: Vvag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732072657175657374
Date: Mon, 1 Nov 2010 20:34:56 GMT
ETag: "b54357faf0632cce46e942fa68356b38"
Content-Length: 0
Connection: keep-alive
Server: AmazonS3

Example: Upload a part with an encryption key in the request for server-side encryption

If you initiated a multipart upload with a request to save an object using server-side encryption with
a customer-provided encryption key, each part upload must also include the same set of encryption-
speciﬁc headers as shown in the following example request.

API Version 2006-03-01

363
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PUT /example-object?
partNumber=1&uploadId=EXAMPLEJZ6e0YupT2h66iePQCc9IEbYbDUy4RTpMeoSMLPRp8Z5o1u8feSRonpvnWsKKG35tI2LB9VDPi
HTTP/1.1
Host: example-bucket.s3.<Region>.amazonaws.com
Authorization: authorization string
Date: Wed, 28 May 2014 19:40:11 +0000
x-amz-server-side-encryption-customer-key: g0lCfA3Dv40jZz5SQJ1ZukLRFqtI5WorC/8SEEXAMPLE
x-amz-server-side-encryption-customer-key-MD5: ZjQrne1X/iTcskbY2example
x-amz-server-side-encryption-customer-algorithm: AES256

In the response, Amazon S3 returns encryption-speciﬁc headers providing the encryption algorithm used
and MD5 digest of the encryption key you provided in the request.

HTTP/1.1 100 Continue HTTP/1.1 200 OK

x-amz-id-2: Zn8bf8aEFQ+kBnGPBc/JaAf9SoWM68QDPS9+SyFwkIZOHUG2BiRLZi5oXw4cOCEt
x-amz-request-id: 5A37448A37622243
Date: Wed, 28 May 2014 19:40:12 GMT
ETag: "7e10e7d25dc4581d89b9285be5f384fd"
x-amz-server-side-encryption-customer-algorithm: AES256
x-amz-server-side-encryption-customer-key-MD5: ZjQrne1X/iTcskbY2example

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

364
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

UploadPartCopy
Service: Amazon Simple Storage Service

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. For more information about multipart
upload limits, go to Quick Facts in the Amazon Simple Storage Service Developer Guide.
Note
Instead of using an existing object as part data, you might use the UploadPart (p. 360) 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.
Amazon S3 returns a unique identiﬁer, the upload ID, that you must include in your upload part request.

For more information about using the UploadPartCopy operation, see the following:

• For conceptual information about multipart uploads, see Uploading Objects Using Multipart Upload in
the Amazon Simple Storage Service Developer Guide.
• For information about permissions required to use the multipart upload API, see Multipart Upload API
and Permissions in the Amazon Simple Storage Service Developer Guide.
• For information about copying objects using a single atomic operation vs. the multipart upload, see
Operations on Objects in the Amazon Simple Storage Service Developer Guide.
• For information about using server-side encryption with customer-provided encryption keys with the
UploadPartCopy operation, see CopyObject (p. 16) and UploadPart (p. 360).

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:

• Consideration 1 - 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;

Amazon S3 returns 200 OK and copies the data.

• Consideration 2 - 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;

Amazon S3 returns 412 Precondition Failed response code.

Versioning

If your bucket has versioning enabled, you could have multiple versions of the same object. By default,
x-amz-copy-source identiﬁes the current version of the object to copy. If the current version is a
delete marker and you don't specify a versionId in the x-amz-copy-source, Amazon S3 returns a 404
error, because the object does not exist. If you specify versionId in the x-amz-copy-source and the
versionId is a delete marker, Amazon S3 returns an HTTP 400 error, because you are not allowed to
specify a delete marker as a version for the x-amz-copy-source.

API Version 2006-03-01

365
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

You can optionally specify a speciﬁc version of the source object to copy by adding the versionId
subresource as shown in the following example:

x-amz-copy-source: /bucket/object?versionId=version id

Special Errors

•
• Code: NoSuchUpload
• Cause: The speciﬁed multipart upload does not exist. The upload ID might be invalid, or the multipart
upload might have been aborted or completed.
• HTTP Status Code: 404 Not Found
•
• Code: InvalidRequest
• Cause: The speciﬁed copy source is not supported as a byte-range copy source.
• HTTP Status Code: 400 Bad Request

Related Resources

• CreateMultipartUpload (p. 32)

• UploadPart (p. 360)
• CompleteMultipartUpload (p. 10)
• AbortMultipartUpload (p. 7)
• ListParts (p. 229)
• ListMultipartUploads (p. 194)

Request Syntax

PUT /Key+?PartNumber=PartNumber&UploadId=UploadId HTTP/1.1

Host: Bucket.s3.amazonaws.com
x-amz-copy-source: CopySource
x-amz-copy-source-if-match: CopySourceIfMatch
x-amz-copy-source-if-modified-since: CopySourceIfModifiedSince
x-amz-copy-source-if-none-match: CopySourceIfNoneMatch
x-amz-copy-source-if-unmodified-since: CopySourceIfUnmodifiedSince
x-amz-copy-source-range: CopySourceRange
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key: SSECustomerKey
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
x-amz-copy-source-server-side-encryption-customer-algorithm: CopySourceSSECustomerAlgorithm
x-amz-copy-source-server-side-encryption-customer-key: CopySourceSSECustomerKey
x-amz-copy-source-server-side-encryption-customer-key-MD5: CopySourceSSECustomerKeyMD5
x-amz-request-payer: RequestPayer

URI Request Parameters

The request requires the following URI parameters.

Bucket (p. 366)

The bucket name.

Key (p. 366)

Object key for which the multipart upload was initiated.

Length Constraints: Minimum length of 1.

API Version 2006-03-01

366
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

partNumber (p. 366)

Part number of part being copied. This is a positive integer between 1 and 10,000.
uploadId (p. 366)

Upload ID identifying the multipart upload whose part is being copied.

x-amz-copy-source (p. 366)

The name of the source bucket and key name of the source object, separated by a slash (/). Must be
URL-encoded.

Pattern: \/.+\/.+
x-amz-copy-source-if-match (p. 366)

Copies the object if its entity tag (ETag) matches the speciﬁed tag.
x-amz-copy-source-if-modiﬁed-since (p. 366)

Copies the object if it has been modiﬁed since the speciﬁed time.
x-amz-copy-source-if-none-match (p. 366)

Copies the object if its entity tag (ETag) is different than the specified ETag.
x-amz-copy-source-if-unmodified-since (p. 366)

Copies the object if it hasn't been modiﬁed since the speciﬁed time.
x-amz-copy-source-range (p. 366)

The range of bytes to copy from the source object. The range value must use the form bytes=first-
last, where the first and last are the zero-based byte offsets to copy. For example, bytes=0-9
indicates that you want to copy the first 10 bytes of the source. You can copy a range only if the
source object is greater than 5 MB.
x-amz-copy-source-server-side-encryption-customer-algorithm (p. 366)

Speciﬁes the algorithm to use when decrypting the source object (for example, AES256).
x-amz-copy-source-server-side-encryption-customer-key (p. 366)

Valid Values: requester

x-amz-server-side-encryption-customer-algorithm (p. 366)

Speciﬁes the algorithm to use to when encrypting the object (for example, AES256).
x-amz-server-side-encryption-customer-key (p. 366)

Speciﬁes the customer-provided encryption key for Amazon S3 to use in encrypting data. This value
is used to store the object and then it is discarded; Amazon S3 does not store the encryption key.

API Version 2006-03-01

367
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

The key must be appropriate for use with the algorithm speciﬁed in the x-amz-server-side-
encryption-customer-algorithm header. This must be the same encryption key speciﬁed in the
initiate multipart upload request.
x-amz-server-side-encryption-customer-key-MD5 (p. 366)

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
x-amz-copy-source-version-id: CopySourceVersionId
x-amz-server-side-encryption: ServerSideEncryption
x-amz-server-side-encryption-customer-algorithm: SSECustomerAlgorithm
x-amz-server-side-encryption-customer-key-MD5: SSECustomerKeyMD5
x-amz-server-side-encryption-aws-kms-key-id: SSEKMSKeyId
x-amz-request-charged: RequestCharged
<?xml version="1.0" encoding="UTF-8"?>
<CopyPartResult>
<ETag>string</ETag>
<LastModified>timestamp</LastModified>
</CopyPartResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

x-amz-copy-source-version-id (p. 368)

The version of the source object that was copied, if you have enabled versioning on the source
bucket.
x-amz-request-charged (p. 368)

If present, indicates that the requester was successfully charged for the request.

Valid Values: requester

x-amz-server-side-encryption (p. 368)

The server-side encryption algorithm used when storing this object in Amazon S3 (for example,
AES256, aws:kms).

Valid Values: AES256 | aws:kms

x-amz-server-side-encryption-aws-kms-key-id (p. 368)

If server-side encryption with a customer-provided encryption key was requested, the response will
include this header conﬁrming the encryption algorithm used.

API Version 2006-03-01

368
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

x-amz-server-side-encryption-customer-key-MD5 (p. 368)

The following data is returned in XML format by the service.

CopyPartResult (p. 368)

Root level tag for the CopyPartResult parameters.

Required: Yes
ETag (p. 368)

Entity tag of the object.

Type: String
LastModiﬁed (p. 368)

Date and time at which the object was uploaded.

Type: Timestamp

Examples
Sample Request

The following PUT request uploads a part (part number 2) in a multipart upload. The request speciﬁes a
byte range from an existing object as the source of this upload. The request includes the upload ID that
you get in response to your Initiate Multipart Upload request.

PUT /newobject?
partNumber=2&uploadId=VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR HTTP/1.1
Host: target-bucket.s3.<Region>.amazonaws.com
Date: Mon, 11 Apr 2011 20:34:56 GMT
x-amz-copy-source: /source-bucket/sourceobject
x-amz-copy-source-range:bytes=500-6291456
Authorization: authorization string

Sample Response

The response includes the ETag value. You need to retain this value to use when you send the Complete
Multipart Upload request.

HTTP/1.1 200 OK
x-amz-id-2: Vvag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732072657175657374
Date: Mon, 11 Apr 2011 20:34:56 GMT
Server: AmazonS3

API Version 2006-03-01

369
Amazon Simple Storage Service API Reference
AWS S3 Control

Sample Request
The following PUT request uploads a part (part number 2) in a multipart upload. The request does not
specify the optional byte range header, but requests the entire source object copy as part 2. The request
includes the upload ID that you got in response to your Initiate Multipart Upload request.

PUT /newobject?
partNumber=2&uploadId=VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR HTTP/1.1
Host: target-bucket.s3.<Region>.amazonaws.com
Date: Mon, 11 Apr 2011 20:34:56 GMT
x-amz-copy-source: /source-bucket/sourceobject?versionId=3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
x-amz-copy-source-range:bytes=500-6291456
Authorization: authorization string

Sample Response
The response includes the ETag value. You need to retain this value to use when you send the Complete
Multipart Upload request.

HTTP/1.1 200 OK
x-amz-id-2: Vvag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732072657175657374
x-amz-copy-source-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
Date: Mon, 11 Apr 2011 20:34:56 GMT
Server: AmazonS3

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

AWS S3 Control
The following actions are supported by AWS S3 Control:

API Version 2006-03-01

370
Amazon Simple Storage Service API Reference
AWS S3 Control

• CreateAccessPoint (p. 372)

API Version 2006-03-01

371
Amazon Simple Storage Service API Reference
AWS S3 Control

CreateAccessPoint
Service: AWS S3 Control

Creates an access point and associates it with the speciﬁed bucket.

Request Syntax

PUT /v20180820/accesspoint/name HTTP/1.1

x-amz-account-id: AccountId
<?xml version="1.0" encoding="UTF-8"?>
<CreateAccessPointRequest xmlns="http://awss3control.amazonaws.com/doc/2018-08-20/">
<Bucket>string</Bucket>
<VpcConfiguration>
<VpcId>string</VpcId>
</VpcConfiguration>
<PublicAccessBlockConfiguration>
<BlockPublicAcls>boolean</BlockPublicAcls>
<BlockPublicPolicy>boolean</BlockPublicPolicy>
<IgnorePublicAcls>boolean</IgnorePublicAcls>
<RestrictPublicBuckets>boolean</RestrictPublicBuckets>
</PublicAccessBlockConfiguration>
</CreateAccessPointRequest>

URI Request Parameters

The request requires the following URI parameters.

name (p. 372)

The name you want to assign to this access point.

Length Constraints: Minimum length of 3. Maximum length of 50.

x-amz-account-id (p. 372)

The AWS account ID for the owner of the bucket for which you want to create an access point.

Length Constraints: Maximum length of 64.

Request Body
The request accepts the following data in XML format.

CreateAccessPointRequest (p. 372)

Root level tag for the CreateAccessPointRequest parameters.

Required: Yes
Bucket (p. 372)

The name of the bucket that you want to associate this access point with.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 255.

Required: Yes
PublicAccessBlockConﬁguration (p. 372)

The PublicAccessBlock conﬁguration that you want to apply to this Amazon S3 bucket. You can
enable the conﬁguration options in any combination. For more information about when Amazon

API Version 2006-03-01

372
Amazon Simple Storage Service API Reference
AWS S3 Control

S3 considers a bucket or object public, see The Meaning of "Public" in the Amazon Simple Storage
Service Developer Guide.

Type: PublicAccessBlockConﬁguration (p. 586) data type

Required: No
VpcConﬁguration (p. 372)

If you include this ﬁeld, Amazon S3 restricts access to this access point to requests from the speciﬁed
Virtual Private Cloud (VPC).

Type: VpcConﬁguration (p. 602) data type

Required: No

Length Constraints: Maximum length of 64.

Request Body
The request accepts the following data in XML format.

CreateJobRequest (p. 374)

Root level tag for the CreateJobRequest parameters.

Required: Yes
ClientRequestToken (p. 374)

An idempotency token to ensure that you don't accidentally submit the same request twice. You can
use any string up to the maximum length.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Required: Yes
ConﬁrmationRequired (p. 374)

Indicates whether conﬁrmation is required before Amazon S3 runs the job. Conﬁrmation is only
required for jobs created through the Amazon S3 console.

Type: Boolean

Required: No
Description (p. 374)

A description for this job. You can use any string within the permitted length. Descriptions don't
need to be unique and can be used for multiple jobs.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Required: No
Manifest (p. 374)

Conﬁguration parameters for the manifest.

Type: JobManifest (p. 577) data type

Required: Yes
Operation (p. 374)

The operation that you want this job to perform on each object listed in the manifest. For more
information about the available operations, see Available Operations in the Amazon Simple Storage
Service Developer Guide.

Type: JobOperation (p. 580) data type

Required: Yes
Priority (p. 374)

The numerical priority for this job. Higher numbers indicate higher priority.

API Version 2006-03-01

376
Amazon Simple Storage Service API Reference
AWS S3 Control

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 2147483647.

Required: Yes
Report (p. 374)

Conﬁguration parameters for the optional job-completion report.

Type: JobReport (p. 582) data type

Required: Yes
RoleArn (p. 374)

The Amazon Resource Name (ARN) for the Identity and Access Management (IAM) Role that batch
operations will use to execute this job's operation on each object in the manifest.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<CreateJobResult>
<JobId>string</JobId>
</CreateJobResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

CreateJobResult (p. 377)

Root level tag for the CreateJobResult parameters.

Required: Yes
JobId (p. 377)

The ID for this job. Amazon S3 generates this ID automatically and returns it after a successful
Create Job request.

Type: String

Length Constraints: Minimum length of 5. Maximum length of 36.

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET

API Version 2006-03-01

377
Amazon Simple Storage Service API Reference
AWS S3 Control

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

378
Amazon Simple Storage Service API Reference
AWS S3 Control

DeleteAccessPoint
Service: AWS S3 Control

Deletes the speciﬁed access point.

Request Syntax

DELETE /v20180820/accesspoint/name HTTP/1.1

x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

name (p. 379)

The name of the access point you want to delete.

Length Constraints: Minimum length of 3. Maximum length of 50.

x-amz-account-id (p. 379)

The account ID for the account that owns the speciﬁed access point.

Length Constraints: Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

379
Amazon Simple Storage Service API Reference
AWS S3 Control

DeleteAccessPointPolicy
Service: AWS S3 Control

Deletes the access point policy for the speciﬁed access point.

Request Syntax

DELETE /v20180820/accesspoint/name/policy HTTP/1.1

x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

name (p. 380)

The name of the access point whose policy you want to delete.

Length Constraints: Minimum length of 3. Maximum length of 50.

x-amz-account-id (p. 380)

The account ID for the account that owns the speciﬁed access point.

Length Constraints: Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

380
Amazon Simple Storage Service API Reference
AWS S3 Control

DeletePublicAccessBlock
Service: AWS S3 Control

Removes the PublicAccessBlock conﬁguration for an Amazon Web Services account.

Request Syntax

DELETE /v20180820/configuration/publicAccessBlock HTTP/1.1

x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

x-amz-account-id (p. 381)

The account ID for the Amazon Web Services account whose PublicAccessBlock conﬁguration
you want to remove.

Length Constraints: Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

381
Amazon Simple Storage Service API Reference
AWS S3 Control

DescribeJob
Service: AWS S3 Control

Retrieves the conﬁguration parameters and status for a batch operations job.

Request Syntax

GET /v20180820/jobs/id HTTP/1.1

x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

id (p. 382)

The ID for the job whose information you want to retrieve.

Length Constraints: Minimum length of 5. Maximum length of 36.

x-amz-account-id (p. 382)

Length Constraints: Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<DescribeJobResult>
<Job>
<ConfirmationRequired>boolean</ConfirmationRequired>
<CreationTime>timestamp</CreationTime>
<Description>string</Description>
<FailureReasons>
<JobFailure>
<FailureCode>string</FailureCode>
<FailureReason>string</FailureReason>
</JobFailure>
</FailureReasons>
<JobArn>string</JobArn>
<JobId>string</JobId>
<Manifest>
<Location>
<ETag>string</ETag>
<ObjectArn>string</ObjectArn>
<ObjectVersionId>string</ObjectVersionId>
</Location>
<Spec>
<Fields>
<INVALID-TYPE-NAME>string</INVALID-TYPE-NAME>
</Fields>
<Format>string</Format>
</Spec>
</Manifest>
<Operation>
<LambdaInvoke>

API Version 2006-03-01

382
Amazon Simple Storage Service API Reference
AWS S3 Control

<FunctionArn>string</FunctionArn>
</LambdaInvoke>
<S3InitiateRestoreObject>
<ExpirationInDays>integer</ExpirationInDays>
<GlacierJobTier>string</GlacierJobTier>
</S3InitiateRestoreObject>
<S3PutObjectAcl>
<AccessControlPolicy>
<AccessControlList>
<Grants>
<S3Grant>
<Grantee>
<DisplayName>string</DisplayName>
<Identifier>string</Identifier>
<TypeIdentifier>string</TypeIdentifier>
</Grantee>
<Permission>string</Permission>
</S3Grant>
</Grants>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
</AccessControlList>
<CannedAccessControlList>string</CannedAccessControlList>
</AccessControlPolicy>
</S3PutObjectAcl>
<S3PutObjectCopy>
<AccessControlGrants>
<S3Grant>
<Grantee>
<DisplayName>string</DisplayName>
<Identifier>string</Identifier>
<TypeIdentifier>string</TypeIdentifier>
</Grantee>
<Permission>string</Permission>
</S3Grant>
</AccessControlGrants>
<CannedAccessControlList>string</CannedAccessControlList>
<MetadataDirective>string</MetadataDirective>
<ModifiedSinceConstraint>timestamp</ModifiedSinceConstraint>
<NewObjectMetadata>
<CacheControl>string</CacheControl>
<ContentDisposition>string</ContentDisposition>
<ContentEncoding>string</ContentEncoding>
<ContentLanguage>string</ContentLanguage>
<ContentLength>long</ContentLength>
<ContentMD5>string</ContentMD5>
<ContentType>string</ContentType>
<HttpExpiresDate>timestamp</HttpExpiresDate>
<RequesterCharged>boolean</RequesterCharged>
<SSEAlgorithm>string</SSEAlgorithm>
<UserMetadata>
<entry>
<key>string</key>
<value>string</value>
</entry>
</UserMetadata>
</NewObjectMetadata>
<NewObjectTagging>
<S3Tag>
<Key>string</Key>
<Value>string</Value>
</S3Tag>
</NewObjectTagging>
<ObjectLockLegalHoldStatus>string</ObjectLockLegalHoldStatus>

API Version 2006-03-01

383
Amazon Simple Storage Service API Reference
AWS S3 Control

<ObjectLockMode>string</ObjectLockMode>
<ObjectLockRetainUntilDate>timestamp</ObjectLockRetainUntilDate>
<RedirectLocation>string</RedirectLocation>
<RequesterPays>boolean</RequesterPays>
<SSEAwsKmsKeyId>string</SSEAwsKmsKeyId>
<StorageClass>string</StorageClass>
<TargetKeyPrefix>string</TargetKeyPrefix>
<TargetResource>string</TargetResource>
<UnModifiedSinceConstraint>timestamp</UnModifiedSinceConstraint>
</S3PutObjectCopy>
<S3PutObjectTagging>
<TagSet>
<S3Tag>
<Key>string</Key>
<Value>string</Value>
</S3Tag>
</TagSet>
</S3PutObjectTagging>
</Operation>
<Priority>integer</Priority>
<ProgressSummary>
<NumberOfTasksFailed>long</NumberOfTasksFailed>
<NumberOfTasksSucceeded>long</NumberOfTasksSucceeded>
<TotalNumberOfTasks>long</TotalNumberOfTasks>
</ProgressSummary>
<Report>
<Bucket>string</Bucket>
<Enabled>boolean</Enabled>
<Format>string</Format>
<Prefix>string</Prefix>
<ReportScope>string</ReportScope>
</Report>
<RoleArn>string</RoleArn>
<Status>string</Status>
<StatusUpdateReason>string</StatusUpdateReason>
<SuspendedCause>string</SuspendedCause>
<SuspendedDate>timestamp</SuspendedDate>
<TerminationDate>timestamp</TerminationDate>
</Job>
</DescribeJobResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

DescribeJobResult (p. 382)

Root level tag for the DescribeJobResult parameters.

Required: Yes
Job (p. 382)

Contains the conﬁguration parameters and status for the job speciﬁed in the Describe Job
request.

Type: JobDescriptor (p. 571) data type

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

API Version 2006-03-01

384
Amazon Simple Storage Service API Reference
AWS S3 Control

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

385
Amazon Simple Storage Service API Reference
AWS S3 Control

GetAccessPoint
Service: AWS S3 Control

Returns conﬁguration information about the speciﬁed access point.

Request Syntax

GET /v20180820/accesspoint/name HTTP/1.1

x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

name (p. 386)

The name of the access point whose conﬁguration information you want to retrieve.

Length Constraints: Minimum length of 3. Maximum length of 50.

x-amz-account-id (p. 386)

The account ID for the account that owns the speciﬁed access point.

Length Constraints: Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetAccessPointResult>
<Name>string</Name>
<Bucket>string</Bucket>
<NetworkOrigin>string</NetworkOrigin>
<VpcConfiguration>
<VpcId>string</VpcId>
</VpcConfiguration>
<PublicAccessBlockConfiguration>
<BlockPublicAcls>boolean</BlockPublicAcls>
<BlockPublicPolicy>boolean</BlockPublicPolicy>
<IgnorePublicAcls>boolean</IgnorePublicAcls>
<RestrictPublicBuckets>boolean</RestrictPublicBuckets>
</PublicAccessBlockConfiguration>
<CreationDate>timestamp</CreationDate>
</GetAccessPointResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

GetAccessPointResult (p. 386)

Root level tag for the GetAccessPointResult parameters.

API Version 2006-03-01

386
Amazon Simple Storage Service API Reference
AWS S3 Control

Required: Yes
Bucket (p. 386)

The name of the bucket associated with the speciﬁed access point.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 255.

CreationDate (p. 386)

The date and time when the speciﬁed access point was created.

Type: Timestamp
Name (p. 386)

The name of the speciﬁed access point.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 50.

NetworkOrigin (p. 386)

Indicates whether this access point allows access from the public Internet. If VpcConfiguration
is speciﬁed for this access point, then NetworkOrigin is VPC, and the access point doesn't allow
access from the public Internet. Otherwise, NetworkOrigin is Internet, and the access point
allows access from the public Internet, subject to the access point and bucket access policies.

Type: String

Valid Values: Internet | VPC

PublicAccessBlockConﬁguration (p. 386)

The PublicAccessBlock conﬁguration that you want to apply to this Amazon S3 bucket. You can
enable the conﬁguration options in any combination. For more information about when Amazon
S3 considers a bucket or object public, see The Meaning of "Public" in the Amazon Simple Storage
Service Developer Guide.

Type: PublicAccessBlockConﬁguration (p. 586) data type

VpcConﬁguration (p. 386)

Contains the Virtual Private Cloud (VPC) conﬁguration for the speciﬁed access point.

Type: VpcConﬁguration (p. 602) data type

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

API Version 2006-03-01

387
Amazon Simple Storage Service API Reference
AWS S3 Control

• AWS SDK for Ruby V2

API Version 2006-03-01

388
Amazon Simple Storage Service API Reference
AWS S3 Control

GetAccessPointPolicy
Service: AWS S3 Control

Returns the access point policy associated with the speciﬁed access point.

Request Syntax

GET /v20180820/accesspoint/name/policy HTTP/1.1

x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

name (p. 389)

The name of the access point whose policy you want to retrieve.

Length Constraints: Minimum length of 3. Maximum length of 50.

x-amz-account-id (p. 389)

The account ID for the account that owns the speciﬁed access point.

Length Constraints: Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetAccessPointPolicyResult>
<Policy>string</Policy>
</GetAccessPointPolicyResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

GetAccessPointPolicyResult (p. 389)

Root level tag for the GetAccessPointPolicyResult parameters.

Required: Yes
Policy (p. 389)

The access point policy associated with the speciﬁed access point.

Type: String

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

API Version 2006-03-01

389
Amazon Simple Storage Service API Reference
AWS S3 Control

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

390
Amazon Simple Storage Service API Reference
AWS S3 Control

GetAccessPointPolicyStatus
Service: AWS S3 Control

Indicates whether the speciﬁed access point currently has a policy that allows public access. For more
information about public access through access points, see Managing Data Access with Amazon S3
Access Points in the Amazon Simple Storage Service Developer Guide.

Request Syntax

GET /v20180820/accesspoint/name/policyStatus HTTP/1.1

x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

name (p. 391)

The name of the access point whose policy status you want to retrieve.

Length Constraints: Minimum length of 3. Maximum length of 50.

x-amz-account-id (p. 391)

The account ID for the account that owns the speciﬁed access point.

Length Constraints: Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<GetAccessPointPolicyStatusResult>
<PolicyStatus>
<IsPublic>boolean</IsPublic>
</PolicyStatus>
</GetAccessPointPolicyStatusResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

GetAccessPointPolicyStatusResult (p. 391)

Root level tag for the GetAccessPointPolicyStatusResult parameters.

Required: Yes
PolicyStatus (p. 391)

Indicates the current policy status of the speciﬁed access point.

Type: PolicyStatus (p. 585) data type

API Version 2006-03-01

391
Amazon Simple Storage Service API Reference
AWS S3 Control

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

392
Amazon Simple Storage Service API Reference
AWS S3 Control

GetPublicAccessBlock
Service: AWS S3 Control

Retrieves the PublicAccessBlock conﬁguration for an Amazon Web Services account.

Request Syntax

GET /v20180820/configuration/publicAccessBlock HTTP/1.1

x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

x-amz-account-id (p. 393)

The account ID for the Amazon Web Services account whose PublicAccessBlock conﬁguration
you want to retrieve.

Length Constraints: Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

PublicAccessBlockConﬁguration (p. 393)

Root level tag for the PublicAccessBlockConﬁguration parameters.

Required: Yes
BlockPublicAcls (p. 393)

Speciﬁes whether Amazon S3 should block public access control lists (ACLs) for buckets in this
account. Setting this element to TRUE causes the following behavior:
• PUT Bucket acl and PUT Object acl calls fail if the speciﬁed ACL is public.
• PUT Object calls fail if the request includes a public ACL.
• PUT Bucket calls fail if the request includes a public ACL.

Enabling this setting doesn't aﬀect existing policies or ACLs.

API Version 2006-03-01

393
Amazon Simple Storage Service API Reference
AWS S3 Control

Type: Boolean
BlockPublicPolicy (p. 393)

Speciﬁes whether Amazon S3 should block public bucket policies for buckets in this account. Setting
this element to TRUE causes Amazon S3 to reject calls to PUT Bucket policy if the speciﬁed bucket
policy allows public access.

Enabling this setting doesn't aﬀect existing bucket policies.

Type: Boolean
IgnorePublicAcls (p. 393)

Speciﬁes whether Amazon S3 should ignore public ACLs for buckets in this account. Setting this
element to TRUE causes Amazon S3 to ignore all public ACLs on buckets in this account and any
objects that they contain.

Enabling this setting doesn't aﬀect the persistence of any existing ACLs and doesn't prevent new
public ACLs from being set.

Type: Boolean
RestrictPublicBuckets (p. 393)

Speciﬁes whether Amazon S3 should restrict public bucket policies for buckets in this account.
Setting this element to TRUE restricts access to buckets with public policies to only AWS services and
authorized users within this account.

Type: Boolean

Amazon S3 throws this exception if you make a GetPublicAccessBlock request against an account that
doesn't have a PublicAccessBlockConﬁguration set.

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

394
Amazon Simple Storage Service API Reference
AWS S3 Control

ListAccessPoints
Service: AWS S3 Control

Returns a list of the access points currently associated with the specified bucket. You can retrieve up to
1000 access points per call. If the specified bucket has more than 1000 access points (or the number
specified in maxResults, whichever is less), then the response will include a continuation token that you
can use to list the additional access points.

Request Syntax

GET /v20180820/accesspoint?Bucket=Bucket&MaxResults=MaxResults&NextToken=NextToken HTTP/1.1

x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

bucket (p. 395)

The name of the bucket whose associated access points you want to list.

Length Constraints: Minimum length of 3. Maximum length of 255.

maxResults (p. 395)

The maximum number of access points that you want to include in the list. If the speciﬁed bucket
has more than this number of access points, then the response will include a continuation token in
the NextToken ﬁeld that you can use to retrieve the next page of access points.

Valid Range: Minimum value of 1. Maximum value of 1000.

nextToken (p. 395)

A continuation token. If a previous call to ListAccessPoints returned a continuation token in

the NextToken ﬁeld, then providing that value here causes Amazon S3 to retrieve the next page of
results.

Length Constraints: Minimum length of 1. Maximum length of 1024.

x-amz-account-id (p. 395)

The AWS account ID for owner of the bucket whose access points you want to list.

Length Constraints: Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListAccessPointsResult>
<AccessPointList>
<AccessPoint>
<Bucket>string</Bucket>
<Name>string</Name>
<NetworkOrigin>string</NetworkOrigin>
<VpcConfiguration>

API Version 2006-03-01

395
Amazon Simple Storage Service API Reference
AWS S3 Control

<VpcId>string</VpcId>
</VpcConfiguration>
</AccessPoint>
</AccessPointList>
<NextToken>string</NextToken>
</ListAccessPointsResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ListAccessPointsResult (p. 395)

Root level tag for the ListAccessPointsResult parameters.

Required: Yes
AccessPointList (p. 395)

Contains identification and configuration information for one or more access points associated with
the specified bucket.

Type: Array of AccessPoint (p. 570) data types

NextToken (p. 395)

If the speciﬁed bucket has more access points than can be returned in one call to this API, then this
ﬁeld contains a continuation token that you can provide in subsequent calls to this API to retrieve
additional access points.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

396
Amazon Simple Storage Service API Reference
AWS S3 Control

ListJobs
Service: AWS S3 Control

Lists current jobs and jobs that have ended within the last 30 days for the AWS account making the
request.

Request Syntax

GET /v20180820/jobs?JobStatuses=JobStatuses&MaxResults=MaxResults&NextToken=NextToken
HTTP/1.1
x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

jobStatuses (p. 397)

The List Jobs request returns jobs that match the statuses listed in this element.

Valid Values: Active | Cancelled | Cancelling | Complete | Completing | Failed

The maximum number of jobs that Amazon S3 will include in the List Jobs response. If there are
more jobs than this number, the response will include a pagination token in the NextToken ﬁeld to
enable you to retrieve the next page of results.

Valid Range: Minimum value of 1. Maximum value of 1000.

nextToken (p. 397)

A pagination token to request the next page of results. Use the token that Amazon S3 returned in
the NextToken element of the ListJobsResult from the previous List Jobs request.

Length Constraints: Minimum length of 1. Maximum length of 1024.

x-amz-account-id (p. 397)

Length Constraints: Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListJobsResult>
<NextToken>string</NextToken>
<Jobs>
<JobListDescriptor>
<CreationTime>timestamp</CreationTime>
<Description>string</Description>
<JobId>string</JobId>
<Operation>string</Operation>
<Priority>integer</Priority>
<ProgressSummary>

API Version 2006-03-01

397
Amazon Simple Storage Service API Reference
AWS S3 Control

<NumberOfTasksFailed>long</NumberOfTasksFailed>
<NumberOfTasksSucceeded>long</NumberOfTasksSucceeded>
<TotalNumberOfTasks>long</TotalNumberOfTasks>
</ProgressSummary>
<Status>string</Status>
<TerminationDate>timestamp</TerminationDate>
</JobListDescriptor>
</Jobs>
</ListJobsResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ListJobsResult (p. 397)

Root level tag for the ListJobsResult parameters.

Required: Yes
Jobs (p. 397)

The list of current jobs and jobs that have ended within the last 30 days.

Type: Array of JobListDescriptor (p. 575) data types

NextToken (p. 397)

If the List Jobs request produced more than the maximum number of results, you can pass this
value into a subsequent List Jobs request in order to retrieve the next page of results.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

398
Amazon Simple Storage Service API Reference
AWS S3 Control

PutAccessPointPolicy
Service: AWS S3 Control

Associates an access policy with the speciﬁed access point. Each access point can have only one policy, so
a request made to this API replaces any existing policy associated with the speciﬁed access point.

Request Syntax

PUT /v20180820/accesspoint/name/policy HTTP/1.1

x-amz-account-id: AccountId
<?xml version="1.0" encoding="UTF-8"?>
<PutAccessPointPolicyRequest xmlns="http://awss3control.amazonaws.com/doc/2018-08-20/">
<Policy>string</Policy>
</PutAccessPointPolicyRequest>

URI Request Parameters

The request requires the following URI parameters.

name (p. 399)

The name of the access point that you want to associate with the speciﬁed policy.

Length Constraints: Minimum length of 3. Maximum length of 50.

x-amz-account-id (p. 399)

The AWS account ID for owner of the bucket associated with the speciﬁed access point.

Length Constraints: Maximum length of 64.

Request Body
The request accepts the following data in XML format.

PutAccessPointPolicyRequest (p. 399)

Root level tag for the PutAccessPointPolicyRequest parameters.

Required: Yes
Policy (p. 399)

The policy that you want to apply to the speciﬁed access point. For more information about access
point policies, see Managing Data Access with Amazon S3 Access Points in the Amazon Simple
Storage Service Developer Guide.

Type: String

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

API Version 2006-03-01

399
Amazon Simple Storage Service API Reference
AWS S3 Control

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

400
Amazon Simple Storage Service API Reference
AWS S3 Control

PutPublicAccessBlock
Service: AWS S3 Control

Creates or modiﬁes the PublicAccessBlock conﬁguration for an Amazon Web Services account.

Request Syntax

PUT /v20180820/configuration/publicAccessBlock HTTP/1.1

x-amz-account-id: AccountId
<?xml version="1.0" encoding="UTF-8"?>
<PublicAccessBlockConfiguration xmlns="http://awss3control.amazonaws.com/doc/2018-08-20/">
<BlockPublicAcls>boolean</BlockPublicAcls>
<IgnorePublicAcls>boolean</IgnorePublicAcls>
<BlockPublicPolicy>boolean</BlockPublicPolicy>
<RestrictPublicBuckets>boolean</RestrictPublicBuckets>
</PublicAccessBlockConfiguration>

URI Request Parameters

The request requires the following URI parameters.

x-amz-account-id (p. 401)

The account ID for the Amazon Web Services account whose PublicAccessBlock conﬁguration
you want to set.

Length Constraints: Maximum length of 64.

Request Body
The request accepts the following data in XML format.

PublicAccessBlockConﬁguration (p. 401)

Root level tag for the PublicAccessBlockConﬁguration parameters.

Required: Yes
BlockPublicAcls (p. 401)

Enabling this setting doesn't aﬀect existing policies or ACLs.

Type: Boolean

Required: No
BlockPublicPolicy (p. 401)

Enabling this setting doesn't aﬀect existing bucket policies.

API Version 2006-03-01

401
Amazon Simple Storage Service API Reference
AWS S3 Control

Type: Boolean

Required: No
IgnorePublicAcls (p. 401)

Enabling this setting doesn't aﬀect the persistence of any existing ACLs and doesn't prevent new
public ACLs from being set.

Type: Boolean

Required: No
RestrictPublicBuckets (p. 401)

Type: Boolean

Required: No

Response Syntax

HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

402
Amazon Simple Storage Service API Reference
AWS S3 Control

UpdateJobPriority
Service: AWS S3 Control

Updates an existing job's priority.

Request Syntax

POST /v20180820/jobs/id/priority?Priority=Priority HTTP/1.1

x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

id (p. 403)

The ID for the job whose priority you want to update.

Length Constraints: Minimum length of 5. Maximum length of 36.

priority (p. 403)

The priority you want to assign to this job.

Valid Range: Minimum value of 0. Maximum value of 2147483647.

x-amz-account-id (p. 403)

Length Constraints: Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<UpdateJobPriorityResult>
<JobId>string</JobId>
<Priority>integer</Priority>
</UpdateJobPriorityResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

UpdateJobPriorityResult (p. 403)

Root level tag for the UpdateJobPriorityResult parameters.

Required: Yes
JobId (p. 403)

The ID for the job whose priority Amazon S3 updated.

Type: String

API Version 2006-03-01

403
Amazon Simple Storage Service API Reference
AWS S3 Control

Length Constraints: Minimum length of 5. Maximum length of 36.

Priority (p. 403)

The new priority assigned to the speciﬁed job.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 2147483647.

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

404
Amazon Simple Storage Service API Reference
AWS S3 Control

UpdateJobStatus
Service: AWS S3 Control

Updates the status for the speciﬁed job. Use this operation to conﬁrm that you want to run a job or to
cancel an existing job.

Request Syntax

POST /v20180820/jobs/id/status?
RequestedJobStatus=RequestedJobStatus&StatusUpdateReason=StatusUpdateReason HTTP/1.1
x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

id (p. 405)

The ID of the job whose status you want to update.

Length Constraints: Minimum length of 5. Maximum length of 36.

requestedJobStatus (p. 405)

The status that you want to move the speciﬁed job to.

Valid Values: Cancelled | Ready

statusUpdateReason (p. 405)

A description of the reason why you want to change the speciﬁed job's status. This ﬁeld can be any
string up to the maximum length.

Length Constraints: Minimum length of 1. Maximum length of 256.

x-amz-account-id (p. 405)

Length Constraints: Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<UpdateJobStatusResult>
<JobId>string</JobId>
<Status>string</Status>
<StatusUpdateReason>string</StatusUpdateReason>
</UpdateJobStatusResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

API Version 2006-03-01

405
Amazon Simple Storage Service API Reference
Data Types

UpdateJobStatusResult (p. 405)

Root level tag for the UpdateJobStatusResult parameters.

API Version 2006-03-01

407
Amazon Simple Storage Service API Reference
Data Types

• LambdaFunctionConﬁguration (p. 480)

• LifecycleConfiguration (p. 482)
• LifecycleExpiration (p. 483)
• LifecycleRule (p. 484)
• LifecycleRuleAndOperator (p. 486)
• LifecycleRuleFilter (p. 487)
• LoggingEnabled (p. 488)
• MetadataEntry (p. 489)
• Metrics (p. 490)
• MetricsAndOperator (p. 491)
• MetricsConfiguration (p. 492)
• MetricsFilter (p. 493)
• MultipartUpload (p. 494)
• NoncurrentVersionExpiration (p. 496)
• NoncurrentVersionTransition (p. 497)
• NotificationConfiguration (p. 498)
• NotificationConfigurationDeprecated (p. 499)
• NotificationConfigurationFilter (p. 500)
• Object (p. 501)
• ObjectIdentifier (p. 503)
• ObjectLockConfiguration (p. 504)
• ObjectLockLegalHold (p. 505)
• ObjectLockRetention (p. 506)
• ObjectLockRule (p. 507)
• ObjectVersion (p. 508)
• OutputLocation (p. 510)
• OutputSerialization (p. 511)
• Owner (p. 512)
• ParquetInput (p. 513)
• Part (p. 514)
• PolicyStatus (p. 515)
• Progress (p. 516)
• ProgressEvent (p. 517)
• PublicAccessBlockConfiguration (p. 518)
• QueueConfiguration (p. 520)
• QueueConfigurationDeprecated (p. 522)
• RecordsEvent (p. 524)
• Redirect (p. 525)
• RedirectAllRequestsTo (p. 527)
• ReplicationConfiguration (p. 528)
• ReplicationRule (p. 529)
• ReplicationRuleAndOperator (p. 531)
• ReplicationRuleFilter (p. 532)
• ReplicationTime (p. 533)
• ReplicationTimeValue (p. 534)
• RequestPaymentConfiguration (p. 535)

API Version 2006-03-01

408
Amazon Simple Storage Service API Reference
Data Types

• RequestProgress (p. 536)

• RestoreRequest (p. 537)
• RoutingRule (p. 539)
• Rule (p. 540)
• S3KeyFilter (p. 542)
• S3Location (p. 543)
• ScanRange (p. 545)
• SelectObjectContentEventStream (p. 546)
• SelectParameters (p. 547)
• ServerSideEncryptionByDefault (p. 548)
• ServerSideEncryptionConfiguration (p. 549)
• ServerSideEncryptionRule (p. 550)
• SourceSelectionCriteria (p. 551)
• SSEKMS (p. 552)
• SseKmsEncryptedObjects (p. 553)
• SSES3 (p. 554)
• Stats (p. 555)
• StatsEvent (p. 556)
• StorageClassAnalysis (p. 557)
• StorageClassAnalysisDataExport (p. 558)
• Tag (p. 559)
• Tagging (p. 560)
• TargetGrant (p. 561)
• TopicConfiguration (p. 562)
• TopicConfigurationDeprecated (p. 564)
• Transition (p. 566)
• VersioningConfiguration (p. 567)
• WebsiteConfiguration (p. 568)

413
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

AbortIncompleteMultipartUpload
Service: Amazon Simple Storage Service

Speciﬁes the days since the initiation of an incomplete multipart upload that Amazon S3 will wait before
permanently removing all parts of the upload. For more information, see Aborting Incomplete Multipart
Uploads Using a Bucket Lifecycle Policy in the Amazon Simple Storage Service Developer Guide.

Contents
DaysAfterInitiation

Speciﬁes the number of days after which Amazon S3 aborts an incomplete multipart upload.

Type: Integer

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

414
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

AccelerateConﬁguration
Service: Amazon Simple Storage Service

Conﬁgures the transfer acceleration state for an Amazon S3 bucket. For more information, see Amazon
S3 Transfer Acceleration in the Amazon Simple Storage Service Developer Guide.

Contents
Status

Speciﬁes the transfer acceleration status of the bucket.

Type: String

Valid Values: Enabled | Suspended

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

415
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

AccessControlPolicy
Service: Amazon Simple Storage Service

Contains the elements that set the ACL permissions for an object per grantee.

Contents
Grants

A list of grants.

Type: Array of Grant (p. 466) data types

Required: No
Owner

Container for the bucket owner's display name and ID.

Type: Owner (p. 512) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

416
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

AccessControlTranslation
Service: Amazon Simple Storage Service

A container for information about access control for replicas.

Contents
Owner

Speciﬁes the replica ownership. For default and valid values, see PUT bucket replication in the
Amazon Simple Storage Service API Reference.

Type: String

Valid Values: Destination

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

417
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

AnalyticsAndOperator
Service: Amazon Simple Storage Service

A conjunction (logical AND) of predicates, which is used in evaluating a metrics ﬁlter. The operator must
have at least two predicates in any combination, and an object must match all of the predicates for the
ﬁlter to apply.

Contents
Preﬁx

The preﬁx to use when evaluating an AND predicate: The preﬁx that an object must have to be
included in the metrics results.

Type: String

Required: No
Tags

The list of tags to use when evaluating an AND predicate.

Type: Array of Tag (p. 559) data types

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

418
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

AnalyticsConﬁguration
Service: Amazon Simple Storage Service

Specifies the configuration and any analyses for the analytics filter of an Amazon S3 bucket.

Contents
Filter

Type: AnalyticsFilter (p. 421) data type

Required: No
Id

The ID that identiﬁes the analytics conﬁguration.

Type: String

Required: Yes
StorageClassAnalysis

Contains data related to access patterns to be collected and made available to analyze the tradeoﬀs
between diﬀerent storage classes.

Type: StorageClassAnalysis (p. 557) data type

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

419
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

AnalyticsExportDestination
Service: Amazon Simple Storage Service

Where to publish the analytics results.

Contents
S3BucketDestination

A destination signifying output to an S3 bucket.

Type: AnalyticsS3BucketDestination (p. 422) data type

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

420
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

AnalyticsFilter
Service: Amazon Simple Storage Service

Contents
And

A conjunction (logical AND) of predicates, which is used in evaluating an analytics ﬁlter. The operator
must have at least two predicates.

Type: AnalyticsAndOperator (p. 418) data type

Required: No
Preﬁx

The preﬁx to use when evaluating an analytics ﬁlter.

Type: String

Required: No
Tag

The tag to use when evaluating an analytics ﬁlter.

Type: Tag (p. 559) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

421
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

AnalyticsS3BucketDestination
Service: Amazon Simple Storage Service

Contains information about where to publish the analytics results.

Contents
Bucket

The Amazon Resource Name (ARN) of the bucket to which data is exported.

Type: String

Required: Yes
BucketAccountId

The account ID that owns the destination bucket. If no account ID is provided, the owner will not be
validated prior to exporting data.

Type: String

Required: No
Format

Speciﬁes the ﬁle format used when exporting data to Amazon S3.

Type: String

Valid Values: CSV

Required: Yes
Preﬁx

The preﬁx to use when exporting data. The preﬁx is prepended to all results.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

422
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Bucket
Service: Amazon Simple Storage Service

In terms of implementation, a Bucket is a resource. An Amazon S3 bucket name is globally unique, and
the namespace is shared by all AWS accounts.

Contents
CreationDate

Date the bucket was created.

Type: Timestamp

Required: No
Name

The name of the bucket.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

423
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

BucketLifecycleConﬁguration
Service: Amazon Simple Storage Service

Speciﬁes the lifecycle conﬁguration for objects in an Amazon S3 bucket. For more information, see
Object Lifecycle Management in the Amazon Simple Storage Service Developer Guide.

Contents
Rules

A lifecycle rule for individual objects in an Amazon S3 bucket.

Type: Array of LifecycleRule (p. 484) data types

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

424
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

BucketLoggingStatus
Service: Amazon Simple Storage Service

Container for logging status information.

Contents
LoggingEnabled

Type: LoggingEnabled (p. 488) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

425
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CloudFunctionConﬁguration
Service: Amazon Simple Storage Service

Container for specifying the AWS Lambda notiﬁcation conﬁguration.

Contents
CloudFunction

Lambda cloud function ARN that Amazon S3 can invoke when it detects events of the speciﬁed type.

Type: String

Required: No
Event

This member has been deprecated.

The bucket event for which to send notiﬁcations.

Type: String

Valid Values: s3:ReducedRedundancyLostObject | s3:ObjectCreated:* |

Required: No
Events

Bucket events for which to send notiﬁcations.

Type: Array of strings

Valid Values: s3:ReducedRedundancyLostObject | s3:ObjectCreated:* |

Required: No
Id

An optional unique identifier for configurations in a notification configuration. If you don't provide
one, Amazon S3 will assign an ID.

Type: String

Required: No
InvocationRole

The role supporting the invocation of the Lambda function

API Version 2006-03-01

426
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

427
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CommonPreﬁx
Service: Amazon Simple Storage Service

Container for all (if there are any) keys between Prefix and the next occurrence of the string specified
by a delimiter. CommonPrefixes lists keys that act like subdirectories in the directory specified by Prefix.
For example, if the prefix is notes/ and the delimiter is a slash (/) as in notes/summer/july, the common
prefix is notes/summer/.

Contents
Preﬁx

Container for the speciﬁed common preﬁx.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

428
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CompletedMultipartUpload
Service: Amazon Simple Storage Service

The container for the completed multipart upload details.

Contents
Parts

Array of CompletedPart data types.

Type: Array of CompletedPart (p. 430) data types

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

429
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CompletedPart
Service: Amazon Simple Storage Service

Details of the parts that were uploaded.

Contents
ETag

Entity tag returned when the part was uploaded.

Type: String

Required: No
PartNumber

Part number that identiﬁes the part. This is a positive integer between 1 and 10,000.

Type: Integer

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

430
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Condition
Service: Amazon Simple Storage Service

A container for describing a condition that must be met for the speciﬁed redirect to apply. For example,
1. If request is for pages in the /docs folder, redirect to the /documents folder. 2. If request results in
HTTP error 4xx, redirect request to another host where you might process the error.

Contents
HttpErrorCodeReturnedEquals

The HTTP error code when the redirect is applied. In the event of an error, if the error code equals
this value, then the specified redirect is applied. Required when parent element Condition is
specified and sibling KeyPrefixEquals is not specified. If both are specified, then both must be
true for the redirect to be applied.

Type: String

Required: No
KeyPreﬁxEquals

The object key name prefix when the redirect is applied. For example, to redirect requests
for ExamplePage.html, the key prefix will be ExamplePage.html. To redirect request for
all pages with the prefix docs/, the key prefix will be /docs, which identifies all objects in
the docs/ folder. Required when the parent element Condition is specified and sibling
HttpErrorCodeReturnedEquals is not specified. If both conditions are specified, both must be
true for the redirect to be applied.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

431
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ContinuationEvent
Service: Amazon Simple Storage Service

Contents
The members of this structure are context-dependent.

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

432
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CopyObjectResult
Service: Amazon Simple Storage Service

Container for all response elements.

Contents
ETag

Returns the ETag of the new object. The ETag reﬂects only changes to the contents of an object, not
its metadata. The source and destination ETag is identical for a successfully copied object.

Type: String

Required: No
LastModiﬁed

Returns the date that the object was last modiﬁed.

Type: Timestamp

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

433
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CopyPartResult
Service: Amazon Simple Storage Service

Container for all response elements.

Contents
ETag

Entity tag of the object.

Type: String

Required: No
LastModiﬁed

Date and time at which the object was uploaded.

Type: Timestamp

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

434
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CORSConﬁguration
Service: Amazon Simple Storage Service

Describes the cross-origin access conﬁguration for objects in an Amazon S3 bucket. For more
information, see Enabling Cross-Origin Resource Sharing in the Amazon Simple Storage Service Developer
Guide.

Contents
CORSRules

A set of origins and methods (cross-origin access that you want to allow). You can add up to 100
rules to the conﬁguration.

Type: Array of CORSRule (p. 436) data types

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

Required: No
MaxAgeSeconds

The time in seconds that your browser is to cache the preﬂight response for the speciﬁed resource.

Type: Integer

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

436
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CreateBucketConﬁguration
Service: Amazon Simple Storage Service

The conﬁguration information for the bucket.

Contents
LocationConstraint

Speciﬁes the Region where the bucket will be created. If you don't specify a Region, the bucket is
created in the US East (N. Virginia) Region (us-east-1).

Type: String

Valid Values: EU | eu-west-1 | us-west-1 | us-west-2 | ap-south-1 | ap-

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

437
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CSVInput
Service: Amazon Simple Storage Service

Describes how an uncompressed comma-separated values (CSV)-formatted input object is formatted.

Contents
AllowQuotedRecordDelimiter

Speciﬁes that CSV ﬁeld values may contain quoted record delimiters and such records should be
allowed. Default value is FALSE. Setting this value to TRUE may lower performance.

Type: Boolean

Required: No
Comments

A single character used to indicate that a row should be ignored when the character is present at the
start of that row. You can specify any character to indicate a comment line.

Type: String

Required: No
FieldDelimiter

A single character used to separate individual ﬁelds in a record. You can specify an arbitrary
delimiter.

Type: String

Required: No
FileHeaderInfo

Describes the ﬁrst line of input. Valid values are:

• NONE: First line is not a header.
• IGNORE: First line is a header, but you can't use the header values to indicate the column in an
expression. You can use column position (such as _1, _2, …) to indicate the column (SELECT s._1
FROM OBJECT s).
• Use: First line is a header, and you can use the header value to identify a column in an expression
(SELECT "name" FROM OBJECT).

Type: String

Valid Values: USE | IGNORE | NONE

Required: No
QuoteCharacter

A single character used for escaping when the ﬁeld delimiter is part of the value. For example, if the
value is a, b, Amazon S3 wraps this ﬁeld value in quotation marks, as follows: " a , b ".

Type: String

Default: "

Ancestors: CSV

Type: String

API Version 2006-03-01

438
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Required: No
QuoteEscapeCharacter

A single character used for escaping the quotation mark character inside an already escaped value.
For example, the value """ a , b """ is parsed as " a , b ".

Type: String

Required: No
RecordDelimiter

A single character used to separate individual records in the input. Instead of the default value, you
can specify an arbitrary delimiter.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

439
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

CSVOutput
Service: Amazon Simple Storage Service

Describes how uncompressed comma-separated values (CSV)-formatted results are formatted.

Contents
FieldDelimiter

The value used to separate individual ﬁelds in a record. You can specify an arbitrary delimiter.

Type: String

Required: No
QuoteCharacter

A single character used for escaping when the ﬁeld delimiter is part of the value. For example, if the
value is a, b, Amazon S3 wraps this ﬁeld value in quotation marks, as follows: " a , b ".

Type: String

Required: No
QuoteEscapeCharacter

The single character used for escaping the quote character inside an already escaped value.

Type: String

Required: No
QuoteFields

Indicates whether to use quotation marks around output ﬁelds.

• ALWAYS: Always use quotation marks for output ﬁelds.
• ASNEEDED: Use quotation marks for output ﬁelds when needed.

Type: String

Valid Values: ALWAYS | ASNEEDED

Required: No
RecordDelimiter

A single character used to separate individual records in the output. Instead of the default value, you
can specify an arbitrary delimiter.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

440
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

API Version 2006-03-01

441
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DefaultRetention
Service: Amazon Simple Storage Service

The container element for specifying the default Object Lock retention settings for new objects placed in
the speciﬁed bucket.

Contents
Days

The number of days that you want to specify for the default retention period.

Type: Integer

Required: No
Mode

The default Object Lock retention mode you want to apply to new objects placed in the speciﬁed
bucket.

Type: String

Valid Values: GOVERNANCE | COMPLIANCE

Required: No
Years

The number of years that you want to specify for the default retention period.

Type: Integer

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

442
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Delete
Service: Amazon Simple Storage Service

Container for the objects to delete.

Contents
Objects

The objects to delete.

Type: Array of ObjectIdentiﬁer (p. 503) data types

Required: Yes
Quiet

Element to enable quiet mode for the request. When you add this element, you must set its value to
true.

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

443
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeletedObject
Service: Amazon Simple Storage Service

Information about the deleted object.

Contents
DeleteMarker

Speciﬁes whether the versioned object that was permanently deleted was (true) or was not (false) a
delete marker. In a simple DELETE, this header indicates whether (true) or not (false) a delete marker
was created.

Type: Boolean

Required: No
DeleteMarkerVersionId

The version ID of the delete marker created as a result of the DELETE operation. If you delete a
speciﬁc object version, the value returned by this header is the version ID of the object version
deleted.

Type: String

Required: No
Key

The name of the deleted object.

Type: String

Length Constraints: Minimum length of 1.

Required: No
VersionId

The version ID of the deleted object.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

444
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteMarkerEntry
Service: Amazon Simple Storage Service

Information about the delete marker.

Contents
IsLatest

Speciﬁes whether the object is (true) or is not (false) the latest version of an object.

Type: Boolean

Required: No
Key

The object key.

Type: String

Length Constraints: Minimum length of 1.

Required: No
LastModiﬁed

Date and time the object was last modiﬁed.

Type: Timestamp

Required: No
Owner

The account that created the delete marker.>

Type: Owner (p. 512) data type

Required: No
VersionId

Version ID of an object.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

445
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

DeleteMarkerReplication
Service: Amazon Simple Storage Service

Specifies whether Amazon S3 replicates the delete markers. If you specify a Filter, you must specify
this element. However, in the latest version of replication configuration (when Filter is specified),
Amazon S3 doesn't replicate delete markers. Therefore, the DeleteMarkerReplication element can
contain only <Status>Disabled</Status>. For an example configuration, see Basic Rule Configuration.
Note
If you don't specify the Filter element, Amazon S3 assumes that the replication configuration
is the earlier version, V1. In the earlier version, Amazon S3 handled replication of delete markers
differently. For more information, see Backward Compatibility.

Contents
Status

Indicates whether to replicate delete markers.

Note
In the current implementation, Amazon S3 doesn't replicate the delete markers. The status
must be Disabled.

Type: String

Valid Values: Enabled | Disabled

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

446
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Destination
Service: Amazon Simple Storage Service

Speciﬁes information about where to publish analysis or conﬁguration results for an Amazon S3 bucket
and S3 Replication Time Control (S3 RTC).

Contents
AccessControlTranslation

Specify this only in a cross-account scenario (where source and destination bucket owners are not
the same), and you want to change replica ownership to the AWS account that owns the destination
bucket. If this is not speciﬁed in the replication conﬁguration, the replicas are owned by same AWS
account that owns the source object.

Type: AccessControlTranslation (p. 417) data type

Required: No
Account

Destination bucket owner account ID. In a cross-account scenario, if you direct Amazon S3 to
change replica ownership to the AWS account that owns the destination bucket by specifying the
AccessControlTranslation property, this is the account ID of the destination bucket owner.
For more information, see Replication Additional Conﬁguration: Changing the Replica Owner in the
Amazon Simple Storage Service Developer Guide.

Type: String

Required: No
Bucket

The Amazon Resource Name (ARN) of the bucket where you want Amazon S3 to store the results.

Type: String

Required: Yes
EncryptionConﬁguration

A container that provides information about encryption. If SourceSelectionCriteria is

speciﬁed, you must specify this element.

Type: EncryptionConﬁguration (p. 450) data type

Required: No
Metrics

A container specifying replication metrics-related settings enabling metrics and Amazon S3 events
for S3 Replication Time Control (S3 RTC). Must be speciﬁed together with a ReplicationTime
block.

Type: Metrics (p. 490) data type

Required: No
ReplicationTime

A container specifying S3 Replication Time Control (S3 RTC), including whether S3 RTC is enabled
and the time when all objects and operations on objects must be replicated. Must be speciﬁed
together with a Metrics block.

API Version 2006-03-01

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

449
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

EncryptionConﬁguration
Service: Amazon Simple Storage Service

Speciﬁes encryption-related information for an Amazon S3 bucket that is a destination for replicated
objects.

452
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• Code: 409 Conflict (in all Regions except the North Virginia Region)
• SOAP Fault Code Prefix: Client
• • Code: BucketNotEmpty
• Description: The bucket you tried to delete is not empty.
• HTTP Status Code: 409 Conflict
• SOAP Fault Code Prefix: Client
• • Code: CredentialsNotSupported
• Description: This request does not support credentials.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: CrossLocationLoggingProhibited
• Description: Cross-location logging not allowed. Buckets in one geographic location cannot log
information to a bucket in another location.
• HTTP Status Code: 403 Forbidden
• SOAP Fault Code Prefix: Client
• • Code: EntityTooSmall
• Description: Your proposed upload is smaller than the minimum allowed object size.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: EntityTooLarge
• Description: Your proposed upload exceeds the maximum allowed object size.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: ExpiredToken
• Description: The provided token has expired.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: IllegalVersioningConfigurationException
• Description: Indicates that the versioning configuration specified in the request is invalid.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: IncompleteBody
• Description: You did not provide the number of bytes specified by the Content-Length HTTP
header
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: IncorrectNumberOfFilesInPostRequest
• Description: POST requires exactly one file upload per request.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InlineDataTooLarge
• Description: Inline data exceeds the maximum allowed size.
• HTTP Status Code: 400 Bad Request
API Version 2006-03-01
• SOAP Fault Code Prefix: Client 453
• • Code: InternalError
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• Description: We encountered an internal error. Please try again.

• HTTP Status Code: 500 Internal Server Error
• SOAP Fault Code Prefix: Server
• • Code: InvalidAccessKeyId
• Description: The AWS access key ID you provided does not exist in our records.
• HTTP Status Code: 403 Forbidden
• SOAP Fault Code Prefix: Client
• • Code: InvalidAddressingHeader
• Description: You must specify the Anonymous role.
• HTTP Status Code: N/A
• SOAP Fault Code Prefix: Client
• • Code: InvalidArgument
• Description: Invalid Argument
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InvalidBucketName
• Description: The specified bucket is not valid.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InvalidBucketState
• Description: The request is not valid with the current state of the bucket.
• HTTP Status Code: 409 Conflict
• SOAP Fault Code Prefix: Client
• • Code: InvalidDigest
• Description: The Content-MD5 you specified is not valid.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InvalidEncryptionAlgorithmError
• Description: The encryption request you specified is not valid. The valid value is AES256.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InvalidLocationConstraint
• Description: The specified location constraint is not valid. For more information about Regions,
see How to Select a Region for Your Buckets.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InvalidObjectState
• Description: The operation is not valid for the current state of the object.
• HTTP Status Code: 403 Forbidden
• SOAP Fault Code Prefix: Client
• • Code: InvalidPart
• Description: One or more of the specified parts could not be found. The part might not have
been uploaded, or the specified entity tag might not have matched the part's entity tag.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InvalidPartOrder
API Version 2006-03-01
454
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• Description: The list of parts was not in ascending order. Parts list must be specified in order by
part number.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InvalidPayer
• Description: All access to this object has been disabled. Please contact AWS Support for further
assistance.
• HTTP Status Code: 403 Forbidden
• SOAP Fault Code Prefix: Client
• • Code: InvalidPolicyDocument
• Description: The content of the form does not meet the conditions specified in the policy
document.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InvalidRange
• Description: The requested range cannot be satisfied.
• HTTP Status Code: 416 Requested Range Not Satisfiable
• SOAP Fault Code Prefix: Client
• • Code: InvalidRequest
• Description: Please use AWS4-HMAC-SHA256.
• HTTP Status Code: 400 Bad Request
• Code: N/A
• • Code: InvalidRequest
• Description: SOAP requests must be made over an HTTPS connection.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InvalidRequest
• Description: Amazon S3 Transfer Acceleration is not supported for buckets with non-DNS
compliant names.
• HTTP Status Code: 400 Bad Request
• Code: N/A
• • Code: InvalidRequest
• Description: Amazon S3 Transfer Acceleration is not supported for buckets with periods (.) in
their names.
• HTTP Status Code: 400 Bad Request
• Code: N/A
• • Code: InvalidRequest
• Description: Amazon S3 Transfer Accelerate endpoint only supports virtual style requests.
• HTTP Status Code: 400 Bad Request
• Code: N/A
• • Code: InvalidRequest
• Description: Amazon S3 Transfer Accelerate is not configured on this bucket.
• HTTP Status Code: 400 Bad Request
• Code: N/A
• • Code: InvalidRequest
API Version 2006-03-01
• Description: Amazon S3 Transfer Accelerate
455 is disabled on this bucket.
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• HTTP Status Code: 400 Bad Request

• Code: N/A
• • Code: InvalidRequest
• Description: Amazon S3 Transfer Acceleration is not supported on this bucket. Contact AWS
Support for more information.
• HTTP Status Code: 400 Bad Request
• Code: N/A
• • Code: InvalidRequest
• Description: Amazon S3 Transfer Acceleration cannot be enabled on this bucket. Contact AWS
Support for more information.
• HTTP Status Code: 400 Bad Request
• Code: N/A
• • Code: InvalidSecurity
• Description: The provided security credentials are not valid.
• HTTP Status Code: 403 Forbidden
• SOAP Fault Code Prefix: Client
• • Code: InvalidSOAPRequest
• Description: The SOAP request body is invalid.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InvalidStorageClass
• Description: The storage class you specified is not valid.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InvalidTargetBucketForLogging
• Description: The target bucket for logging does not exist, is not owned by you, or does not have
the appropriate grants for the log-delivery group.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InvalidToken
• Description: The provided token is malformed or otherwise invalid.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: InvalidURI
• Description: Couldn't parse the specified URI.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: KeyTooLongError
• Description: Your key is too long.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: MalformedACLError
• Description: The XML you provided was not well-formed or did not validate against our
published schema.
• HTTP Status Code: 400 Bad Request
API Version 2006-03-01
• SOAP Fault Code Prefix: Client
456
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• • Code: MalformedPOSTRequest
• Description: The body of your POST request is not well-formed multipart/form-data.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: MalformedXML
• Description: This happens when the user sends malformed XML (XML that doesn't conform to
the published XSD) for the configuration. The error message is, "The XML you provided was not
well-formed or did not validate against our published schema."
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: MaxMessageLengthExceeded
• Description: Your request was too big.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: MaxPostPreDataLengthExceededError
• Description: Your POST request fields preceding the upload file were too large.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: MetadataTooLarge
• Description: Your metadata headers exceed the maximum allowed metadata size.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: MethodNotAllowed
• Description: The specified method is not allowed against this resource.
• HTTP Status Code: 405 Method Not Allowed
• SOAP Fault Code Prefix: Client
• • Code: MissingAttachment
• Description: A SOAP attachment was expected, but none were found.
• HTTP Status Code: N/A
• SOAP Fault Code Prefix: Client
• • Code: MissingContentLength
• Description: You must provide the Content-Length HTTP header.
• HTTP Status Code: 411 Length Required
• SOAP Fault Code Prefix: Client
• • Code: MissingRequestBodyError
• Description: This happens when the user sends an empty XML document as a request. The error
message is, "Request body is empty."
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: MissingSecurityElement
• Description: The SOAP 1.1 request is missing a security element.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: MissingSecurityHeader
• Description: Your request is missing a required header.
API Version 2006-03-01
• HTTP Status Code: 400 Bad Request 457
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• SOAP Fault Code Preﬁx: Client

• • Code: NoLoggingStatusForKey
• Description: There is no such thing as a logging status subresource for a key.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: NoSuchBucket
• Description: The specified bucket does not exist.
• HTTP Status Code: 404 Not Found
• SOAP Fault Code Prefix: Client
• • Code: NoSuchBucketPolicy
• Description: The specified bucket does not have a bucket policy.
• HTTP Status Code: 404 Not Found
• SOAP Fault Code Prefix: Client
• • Code: NoSuchKey
• Description: The specified key does not exist.
• HTTP Status Code: 404 Not Found
• SOAP Fault Code Prefix: Client
• • Code: NoSuchLifecycleConfiguration
• Description: The lifecycle configuration does not exist.
• HTTP Status Code: 404 Not Found
• SOAP Fault Code Prefix: Client
• • Code: NoSuchUpload
• Description: The specified multipart upload does not exist. The upload ID might be invalid, or the
multipart upload might have been aborted or completed.
• HTTP Status Code: 404 Not Found
• SOAP Fault Code Prefix: Client
• • Code: NoSuchVersion
• Description: Indicates that the version ID specified in the request does not match an existing
version.
• HTTP Status Code: 404 Not Found
• SOAP Fault Code Prefix: Client
• • Code: NotImplemented
• Description: A header you provided implies functionality that is not implemented.
• HTTP Status Code: 501 Not Implemented
• SOAP Fault Code Prefix: Server
• • Code: NotSignedUp
• Description: Your account is not signed up for the Amazon S3 service. You must sign up before
you can use Amazon S3. You can sign up at the following URL: https://aws.amazon.com/s3
• HTTP Status Code: 403 Forbidden
• SOAP Fault Code Prefix: Client
• • Code: OperationAborted
• Description: A conflicting conditional operation is currently in progress against this resource. Try
again.
• HTTP Status Code: 409 Conflict
• SOAP Fault Code Prefix: Client
• • Code: PermanentRedirect API Version 2006-03-01
458
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• Description: The bucket you are attempting to access must be addressed using the specified
endpoint. Send all future requests to this endpoint.
• HTTP Status Code: 301 Moved Permanently
• SOAP Fault Code Prefix: Client
• • Code: PreconditionFailed
• Description: At least one of the preconditions you specified did not hold.
• HTTP Status Code: 412 Precondition Failed
• SOAP Fault Code Prefix: Client
• • Code: Redirect
• Description: Temporary redirect.
• HTTP Status Code: 307 Moved Temporarily
• SOAP Fault Code Prefix: Client
• • Code: RestoreAlreadyInProgress
• Description: Object restore is already in progress.
• HTTP Status Code: 409 Conflict
• SOAP Fault Code Prefix: Client
• • Code: RequestIsNotMultiPartContent
• Description: Bucket POST must be of the enclosure-type multipart/form-data.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: RequestTimeout
• Description: Your socket connection to the server was not read from or written to within the
timeout period.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: RequestTimeTooSkewed
• Description: The difference between the request time and the server's time is too large.
• HTTP Status Code: 403 Forbidden
• SOAP Fault Code Prefix: Client
• • Code: RequestTorrentOfBucketError
• Description: Requesting the torrent file of a bucket is not permitted.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: SignatureDoesNotMatch
• Description: The request signature we calculated does not match the signature you provided.
Check your AWS secret access key and signing method. For more information, see REST
Authentication and SOAP Authentication for details.
• HTTP Status Code: 403 Forbidden
• SOAP Fault Code Prefix: Client
• • Code: ServiceUnavailable
• Description: Reduce your request rate.
• HTTP Status Code: 503 Service Unavailable
• SOAP Fault Code Prefix: Server
• • Code: SlowDown
• Description: Reduce your request rate.
• HTTP Status Code: 503 SlowAPIDown
Version 2006-03-01
459
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• SOAP Fault Code Preﬁx: Server

• • Code: TemporaryRedirect
• Description: You are being redirected to the bucket while DNS updates.
• HTTP Status Code: 307 Moved Temporarily
• SOAP Fault Code Prefix: Client
• • Code: TokenRefreshRequired
• Description: The provided token must be refreshed.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: TooManyBuckets
• Description: You have attempted to create more buckets than allowed.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: UnexpectedContent
• Description: This request does not support content.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: UnresolvableGrantByEmailAddress
• Description: The email address you provided does not match any account on record.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client
• • Code: UserKeyMustBeSpecified
• Description: The bucket POST must contain the specified field name. If it is specified, check the
order of the fields.
• HTTP Status Code: 400 Bad Request
• SOAP Fault Code Prefix: Client

Type: String

Required: No
Key

The error key.

Type: String

Length Constraints: Minimum length of 1.

Required: No
Message

The error message contains a generic description of the error condition in English. It is intended for
a human audience. Simple programs display the message directly to the end user if they encounter
an error condition they don't know how or don't care to handle. Sophisticated programs with
more exhaustive error handling and proper internationalization are more likely to ignore the error
message.

Type: String

Required: No
VersionId

The version ID of the error.

API Version 2006-03-01

460
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

461
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ErrorDocument
Service: Amazon Simple Storage Service

The error information.

Contents
Key

The object key name to use when a 4XX class error occurs.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

462
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ExistingObjectReplication
Service: Amazon Simple Storage Service

Optional conﬁguration to replicate existing source bucket objects. For more information, see Replicating
Existing Objects in the Amazon S3 Developer Guide.

Contents
Status

Type: String

Valid Values: Enabled | Disabled

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

463
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

FilterRule
Service: Amazon Simple Storage Service

Specifies the Amazon S3 object key name to filter on and whether to filter on the suffix or prefix of the
key name.

Contents
Name

The object key name prefix or suffix identifying one or more objects to which the filtering rule
applies. The maximum length is 1,024 characters. Overlapping prefixes and suffixes are not
supported. For more information, see Configuring Event Notifications in the Amazon Simple Storage
Service Developer Guide.

Type: String

Valid Values: prefix | suffix

Required: No
Value

The value that the ﬁlter searches for in object key names.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

464
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

GlacierJobParameters
Service: Amazon Simple Storage Service

Container for Glacier job parameters.

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

467
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

IndexDocument
Service: Amazon Simple Storage Service

Container for the Suffix element.

Contents
Suﬃx

A suffix that is appended to a request that is for a directory on the website endpoint (for example,if
the suffix is index.html and you make a request to samplebucket/images/ the data that is returned
will be for the object with the key name images/index.html) The suffix must not be empty and must
not include a slash character.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

468
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Initiator
Service: Amazon Simple Storage Service

Container element that identiﬁes who initiated the multipart upload.

Contents
DisplayName

Name of the Principal.

Type: String

Required: No
ID

If the principal is an AWS account, it provides the Canonical User ID. If the principal is an IAM User, it
provides a user ARN value.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

469
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

InputSerialization
Service: Amazon Simple Storage Service

Describes the serialization format of the object.

Contents
CompressionType

Speciﬁes object's compression format. Valid values: NONE, GZIP, BZIP2. Default Value: NONE.

Type: String

Valid Values: NONE | GZIP | BZIP2

Required: No
CSV

Describes the serialization of a CSV-encoded object.

Type: CSVInput (p. 438) data type

Required: No
JSON

Speciﬁes JSON as object's input serialization format.

Type: JSONInput (p. 478) data type

Required: No
Parquet

Speciﬁes Parquet as object's input serialization format.

Type: ParquetInput (p. 513) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

470
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

InventoryConﬁguration
Service: Amazon Simple Storage Service

Speciﬁes the inventory conﬁguration for an Amazon S3 bucket. For more information, see GET Bucket
inventory in the Amazon Simple Storage Service API Reference.

Contents
Destination

Contains information about where to publish the inventory results.

Type: InventoryDestination (p. 473) data type

Required: Yes
Filter

Specifies an inventory filter. The inventory only includes objects that meet the filter's criteria.

Type: InventoryFilter (p. 475) data type

Required: No
Id

The ID used to identify the inventory conﬁguration.

Type: String

Required: Yes
IncludedObjectVersions

Type: String

Valid Values: All | Current

Required: Yes
IsEnabled

Speciﬁes whether the inventory is enabled or disabled. If set to True, an inventory list is generated.
If set to False, no inventory list is generated.

Type: Boolean

Required: Yes
OptionalFields

Contains the optional ﬁelds that are included in the inventory results.

Type: Array of strings

Valid Values: Size | LastModifiedDate | StorageClass | ETag |

API Version 2006-03-01

471
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Required: No
Schedule

Speciﬁes the schedule for generating inventory results.

Type: InventorySchedule (p. 477) data type

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

472
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

InventoryDestination
Service: Amazon Simple Storage Service

Speciﬁes the inventory conﬁguration for an Amazon S3 bucket.

Contents
S3BucketDestination

Contains the bucket name, ﬁle format, bucket owner (optional), and preﬁx (optional) where
inventory results are published.

Type: InventoryS3BucketDestination (p. 476) data type

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

473
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

InventoryEncryption
Service: Amazon Simple Storage Service

Contains the type of server-side encryption used to encrypt the inventory results.

Contents
SSEKMS

Speciﬁes the use of SSE-KMS to encrypt delivered inventory reports.

Type: SSEKMS (p. 552) data type

Required: No
SSES3

Speciﬁes the use of SSE-S3 to encrypt delivered inventory reports.

Type: SSES3 (p. 554) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

474
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

InventoryFilter
Service: Amazon Simple Storage Service

Specifies an inventory filter. The inventory only includes objects that meet the filter's criteria.

Contents
Preﬁx

Type: String

Valid Values: CSV | ORC | Parquet

Required: Yes
Preﬁx

The preﬁx that is prepended to all inventory results.

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

479
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

LambdaFunctionConﬁguration
Service: Amazon Simple Storage Service

A container for specifying the conﬁguration for AWS Lambda notiﬁcations.

Contents
Events

The Amazon S3 bucket event for which to invoke the AWS Lambda function. For more information,
see Supported Event Types in the Amazon Simple Storage Service Developer Guide.

Type: Array of strings

Valid Values: s3:ReducedRedundancyLostObject | s3:ObjectCreated:* |

Required: Yes
Filter

Specifies object key name filtering rules. For information about key name filtering, see Configuring
Event Notifications in the Amazon Simple Storage Service Developer Guide.

Type: NotiﬁcationConﬁgurationFilter (p. 500) data type

Required: No
Id

An optional unique identifier for configurations in a notification configuration. If you don't provide
one, Amazon S3 will assign an ID.

Type: String

Required: No
LambdaFunctionArn

The Amazon Resource Name (ARN) of the AWS Lambda function that Amazon S3 invokes when the
speciﬁed event type occurs.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

480
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

API Version 2006-03-01

481
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

LifecycleConﬁguration
Service: Amazon Simple Storage Service

Container for lifecycle rules. You can add as many as 1000 rules.

Contents
Rules

Speciﬁes lifecycle conﬁguration rules for an Amazon S3 bucket.

Type: Array of Rule (p. 540) data types

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

482
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

LifecycleExpiration
Service: Amazon Simple Storage Service

Container for the expiration for the lifecycle of the object.

Contents
Date

Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.

Type: Timestamp

Required: No
Days

Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-
zero positive integer.

Type: Integer

Required: No
ExpiredObjectDeleteMarker

Indicates whether Amazon S3 will remove a delete marker with no noncurrent versions. If set to true,
the delete marker will be expired; if set to false the policy takes no action. This cannot be speciﬁed
with Days or Date in a Lifecycle Expiration Policy.

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

483
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

LifecycleRule
Service: Amazon Simple Storage Service

A lifecycle rule for individual objects in an Amazon S3 bucket.

Contents
AbortIncompleteMultipartUpload

Speciﬁes the days since the initiation of an incomplete multipart upload that Amazon S3 will
wait before permanently removing all parts of the upload. For more information, see Aborting
Incomplete Multipart Uploads Using a Bucket Lifecycle Policy in the Amazon Simple Storage Service
Developer Guide.

Type: AbortIncompleteMultipartUpload (p. 414) data type

Required: No
Expiration

Speciﬁes the expiration for the lifecycle of the object in the form of date, days and, whether the
object has a delete marker.

Type: LifecycleExpiration (p. 483) data type

Required: No
Filter

The Filter is used to identify objects that a Lifecycle Rule applies to. A Filter must have exactly
one of Prefix, Tag, or And speciﬁed.

Type: LifecycleRuleFilter (p. 487) data type

Required: No
ID

Unique identiﬁer for the rule. The value cannot be longer than 255 characters.

Type: String

Required: No
NoncurrentVersionExpiration

Specifies when noncurrent object versions expire. Upon expiration, Amazon S3 permanently deletes
the noncurrent object versions. You set this lifecycle configuration action on a bucket that has
versioning enabled (or suspended) to request that Amazon S3 delete noncurrent object versions at a
specific period in the object's lifetime.

Type: NoncurrentVersionExpiration (p. 496) data type

Required: No
NoncurrentVersionTransitions

Specifies the transition rule for the lifecycle rule that describes when noncurrent objects transition
to a specific storage class. If your bucket is versioning-enabled (or versioning is suspended), you can
set this action to request that Amazon S3 transition noncurrent object versions to a specific storage
class at a set period in the object's lifetime.

Type: Array of NoncurrentVersionTransition (p. 497) data types

API Version 2006-03-01

484
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Required: No
Preﬁx

This member has been deprecated.

Preﬁx identifying one or more objects to which the rule applies. This is No longer used; use Filter
instead.

Type: String

Required: No
Status

If 'Enabled', the rule is currently being applied. If 'Disabled', the rule is not currently being applied.

Type: String

Valid Values: Enabled | Disabled

Required: Yes
Transitions

Speciﬁes when an Amazon S3 object transitions to a speciﬁed storage class.

Type: Array of Transition (p. 566) data types

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

485
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

LifecycleRuleAndOperator
Service: Amazon Simple Storage Service

This is used in a Lifecycle Rule Filter to apply a logical AND to two or more predicates. The Lifecycle Rule
will apply to any object matching all of the predicates conﬁgured inside the And operator.

Contents
Preﬁx

Preﬁx identifying one or more objects to which the rule applies.

Type: String

Required: No
Tags

All of these tags must exist in the object's tag set in order for the rule to apply.

Type: Array of Tag (p. 559) data types

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

486
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

LifecycleRuleFilter
Service: Amazon Simple Storage Service

The Filter is used to identify objects that a Lifecycle Rule applies to. A Filter must have exactly one
of Prefix, Tag, or And speciﬁed.

Contents
And

This is used in a Lifecycle Rule Filter to apply a logical AND to two or more predicates. The Lifecycle
Rule will apply to any object matching all of the predicates conﬁgured inside the And operator.

Type: LifecycleRuleAndOperator (p. 486) data type

Required: No
Preﬁx

Preﬁx identifying one or more objects to which the rule applies.

Type: String

Required: No
Tag

This tag must exist in the object's tag set in order for the rule to apply.

Type: Tag (p. 559) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

487
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

LoggingEnabled
Service: Amazon Simple Storage Service

Describes where logs are stored and the preﬁx that Amazon S3 assigns to all log object keys for a bucket.
For more information, see PUT Bucket logging in the Amazon Simple Storage Service API Reference.

Contents
TargetBucket

Specifies the bucket where you want Amazon S3 to store server access logs. You can have your logs
delivered to any bucket that you own, including the same bucket that is being logged. You can also
configure multiple buckets to deliver their logs to the same target bucket. In this case, you should
choose a different TargetPrefix for each source bucket so that the delivered log files can be
distinguished by key.

Type: String

Required: Yes
TargetGrants

Container for granting information.

Type: Array of TargetGrant (p. 561) data types

Required: No
TargetPreﬁx

A prefix for all log object keys. If you store log files from multiple Amazon S3 buckets in a single
bucket, you can use a prefix to distinguish which log files came from which bucket.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

488
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

MetadataEntry
Service: Amazon Simple Storage Service

A metadata key-value pair to store with an object.

Contents
Name

Name of the Object.

Type: String

Required: No
Value

Value of the Object.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

489
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Metrics
Service: Amazon Simple Storage Service

A container specifying replication metrics-related settings enabling metrics and Amazon S3 events for S3
Replication Time Control (S3 RTC). Must be speciﬁed together with a ReplicationTime block.

Contents
EventThreshold

A container specifying the time threshold for emitting the

s3:Replication:OperationMissedThreshold event.

Type: ReplicationTimeValue (p. 534) data type

Required: Yes
Status

Speciﬁes whether the replication metrics are enabled.

Type: String

Valid Values: Enabled | Disabled

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

490
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

MetricsAndOperator
Service: Amazon Simple Storage Service

A conjunction (logical AND) of predicates, which is used in evaluating a metrics ﬁlter. The operator must
have at least two predicates, and an object must match all of the predicates in order for the ﬁlter to
apply.

Contents
Preﬁx

The preﬁx used when evaluating an AND predicate.

Type: String

Required: No
Tags

The list of tags used when evaluating an AND predicate.

Type: Array of Tag (p. 559) data types

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

491
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

MetricsConﬁguration
Service: Amazon Simple Storage Service

Specifies a metrics configuration for the CloudWatch request metrics (specified by the metrics
configuration ID) from an Amazon S3 bucket. If you're updating an existing metrics configuration, note
that this is a full replacement of the existing metrics configuration. If you don't include the elements
you want to keep, they are erased. For more information, see PUT Bucket metrics in the Amazon Simple
Storage Service API Reference.

Contents
Filter

Type: MetricsFilter (p. 493) data type

Required: No
Id

The ID used to identify the metrics conﬁguration.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

492
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

MetricsFilter
Service: Amazon Simple Storage Service

Specifies a metrics configuration filter. The metrics configuration only includes objects that meet the
filter's criteria. A filter must be a prefix, a tag, or a conjunction (MetricsAndOperator).

Contents
And

A conjunction (logical AND) of predicates, which is used in evaluating a metrics ﬁlter. The operator
must have at least two predicates, and an object must match all of the predicates in order for the
ﬁlter to apply.

Type: MetricsAndOperator (p. 491) data type

Required: No
Preﬁx

The preﬁx used when evaluating a metrics ﬁlter.

Type: String

Required: No
Tag

The tag used when evaluating a metrics ﬁlter.

Type: Tag (p. 559) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

493
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

MultipartUpload
Service: Amazon Simple Storage Service

Container for the MultipartUpload for the Amazon S3 object.

Contents
Initiated

Date and time at which the multipart upload was initiated.

Type: Timestamp

Required: No
Initiator

Identiﬁes who initiated the multipart upload.

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

495
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

NoncurrentVersionExpiration
Service: Amazon Simple Storage Service

Specifies when noncurrent object versions expire. Upon expiration, Amazon S3 permanently deletes the
noncurrent object versions. You set this lifecycle configuration action on a bucket that has versioning
enabled (or suspended) to request that Amazon S3 delete noncurrent object versions at a specific period
in the object's lifetime.

Contents
NoncurrentDays

Speciﬁes the number of days an object is noncurrent before Amazon S3 can perform the associated
action. For information about the noncurrent days calculations, see How Amazon S3 Calculates
When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.

Type: Integer

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

496
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

NoncurrentVersionTransition
Service: Amazon Simple Storage Service

Container for the transition rule that describes when noncurrent objects transition to the STANDARD_IA,
ONEZONE_IA, INTELLIGENT_TIERING, GLACIER, or DEEP_ARCHIVE storage class. If your bucket is
versioning-enabled (or versioning is suspended), you can set this action to request that Amazon S3
transition noncurrent object versions to the STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING,
GLACIER, or DEEP_ARCHIVE storage class at a speciﬁc period in the object's lifetime.

Contents
NoncurrentDays

Speciﬁes the number of days an object is noncurrent before Amazon S3 can perform the associated
action. For information about the noncurrent days calculations, see How Amazon S3 Calculates How
Long an Object Has Been Noncurrent in the Amazon Simple Storage Service Developer Guide.

Type: Integer

Required: No
StorageClass

The class of storage used to store the object.

Type: String

Valid Values: GLACIER | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING |

DEEP_ARCHIVE

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

497
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

NotiﬁcationConﬁguration
Service: Amazon Simple Storage Service

A container for specifying the notification configuration of the bucket. If this element is empty,
notifications are turned off for the bucket.

Contents
LambdaFunctionConﬁgurations

Describes the AWS Lambda functions to invoke and the events for which to invoke them.

Type: Array of LambdaFunctionConﬁguration (p. 480) data types

Required: No
QueueConﬁgurations

The Amazon Simple Queue Service queues to publish messages to and the events for which to
publish messages.

Type: Array of QueueConﬁguration (p. 520) data types

Required: No
TopicConﬁgurations

The topic to which notiﬁcations are sent and the events for which notiﬁcations are generated.

Type: Array of TopicConﬁguration (p. 562) data types

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

498
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

NotiﬁcationConﬁgurationDeprecated
Service: Amazon Simple Storage Service

Contents
CloudFunctionConﬁguration

Container for specifying the AWS Lambda notiﬁcation conﬁguration.

Type: CloudFunctionConﬁguration (p. 426) data type

Required: No
QueueConﬁguration

This data type is deprecated. This data type specifies the configuration for publishing messages to
an Amazon Simple Queue Service (Amazon SQS) queue when Amazon S3 detects specified events.

Type: QueueConﬁgurationDeprecated (p. 522) data type

Required: No
TopicConﬁguration

Type: TopicConﬁgurationDeprecated (p. 564) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

499
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

NotiﬁcationConﬁgurationFilter
Service: Amazon Simple Storage Service

Specifies object key name filtering rules. For information about key name filtering, see Configuring Event
Notifications in the Amazon Simple Storage Service Developer Guide.

Contents
Key

A container for object key name prefix and suffix filtering rules.

Type: S3KeyFilter (p. 542) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

500
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Object
Service: Amazon Simple Storage Service

An object consists of data and its descriptive metadata.

Contents
ETag

The entity tag is an MD5 hash of the object. ETag reﬂects only changes to the contents of an object,
not its metadata.

Type: String

Required: No
Key

The name that you assign to an object. You use the object key to retrieve the object.

Type: String

Length Constraints: Minimum length of 1.

Required: No
LastModiﬁed

The date the Object was Last Modiﬁed

Type: Timestamp

Required: No
Owner

The owner of the object

Type: Owner (p. 512) data type

Required: No
Size

Size in bytes of the object

Type: Integer

Required: No
StorageClass

The class of storage used to store the object.

Type: String

Valid Values: STANDARD | REDUCED_REDUNDANCY | GLACIER | STANDARD_IA |

ONEZONE_IA | INTELLIGENT_TIERING | DEEP_ARCHIVE

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

API Version 2006-03-01

501
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

502
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ObjectIdentiﬁer
Service: Amazon Simple Storage Service

Object Identiﬁer is unique value to identify objects.

Contents
Key

Key name of the object to delete.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
VersionId

VersionId for the speciﬁc version of the object to delete.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

503
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ObjectLockConﬁguration
Service: Amazon Simple Storage Service

The container element for Object Lock conﬁguration parameters.

Contents
ObjectLockEnabled

Indicates whether this bucket has an Object Lock conﬁguration enabled.

Type: String

Valid Values: Enabled

Required: No
Rule

The Object Lock rule in place for the speciﬁed object.

Type: ObjectLockRule (p. 507) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

504
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ObjectLockLegalHold
Service: Amazon Simple Storage Service

A Legal Hold conﬁguration for an object.

Contents
Status

Indicates whether the speciﬁed object has a Legal Hold in place.

Type: String

Valid Values: ON | OFF

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

505
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ObjectLockRetention
Service: Amazon Simple Storage Service

A Retention conﬁguration for an object.

Contents
Mode

Indicates the Retention mode for the speciﬁed object.

Type: String

Valid Values: GOVERNANCE | COMPLIANCE

Required: No
RetainUntilDate

The date on which this Object Lock Retention will expire.

Type: Timestamp

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

506
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ObjectLockRule
Service: Amazon Simple Storage Service

The container element for an Object Lock rule.

Contents
DefaultRetention

The default retention period that you want to apply to new objects placed in the speciﬁed bucket.

Type: DefaultRetention (p. 442) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

507
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ObjectVersion
Service: Amazon Simple Storage Service

The version of an object.

Contents
ETag

The entity tag is an MD5 hash of that version of the object.

Type: String

Required: No
IsLatest

Speciﬁes whether the object is (true) or is not (false) the latest version of an object.

Type: Boolean

Required: No
Key

The object key.

Type: String

Length Constraints: Minimum length of 1.

Required: No
LastModiﬁed

Date and time the object was last modiﬁed.

Type: Timestamp

Required: No
Owner

Speciﬁes the owner of the object.

Type: Owner (p. 512) data type

Required: No
Size

Size in bytes of the object.

Type: Integer

Required: No
StorageClass

The class of storage used to store the object.

Type: String

Valid Values: STANDARD

Required: No

API Version 2006-03-01

508
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

VersionId

Version ID of an object.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

509
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

OutputLocation
Service: Amazon Simple Storage Service

Describes the location where the restore job's output is stored.

Contents
S3

Describes an S3 location that will receive the results of the restore request.

Type: S3Location (p. 543) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

510
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

OutputSerialization
Service: Amazon Simple Storage Service

Describes how results of the Select job are serialized.

Contents
CSV

Describes the serialization of CSV-encoded Select results.

Type: CSVOutput (p. 440) data type

Required: No
JSON

Speciﬁes JSON as request's output serialization format.

Type: JSONOutput (p. 479) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

511
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Owner
Service: Amazon Simple Storage Service

Container for the owner's display name and ID.

Contents
DisplayName

Container for the display name of the owner.

Type: String

Required: No
ID

Container for the ID of the owner.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

512
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ParquetInput
Service: Amazon Simple Storage Service

Container for Parquet.

Contents
The members of this structure are context-dependent.

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

513
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Part
Service: Amazon Simple Storage Service

Container for elements related to a part.

Contents
ETag

Entity tag returned when the part was uploaded.

Type: String

Required: No
LastModiﬁed

Date and time at which the part was uploaded.

Type: Timestamp

Required: No
PartNumber

Part number identifying the part. This is a positive integer between 1 and 10,000.

Type: Integer

Required: No
Size

Size in bytes of the uploaded part data.

Type: Integer

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

514
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PolicyStatus
Service: Amazon Simple Storage Service

The container element for a bucket's policy status.

Contents
IsPublic

The policy status for this bucket. TRUE indicates that this bucket is public. FALSE indicates that the
bucket is not public.

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

515
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Progress
Service: Amazon Simple Storage Service

This data type contains information about progress of an operation.

Contents
BytesProcessed

The current number of uncompressed object bytes processed.

Type: Long

Required: No
BytesReturned

The current number of bytes of records payload data returned.

Type: Long

Required: No
BytesScanned

The current number of object bytes scanned.

Type: Long

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

516
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ProgressEvent
Service: Amazon Simple Storage Service

This data type contains information about the progress event of an operation.

Contents
Details

The Progress event details.

Type: Progress (p. 516) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

517
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

PublicAccessBlockConﬁguration
Service: Amazon Simple Storage Service

The PublicAccessBlock conﬁguration that you want to apply to this Amazon S3 bucket. You can enable
the conﬁguration options in any combination. For more information about when Amazon S3 considers
a bucket or object public, see The Meaning of "Public" in the Amazon Simple Storage Service Developer
Guide.

Contents
BlockPublicAcls

Enabling this setting doesn't aﬀect existing policies or ACLs.

Type: Boolean

Required: No
BlockPublicPolicy

Enabling this setting doesn't aﬀect existing bucket policies.

Type: Boolean

Required: No
IgnorePublicAcls

Enabling this setting doesn't aﬀect the persistence of any existing ACLs and doesn't prevent new
public ACLs from being set.

Type: Boolean

Required: No
RestrictPublicBuckets

Type: Boolean

API Version 2006-03-01

518
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

519
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

QueueConﬁguration
Service: Amazon Simple Storage Service

Specifies the configuration for publishing messages to an Amazon Simple Queue Service (Amazon SQS)
queue when Amazon S3 detects specified events.

Contents
Events

A collection of bucket events for which to send notiﬁcations

Type: Array of strings

Valid Values: s3:ReducedRedundancyLostObject | s3:ObjectCreated:* |

Required: Yes
Filter

Specifies object key name filtering rules. For information about key name filtering, see Configuring
Event Notifications in the Amazon Simple Storage Service Developer Guide.

Type: NotiﬁcationConﬁgurationFilter (p. 500) data type

Required: No
Id

An optional unique identifier for configurations in a notification configuration. If you don't provide
one, Amazon S3 will assign an ID.

Type: String

Required: No
QueueArn

The Amazon Resource Name (ARN) of the Amazon SQS queue to which Amazon S3 publishes a
message when it detects events of the speciﬁed type.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

520
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

API Version 2006-03-01

521
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

QueueConﬁgurationDeprecated
Service: Amazon Simple Storage Service

This data type is deprecated. Use QueueConfiguration (p. 520) for the same purposes. This data type
specifies the configuration for publishing messages to an Amazon Simple Queue Service (Amazon SQS)
queue when Amazon S3 detects specified events.

Contents
Event

This member has been deprecated.

The bucket event for which to send notiﬁcations.

Type: String

Valid Values: s3:ReducedRedundancyLostObject | s3:ObjectCreated:* |

Required: No
Events

A collection of bucket events for which to send notiﬁcations

Type: Array of strings

Valid Values: s3:ReducedRedundancyLostObject | s3:ObjectCreated:* |

Required: No
Id

An optional unique identifier for configurations in a notification configuration. If you don't provide
one, Amazon S3 will assign an ID.

Type: String

Required: No
Queue

The Amazon Resource Name (ARN) of the Amazon SQS queue to which Amazon S3 publishes a
message when it detects events of the speciﬁed type.

Type: String

Required: No

API Version 2006-03-01

522
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

523
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

RecordsEvent
Service: Amazon Simple Storage Service

The container for the records event.

Contents
Payload

The byte array of partial, one or more result records.

Type: Base64-encoded binary data object

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

524
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Redirect
Service: Amazon Simple Storage Service

Speciﬁes how requests are redirected. In the event of an error, you can specify a diﬀerent error code to
return.

Contents
HostName

The host name to use in the redirect request.

Type: String

Required: No
HttpRedirectCode

The HTTP redirect code to use on the response. Not required if one of the siblings is present.

Type: String

Required: No
Protocol

Protocol to use when redirecting requests. The default is the protocol that is used in the original
request.

Type: String

Valid Values: http | https

Required: No
ReplaceKeyPreﬁxWith

The object key preﬁx to use in the redirect request. For example, to redirect requests for all pages
with preﬁx docs/ (objects in the docs/ folder) to documents/, you can set a condition block
with KeyPrefixEquals set to docs/ and in the Redirect set ReplaceKeyPrefixWith to /
documents. Not required if one of the siblings is present. Can be present only if ReplaceKeyWith
is not provided.

Type: String

Required: No
ReplaceKeyWith

The speciﬁc object key to use in the redirect request. For example, redirect request to error.html.
Not required if one of the siblings is present. Can be present only if ReplaceKeyPrefixWith is not
provided.

Type: String

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

API Version 2006-03-01

525
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for Go

• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

526
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

RedirectAllRequestsTo
Service: Amazon Simple Storage Service

Speciﬁes the redirect behavior of all requests to a website endpoint of an Amazon S3 bucket.

Contents
HostName

Name of the host where requests are redirected.

Type: String

Required: Yes
Protocol

Protocol to use when redirecting requests. The default is the protocol that is used in the original
request.

Type: String

Valid Values: http | https

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

527
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ReplicationConﬁguration
Service: Amazon Simple Storage Service

A container for replication rules. You can add up to 1,000 rules. The maximum size of a replication
conﬁguration is 2 MB.

Contents
Role

Type: String

Required: Yes
Rules

A container for one or more replication rules. A replication conﬁguration must have at least one rule
and can contain a maximum of 1,000 rules.

Type: Array of ReplicationRule (p. 529) data types

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

528
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ReplicationRule
Service: Amazon Simple Storage Service

Speciﬁes which Amazon S3 objects to replicate and where to store the replicas.

Contents
DeleteMarkerReplication

Specifies whether Amazon S3 replicates the delete markers. If you specify a Filter,
you must specify this element. However, in the latest version of replication configuration
(when Filter is specified), Amazon S3 doesn't replicate delete markers. Therefore, the
DeleteMarkerReplication element can contain only <Status>Disabled</Status>. For an example
configuration, see Basic Rule Configuration.
Note
If you don't specify the Filter element, Amazon S3 assumes that the replication
configuration is the earlier version, V1. In the earlier version, Amazon S3 handled replication
of delete markers differently. For more information, see Backward Compatibility.

Type: DeleteMarkerReplication (p. 446) data type

Required: No
Destination

A container for information about the replication destination and its conﬁgurations including
enabling the S3 Replication Time Control (S3 RTC).

Type: Destination (p. 447) data type

Required: Yes
ExistingObjectReplication

Type: ExistingObjectReplication (p. 463) data type

Required: No
Filter

A ﬁlter that identiﬁes the subset of objects to which the replication rule applies. A Filter must
specify exactly one Prefix, Tag, or an And child element.

Type: ReplicationRuleFilter (p. 532) data type

Required: No
ID

A unique identiﬁer for the rule. The maximum value is 255 characters.

Type: String

Required: No
Preﬁx

This member has been deprecated.

An object key name prefix that identifies the object or objects to which the rule applies. The
maximum prefix length is 1,024 characters. To include all objects in a bucket, specify an empty
string.

API Version 2006-03-01

529
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Type: String

Required: No
Priority

The priority associated with the rule. If you specify multiple rules in a replication configuration,
Amazon S3 prioritizes the rules to prevent conflicts when filtering. If two or more rules identify the
same object based on a specified filter, the rule with higher priority takes precedence. For example:
• Same object quality prefix-based filter criteria if prefixes you specified in multiple rules overlap
• Same object qualify tag-based filter criteria specified in multiple rules

For more information, see Replication in the Amazon Simple Storage Service Developer Guide.

Type: Integer

Required: No
SourceSelectionCriteria

A container that describes additional ﬁlters for identifying the source objects that you want to
replicate. You can choose to enable or disable the replication of these objects. Currently, Amazon S3
supports only the ﬁlter that you can specify for objects created with server-side encryption using a
customer master key (CMK) stored in AWS Key Management Service (SSE-KMS).

Type: SourceSelectionCriteria (p. 551) data type

Required: No
Status

Speciﬁes whether the rule is enabled.

Type: String

Valid Values: Enabled | Disabled

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

530
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ReplicationRuleAndOperator
Service: Amazon Simple Storage Service

A container for specifying rule filters. The filters determine the subset of objects to which the rule
applies. This element is required only if you specify more than one filter.

For example:

• If you specify both a Prefix and a Tag filter, wrap these filters in an And tag.
• If you specify a filter based on multiple tags, wrap the Tag elements in an And tag

Contents
Preﬁx

An object key name preﬁx that identiﬁes the subset of objects to which the rule applies.

Type: String

Required: No
Tags

An array of tags containing key and value pairs.

Type: Array of Tag (p. 559) data types

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

531
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ReplicationRuleFilter
Service: Amazon Simple Storage Service

A ﬁlter that identiﬁes the subset of objects to which the replication rule applies. A Filter must specify
exactly one Prefix, Tag, or an And child element.

Contents
And

A container for specifying rule filters. The filters determine the subset of objects to which the rule
applies. This element is required only if you specify more than one filter. For example:
• If you specify both a Prefix and a Tag filter, wrap these filters in an And tag.
• If you specify a filter based on multiple tags, wrap the Tag elements in an And tag.

Type: ReplicationRuleAndOperator (p. 531) data type

Required: No
Preﬁx

An object key name preﬁx that identiﬁes the subset of objects to which the rule applies.

Type: String

Required: No
Tag

A container for specifying a tag key and value.

The rule applies only to objects that have the tag in their tag set.

Type: Tag (p. 559) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

532
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ReplicationTime
Service: Amazon Simple Storage Service

A container specifying S3 Replication Time Control (S3 RTC) related information, including whether S3
RTC is enabled and the time when all objects and operations on objects must be replicated. Must be
speciﬁed together with a Metrics block.

Contents
Status

Speciﬁes whether the replication time is enabled.

Type: String

Valid Values: Enabled | Disabled

Required: Yes
Time

A container specifying the time by which replication should be complete for all objects and
operations on objects.

Type: ReplicationTimeValue (p. 534) data type

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

533
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ReplicationTimeValue
Service: Amazon Simple Storage Service

A container specifying the time value for S3 Replication Time Control (S3 RTC) and replication metrics
EventThreshold.

Contents
Minutes

Contains an integer specifying time in minutes.

Valid values: 15 minutes.

Type: Integer

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

534
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

RequestPaymentConﬁguration
Service: Amazon Simple Storage Service

Container for Payer.

Contents
Payer

Speciﬁes who pays for the download and request fees.

Type: String

Valid Values: Requester | BucketOwner

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

535
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

RequestProgress
Service: Amazon Simple Storage Service

Container for specifying if periodic QueryProgress messages should be sent.

Contents
Enabled

Speciﬁes whether periodic QueryProgress frames should be sent. Valid values: TRUE, FALSE. Default
value: FALSE.

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

536
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

RestoreRequest
Service: Amazon Simple Storage Service

Container for restore job parameters.

Contents
Days

Lifetime of the active copy in days. Do not use with restores that specify OutputLocation.

Type: Integer

Required: No
Description

The optional description for the job.

Type: String

Required: No
GlacierJobParameters

Glacier related parameters pertaining to this job. Do not use with restores that specify
OutputLocation.

Type: GlacierJobParameters (p. 465) data type

Required: No
OutputLocation

Describes the location where the restore job's output is stored.

Type: OutputLocation (p. 510) data type

Required: No
SelectParameters

Describes the parameters for Select job types.

Type: SelectParameters (p. 547) data type

Required: No
Tier

Glacier retrieval tier at which the restore will be processed.

Type: String

Valid Values: Standard | Bulk | Expedited

Required: No
Type

Type of restore request.

Type: String

Valid Values: SELECT

API Version 2006-03-01

537
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

538
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

RoutingRule
Service: Amazon Simple Storage Service

Speciﬁes the redirect behavior and when a redirect is applied.

Contents
Condition

A container for describing a condition that must be met for the speciﬁed redirect to apply. For
example, 1. If request is for pages in the /docs folder, redirect to the /documents folder. 2. If
request results in HTTP error 4xx, redirect request to another host where you might process the
error.

Type: Condition (p. 431) data type

Required: No
Redirect

Container for redirect information. You can redirect requests to another host, to another page, or
with another protocol. In the event of an error, you can specify a diﬀerent error code to return.

Type: Redirect (p. 525) data type

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

539
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Rule
Service: Amazon Simple Storage Service

Specifies lifecycle rules for an Amazon S3 bucket. For more information, see Put Bucket Lifecycle
Configuration in the Amazon Simple Storage Service API Reference. For examples, see Put Bucket Lifecycle
Configuration Examples

Contents
AbortIncompleteMultipartUpload

Speciﬁes the days since the initiation of an incomplete multipart upload that Amazon S3 will
wait before permanently removing all parts of the upload. For more information, see Aborting
Incomplete Multipart Uploads Using a Bucket Lifecycle Policy in the Amazon Simple Storage Service
Developer Guide.

Type: AbortIncompleteMultipartUpload (p. 414) data type

Required: No
Expiration

Speciﬁes the expiration for the lifecycle of the object.

Type: LifecycleExpiration (p. 483) data type

Required: No
ID

Unique identiﬁer for the rule. The value can't be longer than 255 characters.

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

541
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

S3KeyFilter
Service: Amazon Simple Storage Service

A container for object key name prefix and suffix filtering rules.

Contents
FilterRules

A list of containers for the key-value pair that deﬁnes the criteria for the ﬁlter rule.

Type: Array of FilterRule (p. 464) data types

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

542
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

S3Location
Service: Amazon Simple Storage Service

Describes an Amazon S3 location that will receive the results of the restore request.

Contents
AccessControlList

A list of grants that control access to the staged results.

Type: Array of Grant (p. 466) data types

Required: No
BucketName

The name of the bucket where the restore results will be placed.

Type: String

Required: Yes
CannedACL

The canned ACL to apply to the restore results.

Type: String

Valid Values: private | public-read | public-read-write | authenticated-read |

aws-exec-read | bucket-owner-read | bucket-owner-full-control

Required: No
Encryption

Contains the type of server-side encryption used.

Type: Encryption (p. 449) data type

Required: No
Preﬁx

The preﬁx that is prepended to the restore results for this request.

Type: String

Required: Yes
StorageClass

The class of storage used to store the restore results.

Type: String

Valid Values: STANDARD | REDUCED_REDUNDANCY | STANDARD_IA | ONEZONE_IA |

INTELLIGENT_TIERING | GLACIER | DEEP_ARCHIVE

Required: No
Tagging

The tag-set that is applied to the restore results.

API Version 2006-03-01

543
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Type: Tagging (p. 560) data type

Required: No
UserMetadata

A list of metadata to store with the restore results in S3.

Type: Array of MetadataEntry (p. 489) data types

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

544
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ScanRange
Service: Amazon Simple Storage Service

Specifies the byte range of the object to get the records from. A record is processed when its first byte
is contained by the range. This parameter is optional, but when specified, it must not be empty. See RFC
2616, Section 14.35.1 about how to specify the start and end of the range.

Contents
End

Speciﬁes the end of the byte range. This parameter is optional. Valid values: non-negative
integers. The default value is one less than the size of the object being queried. If only the End
parameter is supplied, it is interpreted to mean scan the last N bytes of the ﬁle. For example,
<scanrange><end>50</end></scanrange> means scan the last 50 bytes.

Type: Long

Required: No
Start

Specifies the start of the byte range. This parameter is optional. Valid values: non-negative integers.
The default value is 0. If only start is supplied, it means scan from that point to the end of the
file.For example; <scanrange><start>50</start></scanrange> means scan from byte 50
until the end of the file.

Type: Long

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

545
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

SelectObjectContentEventStream
Service: Amazon Simple Storage Service

The container for selecting objects from a content event stream.

Contents
Cont

The Continuation Event.

Type: ContinuationEvent (p. 432) data type

Required: No
End

The End Event.

Type: EndEvent (p. 451) data type

Required: No
Progress

The Progress Event.

Type: ProgressEvent (p. 517) data type

Required: No
Records

The Records Event.

Type: RecordsEvent (p. 524) data type

Required: No
Stats

The Stats Event.

Type: StatsEvent (p. 556) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

546
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

SelectParameters
Service: Amazon Simple Storage Service

Describes the parameters for Select job types.

Contents
Expression

The expression that is used to query the object.

Type: String

Required: Yes
ExpressionType

The type of the provided expression (for example, SQL).

Type: String

Valid Values: SQL

Required: Yes
InputSerialization

Describes the serialization format of the object.

Type: InputSerialization (p. 470) data type

Required: Yes
OutputSerialization

Describes how the results of the Select job are serialized.

Type: OutputSerialization (p. 511) data type

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

547
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

ServerSideEncryptionByDefault
Service: Amazon Simple Storage Service

Describes the default server-side encryption to apply to new objects in the bucket. If a PUT Object
request doesn't specify any server-side encryption, this default encryption will be applied. For more
information, see PUT Bucket encryption in the Amazon Simple Storage Service API Reference.

Contents
KMSMasterKeyID

AWS Key Management Service (KMS) customer master key ID to use for the default encryption. This
parameter is allowed if and only if SSEAlgorithm is set to aws:kms.

You can specify the key ID or the Amazon Resource Name (ARN) of the CMK.

For example:
• Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab
• Key ARN: arn:aws:kms:us-
east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
Important
Amazon S3 only supports symmetric CMKs and not asymmetric CMKs. For more
information, see Using Symmetric and Asymmetric Keys in the AWS Key Management Service
Developer Guide.

Type: String

Required: No
SSEAlgorithm

Server-side encryption algorithm to use for the default encryption.

Speciﬁes the ID of the AWS Key Management Service (AWS KMS) symmetric customer managed
customer master key (CMK) to use for encrypting inventory reports.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

552
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

SseKmsEncryptedObjects
Service: Amazon Simple Storage Service

A container for ﬁlter information for the selection of S3 objects encrypted with AWS KMS.

Contents
Status

Speciﬁes whether Amazon S3 replicates objects created with server-side encryption using a
customer master key (CMK) stored in AWS Key Management Service.

Type: String

Valid Values: Enabled | Disabled

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

555
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

StatsEvent
Service: Amazon Simple Storage Service

Container for the Stats Event.

Contents
Details

The Stats event details.

Type: Stats (p. 555) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

556
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

StorageClassAnalysis
Service: Amazon Simple Storage Service

Specifies data related to access patterns to be collected and made available to analyze the tradeoffs
between different storage classes for an Amazon S3 bucket.

Contents
DataExport

Speciﬁes how data related to the storage class analysis for an Amazon S3 bucket should be
exported.

Type: StorageClassAnalysisDataExport (p. 558) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

557
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

StorageClassAnalysisDataExport
Service: Amazon Simple Storage Service

Container for data related to the storage class analysis for an Amazon S3 bucket for export.

Contents
Destination

The place to store the data for an analysis.

Type: AnalyticsExportDestination (p. 420) data type

Required: Yes
OutputSchemaVersion

The version of the output schema to use when exporting data. Must be V_1.

Type: String

Valid Values: V_1

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

558
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Tag
Service: Amazon Simple Storage Service

A container of a key value name pair.

Contents
Key

Name of the tag.

Type: String

Length Constraints: Minimum length of 1.

Required: Yes
Value

Value of the tag.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

559
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Tagging
Service: Amazon Simple Storage Service

Container for TagSet elements.

Contents
TagSet

A collection for a set of tags

Type: Array of Tag (p. 559) data types

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

560
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

TargetGrant
Service: Amazon Simple Storage Service

Container for granting information.

Contents
Grantee

Container for the person being granted permissions.

Type: Grantee (p. 467) data type

Required: No
Permission

Logging permissions assigned to the Grantee for the bucket.

Type: String

Valid Values: FULL_CONTROL | READ | WRITE

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

561
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

TopicConﬁguration
Service: Amazon Simple Storage Service

A container for specifying the configuration for publication of messages to an Amazon Simple
Notification Service (Amazon SNS) topic when Amazon S3 detects specified events.

Contents
Events

The Amazon S3 bucket event about which to send notiﬁcations. For more information, see
Supported Event Types in the Amazon Simple Storage Service Developer Guide.

Type: Array of strings

Valid Values: s3:ReducedRedundancyLostObject | s3:ObjectCreated:* |

Required: Yes
Filter

Specifies object key name filtering rules. For information about key name filtering, see Configuring
Event Notifications in the Amazon Simple Storage Service Developer Guide.

Type: NotiﬁcationConﬁgurationFilter (p. 500) data type

Required: No
Id

An optional unique identifier for configurations in a notification configuration. If you don't provide
one, Amazon S3 will assign an ID.

Type: String

Required: No
TopicArn

The Amazon Resource Name (ARN) of the Amazon SNS topic to which Amazon S3 publishes a
message when it detects events of the speciﬁed type.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java

API Version 2006-03-01

562
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

• AWS SDK for Ruby V2

API Version 2006-03-01

563
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

TopicConﬁgurationDeprecated
Service: Amazon Simple Storage Service

A container for specifying the configuration for publication of messages to an Amazon Simple
Notification Service (Amazon SNS) topic when Amazon S3 detects specified events. This data type is
deprecated. Use TopicConfiguration (p. 562) instead.

Contents
Event

This member has been deprecated.

Bucket event for which to send notiﬁcations.

Type: String

Valid Values: s3:ReducedRedundancyLostObject | s3:ObjectCreated:* |

Required: No
Events

A collection of events related to objects

Type: Array of strings

Valid Values: s3:ReducedRedundancyLostObject | s3:ObjectCreated:* |

Required: No
Id

An optional unique identifier for configurations in a notification configuration. If you don't provide
one, Amazon S3 will assign an ID.

Type: String

Required: No
Topic

Amazon SNS topic to which Amazon S3 will publish a message to report the speciﬁed events for the
bucket.

Type: String

Required: No

API Version 2006-03-01

564
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

565
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

Transition
Service: Amazon Simple Storage Service

Specifies when an object transitions to a specified storage class. For more information about Amazon S3
lifecycle configuration rules, see Transitioning Objects Using Amazon S3 Lifecycle in the Amazon Simple
Storage Service Developer Guide.

Contents
Date

Indicates when objects are transitioned to the speciﬁed storage class. The date value must be in ISO
8601 format. The time is always midnight UTC.

Type: Timestamp

Required: No
Days

Indicates the number of days after creation when objects are transitioned to the speciﬁed storage
class. The value must be a positive integer.

Type: Integer

Required: No
StorageClass

The storage class to which you want the object to transition.

Type: String

Valid Values: GLACIER | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING |

DEEP_ARCHIVE

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

566
Amazon Simple Storage Service API Reference
Amazon Simple Storage Service

VersioningConﬁguration
Service: Amazon Simple Storage Service

Describes the versioning state of an Amazon S3 bucket. For more information, see PUT Bucket versioning
in the Amazon Simple Storage Service API Reference.

Contents
MFADelete

Type: String

Valid Values: Enabled | Disabled

Required: No
Status

The versioning state of the bucket.

Type: String

Valid Values: Enabled | Suspended

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

567
Amazon Simple Storage Service API Reference
AWS S3 Control

WebsiteConﬁguration
Service: Amazon Simple Storage Service

Speciﬁes website conﬁguration parameters for an Amazon S3 bucket.

Contents
ErrorDocument

The name of the error document for the website.

Type: ErrorDocument (p. 462) data type

Required: No
IndexDocument

The name of the index document for the website.

Type: IndexDocument (p. 468) data type

Required: No
RedirectAllRequestsTo

The redirect behavior for every request to this bucket's website endpoint.
Important
If you specify this property, you can't specify any other property.

Type: RedirectAllRequestsTo (p. 527) data type

Required: No
RoutingRules

Rules that deﬁne when a redirect is applied and the redirect behavior.

Type: Array of RoutingRule (p. 539) data types

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

AWS S3 Control
The following data types are supported by AWS S3 Control:

• AccessPoint (p. 570)

• JobDescriptor (p. 571)
• JobFailure (p. 574)

API Version 2006-03-01

568
Amazon Simple Storage Service API Reference
AWS S3 Control

• JobListDescriptor (p. 575)

• JobManifest (p. 577)
• JobManifestLocation (p. 578)
• JobManifestSpec (p. 579)
• JobOperation (p. 580)
• JobProgressSummary (p. 581)
• JobReport (p. 582)
• LambdaInvokeOperation (p. 584)
• PolicyStatus (p. 585)
• PublicAccessBlockConﬁguration (p. 586)
• S3AccessControlList (p. 588)
• S3AccessControlPolicy (p. 589)
• S3CopyObjectOperation (p. 590)
• S3Grant (p. 593)
• S3Grantee (p. 594)
• S3InitiateRestoreObjectOperation (p. 595)
• S3ObjectMetadata (p. 596)
• S3ObjectOwner (p. 598)
• S3SetObjectAclOperation (p. 599)
• S3SetObjectTaggingOperation (p. 600)
• S3Tag (p. 601)
• VpcConﬁguration (p. 602)

API Version 2006-03-01

569
Amazon Simple Storage Service API Reference
AWS S3 Control

Valid Values: Internet | VPC

Required: Yes
VpcConﬁguration

The Virtual Private Cloud (VPC) conﬁguration for this access point, if one exists.

Type: VpcConﬁguration (p. 602) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

570
Amazon Simple Storage Service API Reference
AWS S3 Control

JobDescriptor
Service: AWS S3 Control

A container element for the job conﬁguration and status information returned by a Describe Job
request.

Contents
ConﬁrmationRequired

Indicates whether confirmation is required before Amazon S3 begins running the specified job.
Confirmation is required only for jobs created through the Amazon S3 console.

Type: Boolean

Required: No
CreationTime

A timestamp indicating when this job was created.

Type: Timestamp

Required: No
Description

The description for this job, if one was provided in this job's Create Job request.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Required: No
FailureReasons

If the speciﬁed job failed, this ﬁeld contains information describing the failure.

Type: Array of JobFailure (p. 574) data types

Required: No
JobArn

The Amazon Resource Name (ARN) for this job.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Required: No
JobId

The ID for the speciﬁed job.

Type: String

Length Constraints: Minimum length of 5. Maximum length of 36.

Required: No
Manifest

The conﬁguration information for the speciﬁed job's manifest object.

API Version 2006-03-01

571
Amazon Simple Storage Service API Reference
AWS S3 Control

Type: JobManifest (p. 577) data type

Required: No
Operation

The operation that the speciﬁed job is conﬁgured to execute on the objects listed in the manifest.

Type: JobOperation (p. 580) data type

Required: No
Priority

The priority of the speciﬁed job.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 2147483647.

Required: No
ProgressSummary

Describes the total number of tasks that the speciﬁed job has executed, the number of tasks that
succeeded, and the number of tasks that failed.

Type: JobProgressSummary (p. 581) data type

Required: No
Report

Contains the conﬁguration information for the job-completion report if you requested one in the
Create Job request.

Type: JobReport (p. 582) data type

Required: No
RoleArn

The Amazon Resource Name (ARN) for the Identity and Access Management (IAM) Role assigned to
execute the tasks for this job.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: No
Status

The current status of the speciﬁed job.

Type: String

Valid Values: Active | Cancelled | Cancelling | Complete | Completing | Failed

Required: No
StatusUpdateReason

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

API Version 2006-03-01

572
Amazon Simple Storage Service API Reference
AWS S3 Control

Required: No
SuspendedCause

The reason why the specified job was suspended. A job is only suspended if you create it through the
Amazon S3 console. When you create the job, it enters the Suspended state to await confirmation
before running. After you confirm the job, it automatically exits the Suspended state.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Required: No
SuspendedDate

The timestamp when this job was suspended, if it has been suspended.

Type: Timestamp

Required: No
TerminationDate

A timestamp indicating when this job terminated. A job's termination date is the date and time when
it succeeded, failed, or was canceled.

Type: Timestamp

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

573
Amazon Simple Storage Service API Reference
AWS S3 Control

JobFailure
Service: AWS S3 Control

If this job failed, this element indicates why the job failed.

Contents
FailureCode

The failure code, if any, for the speciﬁed job.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Required: No
FailureReason

The failure reason, if any, for the speciﬁed job.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

574
Amazon Simple Storage Service API Reference
AWS S3 Control

JobListDescriptor
Service: AWS S3 Control

Contains the conﬁguration and status information for a single job retrieved as part of a job list.

Contents
CreationTime

A timestamp indicating when the speciﬁed job was created.

Type: Timestamp

Required: No
Description

The user-speciﬁed description that was included in the speciﬁed job's Create Job request.

The current priority for the speciﬁed job.

Type: Integer

Valid Range: Minimum value of 0. Maximum value of 2147483647.

Required: No
ProgressSummary

Describes the total number of tasks that the speciﬁed job has executed, the number of tasks that
succeeded, and the number of tasks that failed.

Type: JobProgressSummary (p. 581) data type

Required: No

API Version 2006-03-01

575
Amazon Simple Storage Service API Reference
AWS S3 Control

Status

The speciﬁed job's current status.

Type: String

Valid Values: Active | Cancelled | Cancelling | Complete | Completing | Failed

Required: No
TerminationDate

A timestamp indicating when the speciﬁed job terminated. A job's termination date is the date and
time when it succeeded, failed, or was canceled.

Type: Timestamp

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

576
Amazon Simple Storage Service API Reference
AWS S3 Control

JobManifest
Service: AWS S3 Control

Contains the conﬁguration information for a job's manifest.

Contents
Location

Contains the information required to locate the speciﬁed job's manifest.

Type: JobManifestLocation (p. 578) data type

Required: Yes
Spec

Describes the format of the speciﬁed job's manifest. If the manifest is in CSV format, also describes
the columns contained within the manifest.

Type: JobManifestSpec (p. 579) data type

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

577
Amazon Simple Storage Service API Reference
AWS S3 Control

JobManifestLocation
Service: AWS S3 Control

Contains the information required to locate a manifest object.

Contents
ETag

The ETag for the speciﬁed manifest object.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Required: Yes
ObjectArn

The Amazon Resource Name (ARN) for a manifest object.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2000.

Required: Yes
ObjectVersionId

The optional version ID to identify a speciﬁc version of the manifest object.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2000.

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

578
Amazon Simple Storage Service API Reference
AWS S3 Control

JobManifestSpec
Service: AWS S3 Control

Describes the format of a manifest. If the manifest is in CSV format, also describes the columns
contained within the manifest.

Contents
Fields

If the speciﬁed manifest object is in the S3BatchOperations_CSV_20180820 format, this element

describes which columns contain the required data.

Type: Array of strings

Valid Values: Ignore | Bucket | Key | VersionId

Required: No
Format

Indicates which of the available formats the speciﬁed manifest uses.

Type: String

Valid Values: S3BatchOperations_CSV_20180820 | S3InventoryReport_CSV_20161130

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

579
Amazon Simple Storage Service API Reference
AWS S3 Control

JobOperation
Service: AWS S3 Control

Contents
LambdaInvoke

Directs the speciﬁed job to invoke an AWS Lambda function on each object in the manifest.

Type: LambdaInvokeOperation (p. 584) data type

Required: No
S3InitiateRestoreObject

Directs the speciﬁed job to execute an Initiate Glacier Restore call on each object in the manifest.

Type: S3InitiateRestoreObjectOperation (p. 595) data type

Required: No
S3PutObjectAcl

Directs the speciﬁed job to execute a PUT Object acl call on each object in the manifest.

Type: S3SetObjectAclOperation (p. 599) data type

Required: No
S3PutObjectCopy

Directs the speciﬁed job to execute a PUT Copy object call on each object in the manifest.

Type: S3CopyObjectOperation (p. 590) data type

Required: No
S3PutObjectTagging

Directs the speciﬁed job to execute a PUT Object tagging call on each object in the manifest.

Type: S3SetObjectTaggingOperation (p. 600) data type

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

580
Amazon Simple Storage Service API Reference
AWS S3 Control

JobProgressSummary
Service: AWS S3 Control

Describes the total number of tasks that the speciﬁed job has executed, the number of tasks that
succeeded, and the number of tasks that failed.

Contents
NumberOfTasksFailed

Type: Long

Valid Range: Minimum value of 0.

Required: No
NumberOfTasksSucceeded

Type: Long

Valid Range: Minimum value of 0.

Required: No
TotalNumberOfTasks

Type: Long

Valid Range: Minimum value of 0.

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

581
Amazon Simple Storage Service API Reference
AWS S3 Control

JobReport
Service: AWS S3 Control

Contains the conﬁguration parameters for a job-completion report.

Contents
Bucket

The Amazon Resource Name (ARN) for the bucket where speciﬁed job-completion report will be
stored.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Required: No
Enabled

Indicates whether the speciﬁed job will generate a job-completion report.

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

Type: Boolean

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

585
Amazon Simple Storage Service API Reference
AWS S3 Control

PublicAccessBlockConﬁguration
Service: AWS S3 Control

The PublicAccessBlock conﬁguration that you want to apply to this Amazon S3 bucket. You can
enable the conﬁguration options in any combination. For more information about when Amazon S3
considers a bucket or object public, see The Meaning of "Public" in the Amazon Simple Storage Service
Developer Guide.

Contents
BlockPublicAcls

Enabling this setting doesn't aﬀect existing policies or ACLs.

Type: Boolean

Required: No
BlockPublicPolicy

Enabling this setting doesn't aﬀect existing bucket policies.

Type: Boolean

Required: No
IgnorePublicAcls

Enabling this setting doesn't aﬀect the persistence of any existing ACLs and doesn't prevent new
public ACLs from being set.

Type: Boolean

Required: No
RestrictPublicBuckets

Type: Boolean

API Version 2006-03-01

586
Amazon Simple Storage Service API Reference
AWS S3 Control

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

587
Amazon Simple Storage Service API Reference
AWS S3 Control

S3AccessControlList
Service: AWS S3 Control

Contents
Grants

Type: Array of S3Grant (p. 593) data types

Required: No
Owner

Type: S3ObjectOwner (p. 598) data type

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

588
Amazon Simple Storage Service API Reference
AWS S3 Control

S3AccessControlPolicy
Service: AWS S3 Control

Contents
AccessControlList

Type: S3AccessControlList (p. 588) data type

Required: No
CannedAccessControlList

Type: String

Valid Values: private | public-read | public-read-write | aws-exec-read |

authenticated-read | bucket-owner-read | bucket-owner-full-control

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

589
Amazon Simple Storage Service API Reference
AWS S3 Control

S3CopyObjectOperation
Service: AWS S3 Control

Contains the conﬁguration parameters for a PUT Copy object operation. Amazon S3 batch operations
passes each value through to the underlying PUT Copy object API. For more information about the
parameters for this operation, see PUT Object - Copy.

Contents
AccessControlGrants

Type: Array of S3Grant (p. 593) data types

Required: No
CannedAccessControlList

Type: String

Valid Values: private | public-read | public-read-write | aws-exec-read |

authenticated-read | bucket-owner-read | bucket-owner-full-control

Required: No
MetadataDirective

Type: String

Valid Values: COPY | REPLACE

Length Constraints: Minimum length of 1. Maximum length of 2000.

Required: No
StorageClass

Type: String

Valid Values: STANDARD | STANDARD_IA | ONEZONE_IA | GLACIER |

INTELLIGENT_TIERING | DEEP_ARCHIVE

Required: No
TargetKeyPreﬁx

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Required: No
TargetResource

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Required: No
UnModiﬁedSinceConstraint

Type: Timestamp

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go

API Version 2006-03-01

591
Amazon Simple Storage Service API Reference
AWS S3 Control

• AWS SDK for Java

• AWS SDK for Ruby V2

API Version 2006-03-01

592
Amazon Simple Storage Service API Reference
AWS S3 Control

S3Grant
Service: AWS S3 Control

Contents
Grantee

Type: S3Grantee (p. 594) data type

Required: No
Permission

Required: No
TypeIdentiﬁer

Type: String

Valid Values: id | emailAddress | uri

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

594
Amazon Simple Storage Service API Reference
AWS S3 Control

S3InitiateRestoreObjectOperation
Service: AWS S3 Control

Contains the conﬁguration parameters for an Initiate Glacier Restore job. Amazon S3 batch operations
passes each value through to the underlying POST Object restore API. For more information about the
parameters for this operation, see Restoring Archives.

Contents
ExpirationInDays

Type: Integer

Valid Range: Minimum value of 0.

Required: No
GlacierJobTier

API Version 2006-03-01

596
Amazon Simple Storage Service API Reference
AWS S3 Control

RequesterCharged

Type: Boolean

Required: No
SSEAlgorithm

Type: String

Valid Values: AES256 | KMS

Required: No
UserMetadata

Type: String to string map

Key Length Constraints: Minimum length of 1. Maximum length of 1024.

Value Length Constraints: Maximum length of 1024.

Required: No

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

597
Amazon Simple Storage Service API Reference
AWS S3 Control

S3ObjectOwner
Service: AWS S3 Control

Contents
DisplayName

600
Amazon Simple Storage Service API Reference
AWS S3 Control

S3Tag
Service: AWS S3 Control

Contents
Key

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Required: Yes
Value

Type: String

Length Constraints: Maximum length of 1024.

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

601
Amazon Simple Storage Service API Reference
AWS S3 Control

VpcConﬁguration
Service: AWS S3 Control

The Virtual Private Cloud (VPC) conﬁguration for an access point.

Contents
VpcId

If this field is specified, this access point will only allow connections from the specified VPC ID.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1024.

Required: Yes

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2006-03-01

602
Amazon Simple Storage Service API Reference

Authenticating Requests (AWS

Signature Version 4)
Topics
• Authentication Methods (p. 604)
• Introduction to Signing Requests (p. 604)
• Authenticating Requests: Using the Authorization Header (AWS Signature Version 4) (p. 605)
• Authenticating Requests: Using Query Parameters (AWS Signature Version 4) (p. 625)
• Examples: Signature Calculations in AWS Signature Version 4 (p. 630)
• Authenticating Requests: Browser-Based Uploads Using POST (AWS Signature Version 4) (p. 632)
• Amazon S3 Signature Version 4 Authentication Speciﬁc Policy Keys (p. 634)

Every interaction with Amazon S3 is either authenticated or anonymous. This section explains request
authentication with the AWS Signature Version 4 algorithm.
Note
If you use the AWS SDKs (see Sample Code and Libraries) to send your requests, you don't
need to read this section because the SDK clients authenticate your requests by using access
keys that you provide. Unless you have a good reason not to, you should always use the AWS
SDKs. In Regions that support both signature versions, you can request AWS SDKs to use
speciﬁc signature version. For more information, see Specifying Signature Version in Request
Authentication in the Amazon Simple Storage Service Developer Guide. You need to read this
section only if you are implementing the AWS Signature Version 4 algorithm in your custom
client.

Authentication with AWS Signature Version 4 provides some or all of the following, depending on how
you choose to sign your request:

• Verification of the identity of the requester – Authenticated requests require a signature that you
create by using your access keys (access key ID, secret access key). For information about getting access
keys, see Understanding and Getting Your Security Credentials in the AWS General Reference. If you are
using temporary security credentials, the signature calculations also require a security token. For more
information, see Requesting Temporary Security Credentials in the IAM User Guide.
• In-transit data protection – In order to prevent tampering with a request while it is in transit, you use
some of the request elements to calculate the request signature. Upon receiving the request, Amazon
S3 calculates the signature by using the same request elements. If any request component received by
Amazon S3 does not match the component that was used to calculate the signature, Amazon S3 will
reject the request.
• Protect against reuse of the signed portions of the request – The signed portions (using AWS
Signatures) of requests are valid within 15 minutes of the timestamp in the request. An unauthorized
party who has access to a signed request can modify the unsigned portions of the request without
affecting the request's validity in the 15 minute window. Because of this, we recommend that you
maximize protection by signing request headers and body, making HTTPS requests to Amazon S3,
and by using the s3:x-amz-content-sha256 condition key (see Amazon S3 Signature Version 4
Authentication Specific Policy Keys (p. 634)) in AWS policies to require users to sign Amazon S3
request bodies.

Note
Amazon S3 supports Signature Version 4, a protocol for authenticating inbound API requests to
AWS services, in all AWS regions. At this time, AWS Regions created before January 30, 2014 will

API Version 2006-03-01

603
Amazon Simple Storage Service API Reference
Authentication Methods

continue to support the previous protocol, Signature Version 2. Any new Regions after January
30, 2014 will support only Signature Version 4 and therefore all requests to those Regions must
be made with Signature Version 4. For more information about AWS Signature Version 2, see
Signing and Authenticating REST Requests in the Amazon Simple Storage Service Developer
Guide.

Authentication Methods
You can express authentication information by using one of the following methods:

• HTTP Authorization header – Using the HTTP Authorization header is the most common
method of authenticating an Amazon S3 request. All of the Amazon S3 REST operations (except for
browser-based uploads using POST requests) require this header. For more information about the
Authorization header value, and how to calculate signature and related options, see Authenticating
Requests: Using the Authorization Header (AWS Signature Version 4) (p. 605).
• Query string parameters – You can use a query string to express a request entirely in a URL. In
this case, you use query parameters to provide request information, including the authentication
information. Because the request signature is part of the URL, this type of URL is often referred to as
a presigned URL. You can use presigned URLs to embed clickable links, which can be valid for up to
seven days, in HTML. For more information, see Authenticating Requests: Using Query Parameters
(AWS Signature Version 4) (p. 625).

Amazon S3 also supports browser-based uploads that use HTTP POST requests. With an HTTP POST
request, you can upload content to Amazon S3 directly from the browser. For information about
authenticating POST requests, see Browser-Based Uploads Using POST in the Amazon Simple Storage
Service Developer Guide.

Introduction to Signing Requests

Authentication information that you send in a request must include a signature. To calculate a signature,
you ﬁrst concatenate select request elements to form a string, referred to as the string to sign. You then
use a signing key to calculate the hash-based message authentication code (HMAC) of the string to sign.

In AWS Signature Version 4, you don't use your secret access key to sign the request. Instead, you ﬁrst
use your secret access key to create a signing key. The signing key is scoped to a speciﬁc Region and
service, and it never expires.

The following diagram illustrates the general process of computing a signature.

The string to sign depends on the request type. For example, when you use the HTTP Authorization
header or the query parameters for authentication, you use a varying combination of request elements
to create the string to sign. For an HTTP POST request, the POST policy in the request is the string you

API Version 2006-03-01

604
Amazon Simple Storage Service API Reference
Using an Authorization Header

sign. For more information about computing string to sign, follow links provided at the end of this
section.

For signing key, the diagram shows series of calculations, where result of each step you feed into the
next step. The ﬁnal step is the signing key.

Upon receiving an authenticated request, Amazon S3 servers re-create the signature by using the
authentication information that is contained in the request. If the signatures match, Amazon S3
processes your request; otherwise, the request is rejected.

For more information about authenticating requests, see the following topics:

• Authenticating Requests: Using the Authorization Header (AWS Signature Version 4) (p. 605)
• Authenticating Requests: Using Query Parameters (AWS Signature Version 4) (p. 625)
• Authenticating Requests in Browser-Based Uploads Using POST (AWS Signature Version 4) (p. 638)

Authenticating Requests: Using the Authorization

Header (AWS Signature Version 4)
Topics
• Overview (p. 605)
• Signature Calculations for the Authorization Header: Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p. 607)
• Signature Calculations for the Authorization Header: Transferring Payload in Multiple Chunks
(Chunked Upload) (AWS Signature Version 4) (p. 618)

Overview
Using the HTTP Authorization header is the most common method of providing authentication
information. Except for POST requests (p. 639) and requests that are signed by using query parameters,
all Amazon S3 operations use the Authorization request header to provide authentication
information.

The following is an example of the Authorization header value. Line breaks are added to this example
for readability:

Authorization: AWS4-HMAC-SHA256
Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/aws4_request,
SignedHeaders=host;range;x-amz-date,
Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024

The following table describes the various components of the Authorization header value in the
preceding example:

Component Description

AWS4-HMAC-SHA256 The algorithm that was used to calculate the signature. You must
provide this value when you use AWS Signature Version 4 for
authentication.

The string speciﬁes AWS Signature Version 4 (AWS4) and the

signing algorithm (HMAC-SHA256).

API Version 2006-03-01

605
Amazon Simple Storage Service API Reference
Overview

Component Description

Credential Your access key ID and the scope information, which includes the
date, Region, and service that were used to calculate the signature.

This string has the following form:

<your-access-key-id>/<date>/<aws-region>/<aws-service>/
aws4_request

Where:

• <date> value is speciﬁed using YYYYMMDD format.

• <aws-service> value is s3 when sending request to Amazon
S3.

SignedHeaders A semicolon-separated list of request headers that you used to

compute Signature. The list includes header names only, and the
header names must be in lowercase. For example:

host;range;x-amz-date

Signature The 256-bit signature expressed as 64 lowercase hexadecimal

characters. For example:

fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024

Note that the signature calculations vary depending on the option

you choose to transfer the payload.

The signature calculations vary depending on the method you choose to transfer the request payload. S3
supports the following options:

• Transfer payload in a single chunk – In this case, you have the following signature calculation options:
• Signed payload option – You can optionally compute the entire payload checksum and include it in
signature calculation. This provides added security but you need to read your payload twice or buﬀer
it in memory.

For example, in order to upload a file, you need to read the file first to compute a payload hash for
signature calculation and again for transmission when you create the request. For smaller payloads,
this approach might be preferable. However, for large files, reading the file twice can be inefficient,
so you might want to upload data in chunks instead.

We recommend you include payload checksum for added security.

• Unsigned payload option – Do not include payload checksum in signature calculation.

For step-by-step instructions to calculate signature and construct the Authorization header value, see
Signature Calculations for the Authorization Header: Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p. 607).
• Transfer payload in multiple chunks (chunked upload) – In this case you transfer payload in chunks.
You can transfer a payload in chunks regardless of the payload size.

API Version 2006-03-01

606
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in a Single Chunk

the signature for the ﬁrst chunk, and each subsequent chunk contains the signature for the chunk
that precedes it. At the end of the upload, you send a ﬁnal chunk with 0 bytes of data that contains
the signature of the last chunk of the payload. For more information, see Signature Calculations for
the Authorization Header: Transferring Payload in Multiple Chunks (Chunked Upload) (AWS Signature
Version 4) (p. 618).

When you send a request, you must tell Amazon S3 which of the preceding options you have chosen in
your signature calculation, by adding the x-amz-content-sha256 header with one of the following
values:

• If you choose chunked upload options, set the header value to STREAMING-AWS4-HMAC-SHA256-
PAYLOAD.
• If you choose to upload payload in a single chunk, set the header value to the payload checksum
(signed payload option), or set the value to the literal string UNSIGNED-PAYLOAD (unsigned payload
option).

Upon receiving the request, Amazon S3 re-creates the string to sign using information in the
Authorization header and the date header. It then veriﬁes with authentication service the signatures
match. The request date can be speciﬁed by using either the HTTP Date or the x-amz-date header. If
both headers are present, x-amz-date takes precedence.

If the signatures match, Amazon S3 processes your request; otherwise, your request will fail.

For more information, see the following topics:

Signature Calculations for the Authorization Header: Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p. 607)

Signature Calculations for the Authorization Header: Transferring Payload in Multiple Chunks (Chunked
Upload) (AWS Signature Version 4) (p. 618)

Signature Calculations for the Authorization Header:

Transferring Payload in a Single Chunk (AWS
Signature Version 4)
When using the Authorization header to authenticate requests, the header value includes, among
other things, a signature. The signature calculations vary depending on the choice you make for
transferring the payload (Overview (p. 605)). This section explains signature calculations when
you choose to transfer the payload in a single chunk. The example section (see Examples: Signature
Calculations (p. 612)) shows signature calculations and resulting Authorization headers that you can
use as a test suite to verify your code.
Important
When transferring payload in a single chunk, you can optionally choose to include the payload
hash in the signature calculations, referred as signed payload (if you don't include it, the payload
is considered unsigned). The signing procedure discussed in the following section applies to
both, but note the following diﬀerences:

• Signed payload option – You include the payload hash when constructing the canonical
request (that then becomes part of StringToSign, as explained in the signature calculation
section). You also specify the same value as the x-amz-content-sha256 header value when
sending the request to S3.
• Unsigned payload option – You include the literal string UNSIGNED-PAYLOAD when
constructing a canonical request, and set the same value as the x-amz-content-sha256
header value when sending the request to Amazon S3.

API Version 2006-03-01

607
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in a Single Chunk

When you send your request to Amazon S3, the x-amz-content-sha256 header value
informs Amazon S3 whether the payload is signed or not. Amazon S3 can then create signature
accordingly for veriﬁcation.

Calculating a Signature
To calculate a signature, you ﬁrst need a string to sign. You then calculate a HMAC-SHA256 hash of the
string to sign by using a signing key. The following diagram illustrates the process, including the various
components of the string that you create for signing

When Amazon S3 receives an authenticated request, it computes the signature and then compares it
with the signature that you provided in the request. For that reason, you must compute the signature by
using the same method that is used by Amazon S3. The process of putting a request in an agreed-upon
form for signing is called canonicalization.

The following table describes the functions that are shown in the diagram. You need to implement code
for these functions.

Function Description

Lowercase() Convert the string to lowercase.

Hex() Lowercase base 16 encoding.

SHA256Hash() Secure Hash Algorithm (SHA) cryptographic hash function.

HMAC-SHA256() Computes HMAC by using the SHA256 algorithm with the signing
key provided. This is the ﬁnal signature.

Trim() Remove any leading or trailing whitespace.

UriEncode() URI encode every byte. UriEncode() must enforce the following
rules:

API Version 2006-03-01

608
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in a Single Chunk

Function Description
• URI encode every byte except the unreserved characters: 'A'-'Z',
'a'-'z', '0'-'9', '-', '.', '_', and '~'.
• The space character is a reserved character and must be encoded
as "%20" (and not as "+").
• Each URI encoded byte is formed by a '%' and the two-digit
hexadecimal value of the byte.
• Letters in the hexadecimal value must be uppercase, for example
"%1A".
• Encode the forward slash character, '/', everywhere except in the
object key name. For example, if the object key name is photos/
Jan/sample.jpg, the forward slash in the key name is not
encoded.

Important
The standard UriEncode functions provided by your
development platform may not work because of
diﬀerences in implementation and related ambiguity
in the underlying RFCs. We recommend that you write
your own custom UriEncode function to ensure that your
encoding will work.

The following is an example UriEncode() function in Java.

public static String UriEncode(CharSequence input, boolean

encodeSlash) {
StringBuilder result = new StringBuilder();
for (int i = 0; i < input.length(); i++) {
char ch = input.charAt(i);
if ((ch >= 'A' && ch <= 'Z') || (ch >= 'a'
&& ch <= 'z') || (ch >= '0' && ch <= '9') || ch == '_' ||
ch == '-' || ch == '~' || ch == '.') {
result.append(ch);
} else if (ch == '/') {
result.append(encodeSlash ? "%2F" : ch);
} else {
result.append(toHexUTF8(ch));
}
}
return result.toString();
}

Task 1: Create a Canonical Request

This section provides an overview of creating a canonical request.

The following is the canonical request format that Amazon S3 uses to calculate a signature. For
signatures to match, you must create a canonical request in this format:

API Version 2006-03-01

609
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in a Single Chunk

Where:

• HTTPMethod is one of the HTTP methods, for example GET, PUT, HEAD, and DELETE.
• CanonicalURI is the URI-encoded version of the absolute path component of the URI—everything
starting with the "/" that follows the domain name and up to the end of the string or to the question
mark character ('?') if you have query string parameters. The URI in the following example, /
examplebucket/myphoto.jpg, is the absolute path and you don't encode the "/" in the absolute
path:

http://s3.amazonaws.com/examplebucket/myphoto.jpg

Note
You do not normalize URI paths for requests to Amazon S3. For example, you may have a
bucket with an object named "my-object//example//photo.user". Normalizing the path
changes the object name in the request to "my-object/example/photo.user". This is an
incorrect path for that object.
• CanonicalQueryString speciﬁes the URI-encoded query string parameters. You URI-encode name
and values individually. You must also sort the parameters in the canonical query string alphabetically
by key name. The sorting occurs after encoding. The query string in the following URI example is
prefix=somePrefix&marker=someMarker&max-keys=20:

http://s3.amazonaws.com/examplebucket?prefix=somePrefix&marker=someMarker&max-keys=20

The canonical query string is as follows (line breaks are added to this example for readability):

UriEncode("marker")+"="+UriEncode("someMarker")+"&"+
UriEncode("max-keys")+"="+UriEncode("20") + "&" +
UriEncode("prefix")+"="+UriEncode("somePrefix")

When a request targets a subresource, the corresponding query parameter value will be an empty
string (""). For example, the following URI identiﬁes the ACL subresource on the examplebucket
bucket:

http://s3.amazonaws.com/examplebucket?acl

The CanonicalQueryString in this case is as follows:

UriEncode("acl") + "=" + ""

If the URI does not include a '?', there is no query string in the request, and you set the canonical query
string to an empty string (""). You will still need to include the "\n".
• CanonicalHeaders is a list of request headers with their values. Individual header name and value
pairs are separated by the newline character ("\n"). Header names must be in lowercase. You must sort
the header names alphabetically to construct the string, as shown in the following example:

Lowercase(<HeaderName1>)+":"+Trim(<value>)+"\n"
Lowercase(<HeaderName2>)+":"+Trim(<value>)+"\n"
...
Lowercase(<HeaderNameN>)+":"+Trim(<value>)+"\n"

The Lowercase() and Trim() functions used in this example are described in the preceding section.

The CanonicalHeaders list must include the following:

API Version 2006-03-01
610
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in a Single Chunk

• HTTP host header.

• If the Content-Type header is present in the request, you must add it to the CanonicalHeaders
list.
• Any x-amz-* headers that you plan to include in your request must also be added. For example, if
you are using temporary security credentials, you need to include x-amz-security-token in your
request. You must add this header in the list of CanonicalHeaders.
Note
The x-amz-content-sha256 header is required for all AWS Signature Version 4 requests. It
provides a hash of the request payload. If there is no payload, you must provide the hash of
an empty string.

The following is an example CanonicalHeaders string. The header names are in lowercase and
sorted.

host:s3.amazonaws.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b785
2b855
x-amz-date:20130708T220855Z

Note
For the purpose of calculating an authorization signature, only the host and any x-amz-
* headers are required; however, in order to prevent data tampering, you should consider
including all the headers in the signature calculation.
• SignedHeaders is an alphabetically sorted, semicolon-separated list of lowercase request
header names. The request headers in the list are the same headers that you included in the
CanonicalHeaders string. For example, for the previous example, the value of SignedHeaders
would be as follows:

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

• HashedPayload is the hexadecimal value of the SHA256 hash of the request payload.

Hex(SHA256Hash(<payload>)

If there is no payload in the request, you compute a hash of the empty string as follows:

Hex(SHA256Hash(""))

The hash returns the following value:

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

For example, when you upload an object by using a PUT request, you provide object data in the body.
When you retrieve an object by using a GET request, you compute the empty string hash.

Task 2: Create a String to Sign

This section provides an overview of creating a string to sign. For step-by-step instructions, see Task 2:
Create a String to Sign in the AWS General Reference.

The string to sign is a concatenation of the following strings:

"AWS4-HMAC-SHA256" + "\n" +

API Version 2006-03-01

611
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in a Single Chunk

timeStampISO8601Format + "\n" +
<Scope> + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))

The constant string AWS4-HMAC-SHA256 speciﬁes the hash algorithm that you are using,
HMAC-SHA256. The timeStamp is the current UTC time in ISO 8601 format (for example,
20130524T000000Z).

Scope binds the resulting signature to a specific date, an AWS Region, and a service. Thus, your resulting
signature will work only in the specific Region and for a specific service. The signature is valid for seven
days after the specified date.

date.Format(<YYYYMMDD>) + "/" + <region> + "/" + <service> + "/aws4_request"

For Amazon S3, the service string is s3. For a list of region strings, see Regions and Endpoints in the
AWS General Reference. The Region column in this table provides the list of valid Region strings.

The following scope restricts the resulting signature to the us-east-1 Region and Amazon S3.

20130606/us-east-1/s3/aws4_request

Note
Scope must use the same date that you use to compute the signing key, as discussed in the
following section.

Task 3: Calculate Signature

In AWS Signature Version 4, instead of using your AWS access keys to sign a request, you ﬁrst create a
signing key that is scoped to a speciﬁc Region and service. For more information about signing keys, see
Introduction to Signing Requests (p. 604).

DateKey = HMAC-SHA256("AWS4"+"<SecretAccessKey>", "<YYYYMMDD>")

DateRegionKey = HMAC-SHA256(<DateKey>, "<aws-region>")
DateRegionServiceKey = HMAC-SHA256(<DateRegionKey>, "<aws-service>")
SigningKey = HMAC-SHA256(<DateRegionServiceKey>, "aws4_request")

Note
This signing key is valid for seven days from the date speciﬁed in the DateKey hash.

For a list of Region strings, see Regions and Endpoints in the AWS General Reference.

Using a signing key enables you to keep your AWS credentials in one safe place. For example, if you have
multiple servers that communicate with Amazon S3, you share the signing key with those servers; you
don’t have to keep a copy of your secret access key on each server. Signing key is valid for up to seven
days. So each time you calculate signing key you will need to share the signing key with your servers. For
more information, see Authenticating Requests (AWS Signature Version 4) (p. 603).

The ﬁnal signature is the HMAC-SHA256 hash of the string to sign, using the signing key as the key.

HMAC-SHA256(SigningKey, StringToSign)

For step-by-step instructions on creating a signature, see Task 3: Create a Signature in the AWS General
Reference.

Examples: Signature Calculations

You can use the examples in this section as a reference to check signature calculations in your code. For
additional references, see Signature Version 4 Test Suite of the AWS General Reference. The calculations
shown in the examples use the following data:

API Version 2006-03-01

612
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in a Single Chunk

• Example access keys.

Parameter Value

AWSAccessKeyId AKIAIOSFODNN7EXAMPLE

AWSSecretAccessKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

• Request timestamp of 20130524T000000Z (Fri, 24 May 2013 00:00:00 GMT).

• Bucket name examplebucket.
• The bucket is assumed to be in the US East (N. Virginia) Region. The credential Scope and the
Signing Key calculations use us-east-1 as the Region speciﬁer. For information about other
Regions, see Regions and Endpoints in the AWS General Reference.
• You can use either path-style or virtual hosted–style requests. The following examples show how to
sign a virtual hosted–style request, for example:

https://examplebucket.s3.amazonaws.com/photos/photo1.jpg

For more information, see Virtual Hosting of Buckets in the Amazon Simple Storage Service Developer
Guide.

Example: GET Object

The following example gets the ﬁrst 10 bytes of an object (test.txt) from examplebucket. For more
information about the API action, see GetObject (p. 138).

GET /test.txt HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date:20130524T000000Z
Authorization: SignatureToBeCalculated
Range: bytes=0-9
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20130524T000000Z

Because this GET request does not provide any body content, the x-amz-content-sha256 value is the
hash of the empty request body. The following steps show signature calculations and construction of the
Authorization header.

1. StringToSign

a. CanonicalRequest

GET
/test.txt

host:examplebucket.s3.amazonaws.com
range:bytes=0-9
x-amz-content-
sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20130524T000000Z

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

In the canonical request string, the last line is the hash of the empty request body. The third line
is empty because there are no query parameters in the request.

API Version 2006-03-01

613
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in a Single Chunk

b. StringToSign

AWS4-HMAC-SHA256
20130524T000000Z
20130524/us-east-1/s3/aws4_request
7344ae5b7ee6c3e7e6b0fe0640412a37625d1fbfff95c48bbb2dc43964946972

2. SigningKey

signing key = HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("AWS4" +

"<YourSecretAccessKey>","20130524"),"us-east-1"),"s3"),"aws4_request")

3. Signature

f0e8bdb87c964420e857bd35b5d6ed310bd44f0170aba48dd91039c6036bdb41

4. Authorization header

The resulting Authorization header is as follows:

AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/
s3/aws4_request,SignedHeaders=host;range;x-amz-content-sha256;x-amz-
date,Signature=f0e8bdb87c964420e857bd35b5d6ed310bd44f0170aba48dd91039c6036bdb41

Example: PUT Object

This example PUT request creates an object (test$file.text) in examplebucket . The example
assumes the following:

• You are requesting REDUCED_REDUNDANCY as the storage class by adding the x-amz-storage-
class request header. For information about storage classes, see Storage Classes in the Amazon
Simple Storage Service Developer Guide.
• The content of the uploaded ﬁle is a string, "Welcome to Amazon S3." The value of x-amz-
content-sha256 in the request is based on this string.

For information about the API action, see PutObject (p. 310).

PUT test$file.text HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Fri, 24 May 2013 00:00:00 GMT
Authorization: SignatureToBeCalculated
x-amz-date: 20130524T000000Z
x-amz-storage-class: REDUCED_REDUNDANCY
x-amz-content-sha256: 44ce7dd67c959e0d3524ffac1771dfbba87d2b6b4b4e99e42034a8b803f8b072

The following steps show signature calculations.

1. StringToSign

a. CanonicalRequest

PUT
/test%24file.text

date:Fri, 24 May 2013 00:00:00 GMT

API Version 2006-03-01

614
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in a Single Chunk

host:examplebucket.s3.amazonaws.com
x-amz-content-
sha256:44ce7dd67c959e0d3524ffac1771dfbba87d2b6b4b4e99e42034a8b803f8b072
x-amz-date:20130524T000000Z
x-amz-storage-class:REDUCED_REDUNDANCY

date;host;x-amz-content-sha256;x-amz-date;x-amz-storage-class
44ce7dd67c959e0d3524ffac1771dfbba87d2b6b4b4e99e42034a8b803f8b072

In the canonical request, the third line is empty because there are no query parameters in the
request. The last line is the hash of the body, which should be same as the x-amz-content-
sha256 header value.
b. StringToSign

AWS4-HMAC-SHA256
20130524T000000Z
20130524/us-east-1/s3/aws4_request
9e0e90d9c76de8fa5b200d8c849cd5b8dc7a3be3951ddb7f6a76b4158342019d

2. SigningKey

signing key = HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("AWS4" +

"<YourSecretAccessKey>","20130524"),"us-east-1"),"s3"),"aws4_request")

3. Signature

98ad721746da40c64f1a55b78f14c238d841ea1380cd77a1b5971af0ece108bd

4. Authorization header

The resulting Authorization header is as follows:

AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/
aws4_request,SignedHeaders=date;host;x-amz-content-sha256;x-amz-date;x-amz-storage-
class,Signature=98ad721746da40c64f1a55b78f14c238d841ea1380cd77a1b5971af0ece108bd

Example: GET Bucket Lifecycle

The following GET request retrieves the lifecycle conﬁguration of examplebucket. For information
about the API action, see GetBucketLifecycleConﬁguration (p. 102).

GET ?lifecycle HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Authorization: SignatureToBeCalculated
x-amz-date: 20130524T000000Z
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Because the request does not provide any body content, the x-amz-content-sha256 header value is
the hash of the empty request body. The following steps show signature calculations.

1. StringToSign

a. CanonicalRequest

GET
/
lifecycle=
host:examplebucket.s3.amazonaws.com

API Version 2006-03-01

615
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in a Single Chunk

x-amz-content-
sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20130524T000000Z

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

In the canonical request, the last line is the hash of the empty request body.
b. StringToSign

AWS4-HMAC-SHA256
20130524T000000Z
20130524/us-east-1/s3/aws4_request
9766c798316ff2757b517bc739a67f6213b4ab36dd5da2f94eaebf79c77395ca

2. SigningKey

signing key = HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("AWS4" +

"<YourSecretAccessKey>","20130524"),"us-east-1"),"s3"),"aws4_request")

3. Signature

fea454ca298b7da1c68078a5d1bdbfbbe0d65c699e0f91ac7a200a0136783543

4. Authorization header

The resulting Authorization header is as follows:

AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/
s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-
date,Signature=fea454ca298b7da1c68078a5d1bdbfbbe0d65c699e0f91ac7a200a0136783543

Example: Get Bucket (List Objects)

The following example retrieves a list of objects from examplebucket bucket. For information about
the API action, see ListObjects (p. 202).

GET ?max-keys=2&prefix=J HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Authorization: SignatureToBeCalculated
x-amz-date: 20130524T000000Z
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Because the request does not provide a body, the value of x-amz-content-sha256 is the hash of the
empty request body. The following steps show signature calculations.

1. StringToSign

a. CanonicalRequest

GET
/
max-keys=2&prefix=J
host:examplebucket.s3.amazonaws.com
x-amz-content-
sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20130524T000000Z

API Version 2006-03-01

616
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in a Single Chunk

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

In the canonical string, the last line is the hash of the empty request body.
b. StringToSign

AWS4-HMAC-SHA256
20130524T000000Z
20130524/us-east-1/s3/aws4_request
df57d21db20da04d7fa30298dd4488ba3a2b47ca3a489c74750e0f1e7df1b9b7

2. SigningKey

signing key = HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("AWS4" +

"<YourSecretAccessKey>","20130524"),"us-east-1"),"s3"),"aws4_request")

3. Signature

34b48302e7b5fa45bde8084f4b7868a86f0a534bc59db6670ed5711ef69dc6f7

4. Authorization header

The resulting Authorization header is as follows:

AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/
s3/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-
date,Signature=34b48302e7b5fa45bde8084f4b7868a86f0a534bc59db6670ed5711ef69dc6f7

API Version 2006-03-01

617
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in Multiple Chunks

Signature Calculations for the Authorization Header:

Transferring Payload in Multiple Chunks (Chunked
Upload) (AWS Signature Version 4)
As described in the Overview (p. 605), when authenticating requests using the Authorization header,
you have an option of uploading the payload in chunks. You can send data in ﬁxed size or variable size
chunks. This section describes the signature calculation process in chunked upload, how you create the
chunk body, and how the delayed signing works where you ﬁrst upload the chunk, and send its signature
in the subsequent chunk. The example section (see Example: PUT Object (p. 622)) shows signature
calculations and resulting Authorization headers that you can use as a test suite to verify your code.
Note
When transferring data in a series of chunks, you must do one of the following:

• Explicitly specify the total content length (object length in bytes plus metadata in each chunk)
using the Content-Length HTTP header. To do this, you must pre-compute the total length
of the payload, including the metadata that you send in each chunk, before starting your
request.
• Specify the Transfer-Encoding HTTP header. If you include the Transfer-Encoding
header and specify any value other than identity, you must omit the Content-Length
header.

For all requests, you must include the x-amz-decoded-content-length header, specifying
the size of the object in bytes.

Each chunk signature calculation includes the signature of the previous chunk. To begin, you create a
seed signature using only the headers. You use the seed signature in the signature calculation of the
ﬁrst chunk. For each subsequent chunk, you create a chunk signature that includes the signature of the
previous chunk. Thus, the chunk signatures are chained together; that is, the signature of chunk n is a
function F(chunk n, signature(chunk n-1)). The chaining ensures that you send the chunks in the correct
order.

To perform a chunked upload, do the following:

1. Decide the payload chunk size. You need this when you write the code.

The chunk size must be at least 8 KB. We recommend a chunk size of a least 64 KB for better
performance. This chunk size applies to all chunks except the last one. The last chunk you send can be
smaller than 8 KB. If your payload is small and can fit into one chunk, then it can be smaller than the 8
KB.
2. Create the seed signature for inclusion in the first chunk. For more information, see Calculating the
Seed Signature (p. 618).
3. Create the first chunk and stream it. For more information, see Defining the Chunk Body (p. 621).
4. For each subsequent chunk, calculate the chunk signature that includes the previous signature in
the string you sign, construct the chunk, and send it. For more information, see Defining the Chunk
Body (p. 621).
5. Send the final additional chunk, which is the same as the other chunks in the construction, but it has
zero data bytes. For more information, see Defining the Chunk Body (p. 621).

Calculating the Seed Signature

The following diagram illustrates the process of calculating the seed signature.

API Version 2006-03-01

618
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in Multiple Chunks

The following table describes the functions that are shown in the diagram. You need to implement code
for these functions.

Function Description

Lowercase() Convert the string to lowercase.

Hex() Lowercase base 16 encoding.

SHA256Hash() Secure Hash Algorithm (SHA) cryptographic hash function.

HMAC-SHA256() Computes HMAC by using the SHA256 algorithm with the signing
key provided. This is the ﬁnal signature.

Trim() Remove any leading or trailing whitespace.

UriEncode() URI encode every byte. UriEncode() must enforce the following
rules:

• URI encode every byte except the unreserved characters: 'A'-'Z',

API Version 2006-03-01

619
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in Multiple Chunks

Function Description
• Encode the forward slash character, '/', everywhere except in the
object key name. For example, if the object key name is photos/
Jan/sample.jpg, the forward slash in the key name is not
encoded.

The following is an example UriEncode() function in Java.

public static String UriEncode(CharSequence input, boolean

For information about the signing process, see Signature Calculations for the Authorization Header:
Transferring Payload in a Single Chunk (AWS Signature Version 4) (p. 607). The process is the same,
except that the creation of CanonicalRequest diﬀers as follows:

• In addition to the request headers you plan to add, you must include the following headers:

Header Description

x-amz-content- This header is required for all AWS Signature Version 4 requests. Set the
sha256 value to STREAMING-AWS4-HMAC-SHA256-PAYLOAD to indicate that the
signature covers only headers and that there is no payload.

API Version 2006-03-01

620
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in Multiple Chunks

Header Description

Content-Encoding Set the value to aws-chunked.

Amazon S3 supports multiple content encodings. For example:

Content-Encoding : aws-chunked,gzip

That is, you can specify your custom content-encoding when using
Signature Version 4 streaming API.
Note
Amazon S3 stores the resulting object without the aws-chunked
encoding. Therefore, when you retrieve the object, it is not aws-
chunked encoded.

x-amz-decoded- Set the value to the length, in bytes, of the data to be chunked, without
content-length counting any metadata. For example, if you are uploading a 4 GB ﬁle, set
the value to 4294967296. This is the raw size of the object to be uploaded
(data you want to store in Amazon S3).

Content-Length Set the value to the actual size of the transmitted HTTP body, which
includes the length of your data (value set for x-amz-decoded-
content-length), plus chunk metadata. Each chunk has metadata, such
as the signature of the previous chunk. Chunk calculations are discussed
in the following section. If you include the Transfer-Encoding header
and specify any value other than identity, you must not include the
Content-Length header.

You send the ﬁrst chunk with the seed signature. You must construct the chunk as described in the
following section.

Deﬁning the Chunk Body

All chunks include some metadata. Each chunk must conform to the following structure:

string(IntHexBase(chunk-size)) + ";chunk-signature=" + signature + \r\n + chunk-data + \r\n

Where:

• IntHexBase() is a function that you write to convert an integer chunk-size to hexadecimal. For
example, if chunk-size is 65536, hexadecimal string is "10000".
• chunk-size is the size, in bytes, of the chunk-data, without metadata. For example, if you are
uploading a 65 KB object and using a chunk size of 64 KB, you upload the data in three chunks: the
first would be 64 KB, the second 1 KB, and the final chunk with 0 bytes.
• signature For each chunk, you calculate the signature using the following string to sign. For the first
chunk, you use the seed-signature as the previous signature.

API Version 2006-03-01

621
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in Multiple Chunks

The size of the ﬁnal chunk data that you send is 0, although the chunk body still contains metadata,
including the signature of the previous chunk.

Example: PUT Object

You can use the examples in this section as a reference to check signature calculations in your code.
Before you review the examples, note the following:

• The signature calculations in these examples use the following example security credentials.

Parameter Value

AWSAccessKeyId AKIAIOSFODNN7EXAMPLE

AWSSecretAccessKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

• All examples use the request timestamp 20130524T000000Z (Fri, 24 May 2013 00:00:00 GMT).
• All examples use examplebucket as the bucket name.
• The bucket is assumed to be in the US East (N. Virginia) Region, and the credential Scope and the
Signing Key calculations use us-east-1 as the Region speciﬁer. For more information, see Regions
and Endpoints in the Amazon Web Services General Reference.
• You can use either path style or virtual-hosted style requests. The following examples use virtual-
hosted style requests, for example:

https://examplebucket.s3.amazonaws.com/photos/photo1.jpg

For more information, see Virtual Hosting of Buckets in the Amazon Simple Storage Service Developer
Guide.

Example: PUT Object

The following example sends a PUT request to upload an object. The signature calculations assume the
following:

• You are uploading a 65 KB text file, and the file content is a one-character string made up of the letter
'a'.
• The chunk size is 64 KB. As a result, the payload is uploaded in three chunks, 64 KB, 1 KB, and the final
chunk with 0 bytes of chunk data.
• The resulting object has the key name chunkObject.txt.

API Version 2006-03-01

622
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in Multiple Chunks

• You are requesting REDUCED_REDUNDANCY as the storage class by adding the x-amz-storage-
class request header.

For information about the API action, see PutObject (p. 310). The general request syntax is as follows:

PUT /examplebucket/chunkObject.txt HTTP/1.1

Host: s3.amazonaws.com
x-amz-date: 20130524T000000Z
x-amz-storage-class: REDUCED_REDUNDANCY
Authorization: SignatureToBeCalculated
x-amz-content-sha256: STREAMING-AWS4-HMAC-SHA256-PAYLOAD
Content-Encoding: aws-chunked
x-amz-decoded-content-length: 66560
Content-Length: 66824
<Payload>

The following steps show signature calculations.

1. Seed signature — Create String to Sign

a. CanonicalRequest

PUT
/examplebucket/chunkObject.txt

content-encoding:aws-chunked
content-length:66824
host:s3.amazonaws.com
x-amz-content-sha256:STREAMING-AWS4-HMAC-SHA256-PAYLOAD
x-amz-date:20130524T000000Z
x-amz-decoded-content-length:66560
x-amz-storage-class:REDUCED_REDUNDANCY

content-encoding;content-length;host;x-amz-content-sha256;x-amz-date;x-amz-decoded-
content-length;x-amz-storage-class
STREAMING-AWS4-HMAC-SHA256-PAYLOAD

In the canonical request, the third line is empty because there are no query parameters in the
request. The last line is the constant string provided as the value of the hashed Payload, which
should be same as the value of x-amz-content-sha256 header.
b. StringToSign

AWS4-HMAC-SHA256
20130524T000000Z
20130524/us-east-1/s3/aws4_request
cee3fed04b70f867d036f722359b0b1f2f0e5dc0efadbc082b76c4c60e316455

Note
For information about each of line in the string to sign, see the diagram that explains
seed signature calculation.
2. SigningKey

signing key = HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("AWS4" +

"<YourSecretAccessKey>","20130524"),"us-east-1"),"s3"),"aws4_request")

API Version 2006-03-01

623
Amazon Simple Storage Service API Reference
Signature Calculation: Transfer Payload in Multiple Chunks

3. Seed Signature

4f232c4386841ef735655705268965c44a0e4690baa4adea153f7db9fa80a0a9

4. Authorization header

The resulting Authorization header is as follows:

AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/
aws4_request,SignedHeaders=content-encoding;content-length;host;x-amz-
content-sha256;x-amz-date;x-amz-decoded-content-length;x-amz-storage-
class,Signature=4f232c4386841ef735655705268965c44a0e4690baa4adea153f7db9fa80a0a9

5. Chunk 1: (65536 bytes, with value 97 for letter 'a')

a. Chunk string to sign:

AWS4-HMAC-SHA256-PAYLOAD
20130524T000000Z
20130524/us-east-1/s3/aws4_request
4f232c4386841ef735655705268965c44a0e4690baa4adea153f7db9fa80a0a9
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
bf718b6f653bebc184e1479f1935b8da974d701b893afcf49e701f3e2f9f9c5a

Note
For information about each line in the string to sign, see the preceding diagram that
shows various components of the string to sign (for example, the last three lines are,
previous-signature, hash(""), and hash(current-chunk-data)).
b. Chunk signature:

ad80c730a21e5b8d04586a2213dd63b9a0e99e0e2307b0ade35a65485a288648

c. Chunk data sent:

10000;chunk-
signature=ad80c730a21e5b8d04586a2213dd63b9a0e99e0e2307b0ade35a65485a288648
<65536-bytes>

6. Chunk 2: (1024 bytes, with value 97 for letter 'a')

a. Chunk string to sign:

AWS4-HMAC-SHA256-PAYLOAD
20130524T000000Z
20130524/us-east-1/s3/aws4_request
ad80c730a21e5b8d04586a2213dd63b9a0e99e0e2307b0ade35a65485a288648
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
2edc986847e209b4016e141a6dc8716d3207350f416969382d431539bf292e4a

b. Chunk signature:

0055627c9e194cb4542bae2aa5492e3c1575bbb81b612b7d234b86a503ef5497

c. Chunk data sent:

400;chunk-
signature=0055627c9e194cb4542bae2aa5492e3c1575bbb81b612b7d234b86a503ef5497
<1024 bytes>
API Version 2006-03-01
624
Amazon Simple Storage Service API Reference
Using Query Parameters

7. Chunk 3: (0 byte data)

a. Chunk string to sign:

AWS4-HMAC-SHA256-PAYLOAD
20130524T000000Z
20130524/us-east-1/s3/aws4_request
0055627c9e194cb4542bae2aa5492e3c1575bbb81b612b7d234b86a503ef5497
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

b. Chunk signature:

b6c6ea8a5354eaf15b3cb7646744f4275b71ea724fed81ceb9323e279d449df9

c. Chunk data sent:

0;chunk-signature=b6c6ea8a5354eaf15b3cb7646744f4275b71ea724fed81ceb9323e279d449df9

Authenticating Requests: Using Query Parameters

(AWS Signature Version 4)
As described in the authentication overview (see Authentication Methods (p. 604)), you can provide
authentication information using query string parameters. Using query parameters to authenticate
requests is useful when you want to express a request entirely in a URL. This method is also referred as
presigning a URL.

A use case scenario for presigned URLs is that you can grant temporary access to your Amazon S3
resources. For example, you can embed a presigned URL on your website or alternatively use it in
command line client (such as Curl) to download objects.

The following is an example presigned URL.

https://s3.amazonaws.com/examplebucket/test.txt
?X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=<your-access-key-id>/20130721/us-east-1/s3/aws4_request
&X-Amz-Date=20130721T201207Z
&X-Amz-Expires=86400
&X-Amz-SignedHeaders=host
&X-Amz-Signature=<signature-value>

In the example URL, note the following:

• The line feeds are added for readability.

• The X-Amz-Credential value in the URL shows the "/" character only for readability. In practice, it
should be encoded as %2F. For example:

&X-Amz-Credential=<your-access-key-id>%2F20130721%2Fus-east-1%2Fs3%2Faws4_request

The following table describes the query parameters in the URL that provide authentication information.

API Version 2006-03-01

625
Amazon Simple Storage Service API Reference
Using Query Parameters

Query String Parameter Name Example Value

X-Amz-Algorithm Identiﬁes the version of AWS Signature and the algorithm that you
used to calculate the signature.

For AWS Signature Version 4, you set this parameter value to

AWS4-HMAC-SHA256. This string identiﬁes AWS Signature Version
4 (AWS4) and the HMAC-SHA256 algorithm (HMAC-SHA256).

X-Amz-Credential In addition to your access key ID, this parameter also provides
scope (AWS region and service) for which the signature is valid.
This value must match the scope you use in signature calculations,
discussed in the following section. The general form for this
parameter value is as follows:

<your-access-key-id>/<date>/<AWS-region>/<AWS-service>/
aws4_request

For example:

AKIAIOSFODNN7EXAMPLE/20130721/us-east-1/s3/aws4_request

For Amazon S3, the AWS-service string is s3. For a list of S3 AWS-
region strings, see Regions and Endpoints in the AWS General
Reference.

X-Amz-Date The date and time format must follow the ISO 8601 standard, and
must be formatted with the "yyyyMMddTHHmmssZ" format. For
example if the date and time was "08/01/2016 15:32:41.982-700"
then it must ﬁrst be converted to UTC (Coordinated Universal Time)
and then submitted as "20160801T083241Z".

X-Amz-Expires Provides the time period, in seconds, for which the generated
presigned URL is valid. For example, 86400 (24 hours). This value is
an integer. The minimum value you can set is 1, and the maximum
is 604800 (seven days).

A presigned URL can be valid for a maximum of seven days because

the signing key you use in signature calculation is valid for up to
seven days.

X-Amz-SignedHeaders Lists the headers that you used to calculate the signature. The
following headers are required in the signature calculations:

• The HTTP host header.

• Any x-amz-* headers that you plan to add to the request.

Note
For added security, you should sign all the request headers
that you plan to include in your request.

X-Amz-Signature Provides the signature to authenticate your request. This

signature must match the signature Amazon S3 calculates;
otherwise, Amazon S3 denies the request. For example,
733255ef022bec3f2a8701cd61d4b371f3f28c9f193a1f02279211d48d5193

API Version 2006-03-01

626
Amazon Simple Storage Service API Reference
Calculating a Signature

Query String Parameter Name Example Value

Signature calculations are described in the following section.

Calculating a Signature
The following diagram illustrates the signature calculation process.

The following table describes the functions that are shown in the diagram. You need to implement code
for these functions.

Function Description

Lowercase() Convert the string to lowercase.

Hex() Lowercase base 16 encoding.

SHA256Hash() Secure Hash Algorithm (SHA) cryptographic hash function.

HMAC-SHA256() Computes HMAC by using the SHA256 algorithm with the signing
key provided. This is the ﬁnal signature.

Trim() Remove any leading or trailing whitespace.

UriEncode() URI encode every byte. UriEncode() must enforce the following
rules:

• URI encode every byte except the unreserved characters: 'A'-'Z',

'a'-'z', '0'-'9', '-', '.', '_', and '~'.
• The space character is a reserved character and must be encoded
as "%20" (and not as "+").

API Version 2006-03-01

627
Amazon Simple Storage Service API Reference
Calculating a Signature

Function Description
• Each URI encoded byte is formed by a '%' and the two-digit
hexadecimal value of the byte.
• Letters in the hexadecimal value must be uppercase, for example
"%1A".
• Encode the forward slash character, '/', everywhere except in the
object key name. For example, if the object key name is photos/
Jan/sample.jpg, the forward slash in the key name is not
encoded.

The following is an example UriEncode() function in Java.

public static String UriEncode(CharSequence input, boolean

For more information about the signing process (details of creating a canonical request, string to sign,
and signature calculations), see Signature Calculations for the Authorization Header: Transferring
Payload in a Single Chunk (AWS Signature Version 4) (p. 607). The process is generally the same except
that the creation of CanonicalRequest in a presigned URL diﬀers as follows:

• You don't include a payload hash in the Canonical Request, because when you create a presigned URL,
you don't know the payload content because the URL is used to upload an arbitrary payload. Instead,
you use a constant string UNSIGNED-PAYLOAD.
• The Canonical Query String must include all the query parameters from the preceding table except
for X-Amz-Signature.
• Canonical Headers must include the HTTP host header. If you plan to include any of the x-amz-*
headers, these headers must also be added for signature calculation. You can optionally add all other
headers that you plan to include in your request. For added security, you should sign as many headers
as possible.

API Version 2006-03-01

628
Amazon Simple Storage Service API Reference
An Example

An Example
Suppose you have an object test.txt in your examplebucket bucket. You want to share this object
with others for a period of 24 hours (86400 seconds) by creating a presigned URL.

https://s3.amazonaws.com/examplebucket/test.txt
?X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20130524%2Fus-east-1%2Fs3%2Faws4_request
&X-Amz-Date=20130524T000000Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host
&X-Amz-Signature=<signature-value>

The following steps illustrate ﬁrst the signature calculations and then construction of the presigned URL.
The example makes the following additional assumptions:

• Request timestamp is Fri, 24 May 2013 00:00:00 GMT.

• The bucket is in the US East (N. Virginia) region, and the credential Scope and the Signing Key
calculations use us-east-1 as the region speciﬁer. For more information, see Regions and Endpoints
in the AWS General Reference.

You can use this example as a test case to verify the signature that your code calculates; however, you
must use the same bucket name, object key, time stamp, and the following example credentials:

Parameter Value

AWSAccessKeyId AKIAIOSFODNN7EXAMPLE

AWSSecretAccessKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

1. StringToSign

a. CanonicalRequest

GET
/test.txt
X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE
%2F20130524%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20130524T000000Z&X-Amz-
Expires=86400&X-Amz-SignedHeaders=host
host:examplebucket.s3.amazonaws.com

host
UNSIGNED-PAYLOAD

b. StringToSign

AWS4-HMAC-SHA256
20130524T000000Z
20130524/us-east-1/s3/aws4_request
3bfa292879f6447bbcda7001decf97f4a54dc650c8942174ae0a9121cf58ad04

2. SigningKey

signing key = HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("AWS4" +

"<YourSecretAccessKey>","20130524"),"us-east-1"),"s3"),"aws4_request")

API Version 2006-03-01

629
Amazon Simple Storage Service API Reference
Examples: Signature Calculations

3. Signature

aeeed9bbccd4d02ee5c0109b86d86835f995330da4c265957d157751f604d404

Now you have all information to construct a presigned URL. The resulting URL for this example is
shown as follows (you can use this to compare your presigned URL):

https://examplebucket.s3.amazonaws.com/test.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-
Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20130524%2Fus-east-1%2Fs3%2Faws4_request&X-
Amz-Date=20130524T000000Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-
Signature=aeeed9bbccd4d02ee5c0109b86d86835f995330da4c265957d157751f604d404

Examples: Signature Calculations in AWS Signature

Version 4
Topics
• Signature Calculation Examples Using Java (AWS Signature Version 4) (p. 630)
• Examples of Signature Calculations Using C# (AWS Signature Version 4) (p. 631)

For authenticated requests, unless you are using the AWS SDKs, you have to write code to calculate
signatures that provide authentication information in your requests. Signature calculation in AWS
Signature Version 4 (see Authenticating Requests (AWS Signature Version 4) (p. 603)) can be a complex
undertaking, and we recommend that you use the AWS SDKs whenever possible.

This section provides examples of signature calculations written in Java and C#. The code samples send
the following requests and use the HTTP Authorization header to provide authentication information:

• PUT object – Separate examples illustrate both uploading the full payload at once and uploading
the payload in chunks. For information about using the Authorization header for authentication, see
Authenticating Requests: Using the Authorization Header (AWS Signature Version 4) (p. 605).
• GET object – This example generates a presigned URL to get an object. Query parameters provide the
signature and other authentication information. Users can paste a presigned URL in their browser to
retrieve the object, or you can use the URL to create a clickable link. For information about using query
parameters for authentication, see Authenticating Requests: Using Query Parameters (AWS Signature
Version 4) (p. 625).

The rest of this section describes the examples in Java and C#. The topics include instructions for
downloading the samples and for executing them.

Signature Calculation Examples Using Java (AWS

Signature Version 4)
The Java sample that shows signature calculation can be downloaded at https://docs.aws.amazon.com/
AmazonS3/latest/API/samples/AWSS3SigV4JavaSamples.zip. In RunAllSamples.java, the main()
function executes sample requests to create an object, retrieve an object, and create a presigned URL for
the object. The sample creates an object from the text string provided in the code:

PutS3ObjectSample.putS3Object(bucketName, regionName, awsAccessKey, awsSecretKey);

GetS3ObjectSample.getS3Object(bucketName, regionName, awsAccessKey, awsSecretKey);
PresignedUrlSample.getPresignedUrlToS3Object(bucketName, regionName, awsAccessKey,
awsSecretKey);

API Version 2006-03-01

630
Amazon Simple Storage Service API Reference
Signature Calculation Examples Using C#

PutS3ObjectChunkedSample.putS3ObjectChunked(bucketName, regionName, awsAccessKey,

awsSecretKey);

To test the examples on a Linux-based computer

The following instructions are for the Linux operating system.

1. In a terminal, navigate to the directory that contains AWSS3SigV4JavaSamples.zip.

2. Extract the .zip ﬁle.
3. In a text editor, open the ﬁle ./com/amazonaws/services/s3/samples/RunAllSamples.java.
Update code with the following information:
• The name of a bucket where the new object can be created.
Note
The examples use a virtual-hosted style request to access the bucket. To avoid potential
errors, ensure that your bucket name conforms to the bucket naming rules as explained in
Bucket Restrictions and Limitations in the Amazon Simple Storage Service Developer Guide.
• AWS region where the bucket resides.

If bucket is in the US East (N. Virginia) region, use us-east-1 to specify the region. For a list of other
AWS regions, go to Amazon Simple Storage Service (S3) in the AWS General Reference.
4. Compile the source code and store the compiled classes into the bin/ directory.

javac -d bin -source 6 -verbose com

5. Change the directory to bin/, and then execute RunAllSamples.

java com.amazonaws.services.s3.sample.RunAllSamples

The code runs all the methods in main(). For each request, the output will show the canonical
request, the string to sign, and the signature.

Examples of Signature Calculations Using C# (AWS

Signature Version 4)
The C# sample that shows signature calculation can be downloaded at https://docs.aws.amazon.com/
AmazonS3/latest/API/samples/AmazonS3SigV4_Samples_CSharp.zip. In Program.cs, the main()
function executes sample requests to create an object, retrieve an object, and create a presigned URL for
the object. The code for signature calculation is in the \Signers folder.

PutS3ObjectSample.Run(awsRegion, bucketName, "MySampleFile.txt");

Console.WriteLine("\n\n************************************************");
PutS3ObjectChunkedSample.Run(awsRegion, bucketName, "MySampleFileChunked.txt");

Console.WriteLine("\n\n************************************************");
GetS3ObjectSample.Run(awsRegion, bucketName, "MySampleFile.txt");

Console.WriteLine("\n\n************************************************");
PresignedUrlSample.Run(awsRegion bucketName, "MySampleFile.txt");

To test the examples with Microsoft Visual Studio 2010 or later

1. Extract the .zip ﬁle.

API Version 2006-03-01

631
Amazon Simple Storage Service API Reference
Authenticating HTTP POST Requests

2. Start Visual Studio, and then open the .sln ﬁle.

3. Update the App.conﬁg ﬁle with valid security credentials.
4. Update the code as follows:
• In Program.cs, provide the bucket name and the AWS region where the bucket resides. The sample
creates an object in this bucket.
5. Execute the code.
6. To verify that the object was created, copy the presigned URL that the program creates, and then
paste it in a browser window.

Authenticating Requests: Browser-Based Uploads

Using POST (AWS Signature Version 4)
Amazon S3 supports HTTP POST requests so that users can upload content directly to Amazon S3. Using
HTTP POST to upload content simpliﬁes uploads and reduces upload latency where users upload data
to store in Amazon S3. This section describes how you authenticate HTTP POST requests. For more
information about HTTP POST requests, how to create a form, create a POST policy, and an example, see
Authenticating Requests in Browser-Based Uploads Using POST (AWS Signature Version 4) (p. 638).

To authenticate an HTTP POST request you do the following:

1. The form must include the following ﬁelds to provide signature and relevant information that Amazon
S3 can use to re-calculate the signature upon receiving the request:

Element Name Description

policy The Base64-encoded security policy that describes what

is permitted in the request. For signature calculation this
policy is the string you sign. Amazon S3 must get this
policy so it can re-calculate the signature.

x-amz-algorithm The signing algorithm used. For AWS Signature Version 4,

the value is AWS4-HMAC-SHA256.

x-amz-credential In addition to your access key ID, this provides scope

information you used in calculating the signing key for
signature calculation.

It is a string of the following form:

<your-access-key-id>/<date>/<aws-
region>/<aws-service>/aws4_request

For example:

AKIAIOSFODNN7EXAMPLE/20130728/us-east-1/s3/
aws4_request. .

For Amazon S3, the aws-service string is s3. For a list

of Amazon S3 aws-region strings, see Regions and
Endpoints in the AWS General Reference.

x-amz-date It is the date value in ISO8601 format. For example,

20130728T000000Z.

API Version 2006-03-01

632
Amazon Simple Storage Service API Reference
Calculating a Signature

Element Name Description

It is the same date you used in creating the signing key.
This must also be the same value you provide in the policy
(x-amz-date) that you signed.

x-amz-signature (AWS Signature Version 4) The HMAC-SHA256 hash of the

security policy.

2. The POST policy must include the following elements:

Element Name Description

x-amz-algorithm The signing algorithm that you used to calculation the

signature. For AWS Signature Version 4, the value is
AWS4-HMAC-SHA256.

x-amz-credential In addition to your access key ID, this provides scope

information you used in calculating the signing key for
signature calculation.

It is a string of the following form:

<your-access-key-id>/<date>/<aws-
region>/<aws-service>/aws4_request

For example,

AKIAIOSFODNN7EXAMPLE/20130728/us-east-1/s3/
aws4_request. .

x-amz-date The date value speciﬁed in the ISO8601 formatted string.

For example, "20130728T000000Z". The date must
be same that you used in creating the signing key for
signature calculation.

3. For signature calculation the POST policy is the string to sign.

Calculating a Signature
The following diagram illustrates the signature calculation process.

API Version 2006-03-01

633
Amazon Simple Storage Service API Reference
Amazon S3 Signature Version 4
Authentication Speciﬁc Policy Keys

To Calculate a signature

1. Create a policy using UTF-8 encoding.

2. Convert the UTF-8-encoded policy to Base64. The result is the string to sign.
3. Create the signature as an HMAC-SHA256 hash of the string to sign. You will provide the signing key
as key to the hash function.
4. Encode the signature by using hex encoding.

For more information about creating HTML forms, security policies, and an example, see the following
subtopics:

• Creating an HTML Form (Using AWS Signature Version 4) (p. 667)

• Creating a POST Policy (p. 671)
• Example: Browser-Based Upload using HTTP POST (Using AWS Signature Version 4) (p. 676)
• Using POST with Adobe Flash to Upload Objects (p. 678)

Amazon S3 Signature Version 4 Authentication

Speciﬁc Policy Keys
The following table shows the policy keys related Amazon S3 Signature Version 4 authentication
that can be in Amazon S3 policies. In a bucket policy, you can add these conditions to enforce speciﬁc
behavior when requests are authenticated by using Signature Version 4. For example policies, see Bucket
Policy Examples Using Signature Version 4 Related Condition Keys (p. 636).

Applicable Keys for s3:* Actions or any of the Amazon S3 Actions

Applicable Keys Description

s3:signatureversion Identiﬁes the version of AWS Signature that you

want to support for authenticated requests. For
authenticated requests, Amazon S3 supports both
Signature Version 4 and Signature Version 2. You
can add this condition in your bucket policy to
require a speciﬁc signature version.

Valid values:

API Version 2006-03-01

634
Amazon Simple Storage Service API Reference
Amazon S3 Signature Version 4
Authentication Speciﬁc Policy Keys

Applicable Keys Description

"AWS" identiﬁes Signature Version 2

"AWS4-HMAC-SHA256" identiﬁes Signature

Version 4

s3:authType Amazon S3 supports various methods of

authentication (see Authenticating Requests
(AWS Signature Version 4) (p. 603). You can
optionally use this condition key to restrict
incoming requests to use a speciﬁc authentication
method. For example, you can allow only the HTTP
Authorization header to be used in request
authentication.

Valid values:

REST-HEADER

REST-QUERY-STRING

POST

s3:signatureAge The length of time, in milliseconds, that a

signature is valid in an authenticated request.

This condition works only for presigned URLs (the

most restrictive condition wins).

In Signature Version 4, the signing key is valid

for up to seven days (see Introduction to Signing
Requests (p. 604). Therefore, the signatures are
also valid for up to seven days. You can use this
condition to further limit the signature age.

Example value: 100

API Version 2006-03-01

635
Amazon Simple Storage Service API Reference
Bucket Policy Examples Using Signature
Version 4 Related Condition Keys

Applicable Keys Description

s3:x-amz-content-sha256 You can use this condition key to disallow

unsigned content in your bucket.

When you use Signature Version 4, for requests

that use the Authorization header, you add the
x-amz-content-sha256 header in the signature
calculation and then set its value to the hash
payload.

You can use this condition key in your bucket

policy to deny any uploads where payloads are not
signed. For example:

• Deny uploads that use presigned URLs. For

more information, see Authenticating Requests:
Using Query Parameters (AWS Signature Version
4) (p. 625).
• Deny uploads that use Authorization header
to authenticate requests but don't sign the
payload. For more information, see Signature
Calculations for the Authorization Header:
Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p. 607).

Valid value: UNSIGNED-PAYLOAD

Bucket Policy Examples Using Signature Version 4

Related Condition Keys
Deny any Amazon S3 action on the examplebucket to anyone if request is authenticated using
Signature Version 4.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Test",
"Effect": "Deny",
"Principal": "*",
"Action": "s3:*",
"Resource": "arn:aws:s3:::examplebucket/*",
"Condition": {
"StringEquals": {
"s3:signatureversion": "AWS4-HMAC-SHA256"
}
}
}
]
}

The following bucket policy denies any Amazon S3 presigned URL request on objects in examplebucket
if the signature is more than ten minutes old.

API Version 2006-03-01

636
Amazon Simple Storage Service API Reference
Bucket Policy Examples Using Signature
Version 4 Related Condition Keys

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Deny a presigned URL request if the signature is more than 10 min old",
"Effect": "Deny",
"Principal": "*",
"Action": "s3:*",
"Resource": "arn:aws:s3:::examplebucket3/*",
"Condition": {
"NumericGreaterThan": {
"s3:signatureAge": 600000
}
}
}
]
}

The following bucket policy allows only requests that use the Authorization header for request
authentication. Any POST or presigned URL requests will be denied.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Allow only requests that use Authorization header for request
authentication. Deny POST or presigned URL requests.",
"Effect": "Deny",
"Principal": "*",
"Action": "s3:*",
"Resource": "arn:aws:s3:::examplebucket3/*",
"Condition": {
"StringNotEquals": {
"s3:authType": "REST-HEADER"
}
}
}
]
}

The following bucket policy denies any uploads that use presigned URLs.

API Version 2006-03-01

637
Amazon Simple Storage Service API Reference

Authenticating Requests in Browser-

Based Uploads Using POST (AWS
Signature Version 4)
This section discusses how to upload ﬁles directly to Amazon S3 through a browser using HTTP POST
requests. It also contains information about how to use the AWS Amplify JavaScript library for browser-
based ﬁle uploads to Amazon S3.

Topics
• POST Object (p. 639)
• POST Object restore (p. 651)
• Browser-Based Uploads Using HTTP POST (p. 665)
• Calculating a Signature (p. 666)
• Creating an HTML Form (Using AWS Signature Version 4) (p. 667)
• Creating a POST Policy (p. 671)
• Example: Browser-Based Upload using HTTP POST (Using AWS Signature Version 4) (p. 676)
• Using POST with Adobe Flash to Upload Objects (p. 678)
• Browser-Based Uploads to Amazon S3 Using the AWS Amplify Library (p. 679)

API Version 2006-03-01

638
Amazon Simple Storage Service API Reference
POST Object

POST Object
Description
The POST operation adds an object to a specified bucket using HTML forms. POST is an alternate form
of PUT that enables browser-based uploads as a way of putting objects in buckets. Parameters that are
passed to PUT via HTTP Headers are instead passed as form fields to POST in the multipart/form-data
encoded message body. You must have WRITE access on a bucket to add an object to it. Amazon S3
never stores partial objects: if you receive a successful response, you can be confident the entire object
was stored.

Amazon S3 is a distributed system. If Amazon S3 receives multiple write requests for the same object
simultaneously, all but the last object written is overwritten.

To ensure that data is not corrupted traversing the network, use the Content-MD5 form field. When you
use this form field, Amazon S3 checks the object against the provided MD5 value. If they do not match,
Amazon S3 returns an error. Additionally, you can calculate the MD5 value while posting an object to
Amazon S3 and compare the returned ETag to the calculated MD5 value. The ETag only reflects changes
to the contents of an object, not its metadata.
Note
To configure your application to send the Request Headers before sending the request body,
use the 100-continue HTTP status code. For POST operations, this helps you avoid sending the
message body if the message is rejected based on the headers (for example, authentication
failure or redirect). For more information on the 100-continue HTTP status code, go to Section
8.2.3 of http://www.ietf.org/rfc/rfc2616.txt.

Versioning
If you enable versioning for a bucket, POST automatically generates a unique version ID for the object
being added. Amazon S3 returns this ID in the response using the x-amz-version-id response header.

If you suspend versioning for a bucket, Amazon S3 always uses null as the version ID of the object
stored in a bucket.

For more information about returning the versioning state of a bucket, see GET Bucket (Versioning
Status) (p. 132).

Amazon S3 is a distributed system. If you enable versioning for a bucket and Amazon S3 receives
multiple write requests for the same object simultaneously, all of the objects are stored.

To see sample requests that use versioning, see Sample Request (p. 649).

Requests
Syntax
POST / HTTP/1.1
Host: destinationBucket.s3.amazonaws.com
User-Agent: browser_data

API Version 2006-03-01

639
Amazon Simple Storage Service API Reference
Requests

Accept: file_types
Accept-Language: Regions
Accept-Encoding: encoding
Accept-Charset: character_set
Keep-Alive: 300
Connection: keep-alive
Content-Type: multipart/form-data; boundary=9431149156168
Content-Length: length

--9431149156168
Content-Disposition: form-data; name="key"

acl
--9431149156168
Content-Disposition: form-data; name="tagging"

<Tagging><TagSet><Tag><Key>Tag Name</Key><Value>Tag Value</Value></Tag></TagSet></Tagging>

--9431149156168
Content-Disposition: form-data; name="success_action_redirect"

success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Type"

content_type
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-uuid"

uuid
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-tag"

metadata
--9431149156168
Content-Disposition: form-data; name="AWSAccessKeyId"

access-key-id
--9431149156168
Content-Disposition: form-data; name="Policy"

encoded_policy
--9431149156168
Content-Disposition: form-data; name="Signature"

signature=
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg

file_content
--9431149156168
Content-Disposition: form-data; name="submit"

Upload to Amazon S3
--9431149156168--

Request Parameters
This implementation of the operation does not use request parameters.

Form Fields
This operation can use the following form ﬁelds.

API Version 2006-03-01

640
Amazon Simple Storage Service API Reference
Requests

Name Description Required

AWSAccessKeyId The AWS access key ID of the owner of the bucket who Conditional
grants an Anonymous user access for a request that
satisﬁes the set of constraints in the policy.

Type: String

Default: None

Constraints: Required if a policy document is included

with the request.

acl Speciﬁes an Amazon S3 access control list. If an invalid No

access control list is speciﬁed, an error is generated.
For more information on ACLs, go to Access Control
List (ACL) Overview in the Amazon Simple Storage
Service Developer Guide.

Type: String

Default: private

Valid Values: private | public-read |

public-read-write | aws-exec-read |
authenticated-read | bucket-owner-read |
bucket-owner-full-control

Cache-Control, Content- REST-speciﬁc headers. For more information, see No

Type, Content- PutObject (p. 310).
Disposition, Content-
Encoding, Expires Type: String

Default: None

file File or text content. Yes

The ﬁle or text content must be the last ﬁeld in the

form.

You cannot upload more than one ﬁle at a time.

Type: File or text content

Default: None

key The name of the uploaded key. Yes

To use the ﬁle name provided by the user, use the

${ﬁlename} variable. For example, if the user Betty
uploads the ﬁle lolcatz.jpg and you specify /
user/betty/${filename}, the key name is /user/
betty/lolcatz.jpg.

For more information, go to Object Key and Metadata

in the Amazon Simple Storage Service Developer Guide.

Type: String

Default: None

API Version 2006-03-01

641
Amazon Simple Storage Service API Reference
Requests

Name Description Required

policy Security Policy describing what is permitted in the Conditional

request. Requests without a security policy are
considered anonymous and work only on publicly
writable buckets. For more information, go to HTML
Forms and Upload Examples.

Type: String

Default: None

Constraints: Policy is required if the bucket is not

publicly writable.

success_action_redirect, The URL to which the client is redirected upon No

redirect successful upload.

If success_action_redirect is not speciﬁed,

Amazon S3 returns the empty document type speciﬁed
in the success_action_status ﬁeld.

If Amazon S3 cannot interpret the URL, it acts as if the

ﬁeld is not present.

If the upload fails, Amazon S3 displays an error and

does not redirect the user to a URL.

Type: String

Default: None
Note
The redirect ﬁeld name is deprecated, and
support for the redirect ﬁeld name is removed
in the future.

API Version 2006-03-01

642
Amazon Simple Storage Service API Reference
Requests

Name Description Required

success_action_status If you don't specify success_action_redirect, the No

status code is returned to the client when the upload
succeeds.

Accepts the values 200, 201, or 204 (the default).

If the value is set to 200 or 204, Amazon S3 returns an

empty document with a 200 or 204 status code.

If the value is set to 201, Amazon S3 returns an XML

document with a 201 status code.

If the value is not set or if it is set to an invalid value,

Amazon S3 returns an empty document with a 204
status code.

Type: String

Default: None
Note
Some versions of the Adobe Flash player
do not properly handle HTTP responses
with an empty body. To support uploads
through Adobe Flash, we recommend setting
success_action_status to 201.

tagging Speciﬁes set of tags to add to the object using the No

following encoding scheme.

<Tagging>
<TagSet>
<Tag>
<Key>Tag Name</Key>
<Value>Tag Value</Value>
</Tag>
...
</TagSet>
</Tagging>

For more information, see Object Tagging in the

Amazon Simple Storage Service Developer Guide.

Type: String

Default: None

API Version 2006-03-01

643
Amazon Simple Storage Service API Reference
Requests

644
Amazon Simple Storage Service API Reference
Requests

Name Description Required

x-amz-website-redirect- If the bucket is conﬁgured as a website, redirects No

location requests for this object to another object in the same
bucket or to an external URL. Amazon S3 stores
the value of this header in the object metadata. For
information about object metadata, see Object Key
and Metadata.

In the following example, the request header sets the

redirect to an object (anotherPage.html) in the
same bucket:

x-amz-website-redirect-location: /
anotherPage.html

In the following example, the request header sets the

object redirect to another website:

x-amz-website-redirect-location: http://
www.example.com/

For more information about website hosting in

Amazon S3, see Hosting Websites on Amazon S3
and How to Conﬁgure Website Page Redirects in the
Amazon Simple Storage Service Developer Guide.

Type: String

Default: None

Constraints: The value must be preﬁxed by, "/",

"http://" or "https://". The length of the value is
limited to 2 K.

Server-Side Encryption Speciﬁc Request Form Fields

You can optionally request Amazon S3 to encrypt data at rest using server-side encryption. Server-side
encryption is data encryption at rest. Amazon S3 encrypts your data as it writes it to disks in its data
centers and decrypts it when you access it.

For more information, see Protecting Data Using Server-Side Encryption in the Amazon Simple Storage
Service Developer Guide.

Depending on whether you want to use AWS-managed encryption keys or provide your own encryption
keys, the following form ﬁelds:

• Use AWS-managed encryption keys — If you want Amazon S3 to manage keys used to encrypt data,
specify the following form ﬁelds in the request.

Name Description Required

x-amz-server- Speciﬁes a server-side encryption algorithm to use when Yes

side-encryption Amazon S3 creates an object.

Type: String

API Version 2006-03-01

645
Amazon Simple Storage Service API Reference
Requests

Name Description Required

Valid Value: aws:kms, AES256

x-amz-server- If the x-amz-server-side-encryption is present and has Yes, if the

x-amz-server- If x-amz-server-side-encryption is present, and if its No

side-encryption- value is aws:kms, this header speciﬁes the encryption context
context for the object. The value of this header is a base64-encoded
UTF-8 string holding JSON with the key-value pairs for the
encryption context.

Type: String

Note
If you specify x-amz-server-side-encryption:aws:kms, but do not provide x-amz-
server-side- encryption-aws-kms-key-id, Amazon S3 uses the default AWS KMS key
to protect the data.
• Use customer-provided encryption keys — If you want to manage your own encryption keys, you must
provide all the following form ﬁelds in the request.
Note
If you use this feature, the ETag value that Amazon S3 returns in the response is not the MD5
of the object.

Name Description Required

x-amz-server- Speciﬁes the algorithm to use to when encrypting the object. Yes
side-encryption-
customer- Type: String
algorithm
Default: None

Valid Value: AES256

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-key and x-amz-server-
side-encryption-customer-key-MD5 ﬁelds.

x-amz-server- Speciﬁes the customer-provided base64-encoded encryption Yes

side-encryption- key for Amazon S3 to use in encrypting data. This value is used
customer-key to store the object and then it is discarded. Amazon does not
store the encryption key. The key must be appropriate for use
with the algorithm speciﬁed in the x-amz-server-side-
encryption-customer-algorithm header.

Type: String

Default: None

API Version 2006-03-01

646
Amazon Simple Storage Service API Reference
Requests

Name Description Required

Constraints: Must be accompanied by valid x-amz-server-
side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key-MD5 ﬁelds.

x-amz-server- Speciﬁes the base64-encoded 128-bit MD5 digest of the Yes

side-encryption- encryption key according to RFC 1321. Amazon S3 uses this
customer-key-MD5 header for a message integrity check to ensure that the
encryption key was transmitted without error.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key ﬁelds.

Responses
Response Headers
This implementation of the operation can include the following response headers in addition to
the response headers common to all responses. For more information, see Common Response
Headers (p. 683).

Name Description

x-amz-expiration If an Expiration action is conﬁgured for the object

as part of the bucket's lifecycle conﬁguration, Amazon
S3 returns this header. The header value includes an
"expiry-date" component and a URL-encoded "rule-id"
component. For version-enabled buckets, this header
applies only to current versions. Amazon S3 does not
provide a header to infer when a noncurrent version is
eligible for permanent deletion. For more information,
see PutBucketLifecycleConﬁguration (p. 264).

Type: String

success_action_redirect, The URL to which the client is redirected on successful

redirect upload.

Type: String

Ancestor: PostResponse

x-amz-server-side-encryption If you speciﬁed server-side encryption either with AWS

KMS encryption or AWS-managed encryption in your
POST request, the response includes this header. It
conﬁrms the encryption algorithm that Amazon S3 used
to encrypt the object.

Type: String

API Version 2006-03-01

647
Amazon Simple Storage Service API Reference
Requests

Name Description

x-amz-server-side-encryption- If the x-amz-server-side-encryption header is

aws-kms-key-id present and has the value of aws:kms, this header
speciﬁes the ID of the AWS KMS master encryption key
that was used for the object.

Type: String

Type: String

Ancestor: PostResponse

ETag The entity tag is an MD5 hash of the object that you can use to
do conditional GET operations using the If-Modified request
tag with the GET request operation. ETag reﬂects changes only
to the contents of an object, not its metadata.

Type: String

Ancestor: PostResponse

Key The object key name.

Type: String

Ancestor: PostResponse

Location URI of the object.

Type: String

Ancestor: PostResponse

API Version 2006-03-01

648
Amazon Simple Storage Service API Reference
Examples

Special Errors
This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples
Sample Request
POST /Neo HTTP/1.1
Content-Length: 4
Host: quotes.s3.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string
Content-Type: text/plain
Expect: the 100-continue HTTP status code

ObjectContent

Sample Response with Versioning Suspended

The following is a sample response when bucket versioning is suspended:

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
x-amz-version-id: default
Date: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: close
Server: AmazonS3

In this response, the version ID is null.

Sample Response with Versioning Enabled

The following is a sample response when bucket versioning is enabled.

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
x-amz-version-id: 43jfkodU8493jnFJD9fjj3HHNVfdsQUIFDNsidf038jfdsjGFDSIRp
Date: Wed, 01 Mar 2006 12:00:00 GMT
ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f"
Content-Length: 0
Connection: close
Server: AmazonS3

Related Resources
• CopyObject (p. 16)
• POST Object (p. 639)
• GetObject (p. 138)

API Version 2006-03-01

649
Amazon Simple Storage Service API Reference
Related Resources

API Version 2006-03-01

650
Amazon Simple Storage Service API Reference
POST Object restore

POST Object restore

Description
This operation performs the following types of requests:

• select – Perform a select query on an archived object

• restore an archive – Restore an archived object

Querying Archives with Select Requests

When making a select request, do the following:

SELECT * FROM Object

• Assuming that you are not using any headers for data stored in the object, you can specify columns
with positional headers.

SELECT s._1, s._2 FROM Object s WHERE s._3 > 100

SELECT s.Id, s.FirstName, s.SSN FROM S3Object s

API Version 2006-03-01

651
Amazon Simple Storage Service API Reference
Restoring Archives

For more information about using SQL with S3 Glacier Select restore, see SQL Reference for Amazon S3
Select and S3 Glacier Select in the Amazon Simple Storage Service Developer Guide.

When making a select request, you can also do the following:

The following are additional important facts about the select feature:

• The output results are new Amazon S3 objects. Unlike archive retrievals, they are stored until explicitly
deleted—manually or through a lifecycle policy.
• You can issue more than one select request on the same Amazon S3 object. Amazon S3 doesn't
deduplicate requests, so avoid issuing duplicate requests.
• Amazon S3 accepts a select request even if the object has already been restored. A select request
doesn’t return error response 409.

Restoring Archives
Objects in the GLACIER and DEEP_ARCHIVE storage classes are archived. To access an archived object,
you must ﬁrst 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
speciﬁed period, Amazon S3 deletes the temporary copy but the object remains archived in the GLACIER
or DEEP_ARCHIVE storage class that object was restored from.

To restore a speciﬁc object version, you can provide a version ID. If you don't provide a version ID,
Amazon S3 restores the current version.

The time it takes restore jobs to ﬁnish depends on which storage class the object is being restored from
and which data access tier you specify.

When restoring an archived object (or using a select request), you can specify one of the following data
access tier options in the Tier element of the request body:

For more information about archive retrieval options and provisioned capacity for Expedited data
access, see Restoring Archived Objects in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

652
Amazon Simple Storage Service API Reference
Requests

After restoring an archived object, you can update the restoration period by reissuing the request with a
new period. Amazon S3 updates the restoration period relative to the current time and charges only for
the request—there are no data transfer charges. You cannot update the restoration period when Amazon
S3 is actively processing your current restore request for the object.

Requests
Syntax
POST /ObjectName?restore&versionId=VersionID HTTP/1.1
Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))
Content-MD5: MD5

request body

Note
The syntax shows some of the request headers. For a complete list, see "Request Headers," later
in this topic.

Request Parameters
This implementation of the operation does not use request parameters.

Type: Positive integer

Ancestors: RestoreRequest

Container for Glacier job parameters.

GlacierJobParameters No

Do not use this element with a SELECT type of request.

Type: Container

Ancestors: RestoreRequest

Tier The data access tier to use when restoring the archive. No
Standard is the default.

Type: Enum

Valid values: Expedited | Standard | Bulk

Ancestors: GlacierJobParameters

The following XML is the request body for a select query on an archived object:

<RestoreRequest>
<Type>SELECT</Type>

API Version 2006-03-01

654
Amazon Simple Storage Service API Reference
Requests

<Tier>Expedited</Tier>
<Description>Job description</Description>
<SelectParameters>
<Expression>Select * from Object</Expression>
<ExpressionType>SQL</ExpressionType>
<InputSerialization>
<CSV>
<FileHeaderInfo>IGNORE</FileHeaderInfo>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
<Comments>#</Comments>
</CSV>
</InputSerialization>
<OutputSerialization>
<CSV>
<QuoteFields>ASNEEDED</QuoteFields>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
</CSV>
</OutputSerialization>
</SelectParameters>
<OutputLocation>
<S3>
<BucketName>Name of bucket</BucketName>
<Prefix>Key prefix</Prefix>
<CannedACL>Canned ACL string</CannedACL>
<AccessControlList>
<Grantee>
<Type>Grantee Type</Type>
<ID>Grantee identifier</ID>
<URI>Grantee URI</URI>
<Permission>Granted permission</Permission>
<DisplayNmae>Display Name</DisplayName>
<EmailAddress>email</EmailAddress>
</Grantee>
</AccessControlList>
<Encryption>
<EncryptionType>Encryption type</EncryptionType>
<KMSKeyId>KMS Key ID</KMSKeyId>
<KMSContext>Base64-encoded JSON<KMSContext>
</Encryption>
<UserMetadata>
<MetadataEntry>
<Name>Key</Name>
<Value>Value</Value>
</MetadataEntry>
</UserMetadata>
<Tagging>
<TagSet>
<Tag>
<Key>Tag name</Key>
<Value>Tag value</Value>
</Tag>
</TagSet>
</Tagging>
<StorageClass>Storage class</StorageClass>
</S3>
</OutputLocation>
</RestoreRequest>

The following tables explain the XML for a SELECT type of restoration in the request body.

API Version 2006-03-01

655
Amazon Simple Storage Service API Reference
Requests

Name Description Required

RestoreRequest Container for restore information. Yes

Type: Container

Tier The data access tier to use when restoring the archive. No
Standard is the default.

Type: Enum

Valid values: Expedited | Standard | Bulk

Ancestors: RestoreRequest

Description The optional description for the request. No

Type: String

Ancestors: RestoreRequest

Describes the parameters for the select job request.

SelectParameters Yes, if request
type is SELECT
Type: Container

Ancestors: RestoreRequest

OutputLocation Describes the location that receives the results of the select Yes, if request
restore request. type is SELECT

Type: Container for Amazon S3

Ancestors: RestoreRequest

The SelectParameters container element contains the following elements.

Name Description Required

Expression The SQL expression. For example: Yes

• The following SQL expression retrieves the ﬁrst column of the

data from the object stored in CSV format:

SELECT s._1 FROM Object s

• The following SQL expression returns everything from the
object:

SELECT * FROM Object

Type: String

Ancestors: SelectParameters

ExpressionType Identiﬁes the expression type. Yes

Type: String

Valid values: SQL

The CSV container element in the InputSerialization element contains the following
elements.

Name Description Required

RecordDelimiterA single character used to separate individual records in the No

input. Instead of the default value, you can specify an arbitrary
delimiter.

Type: String

Default: \n

Ancestors: CSV

FieldDelimiter A single character used to separate individual ﬁelds in a record. No

You can specify an arbitrary delimiter.

Type: String

Default: ,

Valid values: NONE | USE | IGNORE

Ancestors: CSV

Comments A single character used to indicate that a row should be ignored No

when the character is present at the start of that row. You can
specify any character to indicate a comment line.

Type: String

Ancestors: CSV

The CSV container element (in the OutputSerialization elements) contains the following
elements.

Name Description Required

QuoteFields Indicates whether to use quotation marks around output ﬁelds. No

• ALWAYS: Always use quotation marks for output ﬁelds.

• ASNEEDED: Use quotation marks for output ﬁelds when
needed.

Type: Enum

Valid values: ALWAYS | ASNEEDED

Default: AsNeeded

Ancestors: CSV

RecordDelimiterA single character used to separate individual records in the No

output. Instead of the default value, you can specify an arbitrary
delimiter.

API Version 2006-03-01

658
Amazon Simple Storage Service API Reference
Requests

Name Description Required

Type: String

Default: \n

Ancestors: CSV

FieldDelimiter A single character used to separate individual ﬁelds in a record. No

You can specify an arbitrary delimiter.

Type: String

Default: ,

Ancestors: CSV

QuoteCharacter A single character used for escaping when the ﬁeld delimiter is No
part of the value. For example, if the value is a, b, Amazon S3
wraps this ﬁeld value in quotation marks, as follows: " a , b
".

Type: String

Default: "

Ancestors: CSV

A single character used for escaping the quotation mark

QuoteEscapeCharacter No
character inside an already escaped value. For example, if the
value is " a , b ", Amazon S3 wraps the value in quotation
marks, as follows: """ a , b """.

Type: String

Ancestors: CSV

The S3 container element (in the OutputLocation element) contains the following
elements.

Name Description Required

A list of grants that control access to the staged results.

AccessControlList No

Type: Container for Grant

Ancestors: S3

BucketName The name of the S3 bucket where the select restore results Yes
are stored. The bucket must be in the same AWS Region as the
bucket that contains the input archive object.

Type: String

Ancestors: S3

CannedACL The canned access control list (ACL) to apply to the select No
restore results.

Type: String

API Version 2006-03-01

659
Amazon Simple Storage Service API Reference
Requests

Name Description Required

Ancestors: S3

Encryption Contains encryption information for the stored results. No

Type: Container for Encryption

Ancestors: S3

Prefix The preﬁx that is prepended to the select restore results. The Yes
maximum length for the preﬁx is 512 bytes.

Type: String

Ancestors: S3

StorageClass The class of storage used to store the select request results. No

Type: String

Valid values: STANDARD | REDUCED_REDUNDANCY |

STANDARD_IA | ONEZONE_IA

Ancestors: S3

Tagging Container for tag information. No

Type: Tag structure

Ancestors: S3

UserMetadata Contains a list of metadata to store with the select restore No

results.

Type: MetadataEntry structure

Ancestors: S3

The Grantee container element (in the AccessControlList element) contains the following
elements.

Name Description Required

Ancestors: Encryption

KMSContext Optional. If the encryption type is aws:kms, you can use this No
value to specify the encryption context for the select restore
results.

Type: String

Ancestors: Encryption

KMSKeyId The AWS Key Management Service (AWS KMS) key ID to use for No
object encryption.

Type: String

Ancestors: Encryption

The TagSet container element (in the Tagging element) contains the following element.

Name Description Required

Tag Contains tags. No

Type: Container

API Version 2006-03-01

661
Amazon Simple Storage Service API Reference
Responses

Name Description Required

Ancestors: TagSet

The Tag container element (in the TagSet element) contains the following elements.

Name Description Required

Key Name of the tag. No

Type: String

Ancestors: Tag

Value Value of the tag. No

Type: String

Ancestors: Tag

The MetadataEntry container element (in the UserMetadata element) contains the
following key-value pair elements to store with an object.

Name Description Required

MetadataKey The metadata key. No

Type: String

Ancestors:

MetadataEntry The metadata value. No

Type: String

Ancestors:

Responses
A successful operation returns either the 200 OK or 202 Accepted status code.

• If the object copy is not previously restored, then Amazon S3 returns 202 Accepted in the response.
• If the object copy is previously restored, Amazon S3 returns 200 OK in the response.

Response Headers
This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements
This operation does not return response elements.

API Version 2006-03-01

662
Amazon Simple Storage Service API Reference
Examples

Special Errors

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

RestoreAlreadyInProgress Object restore is already in progress. 409 Conﬂict Client

(This error does not apply to SELECT
type requests.)

Glacier expedited retrievals

GlacierExpeditedRetrievalNotAvailable 503 N/A
are currently not available. Try
again later. (Returned if there is
insuﬃcient capacity to process the
Expedited request. This error
applies only to Expedited retrievals
and not to Standard or Bulk
retrievals.)

Examples
Restore an Object for Two Days Using the Expedited Retrieval
Option
The following restore request restores a copy of the photo1.jpg object from S3 Glacier for a period of
two days using the expedited retrieval option.

POST /photo1.jpg?restore HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Mon, 22 Oct 2012 01:49:52 GMT
Authorization: authorization string
Content-Length: content length

<RestoreRequest>
<Days>2</Days>
<GlacierJobParameters>
<Tier>Expedited</Tier>
</GlacierJobParameters>
</RestoreRequest>

If the examplebucket does not have a restored copy of the object, Amazon S3 returns the following
202 Accepted response.

HTTP/1.1 202 Accepted

x-amz-id-2: GFihv3y6+kE7KG11GEkQhU7/2/cHR3Yb2fCb2S04nxI423Dqwg2XiQ0B/UZlzYQvPiBlZNRcovw=
x-amz-request-id: 9F341CD3C4BA79E0
Date: Sat, 20 Oct 2012 23:54:05 GMT
Content-Length: 0
Server: AmazonS3

If a copy of the object is already restored, Amazon S3 returns a 200 OK response, and updates only the
restored copy's expiry time.

Query an Archive with a SELECT Request

The following is an example select restore request.

API Version 2006-03-01

663
Amazon Simple Storage Service API Reference
Examples

POST /object-one.csv?restore HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Date: Sat, 20 Oct 2012 23:54:05 GMT
Authorization: authorization string
Content-Length: content length

Amazon S3 returns the following 202 Accepted response.

HTTP/1.1 202 Accepted

API Version 2006-03-01

664
Amazon Simple Storage Service API Reference
More Info

More Info
• GetBucketLifecycleConﬁguration (p. 102)
• PutBucketLifecycleConﬁguration (p. 264)
• SQL Reference for Amazon S3 Select and S3 Glacier Select in the Amazon Simple Storage Service
Developer Guide

Browser-Based Uploads Using HTTP POST

Amazon S3 supports HTTP POST requests so that users can upload content directly to Amazon S3.
By using POST, end users can authenticate requests without having to pass data through a secure
intermediary node that protects your credentials. Thus, HTTP POST has the potential to reduce latency.

The following ﬁgure shows an Amazon S3 upload using a POST request.

Uploading Using POST

1 The user accesses your page from a web browser.

2 Your webpage contains an HTML form that contains all the information necessary for the
user to upload content to Amazon S3.

API Version 2006-03-01

665
Amazon Simple Storage Service API Reference
Calculating a Signature

3 The user uploads content to Amazon S3 through the web browser.

The process for sending browser-based POST requests is as follows:

1. Create a security policy specifying conditions that restrict what you want to allow in the request, such
as the bucket name where objects can be uploaded, and key name preﬁxes that you want to allow for
the object that is being created.
2. Create a signature that is based on the policy. For authenticated requests, the form must include a
valid signature and the policy.
3. Create an HTML form that your users can access in order to upload objects to your Amazon S3 bucket.

The following section describes how to create a signature to authenticate a request. For information
about creating forms and security policies, see Creating an HTML Form (Using AWS Signature Version
4) (p. 667).

Calculating a Signature
For authenticated requests, the HTML form must include ﬁelds for a security policy and a signature.

• A security policy (see Creating a POST Policy (p. 671)) controls what is allowed in the request.
• The security policy is the StringToSign (see Introduction to Signing Requests (p. 604)) in your
signature calculation.

To Calculate a signature

1. Create a policy using UTF-8 encoding.

2. Convert the UTF-8-encoded policy bytes to base64. The result is the StringToSign.
3. Create a signing key.
4. Use the signing key to sign the StringToSign using HMAC-SHA256 signing algorithm.

For more information about creating HTML forms, security policies, and an example, see the following:

• Creating an HTML Form (Using AWS Signature Version 4) (p. 667)

API Version 2006-03-01

666
Amazon Simple Storage Service API Reference
Creating HTML Forms

• Creating a POST Policy (p. 671)

• Example: Browser-Based Upload using HTTP POST (Using AWS Signature Version 4) (p. 676)
• Using POST with Adobe Flash to Upload Objects (p. 678)

Creating an HTML Form (Using AWS Signature

Version 4)
Topics
• HTML Form Declaration (p. 667)
• HTML Form Fields (p. 668)

To allow users to upload content to Amazon S3 by using their browsers (HTTP POST requests), you use
HTML forms. HTML forms consist of a form declaration and form ﬁelds. The form declaration contains
high-level information about the request. The form ﬁelds contain detailed request information.

This section describes how to create HTML forms. For a working example of browser-based upload using
HTTP POST and related signature calculations for request authentication, see Example: Browser-Based
Upload using HTTP POST (Using AWS Signature Version 4) (p. 676).

The form and policy must be UTF-8 encoded. You can apply UTF-8 encoding to the form by specifying
charset=UTF-8 in the content attribute. The following is an example of UTF-8 encoding in the HTML
heading.

Following is an example of UTF-8 encoding in a request header.

Content-Type: text/html; charset=UTF-8

Note
The form data and boundaries (excluding the contents of the ﬁle) cannot exceed 20KB.

HTML Form Declaration

The HTML form declaration has the following three attributes:

• action – The URL that processes the request, which must be set to the URL of the
bucket. For example, if the name of your bucket is examplebucket, the URL is http://
examplebucket.s3.amazonaws.com/.
Note
The key name is specified in a form field.
• method – The method must be POST.
• enctype – The enclosure type (enctype) must be set to multipart/form-data for both file uploads
and text area uploads. For more information about enctype, see RFC 1867.

API Version 2006-03-01

667
Amazon Simple Storage Service API Reference
HTML Form Fields

This is a form declaration for the bucket examplebucket.

<form action="http://examplebucket.s3.amazonaws.com/" method="post"

enctype="multipart/form-data">

HTML Form Fields

The following table describes a list of fields that you can use within a form. Among other fields, there is a
signature field that you can use to authenticate requests. There are fields for you to specify the signature
calculation algorithm (x-amz-algorithm), the credential scope (x-amz-credential) that you used to
generate the signing key, and the date (x-amz-date) used to calculate the signature. Amazon S3 uses
this information to re-create the signature. If the signatures match, Amazon S3 processes the request.
Note
The variable ${filename} is automatically replaced with the name of the file provided by the
user and is recognized by all form fields. If the browser or client provides a full or partial path
to the file, only the text following the last slash (/) or backslash (\) is used (for example, C:
\Program Files\directory1\file.txt is interpreted as file.txt). If no file or file name
is provided, the variable is replaced with an empty string.

If you don't provide elements required for authenticated requests, such as the policy element, the
request is assumed to be anonymous and will succeed only if you have conﬁgured the bucket for public
read and write.

Element Name Description Required

acl An Amazon S3 access control list (ACL). If an No

invalid ACL is speciﬁed, Amazon S3 denies the
request. For more information about ACLs, see
Using Amazon S3 ACLs.

Type: String

Default: private

Valid Values: private | public-read |

public-read-write | aws-exec-read |
authenticated-read | bucket-owner-
read | bucket-owner-full-control

Cache-Control REST-speciﬁc headers. For more information, see No

PutObject (p. 310).
Content-Type

Content-Disposition

Content-Encoding

Expires

key The key name of the uploaded object. Yes

To use the ﬁle name provided by the user, use

the ${filename} variable. For example, if you
upload a file photo1.jpg and you specify /
user/user1/${filename} as key name, the
file is stored as /user/user1/photo1.jpg.

API Version 2006-03-01

668
Amazon Simple Storage Service API Reference
HTML Form Fields

Element Name Description Required

For more information, see Object Key and
Metadata in the Amazon Simple Storage Service
Developer Guide.

policy The base64-encoded security policy that Required for

describes what is permitted in the request. For authenticated
authenticated requests, a policy is required. requests

Requests without a security policy are considered

anonymous and will succeed only on a publicly
writable bucket.

success_action_redirect The URL to which the client is redirected upon No

successful upload.

If success_action_redirect is not speciﬁed,

or Amazon S3 cannot interpret the URL, Amazon
S3 returns the empty document type that is
speciﬁed in the success_action_status ﬁeld.

If the upload fails, Amazon S3 returns an error

and does not redirect the user to another URL.

success_action_status The status code returned to the No

client upon successful upload if
success_action_redirect is not speciﬁed.

Valid values are 200, 201, or 204 (default).

If the value is set to 200 or 204, Amazon S3

returns an empty document with the speciﬁed
status code.

If the value is set to 201, Amazon S3 returns

an XML document with a 201 status code. For
information about the content of the XML
document, see POST Object (p. 639).

If the value is not set or is invalid, Amazon S3

returns an empty document with a 204 status
code.
Note
Some versions of the Adobe Flash player
do not properly handle HTTP responses
with an empty body. To support uploads
through Adobe Flash, we recommend
setting success_action_status to
201.

x-amz-algorithm The signing algorithm used to authenticate the Required for

request. For AWS Signature Version 4, the value authenticated
is AWS4-HMAC-SHA256. requests

This ﬁeld is required if a policy document is

included with the request.

API Version 2006-03-01

669
Amazon Simple Storage Service API Reference
HTML Form Fields

Element Name Description Required

x-amz-credential In addition to your access key ID, this ﬁeld also Required for
provides scope information identifying region authenticated
and service for which the signature is valid. This requests
should be the same scope you used in calculating
the signing key for signature calculation.

It is a string of the following form:

<your-access-key-id>/<date>/<aws-
region>/<aws-service>/aws4_request

For example:

AKIAIOSFODNN7EXAMPLE/20130728/us-
east-1/s3/aws4_request
For Amazon S3, the aws-service string is s3.
For a list of Amazon S3 aws-region strings,
see Regions and Endpoints in the AWS General
Reference. This is required if a policy document is
included with the request.

x-amz-date It is the date value in ISO8601 format. For Required for

example, 20130728T000000Z. authenticated
requests
It is the same date you used in creating the
signing key (for example, 20130728). This must
also be the same value you provide in the policy
(x-amz-date) that you signed.

This is required if a policy document is included

with the request.

x-amz-security-token A security token used by Amazon DevPay and No

session credentials

If the request is using Amazon DevPay, it requires

two x-amz-security-token form ﬁelds: one
for the product token and one for the user token.
For more information, see Using DevPay in the
Amazon Simple Storage Service Developer Guide.

If the request is using session credentials, it

requires one x-amz-security-token form.
For more information, see Requesting Temporary
Security Credentials in the IAM User Guide.

x-amz-signature (AWS Signature Version 4) The HMAC-SHA256 Required for

hash of the security policy. authenticated
requests
This ﬁeld is required if a policy document is
included with the request.

API Version 2006-03-01

670
Amazon Simple Storage Service API Reference
Creating a POST Policy

Element Name Description Required

x-amz-meta-* Field names starting with this preﬁx are No

user-deﬁned metadata. Each one is stored
and returned as a set of key-value pairs.
Amazon S3 doesn't validate or interpret user-
deﬁned metadata. For more information, see
PutObject (p. 310).

x-amz-* See POST Object (POST Object (p. 639) for other No
x-amz-* headers.

file File or text content. Yes

The ﬁle or content must be the last ﬁeld in the

form.

You cannot upload more than one ﬁle at a time.

Conditional items are required for authenticated requests and are optional for anonymous requests.

Now that you know how to create forms, next you can create a security policy that you can sign. For
more information, see Creating a POST Policy (p. 671).

Creating a POST Policy

Topics
• Expiration (p. 672)
• Condition Matching (p. 672)
• Conditions (p. 672)
• Character Escaping (p. 675)

The policy required for making authenticated requests using HTTP POST is a UTF-8 and base64-encoded
document written in JavaScript Object Notation (JSON) that speciﬁes conditions that the request must
meet. Depending on how you design your policy document, you can control the access granularity per-
upload, per-user, for all uploads, or according to other designs that meet your needs.

This section describes the POST policy. For example signature calculations using POST policy, see
Example: Browser-Based Upload using HTTP POST (Using AWS Signature Version 4) (p. 676).
Note
Although the policy document is optional, we highly recommend that you use one in order to
control what is allowed in the request. If you make the bucket publicly writable, you have no
control at all over which users can write to your bucket.

The following is an example of a POST policy document.

{ "expiration": "2007-12-01T12:00:00.000Z",
"conditions": [
{"acl": "public-read" },
{"bucket": "johnsmith" },
["starts-with", "$key", "user/eric/"],
]
}

API Version 2006-03-01

671
Amazon Simple Storage Service API Reference
Expiration

The POST policy always contains the expiration and conditions elements. The example policy
uses two condition matching types (exact matching and starts-with matching). The following sections
describe these elements.

Expiration
The expiration element speciﬁes the expiration date and time of the POST policy in ISO8601 GMT
date format. For example, 2013-08-01T12:00:00.000Z speciﬁes that the POST policy is not valid
after midnight GMT on August 1, 2013.

Condition Matching
Following is a table that describes condition matching types that you can use to specify POST policy
conditions (described in the next section). Although you must specify one condition for each form ﬁeld
that you specify in the form, you can create more complex matching criteria by specifying multiple
conditions for a form ﬁeld.

Condition Description
Match Type

Exact Matches The form ﬁeld value must match the value speciﬁed. This example indicates that
the ACL must be set to public-read:

{"acl": "public-read" }

This example is an alternate way to indicate that the ACL must be set to public-read:

[ "eq", "$acl", "public-read" ]

Starts With The value must start with the speciﬁed value. This example indicates that the object
key must start with user/user1:

["starts-with", "$key", "user/user1/"]

Matching Any To conﬁgure the POST policy to allow any content within a form ﬁeld, use
Content starts-with with an empty value (""). This example allows any value for
success_action_redirect:

["starts-with", "$success_action_redirect", ""]

Specifying For form ﬁelds that accept a range, separate the upper and lower limit with a
Ranges comma. This example allows a ﬁle size from 1 to 10 MiB:

["content-length-range", 1048576, 10485760]

The speciﬁc conditions supported in a POST policy are described in Conditions (p. 672).

Conditions
The conditions in a POST policy is an array of objects, each of which is used to validate the request.
You can use these conditions to restrict what is allowed in the request. For example, the preceding policy
conditions require the following:

API Version 2006-03-01

672
Amazon Simple Storage Service API Reference
Conditions

• Request must specify the johnsmith bucket name.

• Object key name must have the user/eric preﬁx.
• Object ACL must be set to public-read.

Each form field that you specify in a form (except x-amz-signature, file, policy, and field names
that have an x-ignore- prefix) must appear in the list of conditions.
Note
All variables within the form are expanded prior to validating the POST policy. Therefore, all
condition matching should be against the expanded form fields. Suppose that you want to
restrict your object key name to a specific prefix (user/user1). In this case, you set the key
form field to user/user1/${filename}. Your POST policy should be [ "starts-with",
"$key", "user/user1/" ] (do not enter [ "starts-with", "$key", "user/user1/
${filename}" ]). For more information, see Condition Matching (p. 672).

Policy document conditions are described in the following table.

Element Name Description

acl Speciﬁes the ACL value that must be used in the form
submission.

This condition supports exact matching and starts-with

condition match type discussed in the following section.

bucket Speciﬁes the acceptable bucket name.

This condition supports exact matching condition match type.

content-length-range The minimum and maximum allowable size for the uploaded
content.

This condition supports content-length-range condition

match type.

Cache-Control REST-speciﬁc headers. For more information, see POST

Object (p. 639).
Content-Type
This condition supports exact matching and starts-with
Content-Disposition condition match type.

Content-Encoding

Expires

key The acceptable key name or a preﬁx of the uploaded object.

This condition supports exact matching and starts-with

condition match type.

success_action_redirect The URL to which the client is redirected upon successful

upload.
redirect
This condition supports exact matching and starts-with
condition match type.

success_action_status The status code returned to the client upon successful upload if
success_action_redirect is not speciﬁed.

API Version 2006-03-01

673
Amazon Simple Storage Service API Reference
Conditions

Element Name Description

This condition supports exact matching.

x-amz-algorithm The signing algorithm that must be used during signature

calculation. For AWS Signature Version 4, the value is AWS4-
HMAC-SHA256.

This condition supports exact matching.

x-amz-credential The credentials that you used to calculate the signature. It

provides access key ID and scope information identifying region
and service for which the signature is valid. This should be the
same scope you used in calculating the signing key for signature
calculation.

It is a string of the following form:

<your-access-key-id>/<date>/<aws-region>/<aws-
service>/aws4_request

For example:

AKIAIOSFODNN7EXAMPLE/20130728/us-east-1/s3/
aws4_request

For Amazon S3, the aws-service string is s3. For a list of

Amazon S3 aws-region strings, see Regions and Endpoints
in the AWS General Reference. This is required if a POST policy
document is included with the request.

This condition supports exact matching.

x-amz-date The date value speciﬁed in the ISO8601 formatted string. For
example, 20130728T000000Z. The date must be same that you
used in creating the signing key for signature calculation.

This is required if a POST policy document is included with the

request.

This condition supports exact matching.

x-amz-security-token Amazon DevPay security token.

Each request that uses Amazon DevPay requires two x-amz-

security-token form ﬁelds: one for the product token
and one for the user token. As a result, the values must
be separated by commas. For example, if the user token is
eW91dHViZQ== and the product token is b0hnNVNKWVJIQTA=,
you set the POST policy entry to: { "x-amz-security-
token": "eW91dHViZQ==,b0hnNVNKWVJIQTA=" }.

For more information about Amazon DevPay, see Using DevPay

in the Amazon Simple Storage Service Developer Guide.

x-amz-meta-* User-speciﬁed metadata.

This condition supports exact matching and starts-with

condition match type.

API Version 2006-03-01

674
Amazon Simple Storage Service API Reference
Character Escaping

Element Name Description

x-amz-* See POST Object (POST Object (p. 639) for other x-amz-*
headers.

This condition supports exact matching.

Note
If your toolkit adds more form fields (for example, Flash adds filename), you must add them to
the POST policy document. If you can control this functionality, prefix x-ignore- to the field
so Amazon S3 ignores the feature and it won't affect future versions of this feature.

Character Escaping
Characters that must be escaped within a POST policy document are described in the following table.

Escape Description
Sequence

\\ Backslash

\$ Dollar symbol

\b Backspace

\f Form feed

\n New line

\r Carriage return

\t Horizontal tab

\v Vertical tab

\uxxxx All Unicode characters

Now that you are acquainted with forms and policies, and understand how signing works, you can try
a POST upload example. You need to write the code to calculate the signature. The example provides
a sample form, and a POST policy that you can use to test your signature calculations. For more
information, see Example: Browser-Based Upload using HTTP POST (Using AWS Signature Version
4) (p. 676).

API Version 2006-03-01

675
Amazon Simple Storage Service API Reference
POST Upload Example

Example: Browser-Based Upload using HTTP POST

(Using AWS Signature Version 4)
This section shows an example of using an HTTP POST request to upload content directly to Amazon S3.

For more information on Signature Version 4, see Signature Version 4 Signing Process.

Uploading a File to Amazon S3 Using HTTP POST

This example provides a sample POST policy and a form that you can use to upload a file. The topic uses
the example policy and fictitious credentials to show you the workflow and resulting signature and policy
hash. You can use this data as test suite to verify your signature calculation code.

The example uses the following example credentials the signature calculations. You can use these
credentials to verify your signature calculation code. However, you must then replace these with your
own credentials when sending requests to AWS.

Parameter Value

AWSAccessKeyId AKIAIOSFODNN7EXAMPLE

AWSSecretAccessKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Sample Policy and Form

The following POST policy supports uploads to Amazon S3 with speciﬁc conditions.

{ "expiration": "2015-12-30T12:00:00.000Z",
"conditions": [
{"bucket": "sigv4examplebucket"},
["starts-with", "$key", "user/user1/"],
{"acl": "public-read"},
{"success_action_redirect": "http://sigv4examplebucket.s3.amazonaws.com/
successful_upload.html"},
["starts-with", "$Content-Type", "image/"],
{"x-amz-meta-uuid": "14365123651274"},
{"x-amz-server-side-encryption": "AES256"},
["starts-with", "$x-amz-meta-tag", ""],

{"x-amz-credential": "AKIAIOSFODNN7EXAMPLE/20151229/us-east-1/s3/aws4_request"},
{"x-amz-algorithm": "AWS4-HMAC-SHA256"},
{"x-amz-date": "20151229T000000Z" }
]
}

This POST policy sets the following conditions on the request:

API Version 2006-03-01

676
Amazon Simple Storage Service API Reference
Uploading a File to Amazon S3 Using HTTP POST

• The ACL must be set to public-read.

• If the upload succeeds, the user's browser is redirected to http://
sigv4examplebucket.s3.amazonaws.com/successful_upload.html.
• The object must be an image ﬁle.
• The x-amz-meta-uuid tag must be set to 14365123651274.
• The x-amz-meta-tag can contain any value.

The following is a Base64-encoded version of this POST policy. You use this value as your StringToSign in
signature calculation.

eyAiZXhwaXJhdGlvbiI6ICIyMDE1LTEyLTMwVDEyOjAwOjAwLjAwMFoiLA0KICAiY29uZGl0aW9ucyI6IFsNCiAgICB7ImJ1Y2tldCI

When you copy/paste the preceding policy, it should have carriage returns and new lines for your
computed hash to match this value (ie. ASCII text, with CRLF line terminators).

Using example credentials to create a signature, the signature value is as follows (in signature
calculation, the date is same as the x-amz-date in the policy (20151229):

8afdbf4008c03f22c2cd3cdb72e4afbb1f6a588f3255ac628749a66d7f09699e

The following example form specifies the preceding POST policy and supports a POST request to the
sigv4examplebucket. Copy/paste the content in a text editor and save it as exampleform.html. You
can then upload image files to the specific bucket using the exampleform.html. Your request will succeed
if the signature you provide matches the signature Amazon S3 calculates.
Note
You must update the bucket name, dates, credential, policy, and signature with valid values for
this to successfully upload to S3.

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

</head>
<body>

<form action="http://sigv4examplebucket.s3.amazonaws.com/" method="post"

enctype="multipart/form-data">
Key to upload:
<input type="input" name="key" value="user/user1/${filename}" /><br />
<input type="hidden" name="acl" value="public-read" />
<input type="hidden" name="success_action_redirect" value="http://
sigv4examplebucket.s3.amazonaws.com/successful_upload.html" />
Content-Type:
<input type="input" name="Content-Type" value="image/jpeg" /><br />
<input type="hidden" name="x-amz-meta-uuid" value="14365123651274" />
<input type="hidden" name="x-amz-server-side-encryption" value="AES256" />
<input type="text" name="X-Amz-Credential" value="AKIAIOSFODNN7EXAMPLE/20151229/us-
east-1/s3/aws4_request" />
<input type="text" name="X-Amz-Algorithm" value="AWS4-HMAC-SHA256" />
<input type="text" name="X-Amz-Date" value="20151229T000000Z" />

Tags for File:

API Version 2006-03-01

677
Amazon Simple Storage Service API Reference
Using POST with Adobe Flash

<input type="file" name="file" /> <br />

<input type="submit" name="submit" value="Upload to Amazon S3" />
</form>

</html>

The post parameters are case insensitive. For example, you can specify x-amz-signature or X-Amz-
Signature.

Using POST with Adobe Flash to Upload Objects

This section discusses uploading objects with an HTTP POST request when using Adobe Flash.

Using POST with Adobe Flash

This section describes how to use POST with Adobe Flash.

Adobe Flash Player Security

By default, the Adobe Flash Player security model prohibits making network connections to servers
outside the domain that serves the Adobe Flash (.swf) ﬁle.

To override the default, you must upload a publicly readable crossdomain.xml ﬁle to the bucket that
will accept POST uploads. Here is a sample crossdomain.xml ﬁle:

<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM
"http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">
<cross-domain-policy>
<allow-access-from domain="*" secure="false" />
</cross-domain-policy>

For more information about the Adobe Flash security model, go to the Adobe web site.

When you add the crossdomain.xml ﬁle to your bucket, any Adobe Flash Player can connect to the
crossdomain.xml ﬁle within your bucket. However, crossdomain.xml does not grant access to the
Amazon S3 bucket.

Other Adobe Flash Considerations

The FileReference class in the Adobe Flash API adds the Filename form ﬁeld to the POST request. When
you build an Adobe Flash application that uploads ﬁles to Amazon S3 by using the FileReference
class, include the following condition in your policy:

['starts-with', '$Filename', '']

Some versions of the Adobe Flash Player do not properly handle HTTP responses that have an
empty body. To conﬁgure POST to return a response that does not have an empty body, set
success_action_status to 201. Then, Amazon S3 will return an XML document with a 201 status
code. For information about using this as an optional element (currently the only allowed value is the
content of the XML document), see POST Object (p. 639). For information about form ﬁelds, see HTML
Form Fields (p. 668).

API Version 2006-03-01

678
Amazon Simple Storage Service API Reference
Browser-Based Uploads Using AWS Amplify

Browser-Based Uploads to Amazon S3 Using the

AWS Amplify Library
This section describes how to upload ﬁles to Amazon S3 using the AWS Amplify JavaScript library.

For information about setting up the AWS Amplify library, see AWS Amplify Installation and
Conﬁguration.

Using the AWS Amplify JavaScript library to Upload

Files to Amazon S3
The AWS Amplify library Storage module gives a simple browser-based upload mechanism for
managing user content in public or private Amazon S3 storage.

Example : AWS Amplify Manual Setup

The following example shows the manual setup for using the AWS Amplify Storage module. The default
implementation of the Storage module uses Amazon S3.

import Amplify from 'aws-amplify';

Amplify.configure(
Auth: {
identityPoolId: 'XX-XXXX-X:XXXXXXXX-XXXX-1234-abcd-1234567890ab', //REQUIRED -
Amazon Cognito Identity Pool ID
region: 'XX-XXXX-X', // REQUIRED - Amazon Cognito Region
userPoolId: 'XX-XXXX-X_abcd1234', //OPTIONAL - Amazon Cognito User Pool ID
userPoolWebClientId: 'XX-XXXX-X_abcd1234', //OPTIONAL - Amazon Cognito Web Client
ID
},
Storage: {
bucket: '', //REQUIRED - Amazon S3 bucket
region: 'XX-XXXX-X', //OPTIONAL - Amazon service region
}
);

Example : Put data into Amazon S3

The following example shows how to put public data into Amazon S3.

Storage.put('test.txt', 'Hello')
.then (result => console.log(result))
.catch(err => console.log(err));

The following example shows how to put private data into Amazon S3.

Storage.put('test.txt', 'Private Content', {

level: 'private',
contentType: 'text/plain'
})
.then (result => console.log(result))
.catch(err => console.log(err));

For more information about using the AWS Amplify Storage module, see AWS Amplify Storage.

API Version 2006-03-01

679
Amazon Simple Storage Service API Reference
More Info

More Info
AWS Amplify Quick Start

API Version 2006-03-01

680
Amazon Simple Storage Service API Reference

Common Request Headers

The following table describes headers that can be used by various types of Amazon S3 REST requests.

Header Name Description

Authorization The information required for request authentication. For more

information, go to The Authentication Header in the Amazon
Simple Storage Service Developer Guide. For anonymous requests
this header is not required.

Content-Length Length of the message (without the headers) according to RFC

2616. This header is required for PUTs and operations that load
XML, such as logging and ACLs.

Content-Type The content type of the resource in case the request content in
the body. Example: text/plain

Content-MD5 The base64 encoded 128-bit MD5 digest of the message (without
the headers) according to RFC 1864. This header can be used as a
message integrity check to verify that the data is the same data
that was originally sent. Although it is optional, we recommend
using the Content-MD5 mechanism as an end-to-end integrity
check. For more information about REST request authentication,
go to REST Authentication in the Amazon Simple Storage Service
Developer Guide.

Date The current date and time according to the requester. Example:
Wed, 01 Mar 2006 12:00:00 GMT. When you specify the
Authorization header, you must specify either the x-amz-
date or the Date header.

Expect When your application uses 100-continue, it does not send the
request body until it receives an acknowledgment. If the message
is rejected based on the headers, the body of the message is not
sent. This header can be used only if you are sending a body.

Valid Values: 100-continue

Host For path-style requests, the value is s3.amazonaws.com.

For virtual-style requests, the value is
BucketName.s3.amazonaws.com. For more information, go to
Virtual Hosting in the Amazon Simple Storage Service Developer
Guide.

This header is required for HTTP 1.1 (most toolkits add this header
automatically); optional for HTTP/1.0 requests.

x-amz-content-sha256 When using signature version 4 to authenticate request, this

API Version 2006-03-01

681
Amazon Simple Storage Service API Reference

Header Name Description

no payload. For more information, see Signature Calculations for
the Authorization Header: Transferring Payload in Multiple Chunks
(Chunked Upload) (AWS Signature Version 4) (p. 618).

x-amz-date The current date and time according to the requester. Example:
Wed, 01 Mar 2006 12:00:00 GMT. When you specify the
Authorization header, you must specify either the x-amz-
date or the Date header. If you specify both, the value speciﬁed
for the x-amz-date header takes precedence.

x-amz-security-token This header can be used in the following scenarios:

• Provide security tokens for Amazon DevPay operations -

Each request that uses Amazon DevPay requires two x-amz-
security-token headers: one for the product token and one
for the user token. When Amazon S3 receives an authenticated
request, it compares the computed signature with the provided
signature. Improperly formatted multi-value headers used to
calculate a signature can cause authentication issues.
• Provide security token when using temporary security
credentials - When making requests using temporary security
credentials you obtained from IAM you must provide a security
token using this header. To learn more about temporary security
credentials, go to Making Requests.

This header is required for requests that use Amazon DevPay and
requests that are signed using temporary security credentials.

API Version 2006-03-01

682
Amazon Simple Storage Service API Reference

Common Response Headers

The following table describes response headers that are common to most AWS S3 responses.

Name Description

Content-Length The length in bytes of the body in the response.

Type: String

Default: None

Content-Type The MIME type of the content. For example, Content-Type: text/html;
charset=utf-8

Type: String

Default: None

Connection speciﬁes whether the connection to the server is open or closed.

Type: Enum

Valid Values: open | close

Default: None

Date The date and time Amazon S3 responded, for example, Wed, 01 Mar 2006
12:00:00 GMT.

Type: String

Default: None

ETag The entity tag is a hash of the object. The ETag reﬂects changes only to the
contents of an object, not its metadata. The ETag may or may not be an MD5
digest of the object data. Whether or not it is depends on how the object was
created and how it is encrypted as described below:

• Objects created by the PUT Object, POST Object, or Copy operation, or

through the AWS Management Console, and are encrypted by SSE-S3 or
plaintext, have ETags that are an MD5 digest of their object data.
• Objects created by the PUT Object, POST Object, or Copy operation, or
through the AWS Management Console, and are encrypted by SSE-C or SSE-
KMS, have ETags that are not an MD5 digest of their object data.
• If an object is created by either the Multipart Upload or Part Copy operation,
the ETag is not an MD5 digest, regardless of the method of encryption.

Type: String

Server The name of the server that created the response.

Type: String

Default: AmazonS3

API Version 2006-03-01

683
Amazon Simple Storage Service API Reference

Name Description

x-amz-delete- Speciﬁes whether the object returned was (true) or was not (false) a delete
marker marker.

Type: Boolean

Valid Values: true | false

Default: false

x-amz-id-2 A special token that is used together with the x-amz-request-id header to
help AWS troubleshoot problems. For information about AWS support using
these request IDs, see Troubleshooting Amazon S3.

Type: String

Default: None

x-amz-request- A value created by Amazon S3 that uniquely identiﬁes the request. This value
id is used together with the x-amz-id-2 header to help AWS troubleshoot
problems. For information about AWS support using these request IDs, see
Troubleshooting Amazon S3.

Type: String

Default: None

x-amz-version- The version of the object. When you enable versioning, Amazon S3 generates
id a random number for objects added to a bucket. The value is UTF-8 encoded
and URL ready. When you PUT an object in a bucket where versioning has been
suspended, the version ID is always null.

Type: String

Valid Values: null | any URL-ready, UTF-8 encoded string

Default: null

API Version 2006-03-01

684
Amazon Simple Storage Service API Reference
REST Error Responses

Error Responses
This section provides reference information about Amazon S3 errors.
Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

Topics
• REST Error Responses (p. 685)
• List of Error Codes (p. 686)
• List of SELECT Object Content Error Codes (p. 693)
• List of Replication-Related Error Codes (p. 699)

REST Error Responses

When an error occurs, the header information contains the following:

• Content-Type: application/xml
• An appropriate 3xx, 4xx, or 5xx HTTP status code

The body or the response also contains information about the error. The following sample error response
shows the structure of response elements common to all REST error responses.

<?xml version="1.0" encoding="UTF-8"?>

<Error>
<Code>NoSuchKey</Code>
<Message>The resource you requested does not exist</Message>
<Resource>/mybucket/myfoto.jpg</Resource>
<RequestId>4442587FB7D0A2F9</RequestId>
</Error>

The following table explains the REST error response elements.

Name Description

Code The error code is a string that uniquely identiﬁes an error condition. It is meant to
be read and understood by programs that detect and handle errors by type. For
more information, see List of Error Codes (p. 686).

For information about general response elements, go to Error Responses.

List of Error Codes

The following table lists Amazon S3 error codes.

Error Code Description HTTP SOAP

Status Fault
Code Code
Preﬁx

AccessDenied Access Denied 403 Client

Forbidden

AccountProblem There is a problem with your AWS 403 Client

account that prevents the operation Forbidden
from completing successfully. Please
contact AWS Support for further
assistance, see Contact Us.

AllAccessDisabled All access to this Amazon S3 resource 403 Client

has been disabled. Please contact Forbidden
AWS Support for further assistance,
see Contact Us.

API Version 2006-03-01

686
Amazon Simple Storage Service API Reference
List of Error Codes

Error Code Description HTTP SOAP

Status Fault
Code Code
Preﬁx

AmbiguousGrantByEmailAddress The email address you provided 400 Bad Client

is associated with more than one Request
account.

AuthorizationHeaderMalformed The authorization header you 400 Bad N/A

provided is invalid. Request

BadDigest The Content-MD5 you speciﬁed did 400 Bad Client

not match what we received. Request

BucketAlreadyExists The requested bucket name is not 409 Client

available. The bucket namespace is Conflict
shared by all users of the system.
Please select a diﬀerent name and try
again.

BucketAlreadyOwnedByYou The bucket you tried to create already 409 Client

exists, and you own it. Amazon S3 Conflict
returns this error in all AWS Regions (in all
except us-east-1 (N. Virginia). For Regions
legacy compatibility, if you re-create except us-
an existing bucket that you already east-1)
own in us-east-1, Amazon S3 returns
200 OK and resets the bucket access
control lists (ACLs).

BucketNotEmpty The bucket you tried to delete is not 409 Client

InvalidObjectState The operation is not valid for the 403 Client

current state of the object. Forbidden

InvalidPart One or more of the speciﬁed parts 400 Bad Client

could not be found. The part might Request
not have been uploaded, or the
speciﬁed entity tag might not have
matched the part's entity tag.

InvalidPartOrder The list of parts was not in ascending 400 Bad Client
order. Parts list must be speciﬁed in Request
order by part number.

InvalidPayer All access to this object has been 403 Client

disabled. Please contact AWS Support Forbidden
for further assistance, see Contact Us.

API Version 2006-03-01

688
Amazon Simple Storage Service API Reference
List of Error Codes

Error Code Description HTTP SOAP

Status Fault
Code Code
Preﬁx

InvalidPolicyDocument The content of the form does not 400 Bad Client
meet the conditions speciﬁed in the Request
policy document.

InvalidRange The requested range cannot be 416 Client

satisﬁed. Requested
Range
Not
Satisfiable

InvalidRequest Please use AWS4-HMAC-SHA256. 400 Bad N/A

Request

InvalidRequest SOAP requests must be made over an 400 Bad Client

HTTPS connection. Request

InvalidRequest Amazon S3 Transfer Acceleration is 400 Bad N/A

not supported for buckets with non- Request
DNS compliant names.

InvalidRequest Amazon S3 Transfer Acceleration 400 Bad N/A

is not supported for buckets with Request
periods (.) in their names.

InvalidRequest Amazon S3 Transfer Accelerate 400 Bad N/A

endpoint only supports virtual style Request
requests.

InvalidRequest Amazon S3 Transfer Accelerate is not 400 Bad N/A

conﬁgured on this bucket. Request

InvalidRequest Amazon S3 Transfer Accelerate is 400 Bad N/A

disabled on this bucket. Request

InvalidRequest Amazon S3 Transfer Acceleration is 400 Bad N/A

not supported on this bucket. Contact Request
AWS Support for more information.

InvalidRequest Amazon S3 Transfer Acceleration 400 Bad N/A

cannot be enabled on this bucket. Request
Contact AWS Support for more
information.

InvalidSecurity The provided security credentials are 403 Client

not valid. Forbidden

InvalidSOAPRequest The SOAP request body is invalid. 400 Bad Client

maximum allowed metadata size. Request

MethodNotAllowed The speciﬁed method is not allowed 405 Client

against this resource. Method
Not
Allowed

MissingAttachment A SOAP attachment was expected, N/A Client

but none were found.

MissingContentLength You must provide the Content-Length 411 Client

HTTP header. Length
Required

MissingRequestBodyError This happens when the user sends an 400 Bad Client
empty XML document as a request. Request
The error message is, "Request body is
empty."

API Version 2006-03-01

690
Amazon Simple Storage Service API Reference
List of Error Codes

Error Code Description HTTP SOAP

Status Fault
Code Code
Preﬁx

MissingSecurityElement The SOAP 1.1 request is missing a 400 Bad Client

security element. Request

MissingSecurityHeader Your request is missing a required 400 Bad Client

header. Request

NoLoggingStatusForKey There is no such thing as a logging 400 Bad Client

status subresource for a key. Request

NoSuchBucket The speciﬁed bucket does not exist. 404 Not Client
Found

NoSuchBucketPolicy The speciﬁed bucket does not have a 404 Not Client
bucket policy. Found

NoSuchKey The speciﬁed key does not exist. 404 Not Client
Found

NoSuchLifecycleConfiguration The lifecycle conﬁguration does not 404 Not Client

exist. Found

NoSuchUpload The speciﬁed multipart upload does 404 Not Client

not exist. The upload ID might be Found
invalid, or the multipart upload might
have been aborted or completed.

NoSuchVersion Indicates that the version ID speciﬁed 404 Not Client

in the request does not match an Found
existing version.

NotImplemented A header you provided implies 501 Not Server

functionality that is not implemented. Implemented

NotSignedUp Your account is not signed up for the 403 Client

Amazon S3 service. You must sign Forbidden
up before you can use Amazon S3.
You can sign up at the following URL:
https://aws.amazon.com/s3

OperationAborted A conﬂicting conditional operation 409 Client

is currently in progress against this Conflict
resource. Try again.

PermanentRedirect The bucket you are attempting to 301 Client

access must be addressed using the Moved
speciﬁed endpoint. Send all future Permanently
requests to this endpoint.

PreconditionFailed At least one of the preconditions you 412 Client

speciﬁed did not hold. Precondition
Failed

Redirect Temporary redirect. 307 Client

Moved
Temporarily

API Version 2006-03-01

691
Amazon Simple Storage Service API Reference
List of Error Codes

Error Code Description HTTP SOAP

Status Fault
Code Code
Preﬁx

RestoreAlreadyInProgress Object restore is already in progress. 409 Client

Conflict

RequestIsNotMultiPartContent Bucket POST must be of the 400 Bad Client

enclosure-type multipart/form-data. Request

RequestTimeout Your socket connection to the server 400 Bad Client

was not read from or written to Request
within the timeout period.

RequestTimeTooSkewed The diﬀerence between the request 403 Client

time and the server's time is too large. Forbidden

RequestTorrentOfBucketError Requesting the torrent ﬁle of a bucket 400 Bad Client

is not permitted. Request

The server-side encryption

ServerSideEncryptionConfigurationNotFoundError 400 Bad Client
conﬁguration was not found. Request

ServiceUnavailable Reduce your request rate. 503 Server

Service
Unavailable

SignatureDoesNotMatch The request signature we calculated 403 Client

does not match the signature Forbidden
you provided. Check your AWS
secret access key and signing
method. For more information, see
REST Authentication and SOAP
Authentication for details.

SlowDown Reduce your request rate. 503 Slow Server

Down

TemporaryRedirect You are being redirected to the bucket 307 Client

while DNS updates. Moved
Temporarily

TokenRefreshRequired The provided token must be 400 Bad Client

refreshed. Request

TooManyBuckets You have attempted to create more 400 Bad Client

buckets than allowed. Request

UnexpectedContent This request does not support 400 Bad Client

content. Request

UnresolvableGrantByEmailAddress The email address you provided does 400 Bad Client
not match any account on record. Request

UserKeyMustBeSpecified The bucket POST must contain the 400 Bad Client
specified field name. If it is specified, Request
check the order of the fields.

API Version 2006-03-01

692
Amazon Simple Storage Service API Reference
List of SELECT Object Content Error Codes

List of SELECT Object Content Error Codes

The following table contains special errors that SELECT Object Content might return. For general
information about Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

Busy The service is unavailable. Please 503 Client

retry.

ColumnTooLong The length of a column in the result 400 Client

is greater than maxCharsPerColumn
of 1 MB.

EmptyRequestBody Request body cannot be empty. 400 Client

ExpressionTooLong The SQL expression is too long: The 400 Client

maximum byte-length for the SQL
expression is 256 KB.

IllegalSqlFunctionArgumentIllegal argument was used in the 400 Client

SQL function.

InternalError Encountered an internal error. 500 Client

InvalidColumnIndex Column index in the SQL expression 400 Client

is invalid.

InvalidCompressionFormat The ﬁle is not in a supported 400 Client

compression format. Only GZIP and
BZIP2 are supported.

InvalidExpressionType The ExpressionType is invalid. Only 400 Client

SQL expressions are supported.

InvalidFileHeaderInfo The FileHeaderInfo is invalid. 400 Client

Only NONE, USE, and IGNORE are
supported.

InvalidKeyPath Key path in the SQL expression is 400 Client

invalid.

InvalidJsonType The JsonType is invalid. Only 400 Client

DOCUMENT and LINES are
supported.

InvalidQuoteFields The QuoteFields is invalid. Only 400 Client

ALWAYS and ASNEEDED are
supported.

InvalidRequestParameter The value of a parameter 400 Client

in SelectRequest element is
invalid. Check the service API
documentation and try again.

OverMaxColumn The number of columns in the 400 Client

result is greater than the maximum
allowable number of columns.

API Version 2006-03-01

693
Amazon Simple Storage Service API Reference
List of SELECT Object Content Error Codes

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

OverMaxRecordSize The length of a record in the 400 Client

input or result is greater than
maxCharsPerRecord of 1 MB.

TruncatedInput Object decompression failed. 400 Client

Check that the object is properly
compressed using the format
speciﬁed in the request.

UnauthorizedAccess You are not authorized to perform 401 Client

this operation.

CSVParsingError Encountered an error parsing the 400 Client

CSV ﬁle. Check the ﬁle and try again.

JSONParsingError Encountered an error parsing the 400 Client

JSON ﬁle. Check the ﬁle and try
again.

ExternalEvalException The query cannot be evaluated. 400 Client

Check the ﬁle and try again.

InvalidDataType The SQL expression contains an 400 Client

invalid data type.

Encountered an invalid record type.

UnrecognizedFormatException 400 Client

InvalidTextEncoding Invalid encoding type. Only UTF-8 400 Client

encoding is supported.

InvalidDataSource Invalid data source type. Only CSV, 400 Client

JSON, and Parquet are supported.

InvalidTableAlias The SQL expression contains an 400 Client

invalid table alias.

MalformedXML The XML provided was not well- 400 Client

formed or did not validate against
our published schema. Check the
service documentation and try
again.

Multiple data sources are not

MultipleDataSourcesUnsupported 400 Client
supported.

MissingRequiredParameter The SelectRequest entity is missing 400 Client

a required parameter. Check the
service documentation and try
again.

InputSerialization speciﬁes more

ObjectSerializationConflict 400 Client
than one format (CSV, JSON, or
Parquet), or OutputSerialization
speciﬁes more than one format (CSV
or JSON). InputSerialization and
OutputSerialization can only specify
one format each.

API Version 2006-03-01

694
Amazon Simple Storage Service API Reference
List of SELECT Object Content Error Codes

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

ParseExpectedWhenClause Did not ﬁnd the expected WHEN 400 Client

clause in the SQL expression. CASE is
not supported.

API Version 2006-03-01

695
Amazon Simple Storage Service API Reference
List of SELECT Object Content Error Codes

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

ParseUnsupportedToken The SQL expression contains an 400 Client

unsupported token.

The SQL expression contains an

ParseUnsupportedLiteralsGroupBy 400 Client
unsupported use of GROUP BY.

ParseExpectedMember The SQL expression contains an 400 Client

unsupported use of MEMBER.

ParseUnsupportedSelect The SQL expression contains an 400 Client

unsupported use of SELECT.

ParseUnsupportedCase The SQL expression contains an 400 Client

unsupported use of CASE.

ParseUnsupportedCaseClauseThe SQL expression contains an 400 Client

unsupported use of CASE.

ParseUnsupportedAlias The SQL expression contains an 400 Client

unsupported use of ALIAS.

ParseUnsupportedSyntax The SQL expression contains 400 Client

unsupported syntax.

ParseUnknownOperator The SQL expression contains an 400 Client

invalid operator.

ParseInvalidPathComponent The SQL expression contains an 400 Client

invalid path component.

ParseMissingIdentAfterAt Did not ﬁnd the expected identiﬁer 400 Client

after the @ symbol in the SQL
expression.

ParseUnexpectedOperator The SQL expression contains an 400 Client

unexpected operator.

ParseUnexpectedTerm The SQL expression contains an 400 Client

unexpected term.

ParseUnexpectedToken The SQL expression contains an 400 Client

unexpected token.

ParseUnExpectedKeyword The SQL expression contains an 400 Client

unexpected keyword.

ParseExpectedExpression Did not ﬁnd the expected SQL 400 Client

expression.

Did not ﬁnd the expected left

ParseExpectedLeftParenAfterCast 400 Client
parenthesis after CAST in the SQL
expression.

Did not ﬁnd expected the left

ParseExpectedLeftParenValueConstructor 400 Client
parenthesis in the SQL expression.

API Version 2006-03-01

696
Amazon Simple Storage Service API Reference
List of SELECT Object Content Error Codes

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

Did not ﬁnd the expected left

ParseExpectedLeftParenBuiltinFunctionCall 400 Client
parenthesis in the SQL expression.

Did not ﬁnd the expected argument

ParseExpectedArgumentDelimiter 400 Client
delimiter in the SQL expression.

ParseCastArity The SQL expression CAST has 400 Client

incorrect arity.

ParseInvalidTypeParam The SQL expression contains an 400 Client

invalid parameter value.

ParseEmptySelect The SQL expression contains an 400 Client

empty SELECT.

ParseSelectMissingFrom The SQL expression contains a 400 Client

missing FROM after SELECT list.

GROUP is not supported in the SQL

ParseExpectedIdentForGroupName 400 Client
expression.

ParseExpectedIdentForAliasDid not ﬁnd the expected identiﬁer 400 Client

for the alias in the SQL expression.

Only COUNT with (*) as a parameter

ParseUnsupportedCallWithStar 400 Client
is supported in the SQL expression.

Only one argument is supported

ParseNonUnaryAgregateFunctionCall 400 Client
for aggregate functions in the SQL
expression.

ParseMalformedJoin JOIN is not supported in the SQL 400 Client

expression.

ParseExpectedIdentForAt Did not ﬁnd the expected identiﬁer 400 Client

for AT name in the SQL expression.

Other expressions are not allowed

ParseAsteriskIsNotAloneInSelectList 400 Client
in the SELECT list when '*' is used
without dot notation in the SQL
expression.

Cannot mix [] and * in the same

ParseCannotMixSqbAndWildcardInSelectList 400 Client
expression in a SELECT list in SQL
expression.

Invalid use of * in SELECT list in the

ParseInvalidContextForWildcardInSelectList 400 Client
SQL expression.

A column name or a path provided

EvaluatorBindingDoesNotExist 400 Client
does not exist in the SQL expression.

ValueParseFailure Time stamp parse failure in the SQL 400 Client

expression.

Incorrect type of arguments in

IncorrectSqlFunctionArgumentType 400 Client
function call in the SQL expression.

API Version 2006-03-01

697
Amazon Simple Storage Service API Reference
List of SELECT Object Content Error Codes

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

AmbiguousFieldName Field name matches to multiple 400 Client

fields in the file. Check the SQL
expression and the file, and try
again.

EvaluatorInvalidArguments Incorrect number of arguments 400 Client

in the function call in the SQL
expression.

Invalid time stamp format string in

EvaluatorInvalidTimestampFormatPattern 400 Client
the SQL expression.

ValueParseFailure Time stamp parse failure in the SQL 400 Client

expression.

IntegerOverflow Integer overﬂow or underﬂow in the 400 Client

SQL expression.

LikeInvalidInputs Invalid argument given to the LIKE 400 Client

clause in the SQL expression.

CastFailed Attempt to convert from one data 400 Client

type to another using CAST failed in
the SQL expression.

InvalidCast Attempt to convert from one data 400 Client

type to another using CAST failed in
the SQL expression.

Time stamp format pattern

EvaluatorInvalidTimestampFormatPattern 400 Client
requires additional ﬁelds in the SQL
expression.

Time stamp format pattern contains 400

EvaluatorInvalidTimestampFormatPatternSymbolForParsing Client
a valid format symbol that cannot
be applied to time stamp parsing in
the SQL expression.

Time stamp format pattern

EvaluatorTimestampFormatPatternDuplicateFields 400 Client
contains multiple format speciﬁers
representing the time stamp ﬁeld in
the SQL expression.

Time stamp format pattern contains

EvaluatorTimestampFormatPatternHourClockAmPmMismatch 400 Client
a 12-hour hour of day format
symbol but doesn't also contain an
AM/PM field, or it contains a 24-
hour hour of day format specifier
and contains an AM/PM field in the
SQL expression.

Time stamp format pattern contains

EvaluatorUnterminatedTimestampFormatPatternToken 400 Client
unterminated token in the SQL
expression.

API Version 2006-03-01

698
Amazon Simple Storage Service API Reference
List of Replication-Related Error Codes

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

Time stamp format pattern

EvaluatorInvalidTimestampFormatPatternToken 400 Client
contains an invalid token in the SQL
expression.

Time stamp format pattern contains

EvaluatorInvalidTimestampFormatPatternSymbol 400 Client
an invalid symbol in the SQL
expression.

ParquetParsingError Error parsing Parquet ﬁle. Please 400 Client

check the ﬁle and try again.

NumberFormatError Error parsing a number. This can 400 Client

be caused by under/over ﬂow of
integers.

Invalid argument given to LIKE

EvaluatorLikePatternInvalidEscapeSequence 400 Client
expression.

EvaluatorNegativeLimit LIMIT must not be negative. 400 Client

CSVUnescapedQuote Unescaped quote found 400 Client

while parsing the .csv
ﬁle. Please ensure that
AllowQuotedRecordDelimiter
is set to 'TRUE' if quoted record
delimiters are present.

CSVEscapingRecordDelimiterQuoted record delimiter found 400 Client

in the ﬁle. To allow quoted
record delimiters, please set
AllowQuotedRecordDelimiter to
'TRUE'.

OverMaxParquetBlockSize Parquet ﬁle is above the max row 400 Client

group size.

UnsupportedParquetType Unsupported Parquet type. 400 Client

Unsupported Parquet compression

ParquetUnsupportedCompressionCodec 400 Client
codec.

UnsupportedScanRangeInput Scan range queries are not 400 Client

supported on this type of object.

InvalidScanRange The provided scan range is invalid. 400 Client

List of Replication-Related Error Codes

The following table contains special errors that the Replication operation might return. For general
information about Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

API Version 2006-03-01

699
Amazon Simple Storage Service API Reference
List of Replication-Related Error Codes

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

InvalidArgument This error might occur for the 400 Client

following reasons:

• The <Account> element is empty.

It must contain a valid account ID.
• The AWS account speciﬁed in the
<Account> element must match
the destination bucket owner.
• ReplicationTime-Status must
contain a value.
• ReplicationTime-
ReplicationTimeValue must
contain a value.
• Replication-
ReplicationTimeValue-
Minutes value must be 15.
• ReplicationMetrics must
contain a Status.
• ReplicationMetrics must
contain an EventThreshold.
• EventThreshold-
ReplicationTimeValue-
Minutes value must be 15.
• Rule ID must not contain non-
ASCII characters.

InvalidRequest This error might occur for the 400 Client

following reasons:

• The <Owner> in
<AccessControlTranslation> has a
value, so the <Account> element
must be speciﬁed.
• The <Account> element is empty.
It must contain a valid account ID.
• Replication destination must
contain both ReplicationTime
and Metrics or neither.
• ReplicationTime and
ReplicationMetrics should
have the same status.
• S3 Replication Time Control (S3
RTC) is not supported in this AWS
Region.

There is no replication conﬁguration

NoSuchReplicationConfiguration 400 Client
with that name.

API Version 2006-03-01

700
Amazon Simple Storage Service API Reference

AWS Glossary
For the latest AWS terminology, see the AWS Glossary in the AWS General Reference.

API Version 2006-03-01

701
Amazon Simple Storage Service API Reference

Amazon S3 Resources
Following is a table that lists related resources that you'll ﬁnd useful as you work with this service.

Resource Description

Amazon Simple Storage Service The getting started guide provides a quick tutorial of the
Getting Started Guide service based on a simple use case.

Amazon Simple Storage Service The developer guide describes how to accomplish tasks using
Developer Guide Amazon S3 operations.

Amazon S3 Technical FAQ The FAQ covers the top 20 questions developers have asked
about this product.

Amazon S3 Release Notes The Release Notes give a high-level overview of the current
release. They speciﬁcally note any new features, corrections,
and known issues.

Tools for Amazon Web Services A central starting point to ﬁnd documentation, code
samples, release notes, and other information to help you
build innovative applications with AWS SDKs and tools.

AWS Management Console The console allows you to perform most of the functions of
Amazon S3 without programming.

Discussion Forums A community-based forum for developers to discuss

technical questions related to Amazon Web Services.

AWS Support Center The home page for AWS Technical Support, including access
to our Developer Forums, Technical FAQs, Service Status
page, and Premium Support.

AWS Premium Support The primary web page for information about AWS Premium
Support, a one-on-one, fast-response support channel to
help you build and run applications on AWS Infrastructure
Services.

Amazon S3 product information The primary web page for information about Amazon S3.

Contact Us A central contact point for inquiries concerning AWS billing,

account, events, abuse, etc.

Conditions of Use Detailed information about the copyright and trademark

usage at Amazon.com and other topics.

API Version 2006-03-01

702
Amazon Simple Storage Service API Reference

Document History
The following table describes the important changes to the documentation since the last release of the
Amazon Simple Storage Service API Reference.

• API version: 2006-03-01

• Latest documentation update: March 27, 2019

Change Description Release

Date

New archive storage Amazon S3 now oﬀers a new archive storage class, March 27,
class DEEP_ARCHIVE, for storing rarely accessed objects. For 2019
more information, see Storage Classes in the Amazon Simple
Storage Service Developer Guide.

Support for Parquet- Amazon S3 now supports the Apache Parquet (Parquet) December
formatted Amazon S3 format in addition to the Apache optimized row columnar 04, 2018
inventory files (ORC) and comma-separated values (CSV) file formats for
inventory output files. For more information, see Amazon
S3 Inventory in the Amazon Simple Storage Service Developer
Guide.

The following APIs were updated accordingly:

• GetBucketInventoryConﬁguration (p. 95)

• PutBucketInventoryConﬁguration (p. 253)

PUT directly to the The Amazon S3 PUT and related operations now support November
GLACIER storage class specifying GLACIER as the storage class when creating 26, 2018
objects. Previously, you had to transition to the GLACIER
storage class from another Amazon S3 storage class. For more
information about the GLACIER storage class, see Storage
Classes in the Amazon Simple Storage Service Developer Guide.

The following APIs were updated accordingly:

• PutObject (p. 310)

• POST Object (p. 639)
• CopyObject (p. 16)
• CreateMultipartUpload (p. 32)

Object Lock Amazon S3 now supports locking objects using a Write Once November
Read Many (WORM) model. You can lock objects for a deﬁnite 26, 2018
period of time using a retention period or indeﬁnitely using
a legal hold. For more information about Amazon S3 Object
Lock, see Locking Objects in the Amazon Simple Storage
Service Developer Guide.

The following APIs were updated for S3 Object Lock:

• PutObject (p. 310)

• GetObject (p. 138)

API Version 2006-03-01

703
Amazon Simple Storage Service API Reference

Change Description Release

Date
• HeadObject (p. 170)
• CreateBucket (p. 27)
• HeadBucket (p. 168)

New storage class Amazon S3 now oﬀers a new storage class named November
INTELLIGENT_TIERING that is for storing data that has 26, 2018
changing or unknown access patterns. For more information,
see Storage Classes in the Amazon Simple Storage Service
Developer Guide.

The following APIs were updated accordingly:

• PutObject (p. 310)

• POST Object (p. 639)
• CopyObject (p. 16)
• CreateMultipartUpload (p. 32)

Block Public Access Amazon S3 now includes the ability to block public access to November
buckets and objects on a per-bucket or account-wide basis. 15, 2018
For more information, see Using Amazon S3 Block Public
Access in the Amazon Simple Storage Service Developer Guide.

Filtering enhancements In a CRR rule configuration, you can specify an object filter September
in cross-region to choose a subset of objects to apply the rule to. Previously, 19, 2018
replication (CRR) rules you could filter only on an object key prefix. In this release,
you can filter on an object key prefix, one or more object tags,
or both. For more information, see Replication Configuration
Overview in the Amazon Simple Storage Service Developer
Guide.

The following APIs are updated accordingly:

• PutBucketReplication (p. 289)

• GetBucketReplication (p. 123)
• DeleteBucketReplication (p. 57)

New storage class Amazon S3 now oﬀers a new storage class, ONEZONE_IA April 4,
(IA, for infrequent access) for storing objects. For more 2018
information, see Storage Classes in the Amazon Simple
Storage Service Developer Guide.

Amazon S3 Select Amazon S3 Select is now generally available. This feature April 4,
retrieves object content based on an SQL expression. For 2018
more information, see Selecting Content from Objects in the
Amazon Simple Storage Service Developer Guide.

The following API has been updated:

• SelectObjectContent (p. 352)

API Version 2006-03-01

704
Amazon Simple Storage Service API Reference

Change Description Release

Date

Asia Pacific (Osaka- Amazon S3 is now available in the Asia Pacific (Osaka-Local) February
Local) Region Region. For more information about Amazon S3 Regions and 12, 2018
endpoints, see Regions and Endpoints in the AWS General
Reference.
Important
You can use the Asia Pacific (Osaka-Local) Region
only in conjunction with the Asia Pacific (Tokyo)
Region. To request access to Asia Pacific (Osaka-
Local) Region, contact your sales representative.

Europe (Paris) Region Amazon S3 is now available in the Europe (Paris) Region. For December
more information about Amazon S3 regions and endpoints, 18, 2017
see Regions and Endpoints in the AWS General Reference.

China (Ningxia) Region Amazon S3 is now available in the China (Ningxia) Region. For December
more information about Amazon S3 regions and endpoints, 11, 2017
see Regions and Endpoints in the AWS General Reference.

Querying archives with Amazon S3 now supports querying S3 Glacier data archives November
SQL with SQL. For more information, see Querying Archived 29, 2017
Objects in the Amazon Simple Storage Service Developer Guide.

The following API changed:

• RestoreObject (p. 343)

SELECT Object Content Amazon S3 now supports the SELECT Object Content November
(Preview) functionality as part of a Preview program. This feature 29, 2017
retrieves object content based on an SQL expression.

The following API has been added:

• SelectObjectContent (p. 352)

Support for ORC- Amazon S3 now supports the Apache optimized row November
formatted Amazon S3 columnar (ORC) format in addition to comma-separated 17, 2017
inventory files values (CSV) file format for inventory output files. For more
information, see Amazon S3 Inventory in the Amazon Simple
Storage Service Developer Guide.

The following APIs are updated accordingly:

• GetBucketInventoryConﬁguration (p. 95)

• PutBucketInventoryConﬁguration (p. 253)

API Version 2006-03-01

705
Amazon Simple Storage Service API Reference

Change Description Release

Date

Default encryption for Amazon S3 default encryption provides a way to set the November
S3 buckets default encryption behavior for an S3 bucket. You can 06, 2017
set default encryption on a bucket so that all objects are
encrypted when they are stored in the bucket. The objects are
encrypted using server-side encryption with either Amazon
S3-managed keys (SSE-S3) or AWS KMS-managed keys
(SSE-KMS). For more information, see Amazon S3 Default
Encryption for S3 Buckets in the Amazon Simple Storage
Service Developer Guide.

The following APIs are updated accordingly:

• DeleteBucketEncryption (p. 47)

• GetBucketEncryption (p. 92)
• PutBucketEncryption (p. 250)

Encryption status in Amazon S3 now supports including encryption status in November

Amazon S3 inventory Amazon S3 inventory so you can see how your objects are 06, 2017
encrypted at rest for compliance auditing or other purposes.
You can also conﬁgure to encrypt Amazon S3 inventory with
server-side encryption (SSE) or SSE-KMS so that all inventory
ﬁles are encrypted accordingly. For more information, see
Amazon S3 Inventory in the Amazon Simple Storage Service
Developer Guide.

The following APIs are updated accordingly:

• GetBucketInventoryConﬁguration (p. 95)

• PutBucketInventoryConﬁguration (p. 253)

Cross-region replication Cross-region replication (CRR) now supports the following: November
(CRR) enhancements 06, 2017
• In a cross-account scenario, you can add a CRR
conﬁguration to change replica ownership to the AWS
account that owns the destination bucket. For more
information, see CRR: Change Replica Owner in the Amazon
Simple Storage Service Developer Guide.
• By default, Amazon S3 does not replicate objects in your
source bucket that are created using server-side encryption
using AWS KMS-managed keys. In your CRR conﬁguration,
you can now direct Amazon S3 to replicate these objects.
For more information, see CRR: Replicating Objects Created
with SEE Using AWS KMS-Managed Encryption Keys in the
Amazon Simple Storage Service Developer Guide.

The following APIs are updated accordingly:

• GetBucketReplication (p. 123)

• PutBucketReplication (p. 289)

API Version 2006-03-01

706
Amazon Simple Storage Service API Reference

Change Description Release

Date

Europe (London) Region Amazon S3 is now available in the Europe (London) Region. December
For more information about Amazon S3 regions and 13, 2016
endpoints, see Regions and Endpoints in the AWS General
Reference.

Canada (Central) Region Amazon S3 is now available in the Canada (Central) Region. December
For more information about Amazon S3 regions and 8, 2016
endpoints, see Regions and Endpoints in the AWS General
Reference.

Object tagging support Amazon S3 now supports object tagging. The following new November
API operations support object tagging: 29, 2016

• PutObjectTagging (p. 336)

• GetObjectTagging (p. 160)
• DeleteObjectTagging (p. 75)

In addition, other API operations are updated to support

object tagging. For more information, see Object Tagging in
the Amazon Simple Storage Service Developer Guide.

S3 lifecycle now Amazon S3 now supports tag-based ﬁltering in lifecycle November

supports object tag configuration. You can now specify a lifecycle rule, in which 29, 2016
based filter you can specify a key prefix, one or more object tags, or a
combination of both, to select a subset of objects to which
the lifecycle rule applies. For more information, see Object
Lifecycle Managementin the Amazon Simple Storage Service
Developer Guide.

Amazon S3 now supports Expedited and Bulk data retrievals

in addition to Standard retrievals when restoring objects
archived to S3 Glacier.

CloudWatch request Amazon S3 now supports CloudWatch metrics for requests November
metrics for buckets made on buckets. The following new API operations support 29, 2016
conﬁguring request metrics:

• DeleteBucketMetricsConﬁguration (p. 53)

• GetBucketMetricsConfiguration (p. 110)
• PutBucketMetricsConfiguration (p. 274)
• ListBucketMetricsConfigurations (p. 188)

For more information, see Monitoring Metrics with Amazon

CloudWatch in the Amazon Simple Storage Service Developer
Guide.

API Version 2006-03-01

707
Amazon Simple Storage Service API Reference

Change Description Release

Date

Amazon S3 Inventory Amazon S3 now supports storage inventory. Amazon S3 November

inventory provides a flat-file output of your objects and their 29, 2016
corresponding metadata on a daily or weekly basis for an S3
bucket or a shared prefix (that is, objects that have names
that begin with a common string).

The following new API operations are for storage inventory:

• DeleteBucketInventoryConﬁguration (p. 49)

• GetBucketInventoryConfiguration (p. 95)
• PutBucketInventoryConfiguration (p. 253)
• ListBucketInventoryConfigurations (p. 183)

For more information, see Amazon S3 Storage Inventory in

the Amazon Simple Storage Service Developer Guide.

Amazon S3 Analytics – The new Amazon S3 analytics – storage class analysis feature November
Storage Class Analysis observes data access patterns to help you determine when 29, 2016
to transition less frequently accessed STANDARD storage to
the STANDARD_IA (IA, for infrequent access) storage class.
After storage class analysis observes the infrequent access
patterns of a filtered set of data over a period of time, you
can use the analysis results to help you improve your lifecycle
policies. This feature also includes a detailed daily analysis of
your storage usage at the specified bucket, prefix, or tag level
that you can export to a S3 bucket.

The following new API operations are for storage class

analysis:

• DeleteBucketAnalyticsConﬁguration (p. 43)

• GetBucketAnalyticsConfiguration (p. 85)
• PutBucketAnalyticsConfiguration (p. 243)
• ListBucketAnalyticsConfigurations (p. 179)

For more information, see Amazon S3 Analytics – Storage

Class Analysis in the Amazon Simple Storage Service Developer
Guide.

Added S3 Glacier Amazon S3 now supports Expedited and Bulk data retrievals November
retrieval options to in addition to Standard retrievals when restoring objects 21, 2016
RestoreObject (p. 343) archived to S3 Glacier. For more information, see Restoring
Archived Objects in the Amazon Simple Storage Service
Developer Guide.

US East (Ohio) Region Amazon S3 is now available in the US East (Ohio) Region. For October 17,
more information about Amazon S3 regions and endpoints, 2016
see Regions and Endpoints in the AWS General Reference.

API Version 2006-03-01

708
Amazon Simple Storage Service API Reference

Change Description Release

Date

Asia Paciﬁc (Mumbai) Amazon S3 is now available in the Asia Paciﬁc (Mumbai) June 27,
region region. For more information about Amazon S3 regions and 2016
endpoints, see Regions and Endpoints in the AWS General
Reference.

GET Bucket (List The GET Bucket (List Objects) API has been revised. We May 4,
Objects) API revised recommend that you use the new version, GET Bucket 2016
(List Objects) version 2. For more information, see
ListObjectsV2 (p. 209).

Amazon S3 Transfer Amazon S3 Transfer Acceleration enables fast, easy, and April 19,
Acceleration secure transfers of ﬁles over long distances between 2016
your client and an S3 bucket. Transfer Acceleration takes
advantage of Amazon CloudFront’s globally distributed edge
locations.

For more information, see Transfer Acceleration in the

Amazon Simple Storage Service Developer Guide.

The following new API operations support Transfer

Acceleration: GetBucketAccelerateConﬁguration (p. 79) and
PutBucketAccelerateConﬁguration (p. 234).

Lifecycle support to Lifecycle conﬁguration expiration action now allows you to March 16,
remove expired object direct Amazon S3 to remove expired object delete markers 2016
delete marker in versioned bucket. For more information, see Elements
to Describe Lifecycle Actions in the Amazon Simple Storage
Service Developer Guide.

API Version 2006-03-01

709
Amazon Simple Storage Service API Reference

Change Description Release

Date

Bucket lifecycle Bucket lifecycle configuration now supports the March 16,
configuration now AbortIncompleteMultipartUpload action that you can 2016
supports the action use to direct Amazon S3 to abort multipart uploads that
to abort incomplete don't complete within a specified number of days after being
multipart uploads initiated. When a multipart upload becomes eligible for an
abort operation, Amazon S3 deletes any uploaded parts and
aborts the multipart upload.

The following API operations have been updated to support

the new action:

• PutBucketLifecycleConﬁguration (p. 264) – The

XML configuration now allows you to specify the
AbortIncompleteMultipartUpload action in a lifecycle
configuration rule.
• ListParts (p. 229) and CreateMultipartUpload (p. 32) –
Both of these API operations now return two additional
response headers (x-amz-abort-date, and x-amz-
abort-rule-id) if the bucket has a lifecycle rule that
specifies the AbortIncompleteMultipartUpload
action. These headers in the response indicate when the
initiated multipart upload will become eligible for an abort
operation and which lifecycle rule is applicable.

For conceptual information, see the following topics in the

Amazon Simple Storage Service Developer Guide:

• Aborting Incomplete Multipart Uploads Using a Bucket

Lifecycle Policy
• Elements to Describe Lifecycle Actions

Amazon S3 Signature Amazon S3 Signature Version 4 now supports unsigned January 15,
Version 4 now supports payloads when authenticating requests using the 2016
unsigned payloads Authorization header. Because you don't sign the payload,
it does not provide the same security that comes with payload
signing, but it provides similar performance characteristics
as signature version 2. For more information, see Signature
Calculations for the Authorization Header: Transferring
Payload in a Single Chunk (AWS Signature Version 4) (p. 607).

Asia Paciﬁc (Seoul) Amazon S3 is now available in the Asia Paciﬁc (Seoul) January 6,
region region. For more information about Amazon S3 regions and 2016
endpoints, see Regions and Endpoints in the AWS General
Reference.

Renamed the US Changed the region name string from US Standard to US East December
Standard region (N. Virginia). This is only a region name update, there is no 11, 2015
change in the functionality.

API Version 2006-03-01

710
Amazon Simple Storage Service API Reference

Change Description Release

Date

New storage class Amazon S3 now oﬀers a new storage class, STANDARD_IA (IA, September
for infrequent access) for storing objects. This storage class 16, 2015
is optimized for long-lived and less frequently accessed data.
For more information, see Storage Classes in the Amazon
Simple Storage Service Developer Guide.

Lifecycle conﬁguration feature updates now allow you to

transition objects to the STANDARD_IA storage class. For
more information, see Object Lifecycle Management in the
Amazon Simple Storage Service Developer Guide.

Previously, the cross-region replication feature used the

storage class of the source object for object replicas. Now,
when you conﬁgure cross-region replication you can specify a
storage class for the object replica created in the destination
bucket. For more information, see Cross-Region Replication in
the Amazon Simple Storage Service Developer Guide.

Event notifications Amazon S3 event notifications have been updated July 28,
to add notifications when objects are deleted and 2015
to add filtering on object names with prefix and
suffix matching. For the relevant API operations, see
PutBucketNotificationConfiguration (p. 280), and
GetBucketNotificationConfiguration (p. 116). For more
information, see Configuring Amazon S3 Event Notifications
in the Amazon Simple Storage Service Developer Guide.

Cross-region replication Amazon S3 now supports cross-region replication. March 24,

Cross-region replication is the automatic, asynchronous 2015
copying of objects across buckets in diﬀerent
AWS regions. For the relevant API operations, see
PutBucketReplication (p. 289), GetBucketReplication (p. 123)
and DeleteBucketReplication (p. 57). For more information,
see Enabling Cross-Region Replication in the Amazon Simple
Storage Service Developer Guide.

Event notifications Amazon S3 now supports new event types and November
destinations in a bucket notification configuration. 13, 2014
Prior to this release, Amazon S3 supported only the
s3:ReducedRedundancyLostObject event type
and an Amazon SNS topic as the destination. For more
information about the new event types, go to Setting Up
Notification of Bucket Events in the Amazon Simple Storage
Service Developer Guide. For the relevant API operations,
see PutBucketNotificationConfiguration (p. 280) and
GetBucketNotificationConfiguration (p. 116).

API Version 2006-03-01

711
Amazon Simple Storage Service API Reference

Change Description Release

Date

Server-side encryption Amazon S3 now supports server-side encryption using AWS November
with AWS Key Key Management Service (KMS). With server-side encryption 12, 2014
Management Service with KMS, you manage the envelope key through KMS, and
(KMS) Amazon S3 calls KMS to access the envelope key within the
permissions you set.

For more information about server-side encryption with

KMS, see Protecting Data Using Server-Side Encryption with
AWS Key Management Service in the Amazon Simple Storage
Service Developer Guide.

The following Amazon S3 REST API operations support

headers related to KMS.

• PutObject (p. 310)

• CopyObject (p. 16)
• POST Object (p. 639)
• CreateMultipartUpload (p. 32)
• UploadPart (p. 360)

EU (Frankfurt) region Amazon S3 is now available in the EU (Frankfurt) region. October 23,
2014

Server-side encryption Amazon S3 now supports server-side encryption using June 12,
with customer-provided customer-provided encryption keys (SSE-C). Server-side 2014
encryption keys encryption enables you to request Amazon S3 to encrypt your
data at rest. When using SSE-C, Amazon S3 encrypts your
objects with the custom encryption keys that you provide.
Since Amazon S3 performs the encryption for you, you get
the beneﬁts of using your own encryption keys without the
cost of writing or executing your own encryption code.

For more information about SSE-C, go to Server-Side

Encryption (Using Customer-Provided Encryption Keys) in the
Amazon Simple Storage Service Developer Guide.

The following Amazon S3 REST API operations support

headers related to SSE-C.

• GetObject (p. 138)

• HeadObject (p. 170)
• PutObject (p. 310)
• CopyObject (p. 16)
• POST Object (p. 639)
• CreateMultipartUpload (p. 32)
• UploadPart (p. 360)
• UploadPartCopy (p. 365)

API Version 2006-03-01

712
Amazon Simple Storage Service API Reference

Change Description Release

Date

Lifecycle support for Prior to this release lifecycle conﬁguration was supported May 20,
versioning only on nonversioned buckets. Now you can conﬁgure 2014
lifecycle on both the nonversioned and versioning-enabled
buckets.

For more information, go to Object Lifecycle Management in

the Amazon Simple Storage Service Developer Guide.

The related API operations, see

PutBucketLifecycleConﬁguration (p. 264),
GetBucketLifecycleConﬁguration (p. 102), and
DeleteBucketLifecycle (p. 51).

Amazon S3 now Amazon S3 now supports Signature Version 4 (SigV4) in January 30,
supports Signature all regions, the latest speciﬁcation for how to sign and 2014
Version 4 authenticate AWS requests.

For more information, see Authenticating Requests (AWS

Signature Version 4) (p. 603).

Amazon S3 list The following Amazon S3 list actions now support November
actions now support encoding-type optional request parameter. 1, 2013
encoding-type
request parameter ListObjects (p. 202)

ListObjectVersions (p. 218)

ListMultipartUploads (p. 194)

ListParts (p. 229)

An object key can contain any Unicode character; however,

the XML 1.0 parser cannot parse some characters, such as
characters with an ASCII value from 0 to 10. For characters
that are not supported in XML 1.0, you can add this
parameter to request that Amazon S3 encode the keys in the
response.

SOAP Support Over SOAP support over HTTP is deprecated, but it is still available September
HTTP Deprecated over HTTPS. New Amazon S3 features will not be supported 19, 2013
for SOAP. We recommend that you use either the REST API or
the AWS SDKs.

API Version 2006-03-01

713
Amazon Simple Storage Service API Reference

Change Description Release

Date

Root domain support Amazon S3 now supports hosting static websites at the root December
for website hosting domain. Visitors to your website can access your site from 27, 2012
their browser without specifying "www" in the web address
(e.g., "example.com"). Many customers already host static
websites on Amazon S3 that are accessible from a "www"
subdomain (e.g., "www.example.com"). Previously, to support
root domain access, you needed to run your own web server
to proxy root domain requests from browsers to your website
on Amazon S3. Running a web server to proxy requests
introduces additional costs, operational burden, and another
potential point of failure. Now, you can take advantage of the
high availability and durability of Amazon S3 for both "www"
and root domain addresses.

For an example walkthrough, go to Example: Setting Up a

Static Website Using a Custom Domain in the Amazon Simple
Storage Service Developer Guide. For conceptual information,
go to Hosting Static Websites on Amazon S3 in the Amazon
Simple Storage Service Developer Guide.

Support for Archiving Amazon S3 now supports a storage option that enables November
Data to Amazon Glacier you to utilize Amazon Glacier's low-cost storage service for 13, 2012
data archival. To archive objects, you deﬁne archival rules
identifying objects and a timeline when you want Amazon
S3 to archive these objects to S3 Glacier. You can easily
set the rules on a bucket using the Amazon S3 console or
programmatically using the Amazon S3 API or AWS SDKs.

To support data archival rules, Amazon S3 lifecycle

management API has been updated. For more information,
see PutBucketLifecycleConﬁguration (p. 264).

After you archive objects, you must ﬁrst restore a copy

before you can access the data. Amazon S3 oﬀers a new
API for you to initiate a restore. For more information, see
RestoreObject (p. 343).

For conceptual information, go to Object Lifecycle

Management in the Amazon Simple Storage Service Developer
Guide.

Support for Website For a bucket that is conﬁgured as a website, Amazon S3 now October 4,
Page Redirects supports redirecting a request for an object to another object 2012
in the same bucket or to an external URL. You can conﬁgure
redirect by adding the x-amz-website-redirect-
location metadata to the object.

The object upload API operations PutObject (p. 310),

CreateMultipartUpload (p. 32), and POST Object (p. 639)
allow you to conﬁgure the x-amz-website-redirect-
location object metadata.

For conceptual information, go to How to Conﬁgure Website

Page Redirects in the Amazon Simple Storage Service
Developer Guide.

API Version 2006-03-01

714
Amazon Simple Storage Service API Reference

Change Description Release

Date

Cross-Origin Resource Amazon S3 now supports Cross-Origin Resource Sharing August 31,
Sharing (CORS) support (CORS). CORS deﬁnes a way in which client web applications 2012
that are loaded in one domain can interact with or access
resources in a diﬀerent domain. With CORS support in
Amazon S3, you can build rich client-side web applications
on top of Amazon S3 and selectively allow cross-domain
access to your Amazon S3 resources. For more information,
see Enabling Cross-Origin Resource Sharing in the Amazon
Simple Storage Service Developer Guide.

Cost Allocation Tagging Amazon S3 now supports cost allocation tagging, which August 21,
support allows you to label S3 buckets so you can more easily 2012
track their cost against projects or other criteria. For more
information, see Cost Allocation Tagging in the Amazon
Simple Storage Service Developer Guide.

Object Expiration You can use Object Expiration to schedule automatic December
support removal of data after a conﬁgured time period. You set 27, 2011
object expiration by adding lifecycle conﬁguration to a
bucket. For more information, see Transitioning Objects:
General Considerations in the Amazon Simple Storage Service
Developer Guide.

New Region supported Amazon S3 now supports the South America (São Paulo) December
region. For more information, see Buckets and Regions in the 14, 2011
Amazon Simple Storage Service Developer Guide.

Multi-Object Delete Amazon S3 now supports Multi-Object Delete API that December
enables you to delete multiple objects in a single request. 7, 2011
With this feature, you can remove large numbers of objects
from Amazon S3 more quickly than using multiple individual
DELETE requests.

For more information about the API see, see

DeleteObjects (p. 67).

For conceptual information about the delete operation,

see Deleting Objects in the Amazon Simple Storage Service
Developer Guide.

New region supported Amazon S3 now supports the US West (Oregon) region. For November
more information, see Buckets and Regions in the Amazon 8, 2011
Simple Storage Service Developer Guide.

Server-side encryption Amazon S3 now supports server-side encryption. It enables October 17,
support you to request Amazon S3 to encrypt your data at rest, that 2011
is, encrypt your object data when Amazon S3 writes your data
to disks in its data centers. To request server-side encryption,
you must add the x-amz-server-side-encryption
header to your request. To learn more about data encryption,
go to Using Data Encryption in the Amazon Simple Storage
Service Developer Guide.

API Version 2006-03-01

715
Amazon Simple Storage Service API Reference

Change Description Release

Date

Multipart Upload API Prior to this release, Amazon S3 API supported copying June 21,
extended to enable objects (see CopyObject (p. 16)) of up to 5 GB in size. To 2011
copying objects up to 5 enable copying objects larger than 5 GB, Amazon S3 extends
TB the multipart upload API with a new operation, Upload
Part (Copy). You can use this multipart upload operation
to copy objects up to 5 TB in size. For conceptual information
about multipart upload, go to Uploading Objects Using
Multipart Upload in the Amazon Simple Storage Service
Developer Guide. To learn more about the new API, see
UploadPartCopy (p. 365).

SOAP API calls over To increase security, SOAP API calls over HTTP are disabled. June 6,
HTTP disabled Authenticated and anonymous SOAP requests must be sent to 2011
Amazon S3 using SSL.

Support for hosting Amazon S3 introduces enhanced support for hosting static February
static websites in websites. This includes support for index documents and 17, 2011
Amazon S3 custom error documents. When using these features, requests
to the root of your bucket or a subfolder (e.g., http://
mywebsite.com/subfolder) returns your index document
instead of the list of objects in your bucket. If an error is
encountered, Amazon S3 returns your custom error message
instead of an Amazon S3 error message. For API information
to conﬁgure your bucket as a website, see the following
sections:

• PutBucketWebsite (p. 304)

• GetBucketWebsite (p. 135)
• DeleteBucketWebsite (p. 61)

For conceptual overview, go to Hosting Websites on Amazon

S3 in the Amazon Simple Storage Service Developer Guide.

Response Header API The GET Object REST API now allows you to change the January 14,
Support response headers of the REST GET Object request for 2011
each request. That is, you can alter object metadata in
the response, without altering the object itself. For more
information, see GetObject (p. 138).

Large Object Support Amazon S3 has increased the maximum size of an object December
you can store in an S3 bucket from 5 GB to 5 TB. If you are 9, 2010
using the REST API you can upload objects of up to 5 GB
size in a single PUT operation. For larger objects, you must
use the Multipart Upload REST API to upload objects in
parts. For conceptual information, go to Uploading Objects
Using Multipart Upload in the Amazon Simple Storage Service
Developer Guide. For multipart upload API information,
see CreateMultipartUpload (p. 32), UploadPart (p. 360),
CompleteMultipartUpload (p. 10), ListParts (p. 229), and
ListMultipartUploads (p. 194)

API Version 2006-03-01

716
Amazon Simple Storage Service API Reference

Change Description Release

Date

Multipart upload Multipart upload enables faster, more ﬂexible uploads into November
Amazon S3. It allows you to upload a single object as a set of 10, 2010
parts. For conceptual information, go to Uploading Objects
Using Multipart Upload in the Amazon Simple Storage Service
Developer Guide. For multipart upload API information,
see CreateMultipartUpload (p. 32), UploadPart (p. 360),
CompleteMultipartUpload (p. 10), ListParts (p. 229), and
ListMultipartUploads (p. 194)

Notifications The Amazon S3 notifications feature enables you to configure July 14,
a bucket so that Amazon S3 publishes a message to an 2010
Amazon Simple Notification Service (SNS) topic when
Amazon S3 detects a key event on a bucket. For more
information, see GET Bucket notification (p. 116) and PUT
Bucket notification (p. 116).

Bucket policies Bucket policies is an access management system you use to July 6, 2010
set access permissions on buckets, objects, and sets of objects.
This functionality supplements and in many cases replaces
access control lists.

Reduced Redundancy Amazon S3 now enables you to reduce your storage costs by May 12,
storing objects in Amazon S3 with reduced redundancy. For 2010
more information, see PUT Object (p. 310).

New region supported Amazon S3 now supports the Asia Paciﬁc (Singapore) region April 28,
and therefore new location constraints. For more information, 2010
see GET Bucket location (p. 105) and PUT Bucket (p. 27).

Object Versioning This release introduces object Versioning. All objects now February 8,
have a key and a version. If you enable versioning for a 2010
bucket, Amazon S3 gives all objects added to a bucket
a unique version ID. This feature enables you to recover
from unintended overwrites and deletions. For more
information, see GET Object (p. 138), DELETE Object (p. 63),
PUT Object (p. 310), PUT Object Copy (p. 16), or POST
Object (p. 639). The SOAP API does not support versioned
objects.

New region supported Amazon S3 now supports the US-West (Northern December
California) region. The new endpoint is s3-us- 2, 2009
west-1.amazonaws.com. For more information, see How
to Select a Region for Your Buckets in the Amazon Simple
Storage Service Developer Guide.

C# Library Support AWS now provides Amazon S3 C# libraries, sample code, November
tutorials, and other resources for software developers who 11, 2009
prefer to build applications using language-speciﬁc API
operations instead of REST or SOAP. These libraries provide
basic functions (not included in the REST or SOAP APIs), such
as request authentication, request retries, and error handling
so that it's easier to get started.

API Version 2006-03-01

717
Amazon Simple Storage Service API Reference

Change Description Release

Date

Technical documents The API reference has been split out of the Amazon S3 September
reorganized Developer Guide. Now, on the documentation landing page, 16, 2009
Amazon Simple Storage Service Documentation, you can
select the document you want to view. When viewing the
documents online, the links in one document will take you,
when appropriate, to one of the other guides.

API Version 2006-03-01

718
Amazon Simple Storage Service API Reference

Appendix
Topics
• Appendix: SelectObjectContent Response (p. 720)
• Appendix: OPTIONS object (p. 730)
• Appendix: SOAP API (p. 732)
• Appendix: Lifecycle Conﬁguration APIs (Deprecated) (p. 759)

API Version 2006-03-01

719
Amazon Simple Storage Service API Reference
Appendix: SelectObjectContent Response

Appendix: SelectObjectContent Response

Description
The Amazon S3 Select operation ﬁlters the contents of an Amazon S3 object based on a simple
structured query language (SQL) statement. Given the response size of this operation is unknown,
Amazon S3 Select streams the response as a series of messages and includes a Transfer-Encoding
header with chunked as its value in the response.

For more information about Amazon S3 Select, see Selecting Content from Objects in the Amazon
Simple Storage Service Developer Guide.

For more information about using SQL with Amazon S3 Select, see SQL Reference for Amazon S3 Select
and S3 Glacier Select in the Amazon Simple Storage Service Developer Guide.

Responses
A successful Amazon S3 Select Operation returns 200 OK status code.

Response Headers
This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Body
Since the Amazon S3 Select response size is unknown, Amazon S3 streams the response as a series of
messages and includes a Transfer-Encoding header with chunked as its value in the response. The
following example shows the response format at the top level:

Each message consists of two sections: the prelude and the data. The prelude section consists of 1) the
total byte-length of the message, and 2) the combined byte-length of all the headers. The data section
consists of 1) the headers, and 2) a payload.

Each section ends with a 4-byte big-endian integer checksum (CRC). Amazon S3 Select uses CRC32
(often referred to as GZIP CRC32) to calculate both CRCs. For more information about CRC32, see GZIP
ﬁle format speciﬁcation version 4.3.

Total message overhead including the prelude and both checksums is 16 bytes.
Note
All integer values within messages are in network byte order, or big-endian order.

The following diagram shows the components that make up a message and a header. Note that there are
multiple headers per message.

API Version 2006-03-01

720
Amazon Simple Storage Service API Reference
Responses

Note
For Amazon S3 Select, the header value type is always 7 (type=String). For this type, the header
value consists of two components, a 2-byte big-endian integer length, and a UTF-8 string that
is of that byte-length. The following diagram shows the components that make up Amazon S3
Select headers.

Payload byte-length calculations (these two calculations are equivalent):

• payload_length = total_length - header_length - sizeOf(total_length) - sizeOf(header_length) -

sizeOf(prelude_crc) - sizeOf(message_crc)
• payload_length = total_length - header_length - 16

Each message contains the following components:

• Prelude: Always ﬁxed size of 8 bytes (two ﬁelds of 4 bytes each):

API Version 2006-03-01

721
Amazon Simple Storage Service API Reference
Responses

• First four bytes: Total byte-length: Big-endian integer byte-length of the entire message (including
the 4-byte total length field itself).
• Second four bytes: Headers byte-length: Big-endian integer byte-length of the headers portion of
the message (excluding the headers length field itself).
• Prelude CRC: 4-byte big-endian integer checksum (CRC) for the prelude portion of the message
(excluding the CRC itself). The prelude has a separate CRC from the message CRC (see below),
to ensure that corrupted byte-length information can be detected immediately, without causing
pathological buffering behavior.
• Headers: A set of metadata annotating the message, such as the message type, payload format, and
so on. Messages can have multiple headers, so this portion of the message can have different byte-
lengths depending on the message type. Headers are key-value pairs, where both the key and value
are UTF-8 strings. Headers can appear in any order within the headers portion of the message, and any
given header type can only appear once.

For Amazon S3 Select, following is a list of header names and the set of valid values depending on the
message type.
• MessageType Header:
• HeaderName => ":message-type"
• Valid HeaderValues => "error", "event"
• EventType Header:
• HeaderName => ":event-type"
• Valid HeaderValues => "Records", "Cont", "Progress", "Stats", "End"
• ErrorCode Header:
• HeaderName => ":error-code"
• Valid HeaderValues => Error Code from the table in the List of SELECT Object Content Error
Codes (p. 693) section.
• ErrorMessage Header:
• HeaderName => ":error-message"
• Valid HeaderValues => Error message returned by the service, to help diagnose request-level
errors.
• Payload: Can be anything.
• Message CRC: 4-byte big-endian integer checksum (CRC) from the start of the message to the start of
the checksum (that is, everything in the message excluding the message CRC itself).

Each header contains the following components. There can be multiple headers per message.

• Header Name Byte-Length: Byte-length of the header name.

• Header Name: Name of the header, indicating the header type. Valid values: ":message-type" ":event-
type" ":error-code" ":error-message"
• Header Value Type: Enum indicating the header value type. For Amazon S3 Select, this is always 7.
• Value String Byte-Length: (For Amazon S3 Select) Byte-length of the header value string.
• Header Value String: (For Amazon S3 Select) Value of the header string. Valid values for this ﬁeld
vary based on the type of the header. See the sections below for valid values for each header type and
message type.

For Amazon S3 Select, responses can be messages of the following types:

• Records message: Can contain a single record, partial records, or multiple records. Depending on the
size of the result, a response can contain one or more of these messages.
API Version 2006-03-01
722
Amazon Simple Storage Service API Reference
Responses

• Continuation message: Amazon S3 periodically sends this message to keep the TCP connection open.
These messages appear in responses at random. The client must detect the message type and process
accordingly.
• Progress message: Amazon S3 periodically sends this message, if requested. It contains information
about the progress of a query that has started but has not yet completed.
• Stats message: Amazon S3 sends this message at the end of the request. It contains statistics about
the query.
• End message: Indicates that the request is complete, and no more messages will be sent. You should
not assume that the request is complete until the client receives an End message.
• RequestLevelError message: Amazon S3 sends this message if the request failed for any reason. It
contains the error code and error message for the failure. If Amazon S3 sends a RequestLevelError
message, it doesn't send an End message.

The following sections explain the structure of each message type in more detail.

For sample code and unit tests that use this protocol, see AWS C Event Stream on the GitHub website.

Records Message
Header speciﬁcation

Records messages contain three headers, as follows:

API Version 2006-03-01

723
Amazon Simple Storage Service API Reference
Responses

Payload speciﬁcation

Records message payloads can contain a single record, partial records, or multiple records.

Continuation Message
Header speciﬁcation

Continuation messages contain two headers, as follows:

End Message
Header speciﬁcation

End messages contain two headers, as follows:

Payload speciﬁcation

End messages have no payload.

Request Level Error Message

Header speciﬁcation

Request-level error messages contain three headers, as follows:

API Version 2006-03-01

728
Amazon Simple Storage Service API Reference
Related Resources

For a list of possible error codes and error messages, see the List of SELECT Object Content Error
Codes (p. 693).

Payload speciﬁcation

Request-level error messages have no payload.

Related Resources
• the section called “SelectObjectContent” (p. 352)
• the section called “GetObject” (p. 138)
• the section called “GetBucketLifecycleConﬁguration” (p. 102)
• the section called “PutBucketLifecycleConﬁguration” (p. 264)

API Version 2006-03-01

729
Amazon Simple Storage Service API Reference
Appendix: OPTIONS object

Appendix: OPTIONS object

Description
A browser can send this preﬂight request to Amazon S3 to determine if it can send an actual request
with the speciﬁc origin, HTTP method, and headers.

Amazon S3 supports cross-origin resource sharing (CORS) by enabling you to add a cors subresource on
a bucket. When a browser sends this preflight request, Amazon S3 responds by evaluating the rules that
are defined in the cors configuration.

If cors is not enabled on the bucket, then Amazon S3 returns a 403 Forbidden response.

For more information about CORS, go to Enabling Cross-Origin Resource Sharing in the Amazon Simple
Storage Service Developer Guide.

Requests
Syntax
OPTIONS /ObjectName HTTP/1.1
Host: BucketName.s3.amazonaws.com
Origin: Origin
Access-Control-Request-Method: HTTPMethod
Access-Control-Request-Headers: RequestHeader

Request Parameters
This operation does not introduce any speciﬁc request parameters, but it may contain any request
parameters that are required by the actual request.

Request Headers

Name Description Required

Origin Identiﬁes the origin of the cross-origin request to Amazon S3. Yes
For example, http://www.example.com.

Type: String

Default: None

Access-Control- Identiﬁes what HTTP method will be used in the actual request. Yes
Request-Method
Type: String

Default: None

Access-Control- A comma-delimited list of HTTP headers that will be sent in the No

Request-Headers actual request.

For example, to put an object with server-side encryption, this

preﬂight request will determine if it can include the x-amz-
server-side-encryption header with the request.

API Version 2006-03-01

730
Amazon Simple Storage Service API Reference
Responses

Name Description Required

Type: String

Default: None

Request Elements
This implementation of the operation does not use request elements.

Responses
Response Headers

Header Description

Access-Control-Allow- The origin you sent in your request. If the origin in your request is not
Origin allowed, Amazon S3 will not include this header in the response.

Type: String

Access-Control-Max-Age How long, in seconds, the results of the preﬂight request can be
cached.

Type: String

Access-Control-Allow- The HTTP method that was sent in the original request. If the
Methods method in the request is not allowed, Amazon S3 will not include this
header in the response.

Type: String

Access-Control-Allow- A comma-delimited list of HTTP headers that the browser can send
Headers in the actual request. If any of the requested headers is not allowed,
Amazon S3 will not include that header in the response, nor will the
response contain any of the headers with the Access-Control
preﬁx.

Type: String

Access-Control-Expose- A comma-delimited list of HTTP headers. This header provides the

Headers JavaScript client with access to these headers in the response to the
actual request.

Type: String

Response Elements
This implementation of the operation does not return response elements.

API Version 2006-03-01

731
Amazon Simple Storage Service API Reference
Examples

Examples
Example : Send a preﬂight OPTIONS request to a cors enabled
bucket
A browser can send this preﬂight request to Amazon S3 to determine if it can send the actual PUT
request from http://www.example.com origin to the Amazon S3 bucket named examplebucket.

Sample Request

OPTIONS /exampleobject HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Origin: http://www.example.com
Access-Control-Request-Method: PUT

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: 6SvaESv3VULYPLik5LLl7lSPPtSnBvDdGmnklX1HfUl7uS2m1DF6td6KWKNjYMXZ
x-amz-request-id: BDC4B83DF5096BBE
Date: Wed, 21 Aug 2012 23:09:55 GMT
Etag: "1f1a1af1f1111111111111c11aed1da1"
Access-Control-Allow-Origin: http://www.example.com
Access-Control-Allow-Methods: PUT
Access-Control-Expose-Headers: x-amz-request-id
Content-Length: 0
Server: AmazonS3

Related Resources
• GetBucketCors (p. 89)
• DeleteBucketCors (p. 45)
• PutBucketCors (p. 247)

Appendix: SOAP API

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

This section describes the SOAP API with respect to service, bucket, and object operations. Note that
SOAP requests, both authenticated and anonymous, must be sent to Amazon S3 using SSL. Amazon S3
returns an error when you send a SOAP request over HTTP.

The latest Amazon S3 WSDL is available at http://doc.s3.amazonaws.com/2006-03-01/AmazonS3.wsdl.

Topics
• Operations on the Service (SOAP API) (p. 733)
• Operations on Buckets (SOAP API) (p. 734)
• Operations on Objects (SOAP API) (p. 742)

API Version 2006-03-01

732
Amazon Simple Storage Service API Reference
Operations on the Service (SOAP API)

• SOAP Error Responses (p. 758)

Operations on the Service (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

This section describes operations you can perform on the Amazon S3 service.

Topics
• ListAllMyBuckets (SOAP API) (p. 733)

ListAllMyBuckets (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The ListAllMyBuckets operation returns a list of all buckets owned by the sender of the request.

Example
Sample Request

<ListAllMyBuckets xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</ListAllMyBuckets>

Sample Response

<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<Owner>
<ID>bcaf1ffd86f41161ca5fb16fd081034f</ID>
<DisplayName>webfile</DisplayName>
</Owner>
<Buckets>
<Bucket>
<Name>quotes;/Name>
<CreationDate>2006-02-03T16:45:09.000Z</CreationDate>
</Bucket>
<Bucket>
<Name>samples</Name>
<CreationDate>2006-02-03T16:41:58.000Z</CreationDate>
</Bucket>
</Buckets>
</ListAllMyBucketsResult>

Response Body
• Owner:

This provides information that Amazon S3 uses to represent your identity for purposes of
authentication and access control. ID is a unique and permanent identiﬁer for the developer who

API Version 2006-03-01

733
Amazon Simple Storage Service API Reference
Operations on Buckets (SOAP API)

made the request. DisplayName is a human-readable name representing the developer who made
the request. It is not unique, and might change over time.We recommend that you match your
DisplayName to your Forum name.
• Name:

The name of a bucket. Note that if one of your buckets was recently deleted, the name of the deleted
bucket might still be present in this list for a period of time.
• CreationDate:

The time that the bucket was created.

Access Control
You must authenticate with a valid AWS Access Key ID. Anonymous requests are never allowed to list
buckets, and you can only list buckets for which you are the owner.

Operations on Buckets (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

This section describes operations you can perform on Amazon S3 buckets.

Topics
• CreateBucket (SOAP API) (p. 734)
• DeleteBucket (SOAP API) (p. 735)
• ListBucket (SOAP API) (p. 736)
• GetBucketAccessControlPolicy (SOAP API) (p. 739)
• SetBucketAccessControlPolicy (SOAP API) (p. 740)
• GetBucketLoggingStatus (SOAP API) (p. 741)
• SetBucketLoggingStatus (SOAP API) (p. 741)

CreateBucket (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The CreateBucket operation creates a bucket. Not every string is an acceptable bucket name. For
information on bucket naming restrictions, see Working with Amazon S3 Buckets .
Note
To determine whether a bucket name exists, use ListBucket and set MaxKeys to 0. A
NoSuchBucket response indicates that the bucket is available, an AccessDenied response
indicates that someone else owns the bucket, and a Success response indicates that you own the
bucket or have permission to access it.

Example Create a bucket named "quotes"

Sample Request

API Version 2006-03-01

734
Amazon Simple Storage Service API Reference
Operations on Buckets (SOAP API)

<CreateBucket xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</CreateBucket>

Sample Response

<CreateBucketResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<CreateBucketResponse>
<Bucket>quotes</Bucket>
</CreateBucketResponse>
</CreateBucketResponse>

Elements
• Bucket: The name of the bucket you are trying to create.
• AccessControlList: The access control list for the new bucket. This element is optional. If not
provided, the bucket is created with an access policy that give the requester FULL_CONTROL access.

Access Control
You must authenticate with a valid AWS Access Key ID. Anonymous requests are never allowed to create
buckets.

Related Resources
• ListBucket (SOAP API) (p. 736)

DeleteBucket (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The DeleteBucket operation deletes a bucket. All objects in the bucket must be deleted before the
bucket itself can be deleted.

Example

This example deletes the "quotes" bucket.

Sample Request

<DeleteBucket xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
<AWSAccessKeyId> AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</DeleteBucket>

Sample Response

API Version 2006-03-01

735
Amazon Simple Storage Service API Reference
Operations on Buckets (SOAP API)

<DeleteBucketResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<DeleteBucketResponse>
<Code>204</Code>
<Description>No Content</Description>
</DeleteBucketResponse>
</DeleteBucketResponse>

Elements
• Bucket: The name of the bucket you want to delete.

Access Control
Only the owner of a bucket is allowed to delete it, regardless the access control policy on the bucket.

ListBucket (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The ListBucket operation returns information about some of the items in the bucket.

For a general introduction to the list operation, see the Listing Object Keys.

Requests
This example lists up to 1000 keys in the "quotes" bucket that have the preﬁx "notes."

Syntax

<ListBucket xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
<Prefix>notes/</Prefix>
<Delimiter>/</Delimiter>
<MaxKeys>1000</MaxKeys>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</ListBucket>

Parameters

Name Description Required

prefix Limits the response to keys which begin with the indicated prefix. No
You can use prefixes to separate a bucket into different sets of keys
in a way similar to how a file system uses folders.

Type: String

Default: None

marker Indicates where in the bucket to begin listing. The list will only No
include keys that occur lexicographically after marker. This is

API Version 2006-03-01

736
Amazon Simple Storage Service API Reference
Operations on Buckets (SOAP API)

Name Description Required

convenient for pagination: To get the next page of results use the
last key of the current page as the marker.

Type: String

Default: None

max-keys The maximum number of keys you'd like to see in the response No
body. The server might return fewer than this many keys, but will
not return more.

Type: String

Default: None

delimiter Causes keys that contain the same string between the prefix and No
the first occurrence of the delimiter to be rolled up into a single
result element in the CommonPrefixes collection. These rolled-up
keys are not returned elsewhere in the response.

Type: String

Default: None

Success Response
This response assumes the bucket contains the following keys:

notes/todos.txt
notes/2005-05-23/customer_mtg_notes.txt
notes/2005-05-23/phone_notes.txt
notes/2005-05-28/sales_notes.txt

Syntax

<?xml version="1.0" encoding="UTF-8"?>

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>backups</Name>
<Prefix>notes/</Prefix>
<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>notes/todos.txt</Key>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
<Size>5126</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>webfile</DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Contents>
<CommonPrefixes>
<Prefix>notes/2005-05-23/</Prefix>
</CommonPrefixes>
<CommonPrefixes>

API Version 2006-03-01

737
Amazon Simple Storage Service API Reference
Operations on Buckets (SOAP API)

<Prefix>notes/2005-05-28/</Prefix>
</CommonPrefixes>
</ListBucketResult>

As you can see, many of the ﬁelds in the response echo the request parameters. IsTruncated,
Contents, and CommonPrefixes are the only response elements that can contain new information.

Response Elements

Name Description

Contents Metadata about each object returned.

Type: XML metadata

Ancestor: ListBucketResult

CommonPrefixes A response can contain CommonPrefixes only if you specify a delimiter.

When you do, CommonPrefixes contains all (if there are any) keys between
Prefix and the next occurrence of the string specified by delimiter. In effect,
CommonPrefixes lists keys that act like subdirectories in the directory specified
by Prefix. For example, if prefix is notes/ and delimiter is a slash (/), in
notes/summer/july, the common prefix is notes/summer/.

Type: String

Ancestor: ListBucketResult

Delimiter Causes keys that contain the same string between the prefix and the first
occurrence of the delimiter to be rolled up into a single result element in the
CommonPrefixes collection. These rolled-up keys are not returned elsewhere in
the response.

Type: String

Ancestor: ListBucketResult

IsTruncated Speciﬁes whether (true) or not (false) all of the results were returned. All of the
results may not be returned if the number of results exceeds that speciﬁed by
MaxKeys.

Type: String

Ancestor: boolean

Marker Indicates where in the bucket to begin listing.

Type: String

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The GetBucketAccessControlPolicy operation fetches the access control policy for a bucket.

Example

This example retrieves the access control policy for the "quotes" bucket.

Sample Request

<GetBucketAccessControlPolicy xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetBucketAccessControlPolicy>

Sample Response

<AccessControlPolicy>
<Owner>
<ID>a9a7b886d6fd2441bf9b1c61be666e9</ID>
<DisplayName>chriscustomer</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xsi:type="CanonicalUser">
<ID>a9a7b886d6f41bf9b1c61be666e9</ID>
<DisplayName>chriscustomer</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
<Grant>
<Grantee xsi:type="Group">
<URI>http://acs.amazonaws.com/groups/global/AllUsers<URI>
</Grantee>

API Version 2006-03-01

739
Amazon Simple Storage Service API Reference
Operations on Buckets (SOAP API)

Response Body
The response contains the access control policy for the bucket. For an explanation of this response, see
SOAP Access Policy .

Access Control
You must have READ_ACP rights to the bucket in order to retrieve the access control policy for a bucket.

SetBucketAccessControlPolicy (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The SetBucketAccessControlPolicy operation sets the Access Control Policy for an existing bucket.
If successful, the previous Access Control Policy for the bucket is entirely replaced with the speciﬁed
Access Control Policy.

Example

Give the speciﬁed user (usually the owner) FULL_CONTROL access to the "quotes" bucket.

Sample Request

<SetBucketAccessControlPolicy xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
<AccessControlList>
<Grant>
<Grantee xsi:type="CanonicalUser">
<ID>a9a7b8863000e241bf9b1c61be666e9</ID>
<DisplayName>chriscustomer</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</SetBucketAccessControlPolicy >

Sample Response

Access Control
You must have WRITE_ACP rights to the bucket in order to set the access control policy for a bucket.

API Version 2006-03-01

740
Amazon Simple Storage Service API Reference
Operations on Buckets (SOAP API)

GetBucketLoggingStatus (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The GetBucketLoggingStatus retrieves the logging status for an existing bucket.

For a general introduction to this feature, see Server Logs.

Example
Sample Request

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/
XMLSchema">
<soap:Body>
<GetBucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>mybucket</Bucket>
<AWSAccessKeyId>YOUR_AWS_ACCESS_KEY_ID</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>YOUR_SIGNATURE_HERE</Signature>
</GetBucketLoggingStatus>
</soap:Body>
</soap:Envelope>

Sample Response

<?xml version="1.0" encoding="utf-8"?>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" >
<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<GetBucketLoggingStatusResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<GetBucketLoggingStatusResponse>
<LoggingEnabled>
<TargetBucket>mylogs</TargetBucket>
<TargetPrefix>mybucket-access_log-</TargetPrefix>
</LoggingEnabled>
</GetBucketLoggingStatusResponse>
</GetBucketLoggingStatusResponse>
</soapenv:Body>
</soapenv:Envelope>

Access Control
Only the owner of a bucket is permitted to invoke this operation.

SetBucketLoggingStatus (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

API Version 2006-03-01

741
Amazon Simple Storage Service API Reference
Operations on Objects (SOAP API)

The SetBucketLoggingStatus operation updates the logging status for an existing bucket.

For a general introduction to this feature, see Server Logs.

Example

This sample request enables server access logging for the 'mybucket' bucket, and conﬁgures the logs to
be delivered to 'mylogs' under preﬁx 'access_log-'

Sample Request

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/
XMLSchema">
<soap:Body>
<SetBucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>myBucket</Bucket>
<AWSAccessKeyId>YOUR_AWS_ACCESS_KEY_ID</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>YOUR_SIGNATURE_HERE</Signature>
<BucketLoggingStatus>
<LoggingEnabled>
<TargetBucket>mylogs</TargetBucket>
<TargetPrefix>mybucket-access_log-</TargetPrefix>
</LoggingEnabled>
</BucketLoggingStatus>
</SetBucketLoggingStatus>
</soap:Body>
:</soap:Envelope>

Sample Response

<?xml version="1.0" encoding="utf-8"?>

Access Control
Only the owner of a bucket is permitted to invoke this operation.

Operations on Objects (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

This section describes operations you can perform on Amazon S3 objects.

API Version 2006-03-01

742
Amazon Simple Storage Service API Reference
Operations on Objects (SOAP API)

Topics
• PutObjectInline (SOAP API) (p. 743)
• PutObject (SOAP API) (p. 745)
• CopyObject (SOAP API) (p. 746)
• GetObject (SOAP API) (p. 751)
• GetObjectExtended (SOAP API) (p. 755)
• DeleteObject (SOAP API) (p. 756)
• GetObjectAccessControlPolicy (SOAP API) (p. 757)
• SetObjectAccessControlPolicy (SOAP API) (p. 757)

PutObjectInline (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The PutObjectInline operation adds an object to a bucket. The data for the object is provided in the
body of the SOAP message.

If an object already exists in a bucket, the new object will overwrite it because Amazon S3 stores the last
write request. However, Amazon S3 is a distributed system. If Amazon S3 receives multiple write requests
for the same object nearly simultaneously, all of the objects might be stored, even though only one wins
in the end. Amazon S3 does not provide object locking; if you need this, make sure to build it into your
application layer.

To ensure an object is not corrupted over the network, you can calculate the MD5 of an object, PUT it to
Amazon S3, and compare the returned Etag to the calculated MD5 value.

PutObjectInline is not suitable for use with large objects. The system limits this operation to working
with objects 1MB or smaller. PutObjectInline will fail with the InlineDataTooLargeError status code
if the Data parameter encodes an object larger than 1MB. To upload large objects, consider using the
non-inline PutObject API, or the REST API instead.

Example

This example writes some text and metadata into the "Nelson" object in the "quotes" bucket, give a user
(usually the owner) FULL_CONTROL access to the object, and make the object readable by anonymous
parties.

Sample Request

API Version 2006-03-01

CopySourceIfNoneMatch.
Note
You might need to conﬁgure the SOAP stack socket timeout for copying large objects.

Request Syntax

<CopyObject xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01">
<SourceBucket>source_bucket</SourceBucket>
<SourceObject>source_object</SourceObject>
<DestinationBucket>destination_bucket</DestinationBucket>
<DestinationObject>destination_object</DestinationObject>
<MetadataDirective>{REPLACE | COPY}</MetadataDirective>
<Metadata>
<Name>metadata_name</Name>
<Value>metadata_value</Value>
</Metadata>
...
<AccessControlList>
<Grant>
<Grantee xsi:type="user_type">
<ID>user_id</ID>
<DisplayName>display_name</DisplayName>
</Grantee>
<Permission>permission</Permission>
</Grant>
...
</AccessControlList>
<CopySourceIfMatch>etag</CopySourceIfMatch>
<CopySourceIfNoneMatch>etag</CopySourceIfNoneMatch>
<CopySourceIfModifiedSince>date_time</CopySourceIfModifiedSince>
<CopySourceIfUnmodifiedSince>date_time</CopySourceIfUnmodifiedSince>
<AWSAccessKeyId>AWSAccessKeyId</AWSAccessKeyId>
<Timestamp>TimeStamp</Timestamp>
<Signature>Signature</Signature>
</CopyObject>

Request Parameters

Name Description Required

SourceBucket The name of the source bucket. Yes

Type: String

Default: None

Constraints: A valid source bucket.

SourceKey The key name of the source object. Yes

Type: String

the destination bucket.

MetadataDirective Speciﬁes whether the metadata is copied No

from the source object or replaced with
metadata provided in the request.

Type: String

Default: COPY

Valid values: COPY | REPLACE

Constraints: Values other than COPY or

REPLACE will result in an immediate error.
You cannot copy an object to itself unless
the MetadataDirective header is speciﬁed
and its value set to REPLACE.

Metadata Speciﬁes metadata name-value pairs to set No

for the object.If MetadataDirective is set to
COPY, all metadata is ignored.

Type: String

Default: None

since the speciﬁed time; otherwise returns a
PreconditionFailed.

Type: dateTime

Default: None

CopySourceIfModifiedSince Copies the object if it has been modiﬁed No

since the speciﬁed time; otherwise returns an
error.

Type: dateTime

Sample Response

API Version 2006-03-01

751
Amazon Simple Storage Service API Reference
Operations on Objects (SOAP API)

<GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<GetObjectResponse>
<Status>
<Code>200</Code>
<Description>OK</Description>
</Status>
<Metadata>
<Name>Content-Type</Name>
<Value>text/plain</Value>
</Metadata>
<Metadata>
<Name>family</Name>
<Value>Muntz</Value>
</Metadata>
<Data>aGEtaGE=</Data>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
</GetObjectResponse>
</GetObjectResponse>

Elements
• Bucket: The bucket from which to retrieve the object.
• Key: The key that identifies the object.
• GetMetadata: The metadata is returned with the object if this is true.
• GetData: The object data is returned if this is true.
• InlineData: If this is true, then the data is returned, base 64-encoded, as part of the SOAP body of
the response. If false, then the data is returned as a SOAP attachment. The InlineData option is not
suitable for use with large objects. The system limits this operation to working with 1MB of data or
less. A GetObject request with the InlineData flag set will fail with the InlineDataTooLargeError
status code if the resulting Data parameter would have encoded more than 1MB. To download large
objects, consider calling GetObject without setting the InlineData flag, or use the REST API instead.

Returned Elements
• Metadata: The name-value paired metadata stored with the object.
• Data: If InlineData was true in the request, this contains the base 64 encoded object data.
• LastModified: The time that the object was stored in Amazon S3.
• ETag: The object's entity tag. This is a hash of the object that can be used to do conditional gets. The
ETag only reﬂects changes to the contents of an object, not its metadata.

Access Control
You can read an object only if you have been granted READ access to the object.

SOAP Chunked and Resumable Downloads

To provide GET ﬂexibility, Amazon S3 supports chunked and resumable downloads.

Select from the following:

• For large object downloads, you might want to break them into smaller chunks. For more information,
see Range GETs (p. 753)
• For GET operations that fail, you can design your application to download the remainder instead of the
entire ﬁle. For more information, see REST GET Error Recovery (p. 755)

API Version 2006-03-01

752
Amazon Simple Storage Service API Reference
Operations on Objects (SOAP API)

Range GETs

For some clients, you might want to break large downloads into smaller downloads. To break a GET into
smaller units, use Range.

Before you can break a GET into smaller units, you must determine its size. For example, the following
request gets the size of the bigﬁle object.

<ListBucket xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>bigbucket</Bucket>
<Prefix>bigfile</Prefix>
<MaxKeys>1</MaxKeys>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</ListBucket>

Amazon S3 returns the following response.

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<Name>quotes</Name>
<Prefix>N</Prefix>
<MaxKeys>1</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>bigfile</Key>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
<Size>2023276</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>bcaf1ffd86f41161ca5fb16fd081034f</ID>
<DisplayName>bigfile</DisplayName>
</Owner>
</Contents>
</ListBucketResult>

Following is a request that downloads the ﬁrst megabyte from the bigﬁle object.

<GetObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>bigbucket</Bucket>
<Key>bigfile</Key>
<GetMetadata>true</GetMetadata>
<GetData>true</GetData>
<InlineData>true</InlineData>
<ByteRangeStart>0</ByteRangeStart>
<ByteRangeEnd>1048576</ByteRangeEnd>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

Amazon S3 returns the first megabyte of the file and the Etag of the file.

API Version 2006-03-01

753
Amazon Simple Storage Service API Reference
Operations on Objects (SOAP API)

<Name>Content-Type</Name>
<Value>text/plain</Value>
</Metadata>
<Metadata>
<Name>family</Name>
<Value>Muntz</Value>
</Metadata>
<Data>--first megabyte of bigfile--</Data>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
</GetObjectResponse>
</GetObjectResponse>

To ensure the ﬁle did not change since the previous portion was downloaded, specify the IfMatch
element. Although the IfMatch element is not required, it is recommended for content that is likely to
change.

The following is a request that gets the remainder of the ﬁle, using the IfMatch request header.

<GetObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>bigbucket</Bucket>
<Key>bigfile</Key>
<GetMetadata>true</GetMetadata>
<GetData>true</GetData>
<InlineData>true</InlineData>
<ByteRangeStart>10485761</ByteRangeStart>
<ByteRangeEnd>2023276</ByteRangeEnd>
<IfMatch>"828ef3fdfa96f00ad9f27c383fc9ac7f"</IfMatch>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

Amazon S3 returns the following response and the remainder of the ﬁle.

<GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<GetObjectResponse>
<Status>
<Code>200</Code>
<Description>OK</Description>
</Status>
<Metadata>
<Name>Content-Type</Name>
<Value>text/plain</Value>
</Metadata>
<Metadata>
<Name>family</Name>
<Value>>Muntz</Value>
</Metadata>
<Data>--remainder of bigfile--</Data>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
</GetObjectResponse>
</GetObjectResponse>

Versioned GetObject
The following request returns the speciﬁed version of the object in the bucket.

<GetObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
<Key>Nelson</Key>

API Version 2006-03-01

754
Amazon Simple Storage Service API Reference
Operations on Objects (SOAP API)

<GetMetadata>true</GetMetadata>
<GetData>true</GetData>
<InlineData>true</InlineData>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

Sample Response

REST GET Error Recovery

If an object GET fails, you can get the rest of the ﬁle by specifying the range to download. To do so, you
must get the size of the object using ListBucket and perform a range GET on the remainder of the ﬁle.
For more information, see GetObjectExtended (SOAP API) (p. 755).

Related Resources

Operations on Objects (SOAP API) (p. 742)

GetObjectExtended (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

GetObjectExtended is exactly like GetObject (SOAP API) (p. 751), except that it supports the
following additional elements that can be used to accomplish much of the same functionality provided
by HTTP GET headers (go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).

GetObjectExtended supports the following elements in addition to those supported by GetObject:

API Version 2006-03-01

755
Amazon Simple Storage Service API Reference
Operations on Objects (SOAP API)

• IfMatch: Return the object only if its ETag matches the supplied tag(s). (go to http://www.w3.org/
Protocols/rfc2616/rfc2616-sec14.html#sec14.24)
• IfNoneMatch: Return the object only if its ETag does not match the supplied tag(s). (go to http://
www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26)
• ReturnCompleteObjectOnConditionFailure:ReturnCompleteObjectOnConditionFailure: If
true, then if the request includes a range element and one or both of IfUnmodiﬁedSince/IfMatch
elements, and the condition fails, return the entire object rather than a fault. This enables the If-Range
functionality (go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.27).

DeleteObject (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The DeleteObject operation removes the speciﬁed object from Amazon S3. Once deleted, there is no
method to restore or undelete an object.
Note
If you delete an object that does not exist, Amazon S3 will return a success (not an error
message).

Example

This example deletes the "Nelson" object from the "quotes" bucket.

Sample Request

<DeleteObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
<Key>Nelson</Key>
<AWSAccessKeyId> AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</DeleteObject>

Sample Response

Elements
• Bucket: The bucket that holds the object.
• Key: The key that identiﬁes the object.

Access Control
You can delete an object only if you have WRITE access to the bucket, regardless of who owns the object
or what rights are granted to it.

API Version 2006-03-01

756
Amazon Simple Storage Service API Reference
Operations on Objects (SOAP API)

GetObjectAccessControlPolicy (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The GetObjectAccessControlPolicy operation fetches the access control policy for an object.

Example
This example retrieves the access control policy for the "Nelson" object from the "quotes" bucket.

Sample Request

<GetObjectAccessControlPolicy xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
<Key>Nelson</Key>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObjectAccessControlPolicy>

Sample Response

<AccessControlPolicy>
<Owner>
<ID>a9a7b886d6fd24a541bf9b1c61be666e9</ID>
<DisplayName>chriscustomer</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xsi:type="CanonicalUser">
<ID>a9a7b841bf9b1c61be666e9</ID>
<DisplayName>chriscustomer</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
<Grant>
<Grantee xsi:type="Group">
<URI>http://acs.amazonaws.com/groups/global/AllUsers<URI>
</Grantee>
<Permission>READ</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>

Response Body
The response contains the access control policy for the bucket. For an explanation of this response, SOAP
Access Policy .

Access Control
You must have READ_ACP rights to the object in order to retrieve the access control policy for an object.

SetObjectAccessControlPolicy (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

API Version 2006-03-01

757
Amazon Simple Storage Service API Reference
SOAP Error Responses

The SetObjectAccessControlPolicy operation sets the access control policy for an existing object.
If successful, the previous access control policy for the object is entirely replaced with the speciﬁed
access control policy.

Example

This example gives the speciﬁed user (usually the owner) FULL_CONTROL access to the "Nelson" object
from the "quotes" bucket.

Sample Request

<SetObjectAccessControlPolicy xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
<Key>Nelson</Key>
<AccessControlList>
<Grant>
<Grantee xsi:type="CanonicalUser">
<ID>a9a7b886d6fd24a52fe8ca5bef65f89a64e0193f23000e241bf9b1c61be666e9</ID>
<DisplayName>chriscustomer</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</SetObjectAccessControlPolicy>

Sample Response

Access Control
You must have WRITE_ACP rights to the object in order to set the access control policy for a bucket.

SOAP Error Responses

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

In SOAP, an error result is returned to the client as a SOAP fault, with the HTTP response code 500. If
you do not receive a SOAP fault, then your request was successful. The Amazon S3 SOAP fault code is
comprised of a standard SOAP 1.1 fault code (either "Server" or "Client") concatenated with the Amazon
S3-speciﬁc error code. For example: "Server.InternalError" or "Client.NoSuchBucket". The SOAP fault
string element contains a generic, human readable error message in English. Finally, the SOAP fault
detail element contains miscellaneous information relevant to the error.

For example, if you attempt to delete the object "Fred", which does not exist, the body of the SOAP
response contains a "NoSuchKey" SOAP fault.

The following example shows a sample SOAP error response.

API Version 2006-03-01

758
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

<soapenv:Body>
<soapenv:Fault>
<Faultcode>soapenv:Client.NoSuchKey</Faultcode>
<Faultstring>The specified key does not exist.</Faultstring>
<Detail>
<Key>Fred</Key>
</Detail>
</soapenv:Fault>
</soapenv:Body>

The following table explains the SOAP error response elements

Name Description

Detail Container for the key involved in the error

Type: Container

Ancestor: Body.Fault

Fault Container for error information.

Type: Container

Ancestor: Body

Faultcode The fault code is a string that uniquely identiﬁes an error condition. It is meant to be
read and understood by programs that detect and handle errors by type. For more
information, see List of Error Codes (p. 686).

Type: String

Ancestor: Body.Fault

Faultstring The fault string contains a generic description of the error condition in English. It is
intended for a human audience. Simple programs display the message directly to
the end user if they encounter an error condition they don't know how or don't care
to handle. Sophisticated programs with more exhaustive error handling and proper
internationalization are more likely to ignore the fault string.

Type: String

Ancestor: Body.Fault

Key Identiﬁes the key involved in the error

Type: String

Ancestor: Body.Fault

Appendix: Lifecycle Conﬁguration APIs

(Deprecated)
Bucket lifecycle configuration is updated to support filters based on object tags. That is, you can now
specify a rule that specifies key name prefix, one or more object tags, or both to select a subset of

API Version 2006-03-01

759
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

objects to which the rule applies. The APIs have been updated accordingly. The following topics describes
the prior version of the PUT and GET bucket lifecycle operations for backward compatibility.

Topics
• PUT Bucket lifecycle (Deprecated) (p. 761)
• GET Bucket lifecycle (Deprecated) (p. 771)

API Version 2006-03-01

760
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle (Deprecated)

PUT Bucket lifecycle (Deprecated)

Description
Important
For an updated version of this API, see PutBucketLifecycleConfiguration (p. 264). This version
has been deprecated. Existing lifecycle configurations will work. For new lifecycle configurations,
use the updated API.

Permissions
By default, all Amazon S3 resources, including buckets, objects, and related subresources (for
example, lifecycle conﬁguration and website conﬁguration) are private. Only the resource owner,
the AWS account that created the resource, can access it. The resource owner can optionally grant
access permissions to others by writing an access policy. For this operation, users must get the
s3:PutLifecycleConfiguration permission.

• s3:DeleteObject
• s3:DeleteObjectVersion
• s3:PutLifecycleConfiguration

For more information about permissions, see Managing Access Permissions to Your Amazon S3 Resources
in the Amazon Simple Storage Service Developer Guide.

Requests
Syntax
PUT /?lifecycle HTTP/1.1
Host: bucketname.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string
Content-MD5: MD5

Lifecycle configuration in the request body

For details about authorization strings, see Authenticating Requests (AWS Signature Version 4) (p. 603).

Request Parameters
This implementation of the operation does not use request parameters.

Request Headers

Name Description Required

Content-MD5 The base64-encoded 128-bit MD5 digest of the Yes

data. You must use this header as a message

API Version 2006-03-01

761
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle (Deprecated)

Name Description Required

integrity check to verify that the request body was
not corrupted in transit. For more information, see
RFC 1864.

Type: String

Default: None

Request Body
In the request, you specify the lifecycle configuration in the request body. The lifecycle configuration
is specified as XML. The following is an example of a basic lifecycle configuration. It specifies one rule.
The Prefix in the rule identifies objects to which the rule applies. The rule also specifies two actions
(Transitionand Expiration). Each action specifies a timeline when Amazon S3 should perform the
action. The Status indicates whether the rule is enabled or disabled.

API Version 2006-03-01

762
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle (Deprecated)

<LifecycleConfiguration>
<Rule>
<ID>sample-rule</ID>
<Prefix>SomeKeyPrefix/</Prefix>
<Status>rule-status</Status>
<AbortIncompleteMultipartUpload>
<DaysAfterInitiation>7</DaysAfterInitiation>
</AbortIncompleteMultipartUpload>
</Rule>
</LifecycleConfiguration>

The following table describes the XML elements in the lifecycle conﬁguration.

Name Description Required

Container for specifying when an incomplete

AbortIncompleteMultipartUpload Yes, if no
multipart upload becomes eligible for an abort other action
operation. is speciﬁed
for the rule
Child: DaysAfterInitiation

Type: Container

Ancestor: Rule

Date Date when you want Amazon S3 to take the Yes, if

action. For more information, see Lifecycle Rules: Days and
Based on a Speciﬁc Date in the Amazon Simple ExpiredObjectDeleteMa
Storage Service Developer Guide. are absent

The date value must conform to ISO 8601

format. The time is always midnight UTC.

Type: String

Ancestor: Expiration or Transition

Days Speciﬁes the number of days after object creation Yes, if

when the speciﬁc rule action takes eﬀect. Date and
ExpiredObjectDeleteMa
Type: Nonnegative Integer when used with are absent
Transition, Positive Integer when used with
Expiration

Ancestor: Expiration, Transition

DaysAfterInitiation Speciﬁes the number of days after initiating a Yes, if a

multipart upload when the multipart upload parent tag is
must be completed. If it does not complete by speciﬁed
the speciﬁed number of days, it becomes eligible
for an abort operation and Amazon S3 aborts the
incomplete multipart upload.

Type: Positive Integer

Ancestor: AbortIncompleteMultipartUpload

API Version 2006-03-01

763
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle (Deprecated)

Name Description Required

Expiration This action speciﬁes a period in an object's Yes, if no

lifetime when Amazon S3 should take the other action
appropriate expiration action. The action Amazon is present in
S3 takes depends on whether the bucket is the Rule.
versioning-enabled.

• If versioning has never been enabled on the

bucket, Amazon S3 deletes the only copy of the
object permanently.
• If the bucket is versioning-enabled (or
versioning is suspended), the action applies
only to the current version of the object. A
versioning-enabled bucket can have many
versions of the same object: one current version
and zero or more noncurrent versions.

Instead of deleting the current version, Amazon

S3 makes it a noncurrent version by adding a
delete marker as the new current version.
Important
If a bucket's state is versioning-
suspended, Amazon S3 creates a
delete marker with version ID null.
If you have a version with version ID
null, Amazon S3 overwrites that
version.
Note
To set the expiration for
noncurrent objects, use the
NoncurrentVersionExpiration
action.

Type: Container

Children: Days or Date

Ancestor: Rule

ID Unique identiﬁer for the rule. The value cannot No

be longer than 255 characters.

Type: String

Ancestor: Rule

LifecycleConfiguration Container for lifecycle rules. You can add as many Yes
as 1000 rules.

Type: Container

Children: Rule

Ancestor: None

API Version 2006-03-01

764
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle (Deprecated)

Name Description Required

ExpiredObjectDeleteMarker On a versioned bucket (a versioning-enabled Yes, if Date

or versioning-suspended bucket), you can add and Days
this element in the lifecycle conﬁguration are absent
to tell Amazon S3 to delete expired object
delete markers. For an example, see Example
8: Removing Expired Object Delete Markers in
the Amazon Simple Storage Service Developer
Guide. Don't add it to a non-versioned bucket,
because that type of bucket cannot include delete
markers.

Type: String

Valid values: true | false (the value false is

allowed, but it is no-op, which means that
Amazon S3 will not take action)

Ancestor: Expiration

NoncurrentDays Speciﬁes the number of days an object is Yes

noncurrent before Amazon S3 can perform
the associated action. For information about
the noncurrent days calculations, see How
Amazon S3 Calculates When an Object Became
Noncurrent in the Amazon Simple Storage Service
Developer Guide.

Type: Nonnegative Integer when used

with NoncurrentVersionTransition,
Positive Integer when used with
NoncurrentVersionExpiration

Ancestor: NoncurrentVersionExpiration or
NoncurrentVersionTransition

NoncurrentVersionExpiration Speciﬁes when noncurrent object versions expire. Yes, if no

Upon expiration, Amazon S3 permanently deletes other action
the noncurrent object versions. is present in
the Rule
Set this lifecycle conﬁguration action on a bucket
that has versioning enabled (or suspended) to tell
Amazon S3 to delete noncurrent object versions
at a speciﬁc period in the object's lifetime.

Type: Container

Children: NoncurrentDays

Ancestor: Rule

API Version 2006-03-01

765
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle (Deprecated)

Name Description Required

NoncurrentVersionTransition Container for the transition rule that describes Yes, if no

when noncurrent objects transition to the other action
STANDARD_IA, ONEZONE_IA, or GLACIER storage is present in
class. the Rule

If your bucket is versioning-enabled (or if

versioning is suspended), you can set this action
to tell Amazon S3 to transition noncurrent
object versions at a speciﬁc period in the object's
lifetime.

Type: Container

Children: NoncurrentDays and StorageClass

Ancestor: Rule

Prefix Object key preﬁx that identiﬁes one or more Yes

objects to which the rule applies.

Type: String

Ancestor: Rule

Rule Container for a lifecycle rule. A lifecycle Yes

conﬁguration can contain as many as 1000 rules.

Type: Container

Ancestor:LifecycleConﬁguration

Status If enabled, Amazon S3 executes the rule as Yes

scheduled. If it is disabled, Amazon S3 ignores the
rule.

Type: String

Ancestor: Rule

Valid values: Enabled, Disabled

StorageClass Speciﬁes the Amazon S3 storage class to which Yes

you want the object to transition.
This element
Type: String is required
only if you
Ancestor: Transition and specify one
NoncurrentVersionTransition or both its
ancestors.
Valid values: STANDARD_IA | ONEZONE_IA |
GLACIER

API Version 2006-03-01

766
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle (Deprecated)

Name Description Required

Transition This action speciﬁes a period in the objects' Yes, if no

lifetime when Amazon S3 should transition them other action
to the STANDARD_IA, ONEZONE_IA, or GLACIER is present in
storage class. When this action is in eﬀect, what the Rule
Amazon S3 does depends on whether the bucket
is versioning-enabled.

• If versioning has never been enabled on the

bucket, Amazon S3 transitions the only copy of
the object to the specified storage class.
• If your bucket is versioning-enabled (or
versioning is suspended), Amazon S3
transitions only the current versions of objects
identified in the rule.
Note
A versioning-enabled bucket can
have many versions of an object. This
action has no effect on noncurrent
object versions. To transition
noncurrent objects, you must use the
NoncurrentVersionTransition
action.

Type: Container

Children: Days or Date, and StorageClass

Ancestor: Rule

Responses
Response Headers
This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements
This implementation of the operation does not return response elements.

Special Errors
This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples
Example 1: Add Lifecycle Configuration to a Bucket That Is Not Versioning-
enabled
The following lifecycle configuration specifies two rules, each with one action.

API Version 2006-03-01

767
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle (Deprecated)

<LifecycleConfiguration>
<Rule>
<ID>id1</ID>
<Prefix>documents/</Prefix>
<Status>Enabled</Status>
<Transition>
<Days>30</Days>
<StorageClass>GLACIER</StorageClass>
</Transition>
</Rule>
<Rule>
<ID>id2</ID>
<Prefix>logs/</Prefix>
<Status>Enabled</Status>
<Expiration>
<Days>365</Days>
</Expiration>
</Rule>
</LifecycleConfiguration>

The following is a sample PUT /?lifecycle request that adds the preceding lifecycle conﬁguration to
the examplebucket bucket.

PUT /?lifecycle HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Wed, 14 May 2014 02:11:21 GMT
Content-MD5: q6yJDlIkcBaGGfb3QLY69A==
Authorization: authorization string
Content-Length: 415

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: r+qR7+nhXtJDDIJ0JJYcd+1j5nM/rUFiiiZ/fNbDOsd3JUE8NWMLNHXmvPfwMpdc
x-amz-request-id: 9E26D08072A8EF9E
Date: Wed, 14 May 2014 02:11:22 GMT

API Version 2006-03-01

768
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle (Deprecated)

Content-Length: 0
Server: AmazonS3

Example 2: Add Lifecycle Conﬁguration to a Versioning-enabled Bucket

• The NoncurrentVersionExpiration action tells Amazon S3 to expire noncurrent versions of

<LifeCycleConfiguration>
<Rule>
<ID>DeleteAfterBecomingNonCurrent</ID>
<Prefix>logs/</Prefix>
<Status>Enabled</Status>
<NoncurrentVersionExpiration>
<NoncurrentDays>100</NoncurrentDays>
</NoncurrentVersionExpiration>
</Rule>
<Rule>
<ID>TransitionAfterBecomingNonCurrent</ID>
<Prefix>documents/</Prefix>
<Status>Enabled</Status>
<NoncurrentVersionTransition>
<NoncurrentDays>30</NoncurrentDays>
<StorageClass>GLACIER</StorageClass>
</NoncurrentVersionTransition>
</Rule>
</LifeCycleConfiguration>

The following is a sample PUT /?lifecycle request that adds the preceding lifecycle conﬁguration to
the examplebucket bucket.

PUT /?lifecycle HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Wed, 14 May 2014 02:21:48 GMT
Content-MD5: 96rxH9mDqVNKkaZDddgnw==
Authorization: authorization string
Content-Length: 598

<LifeCycleConfiguration>
<Rule>
<ID>DeleteAfterBecomingNonCurrent</ID>
<Prefix>logs/</Prefix>
<Status>Enabled</Status>
<NoncurrentVersionExpiration>
<NoncurrentDays>1</NoncurrentDays>
</NoncurrentVersionExpiration>
</Rule>
<Rule>
<ID>TransitionSoonAfterBecomingNonCurrent</ID>
<Prefix>documents/</Prefix>
<Status>Enabled</Status>
<NoncurrentVersionTransition>
<NoncurrentDays>0</NoncurrentDays>
<StorageClass>GLACIER</StorageClass>
</NoncurrentVersionTransition>

API Version 2006-03-01

769
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle (Deprecated)

</Rule>
</LifeCycleConfiguration>

The following is a sample response.

Additional Examples
For more examples of transitioning objects to storage classes such as STANDARD_IA or ONEZONE_IA, see
Examples of Lifecycle Conﬁguration.

Related Resources
• GetBucketLifecycleConﬁguration (p. 102)
• POST Object restore (p. 651)
• By default, a resource owner—in this case, a bucket owner, which is the AWS account that created the
bucket—can perform any of the operations. A resource owner can also grant others permission to
perform the operation. For more information, see the following topics in the Amazon Simple Storage
Service Developer Guide:
• Specifying Permissions in a Policy
• Managing Access Permissions to Your Amazon S3 Resources

API Version 2006-03-01

770
Amazon Simple Storage Service API Reference
GET Bucket lifecycle (Deprecated)

GET Bucket lifecycle (Deprecated)

Description
Important
For an updated version of this API, see GetBucketLifecycleConfiguration (p. 102). If you
configured a bucket lifecycle using the <filter> element, you should see an updated version of
this topic. This topic is provided for backward compatibility.

Returns the lifecycle conﬁguration information set on the bucket. For information about lifecycle
conﬁguration, go to Object Lifecycle Management in the Amazon Simple Storage Service Developer Guide.

To use this operation, you must have permission to perform the s3:GetLifecycleConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission to
others. For more information about permissions, see Managing Access Permissions to Your Amazon S3
Resources in the Amazon Simple Storage Service Developer Guide.

Requests
Syntax

GET /?lifecycle HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters
This implementation of the operation does not use request parameters.

Request Headers
This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements
This implementation of the operation does not use request elements.

Responses
Response Headers
This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements
This implementation of GET returns the following response elements.

Name Description Required

Container for specifying when an incomplete

AbortIncompleteMultipartUpload Yes, if no
multipart upload becomes eligible for an abort other action
operation. is speciﬁed
for the rule

API Version 2006-03-01

771
Amazon Simple Storage Service API Reference
GET Bucket lifecycle (Deprecated)

Name Description Required

Child: DaysAfterInitiation

Type: Container

Ancestor: Rule

Date Date when you want Amazon S3 to take the Yes, if

action. For more information, see Lifecycle Rules: Days and
Based on a Speciﬁc Date in the Amazon Simple ExpiredObjectDeleteMa
Storage Service Developer Guide. are absent

The date value must conform to the ISO 8601

format. The time is always midnight UTC.

Type: String

Ancestor: Expiration or Transition

Days Speciﬁes the number of days after object creation Yes, if

when the speciﬁc rule action takes eﬀect. The Date and
object's eligibility time is calculated as creation ExpiredObjectDeleteMa
time + the number of days with the resulting time are absent
rounded to midnight UTC of the next day.

Type: Non-negative Integer when used with

Transition, Positive Integer when used with
Expiration.

Ancestor: Transition or Expiration

DaysAfterInitiation Speciﬁes the number of days after initiating a Yes, if Date

multipart upload when the multipart upload is absent
must be completed. If it does not complete by
the speciﬁed number of days, it becomes eligible
for an abort operation and Amazon S3 aborts the
incomplete multipart upload.

Type: Positive Integer

Ancestor: AbortIncompleteMultipartUpload

API Version 2006-03-01

772
Amazon Simple Storage Service API Reference
GET Bucket lifecycle (Deprecated)

Name Description Required

Expiration This action speciﬁes a period in the object's Yes, if the

lifetime when Amazon S3 should take the parent tag is
appropriate expiration action. The expiration speciﬁed
action occurs only on objects that are eligible
according to the period speciﬁed in the child
Date or Days element. The action Amazon
S3 takes depends on whether the bucket is
versioning enabled.

• If versioning has never been enabled on the

bucket, Amazon S3 deletes the only copy of the
object permanently.
• Otherwise, if your bucket is versioning-
enabled (or versioning is suspended), the
action applies only to the current version of the
object. Buckets that are versioning-enabled or
versioning-suspended can have many versions
of the same object: one current version, and
zero or more noncurrent versions.

Instead of deleting the current version, Amazon

S3 makes it a noncurrent version by adding a
delete marker as the new current version.
Important
If the state of a bucket is versioning-
suspended, Amazon S3 creates a
delete marker with version ID null.
If you have a version with version ID
null, then Amazon S3 overwrites that
version.
Note
To set the expiration for noncurrent
objects, you must use the
NoncurrentVersionExpiration
action.

Type: Container

Children: Days or Date

Ancestor: Rule

ID Unique identiﬁer for the rule. The value cannot No

be longer than 255 characters.

Type: String

Ancestor: Rule

API Version 2006-03-01

773
Amazon Simple Storage Service API Reference
GET Bucket lifecycle (Deprecated)

Name Description Required

LifecycleConfiguration Container for lifecycle rules. You can add as many Yes
as 1000 rules.

Type: Container

Children: Rule

Ancestor: None

ExpiredObjectDeleteMarker On a versioned bucket (versioning-enabled or Yes, if Date

versioning-suspended bucket), this element and Days
indicates whether Amazon S3 will delete any are absent
expired object delete markers in the bucket. For
an example, go to Example 8: Specify Expiration
Action to Remove Expired Object Delete Markers
in the Amazon Simple Storage Service Developer
Guide.

Type: String

Valid values: true | false (the value false is

allowed but it is no-op, Amazon S3 doesn't take
action if the value is false)

Ancestor: Expiration

NoncurrentDays Speciﬁes the number of days that an object Yes, only if

is noncurrent before Amazon S3 can perform the ancestor
the associated action. For information about is present
calculating noncurrent days, see Lifecycle Rules
Based on the Number of Days in the Amazon
Simple Storage Service Developer Guide.

Type: Nonnegative Integer when used

with NoncurrentVersionTransition,
Positive Integer when used with
NoncurrentVersionExpiration

Ancestor: NoncurrentVersionExpiration or
NoncurrentVersionTransition

NoncurrentVersionExpiration Speciﬁes when noncurrent object versions expire. Yes, if no

Upon expiration, Amazon S3 permanently deletes other action
the noncurrent object versions. is present in
the Rule
Set this lifecycle conﬁguration action on a bucket
that has versioning enabled (or suspended)
to request that Amazon S3 delete noncurrent
object versions at a speciﬁc period in the object's
lifetime.

Type: Container

Children: NoncurrentDays

Ancestor: Rule

API Version 2006-03-01

774
Amazon Simple Storage Service API Reference
GET Bucket lifecycle (Deprecated)

Name Description Required

NoncurrentVersionTransition Container for the transition rule that describes Yes, if no

when noncurrent objects transition to the other action
STANDARD_IA, ONEZONE_IA, or the GLACIER is present in
storage class. the Rule

If your bucket is versioning-enabled (or

versioning is suspended), you can set this action
to request Amazon S3 to transition noncurrent
object versions to the GLACIER storage class at a
speciﬁc period in the object's lifetime.

Type: Container

Children: NoncurrentDays and StorageClass

Ancestor: Rule

Prefix Object key preﬁx identifying one or more objects Yes

to which the rule applies.

Type: String

Ancestor: Rule

Rule Container for a lifecycle rule. Yes

Type: Container

Ancestor: LifecycleConﬁguration

Status If Enabled, Amazon S3 executes the rule as Yes

scheduled. If Disabled, Amazon S3 ignores the
rule.

Type: String

Ancestor: Rule

Valid values: Enabled or Disabled

StorageClass Speciﬁes the Amazon S3 storage class to which Yes

you want to transition the object.

Type: String

Ancestor: Transition and

NoncurrentVersionTransition

Valid values: STANDARD_IA | ONEZONE_IA |

GLACIER

API Version 2006-03-01

775
Amazon Simple Storage Service API Reference
GET Bucket lifecycle (Deprecated)

Name Description Required

Transition This action speciﬁes a period in the objects' Yes, if no

• If versioning has never been enabled on the

bucket, Amazon S3 transitions the only copy of
the object to the specified storage class.
• When your bucket is versioning-enabled
(or versioning is suspended), Amazon S3
transitions only the current versions of the
objects identified in the rule.
Note
A versioning-enabled or versioning-
suspended bucket can contain many
versions of an object. This action
has no effect on the noncurrent
object versions. To transition
noncurrent objects, you must use the
NoncurrentVersionTransition
action.

Type: Container

Children: Days or Date, and StorageClass

Ancestor: Rule

Special Errors

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

The lifecycle conﬁguration does not

NoSuchLifecycleConfiguration 404 Not Client
exist. Found

For general information about Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples
Example 1: Retrieve a Lifecycle Subresource
This example is a GET request to retrieve the lifecycle subresource from the speciﬁed bucket, and an
example response with the returned lifecycle conﬁguration.

Sample Request

GET /?lifecycle HTTP/1.1

Host: examplebucket.s3.amazonaws.com

API Version 2006-03-01

776
Amazon Simple Storage Service API Reference
GET Bucket lifecycle (Deprecated)

x-amz-date: Thu, 15 Nov 2012 00:17:21 GMT

Authorization: signatureValue

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

Related Resources
• PutBucketLifecycleConﬁguration (p. 264)
• DeleteBucketLifecycle (p. 51)

API Version 2006-03-01

777
Amazon Simple Storage Service API Reference
Amazon S3 REST API Introduction

API Reference Archive

The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

Topics
• Amazon S3 REST API Introduction (p. 778)
• Common Request Headers (p. 779)
• Common Response Headers (p. 782)
• Error Responses (p. 783)
• Authenticating Requests (AWS Signature Version 4) (p. 792)
• Authenticating Requests in Browser-Based Uploads Using POST (AWS Signature Version 4) (p. 829)
• Operations on the Service (p. 846)
• Operations on AWS Accounts (p. 851)
• Operations on Buckets (p. 889)
• Operations on Objects (p. 1227)
• Data Types (p. 1456)
• Amazon S3 Resources (p. 1461)
• Document History (p. 1462)
• Appendix (p. 1477)

Amazon S3 REST API Introduction

Amazon S3 supports the REST API.

Read the following about authentication and access control before going to speciﬁc API topics.

Requests to Amazon S3 can be authenticated or anonymous. Authenticated access requires credentials

API Version 2006-03-01

778
Amazon Simple Storage Service API Reference
Common Request Headers

Set Up the AWS CLI in the Amazon Simple Storage Service Developer Guide.

Using Amazon S3 with the AWS Command Line Interface in the AWS Command Line Interface User
Guide.

Common Request Headers

The following table describes headers that can be used by various types of Amazon S3 REST requests.

Header Name Description

Authorization The information required for request authentication. For more

information, go to The Authentication Header in the Amazon
Simple Storage Service Developer Guide. For anonymous requests
this header is not required.

Content-Length Length of the message (without the headers) according to RFC

2616. This header is required for PUTs and operations that load
XML, such as logging and ACLs.

Content-Type The content type of the resource in case the request content in
the body. Example: text/plain

API Version 2006-03-01

779
Amazon Simple Storage Service API Reference
Common Request Headers

Header Name Description

Valid Values: 100-continue

Host For path-style requests, the value is s3.amazonaws.com.

For virtual-style requests, the value is
BucketName.s3.amazonaws.com. For more information, go to
Virtual Hosting in the Amazon Simple Storage Service Developer
Guide.

This header is required for HTTP 1.1 (most toolkits add this header
automatically); optional for HTTP/1.0 requests.

x-amz-content-sha256 When using signature version 4 to authenticate request, this

header provides a hash of the request payload. For more
information see Signature Calculations for the Authorization
Header: Transferring Payload in a Single Chunk (AWS Signature
Version 4) (p. 797). When uploading object in chunks, you set
the value to STREAMING-AWS4-HMAC-SHA256-PAYLOAD to
indicate that the signature covers only headers and that there is
no payload. For more information, see Signature Calculations for
the Authorization Header: Transferring Payload in Multiple Chunks
(Chunked Upload) (AWS Signature Version 4) (p. 809).

x-amz-security-token This header can be used in the following scenarios:

• Provide security tokens for Amazon DevPay operations -

This header is required for requests that use Amazon DevPay and
requests that are signed using temporary security credentials.

API Version 2006-03-01

780
Amazon Simple Storage Service API Reference
Common Request Headers

API Version 2006-03-01

781
Amazon Simple Storage Service API Reference
Common Response Headers

Common Response Headers

The following table describes response headers that are common to most AWS S3 responses.

Name Description

Content-Length The length in bytes of the body in the response.

Type: String

Default: None

Error Responses
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

This section provides reference information about Amazon S3 errors.

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

Topics

API Version 2006-03-01

783
Amazon Simple Storage Service API Reference
REST Error Responses

• REST Error Responses (p. 784)

• List of Error Codes (p. 785)

REST Error Responses

When an error occurs, the header information contains the following:

• Content-Type: application/xml
• An appropriate 3xx, 4xx, or 5xx HTTP status code

The body or the response also contains information about the error. The following sample error response
shows the structure of response elements common to all REST error responses.

<?xml version="1.0" encoding="UTF-8"?>

<Error>
<Code>NoSuchKey</Code>
<Message>The resource you requested does not exist</Message>
<Resource>/mybucket/myfoto.jpg</Resource>
<RequestId>4442587FB7D0A2F9</RequestId>
</Error>

The following table explains the REST error response elements.

Name Description

Type: String

Ancestor: Error

Error Container for all error elements.

Type: Container

Ancestor: None

The following table lists Amazon S3 error codes.

Error Code Description HTTP SOAP

Status Fault
Code Code
Preﬁx

AccessDenied Access Denied 403 Client

Forbidden

AccountProblem There is a problem with your AWS 403 Client

account that prevents the operation Forbidden
from completing successfully. Please
contact AWS Support for further
assistance, see Contact Us.

AllAccessDisabled All access to this Amazon S3 resource 403 Client

has been disabled. Please contact Forbidden
AWS Support for further assistance,
see Contact Us.

AmbiguousGrantByEmailAddress The email address you provided 400 Bad Client

is associated with more than one Request
account.

AuthorizationHeaderMalformed The authorization header you 400 Bad N/A

provided is invalid. Request

API Version 2006-03-01

785
Amazon Simple Storage Service API Reference
List of Error Codes

Error Code Description HTTP SOAP

Status Fault
Code Code
Preﬁx

BadDigest The Content-MD5 you speciﬁed did 400 Bad Client

not match what we received. Request

BucketAlreadyExists The requested bucket name is not 409 Client

available. The bucket namespace is Conflict
shared by all users of the system.
Please select a diﬀerent name and try
again.

BucketAlreadyOwnedByYou The bucket you tried to create already 409 Client

exists, and you own it. Amazon S3 Conflict
returns this error in all AWS Regions (in all
except us-east-1 (N. Virginia). For regions
legacy compatibility, if you re-create except us-
an existing bucket that you already east-1)
own in us-east-1, Amazon S3 returns
200 OK and resets the bucket access
control lists (ACLs).

BucketNotEmpty The bucket you tried to delete is not 409 Client

InvalidObjectState The operation is not valid for the 403 Client

current state of the object. Forbidden

InvalidPart One or more of the speciﬁed parts 400 Bad Client

could not be found. The part might Request
not have been uploaded, or the
speciﬁed entity tag might not have
matched the part's entity tag.

InvalidPartOrder The list of parts was not in ascending 400 Bad Client
order. Parts list must be speciﬁed in Request
order by part number.

InvalidPayer All access to this object has been 403 Client

disabled. Please contact AWS Support Forbidden
for further assistance, see Contact Us.

InvalidPolicyDocument The content of the form does not 400 Bad Client
meet the conditions speciﬁed in the Request
policy document.

API Version 2006-03-01

787
Amazon Simple Storage Service API Reference
List of Error Codes

Error Code Description HTTP SOAP

Status Fault
Code Code
Preﬁx

InvalidRange The requested range cannot be 416 Client

satisﬁed. Requested
Range
Not
Satisfiable

InvalidRequest Please use AWS4-HMAC-SHA256. 400 Bad N/A

Request

InvalidRequest SOAP requests must be made over an 400 Bad Client

HTTPS connection. Request

InvalidRequest Amazon S3 Transfer Acceleration is 400 Bad N/A

not supported for buckets with non- Request
DNS compliant names.

InvalidRequest Amazon S3 Transfer Acceleration 400 Bad N/A

is not supported for buckets with Request
periods (.) in their names.

InvalidRequest Amazon S3 Transfer Accelerate 400 Bad N/A

endpoint only supports virtual style Request
requests.

InvalidRequest Amazon S3 Transfer Accelerate is not 400 Bad N/A

conﬁgured on this bucket. Request

InvalidRequest Amazon S3 Transfer Accelerate is 400 Bad N/A

disabled on this bucket. Request

InvalidRequest Amazon S3 Transfer Acceleration is 400 Bad N/A

not supported on this bucket. Contact Request
AWS Support for more information.

InvalidRequest Amazon S3 Transfer Acceleration 400 Bad N/A

cannot be enabled on this bucket. Request
Contact AWS Support for more
information.

InvalidSecurity The provided security credentials are 403 Client

not valid. Forbidden

InvalidSOAPRequest The SOAP request body is invalid. 400 Bad Client

Request

InvalidStorageClass The storage class you speciﬁed is not 400 Bad Client
valid. Request

HTTP header. Length
Required

MissingRequestBodyError This happens when the user sends an 400 Bad Client
empty XML document as a request. Request
The error message is, "Request body is
empty."

MissingSecurityElement The SOAP 1.1 request is missing a 400 Bad Client

security element. Request

MissingSecurityHeader Your request is missing a required 400 Bad Client

header. Request

NoLoggingStatusForKey There is no such thing as a logging 400 Bad Client

status subresource for a key. Request

API Version 2006-03-01

789
Amazon Simple Storage Service API Reference
List of Error Codes

Error Code Description HTTP SOAP

Status Fault
Code Code
Preﬁx

NoSuchBucket The speciﬁed bucket does not exist. 404 Not Client
Found

NoSuchBucketPolicy The speciﬁed bucket does not have a 404 Not Client
bucket policy. Found

NoSuchKey The speciﬁed key does not exist. 404 Not Client
Found

NoSuchLifecycleConfiguration The lifecycle conﬁguration does not 404 Not Client

exist. Found

NoSuchUpload The speciﬁed multipart upload does 404 Not Client

not exist. The upload ID might be Found
invalid, or the multipart upload might
have been aborted or completed.

NoSuchVersion Indicates that the version ID speciﬁed 404 Not Client

in the request does not match an Found
existing version.

NotImplemented A header you provided implies 501 Not Server

functionality that is not implemented. Implemented

NotSignedUp Your account is not signed up for the 403 Client

Amazon S3 service. You must sign Forbidden
up before you can use Amazon S3.
You can sign up at the following URL:
https://aws.amazon.com/s3

OperationAborted A conﬂicting conditional operation 409 Client

is currently in progress against this Conflict
resource. Try again.

PermanentRedirect The bucket you are attempting to 301 Client

access must be addressed using the Moved
speciﬁed endpoint. Send all future Permanently
requests to this endpoint.

PreconditionFailed At least one of the preconditions you 412 Client

speciﬁed did not hold. Precondition
Failed

Redirect Temporary redirect. 307 Client

Moved
Temporarily

RestoreAlreadyInProgress Object restore is already in progress. 409 Client

Conflict

RequestIsNotMultiPartContent Bucket POST must be of the 400 Bad Client

enclosure-type multipart/form-data. Request

API Version 2006-03-01

790
Amazon Simple Storage Service API Reference
List of Error Codes

Error Code Description HTTP SOAP

Status Fault
Code Code
Preﬁx

RequestTimeout Your socket connection to the server 400 Bad Client

was not read from or written to Request
within the timeout period.

RequestTimeTooSkewed The diﬀerence between the request 403 Client

time and the server's time is too large. Forbidden

RequestTorrentOfBucketError Requesting the torrent ﬁle of a bucket 400 Bad Client

is not permitted. Request

The server side encryption

ServerSideEncryptionConfigurationNotFoundError 400 Bad Client
conﬁguration was not found. Request

ServiceUnavailable Reduce your request rate. 503 Server

Service
Unavailable

SignatureDoesNotMatch The request signature we calculated 403 Client

does not match the signature Forbidden
you provided. Check your AWS
secret access key and signing
method. For more information, see
REST Authentication and SOAP
Authentication for details.

SlowDown Reduce your request rate. 503 Slow Server

Down

TemporaryRedirect You are being redirected to the bucket 307 Client

while DNS updates. Moved
Temporarily

TokenRefreshRequired The provided token must be 400 Bad Client

refreshed. Request

TooManyBuckets You have attempted to create more 400 Bad Client

buckets than allowed. Request

UnexpectedContent This request does not support 400 Bad Client

content. Request

UnresolvableGrantByEmailAddress The email address you provided does 400 Bad Client
not match any account on record. Request

UserKeyMustBeSpecified The bucket POST must contain the 400 Bad Client
specified field name. If it is specified, Request
check the order of the fields.

API Version 2006-03-01

791
Amazon Simple Storage Service API Reference
Authenticating Requests (AWS Signature Version 4)

Authenticating Requests (AWS Signature Version

4)
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

Topics
• Authentication Methods (p. 793)
• Introduction to Signing Requests (p. 793)
• Authenticating Requests: Using the Authorization Header (AWS Signature Version 4) (p. 794)
• Authenticating Requests: Using Query Parameters (AWS Signature Version 4) (p. 816)
• Examples: Signature Calculations in AWS Signature Version 4 (p. 821)
• Authenticating Requests: Browser-Based Uploads Using POST (AWS Signature Version 4) (p. 823)
• Amazon S3 Signature Version 4 Authentication Speciﬁc Policy Keys (p. 826)

Every interaction with Amazon S3 is either authenticated or anonymous. This section explains request
authentication with the AWS Signature Version 4 algorithm.
Note
If you use the AWS SDKs (see Sample Code and Libraries) to send your requests, you don't
need to read this section because the SDK clients authenticate your requests by using access
keys that you provide. Unless you have a good reason not to, you should always use the AWS
SDKs. In regions that support both signature versions, you can request AWS SDKs to use
speciﬁc signature version. For more information, see Specifying Signature Version in Request
Authentication in the Amazon Simple Storage Service Developer Guide. You need to read this
section only if you are implementing the AWS Signature Version 4 algorithm in your custom
client.

Authentication with AWS Signature version 4 provides some or all of the following, depending on how
you choose to sign your request:

• Verification of the identity of the requester – Authenticated requests require a signature that you
create by using your access keys (access key ID, secret access key). For information about getting access
keys, see Understanding and Getting Your Security Credentials in the AWS General Reference. If you are
using temporary security credentials, the signature calculations also require a security token. For more
information, see Requesting Temporary Security Credentials in the IAM User Guide.
• In-transit data protection – In order to prevent tampering with a request while it is in transit, you use
some of the request elements to calculate the request signature. Upon receiving the request, Amazon
S3 calculates the signature by using the same request elements. If any request component received by
Amazon S3 does not match the component that was used to calculate the signature, Amazon S3 will
reject the request.
• Protect against reuse of the signed portions of the request – The signed portions (using AWS
Signatures) of requests are valid within 15 minutes of the timestamp in the request. An unauthorized
party who has access to a signed request can modify the unsigned portions of the request without
affecting the request's validity in the 15 minute window. Because of this, we recommend that you
maximize protection by signing request headers and body, making HTTPS requests to Amazon S3,
and by using the s3:x-amz-content-sha256 condition key (see Amazon S3 Signature Version
4 Authentication Specific Policy Keys (p. 826)) in AWS policies to require users to sign S3 request
bodies.

API Version 2006-03-01

792
Amazon Simple Storage Service API Reference
Authentication Methods

Note
Amazon S3 supports Signature Version 4, a protocol for authenticating inbound API requests to
AWS services, in all AWS regions. At this time, AWS regions created before January 30, 2014 will
continue to support the previous protocol, Signature Version 2. Any new regions after January
30, 2014 will support only Signature Version 4 and therefore all requests to those regions must
be made with Signature Version 4. For more information about AWS Signature Version 2, see
Signing and Authenticating REST Requests in the Amazon Simple Storage Service Developer
Guide.

Authentication Methods

You can express authentication information by using one of the following methods:

• HTTP Authorization header – Using the HTTP Authorization header is the most common
method of authenticating an Amazon S3 request. All of the Amazon S3 REST operations (except for
browser-based uploads using POST requests) require this header. For more information about the
Authorization header value, and how to calculate signature and related options, see Authenticating
Requests: Using the Authorization Header (AWS Signature Version 4) (p. 794).
• Query string parameters – You can use a query string to express a request entirely in a URL. In
this case, you use query parameters to provide request information, including the authentication
information. Because the request signature is part of the URL, this type of URL is often referred to as
a presigned URL. You can use presigned URLs to embed clickable links, which can be valid for up to
seven days, in HTML. For more information, see Authenticating Requests: Using Query Parameters
(AWS Signature Version 4) (p. 816).

Amazon S3 also supports browser-based uploads that use an HTTP POST requests. With an HTTP
POST request, you can upload content to Amazon S3 directly from the browser. For information about
authenticating POST requests, see Browser-Based Uploads Using POST in the Amazon Simple Storage
Service Developer Guide.

Introduction to Signing Requests

The following diagram illustrates the general process of computing a signature.

API Version 2006-03-01

793
Amazon Simple Storage Service API Reference
Using an Authorization Header

For signing key, the diagram shows series of calculations, where result of each step you feed into the
next step.The ﬁnal step is the signing key.

For more information about authenticating requests, see the following topics:

• Authenticating Requests: Using the Authorization Header (AWS Signature Version 4) (p. 794)
• Authenticating Requests: Using Query Parameters (AWS Signature Version 4) (p. 816)
• Authenticating Requests in Browser-Based Uploads Using POST (AWS Signature Version 4) (p. 829)

Authenticating Requests: Using the Authorization

Header (AWS Signature Version 4)
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

Topics
• Overview (p. 794)
• Signature Calculations for the Authorization Header: Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p. 797)
• Signature Calculations for the Authorization Header: Transferring Payload in Multiple Chunks
(Chunked Upload) (AWS Signature Version 4) (p. 809)

Overview

API Version 2006-03-01

794
Amazon Simple Storage Service API Reference
Using an Authorization Header

Using the HTTP Authorization header is the most common method of providing authentication
information. Except for POST requests (p. 1295) and requests that are signed by using query parameters,
all Amazon S3 bucket operations (p. 889) and object operations (p. 1227) use the Authorization
request header to provide authentication information.

The following is an example of the Authorization header value. Line breaks are added to this example
for readability:

The following table describes the various components of the Authorization header value in the
preceding example:

Component Description

AWS4-HMAC-SHA256 The algorithm that was used to calculate the signature. You must
provide this value when you use AWS Signature Version 4 for
authentication.

The string speciﬁes AWS Signature Version 4 (AWS4) and the

signing algorithm (HMAC-SHA256).

Credential Your access key ID and the scope information, which includes the
date, region, and service that were used to calculate the signature.

This string has the following form:

<your-access-key-id>/<date>/<aws-region>/<aws-service>/
aws4_request

Where:

• <date> value is speciﬁed using YYYYMMDD format.

• <aws-service> value is s3 when sending request to Amazon
S3.

SignedHeaders A semicolon-separated list of request headers that you used to

compute Signature. The list includes header names only, and the
header names must be in lowercase. For example:

host;range;x-amz-date

Signature The 256-bit signature expressed as 64 lowercase hexadecimal

characters. For example:

fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024

Note that the signature calculations vary depending on the option

you choose to transfer the payload.

The signature calculations vary depending on the method you choose to transfer the request payload. S3
supports the following options:

API Version 2006-03-01

795
Amazon Simple Storage Service API Reference
Using an Authorization Header

We recommend you include payload checksum for added security.

• Unsigned payload option – Do not include payload checksum in signature calculation.

For step-by-step instructions to calculate signature and construct the Authorization header value, see
Signature Calculations for the Authorization Header: Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p. 797).
• Transfer payload in multiple chunks (chunked upload) – In this case you transfer payload in chunks.
You can transfer a payload in chunks regardless of the payload size.

You can break up your payload into chunks. These can be fixed or variable-size chunks. By uploading
data in chunks, you avoid reading the entire payload to calculate the signature. Instead, for the first
chunk, you calculate a seed signature that uses only the request headers. The second chunk contains
the signature for the first chunk, and each subsequent chunk contains the signature for the chunk
that precedes it. At the end of the upload, you send a final chunk with 0 bytes of data that contains
the signature of the last chunk of the payload. For more information, see Signature Calculations for
the Authorization Header: Transferring Payload in Multiple Chunks (Chunked Upload) (AWS Signature
Version 4) (p. 809).

If the signatures match, Amazon S3 processes your request; otherwise, your request will fail.

For more information, see the following topics:

Signature Calculations for the Authorization Header: Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p. 797)

Signature Calculations for the Authorization Header: Transferring Payload in Multiple Chunks (Chunked
Upload) (AWS Signature Version 4) (p. 809)

API Version 2006-03-01

796
Amazon Simple Storage Service API Reference
Using an Authorization Header

Signature Calculations for the Authorization Header:

Transferring Payload in a Single Chunk (AWS Signature Version
4)

When using the Authorization header to authenticate requests, the header value includes, among
other things, a signature. The signature calculations vary depending on the choice you make for
transferring the payload (Overview (p. 794)). This section explains signature calculations when
you choose to transfer the payload in a single chunk. The example section (see Examples: Signature
Calculations (p. 803)) shows signature calculations and resulting Authorization headers that you can
use as a test suite to verify your code.
Important
When transferring payload in a single chunk, you can optionally choose to include the payload
hash in the signature calculations, referred as signed payload (if you don't include it, the payload
is considered unsigned). The signing procedure discussed in the following section applies to
both, but note the following diﬀerences:

When you send your request to S3, the x-amz-content-sha256 header value informs S3
whether the payload is signed or not. Amazon S3 can then create signature accordingly for
veriﬁcation.

Calculating a Signature

To calculate a signature, you ﬁrst need a string to sign. You then calculate a HMAC-SHA256 hash of the
string to sign by using a signing key. The following diagram illustrates the process, including the various
components of the string that you create for signing

API Version 2006-03-01

797
Amazon Simple Storage Service API Reference
Using an Authorization Header

The following table describes the functions that are shown in the diagram. You need to implement code
for these functions.

Function Description

Lowercase() Convert the string to lowercase.

Hex() Lowercase base 16 encoding.

SHA256Hash() Secure Hash Algorithm (SHA) cryptographic hash function.

HMAC-SHA256() Computes HMAC by using the SHA256 algorithm with the signing
key provided. This is the ﬁnal signature.

Trim() Remove any leading or trailing whitespace.

UriEncode() URI encode every byte. UriEncode() must enforce the following
rules:

• URI encode every byte except the unreserved characters: 'A'-'Z',

'a'-'z', '0'-'9', '-', '.', '_', and '~'.
• The space character is a reserved character and must be encoded
as "%20" (and not as "+").
• Each URI encoded byte is formed by a '%' and the two-digit
hexadecimal value of the byte.
• Letters in the hexadecimal value must be uppercase, for example
"%1A".
• Encode the forward slash character, '/', everywhere except in the
object key name. For example, if the object key name is photos/
Jan/sample.jpg, the forward slash in the key name is not
encoded.

API Version 2006-03-01

798
Amazon Simple Storage Service API Reference
Using an Authorization Header

Function Description
Important
The standard UriEncode functions provided by your
development platform may not work because of
diﬀerences in implementation and related ambiguity
in the underlying RFCs. We recommend that you write
your own custom UriEncode function to ensure that your
encoding will work.

The following is an example UriEncode() function in Java.

public static String UriEncode(CharSequence input, boolean

Task 1: Create a Canonical Request

This section provides an overview of creating a canonical request.

The following is the canonical request format that Amazon S3 uses to calculate a signature. For
signatures to match, you must create a canonical request in this format:

Where:

API Version 2006-03-01

799
Amazon Simple Storage Service API Reference
Using an Authorization Header

http://s3.amazonaws.com/examplebucket/myphoto.jpg

http://s3.amazonaws.com/examplebucket?prefix=somePrefix&marker=someMarker&max-keys=20

The canonical query string is as follows (line breaks are added to this example for readability):

UriEncode("marker")+"="+UriEncode("someMarker")+"&"+
UriEncode("max-keys")+"="+UriEncode("20") + "&" +
UriEncode("prefix")+"="+UriEncode("somePrefix")

When a request targets a subresource, the corresponding query parameter value will be an empty
string (""). For example, the following URI identiﬁes the ACL subresource on the examplebucket
bucket:

http://s3.amazonaws.com/examplebucket?acl

The CanonicalQueryString in this case is as follows:

UriEncode("acl") + "=" + ""

Lowercase(<HeaderName1>)+":"+Trim(<value>)+"\n"
Lowercase(<HeaderName2>)+":"+Trim(<value>)+"\n"
...
Lowercase(<HeaderNameN>)+":"+Trim(<value>)+"\n"

The Lowercase() and Trim() functions used in this example are described in the preceding section.

The CanonicalHeaders list must include the following:

• HTTP host header.
• If the Content-Type header is present in the request, you must add it to the CanonicalHeaders
list.
• Any x-amz-* headers that you plan to include in your request must also be added. For example, if
you are using temporary security credentials, you need to include x-amz-security-token in your
request. You must add this header in the list of CanonicalHeaders.

API Version 2006-03-01

800
Amazon Simple Storage Service API Reference
Using an Authorization Header

Note
The x-amz-content-sha256 header is required for all AWS Signature Version 4 requests. It
provides a hash of the request payload. If there is no payload, you must provide the hash of
an empty string.

The following is an example CanonicalHeaders string. The header names are in lowercase and
sorted.

host:s3.amazonaws.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b785
2b855
x-amz-date:20130708T220855Z

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

• HashedPayload is the hexadecimal value of the SHA256 hash of the request payload.

Hex(SHA256Hash(<payload>)

If there is no payload in the request, you compute a hash of the empty string as follows:

Hex(SHA256Hash(""))

The hash returns the following value:

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

For example, when you upload an object by using a PUT request, you provide object data in the body.
When you retrieve an object by using a GET request, you compute the empty string hash.

Task 2: Create a String to Sign

This section provides an overview of creating a string to sign. For step-by-step instructions, see Task 2:
Create a String to Sign in the AWS General Reference.

The string to sign is a concatenation of the following strings:

"AWS4-HMAC-SHA256" + "\n" +
timeStampISO8601Format + "\n" +

API Version 2006-03-01

801
Amazon Simple Storage Service API Reference
Using an Authorization Header

<Scope> + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))

The constant string AWS4-HMAC-SHA256 speciﬁes the hash algorithm that you are using,
HMAC-SHA256. The timeStamp is the current UTC time in ISO 8601 format (for example,
20130524T000000Z).

Scope binds the resulting signature to a specific date, an AWS region, and a service. Thus, your resulting
signature will work only in the specific region and for a specific service. The signature is valid for seven
days after the specified date.

date.Format(<YYYYMMDD>) + "/" + <region> + "/" + <service> + "/aws4_request"

For Amazon S3, the service string is s3. For a list of region strings, see Regions and Endpoints in the
AWS General Reference. The region column in this table provides the list of valid region strings.

The following scope restricts the resulting signature to the us-east-1 region and Amazon S3.

20130606/us-east-1/s3/aws4_request

Note
Scope must use the same date that you use to compute the signing key, as discussed in the
following section.

Task 3: Calculate Signature

In AWS Signature Version 4, instead of using your AWS access keys to sign a request, you ﬁrst create a
signing key that is scoped to a speciﬁc region and service. For more information about signing keys, see
Introduction to Signing Requests (p. 793).

DateKey = HMAC-SHA256("AWS4"+"<SecretAccessKey>", "<YYYYMMDD>")

DateRegionKey = HMAC-SHA256(<DateKey>, "<aws-region>")
DateRegionServiceKey = HMAC-SHA256(<DateRegionKey>, "<aws-service>")
SigningKey = HMAC-SHA256(<DateRegionServiceKey>, "aws4_request")

Note
This signing key is valid for seven days from the date speciﬁed in the DateKey hash.

For a list of region strings, see Regions and Endpoints in the AWS General Reference.

The ﬁnal signature is the HMAC-SHA256 hash of the string to sign, using the signing key as the key.

HMAC-SHA256(SigningKey, StringToSign)

For step-by-step instructions on creating a signature, see Task 3: Create a Signature in the AWS General
Reference.

API Version 2006-03-01

802
Amazon Simple Storage Service API Reference
Using an Authorization Header

Examples: Signature Calculations

• Example access keys.

Parameter Value

AWSAccessKeyId AKIAIOSFODNN7EXAMPLE

AWSSecretAccessKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

• Request timestamp of 20130524T000000Z (Fri, 24 May 2013 00:00:00 GMT).

• Bucket name examplebucket.
• The bucket is assumed to be in the US East (N. Virginia) region. The credential Scope and the Signing
Key calculations use us-east-1 as the region speciﬁer. For information about other regions, see
Regions and Endpoints in the AWS General Reference.
• You can use either path-style or virtual hosted–style requests. The following examples show how to
sign a virtual hosted–style request, for example:

https://examplebucket.s3.amazonaws.com/photos/photo1.jpg

For more information, see Virtual Hosting of Buckets in the Amazon Simple Storage Service Developer
Guide.

Example: GET Object

The following example gets the ﬁrst 10 bytes of an object (test.txt) from examplebucket. For more
information about the API action, see GET Object (p. 1248).

GET /test.txt HTTP/1.1

API Version 2006-03-01

803
Amazon Simple Storage Service API Reference
Using an Authorization Header

1. StringToSign

a. CanonicalRequest

GET
/test.txt

host:examplebucket.s3.amazonaws.com
range:bytes=0-9
x-amz-content-
sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20130524T000000Z

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

In the canonical request string, the last line is the hash of the empty request body. The third line
is empty because there are no query parameters in the request.
b. StringToSign

AWS4-HMAC-SHA256
20130524T000000Z
20130524/us-east-1/s3/aws4_request
7344ae5b7ee6c3e7e6b0fe0640412a37625d1fbfff95c48bbb2dc43964946972

2. SigningKey

signing key = HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("AWS4" +

"<YourSecretAccessKey>","20130524"),"us-east-1"),"s3"),"aws4_request")

3. Signature

f0e8bdb87c964420e857bd35b5d6ed310bd44f0170aba48dd91039c6036bdb41

4. Authorization header

The resulting Authorization header is as follows:

Example: PUT Object

This example PUT request creates an object (test$file.text) in examplebucket . The example
assumes the following:

API Version 2006-03-01

804
Amazon Simple Storage Service API Reference
Using an Authorization Header

• The content of the uploaded ﬁle is a string, "Welcome to Amazon S3." The value of x-amz-
content-sha256 in the request is based on this string.

For information about the API action, see PUT Object (p. 1324).

PUT test$file.text HTTP/1.1

The following steps show signature calculations.

1. StringToSign

a. CanonicalRequest

PUT
/test%24file.text

date:Fri, 24 May 2013 00:00:00 GMT

host:examplebucket.s3.amazonaws.com
x-amz-content-
sha256:44ce7dd67c959e0d3524ffac1771dfbba87d2b6b4b4e99e42034a8b803f8b072
x-amz-date:20130524T000000Z
x-amz-storage-class:REDUCED_REDUNDANCY

date;host;x-amz-content-sha256;x-amz-date;x-amz-storage-class
44ce7dd67c959e0d3524ffac1771dfbba87d2b6b4b4e99e42034a8b803f8b072

AWS4-HMAC-SHA256
20130524T000000Z
20130524/us-east-1/s3/aws4_request
9e0e90d9c76de8fa5b200d8c849cd5b8dc7a3be3951ddb7f6a76b4158342019d

2. SigningKey

signing key = HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("AWS4" +

"<YourSecretAccessKey>","20130524"),"us-east-1"),"s3"),"aws4_request")

3. Signature

98ad721746da40c64f1a55b78f14c238d841ea1380cd77a1b5971af0ece108bd

4. Authorization header

The resulting Authorization header is as follows:

API Version 2006-03-01

805
Amazon Simple Storage Service API Reference
Using an Authorization Header

Example: GET Bucket Lifecycle

The following GET request retrieves the lifecycle conﬁguration of examplebucket. For information
about the API action, see GET Bucket lifecycle (p. 983).

GET ?lifecycle HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Authorization: SignatureToBeCalculated
x-amz-date: 20130524T000000Z
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Because the request does not provide any body content, the x-amz-content-sha256 header value is
the hash of the empty request body. The following steps show signature calculations.

1. StringToSign

a. CanonicalRequest

GET
/
lifecycle=
host:examplebucket.s3.amazonaws.com
x-amz-content-
sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20130524T000000Z

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

In the canonical request, the last line is the hash of the empty request body.
b. StringToSign

AWS4-HMAC-SHA256
20130524T000000Z
20130524/us-east-1/s3/aws4_request
9766c798316ff2757b517bc739a67f6213b4ab36dd5da2f94eaebf79c77395ca

2. SigningKey

signing key = HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("AWS4" +

"<YourSecretAccessKey>","20130524"),"us-east-1"),"s3"),"aws4_request")

3. Signature

fea454ca298b7da1c68078a5d1bdbfbbe0d65c699e0f91ac7a200a0136783543

API Version 2006-03-01

806
Amazon Simple Storage Service API Reference
Using an Authorization Header

4. Authorization header

The resulting Authorization header is as follows:

Example: Get Bucket (List Objects)

The following example retrieves a list of objects from examplebucket bucket. For information about
the API action, see GET Bucket (List Objects) Version 1 (p. 940).

GET ?max-keys=2&prefix=J HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Authorization: SignatureToBeCalculated
x-amz-date: 20130524T000000Z
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Because the request does not provide a body, the value of x-amz-content-sha256 is the hash of the
empty request body. The following steps show signature calculations.

1. StringToSign

a. CanonicalRequest

809
Amazon Simple Storage Service API Reference
Using an Authorization Header

The following table describes the functions that are shown in the diagram. You need to implement code
for these functions.

Function Description

Lowercase() Convert the string to lowercase.

Hex() Lowercase base 16 encoding.

SHA256Hash() Secure Hash Algorithm (SHA) cryptographic hash function.

HMAC-SHA256() Computes HMAC by using the SHA256 algorithm with the signing
key provided. This is the ﬁnal signature.

Trim() Remove any leading or trailing whitespace.

UriEncode() URI encode every byte. UriEncode() must enforce the following
rules:

• URI encode every byte except the unreserved characters: 'A'-'Z',

API Version 2006-03-01

810
Amazon Simple Storage Service API Reference
Using an Authorization Header

The following is an example UriEncode() function in Java.

public static String UriEncode(CharSequence input, boolean

For information about the signing process, see Signature Calculations for the Authorization Header:
Transferring Payload in a Single Chunk (AWS Signature Version 4) (p. 797). The process is the same,
except that the creation of CanonicalRequest diﬀers as follows:

• In addition to the request headers you plan to add, you must include the following headers:

Header Description

API Version 2006-03-01

811
Amazon Simple Storage Service API Reference
Using an Authorization Header

Header Description

Content-Encoding Set the value to aws-chunked.

Amazon S3 supports multiple content encodings. For example:

Content-Encoding : aws-chunked,gzip

Content-Length Set the value to the actual size of the transmitted HTTP body, which
includes the length of your data (value set for x-amz-decoded-content-
length) plus, chunk metadata. Each chunk has metadata, such as the
signature of the previous chunk. Chunk calculations are discussed in the
following section.

You send the ﬁrst chunk with the seed signature. You must construct the chunk as described in the
following section.

Deﬁning the Chunk Body

All chunks include some metadata. Each chunk must conform to the following structure:

string(IntHexBase(chunk-size)) + ";chunk-signature=" + signature + \r\n + chunk-data + \r\n

Where:

API Version 2006-03-01

812
Amazon Simple Storage Service API Reference
Using an Authorization Header

The size of the ﬁnal chunk data that you send is 0, although the chunk body still contains metadata,
including the signature of the previous chunk.

Example: PUT Object

You can use the examples in this section as a reference to check signature calculations in your code.
Before you review the examples, note the following:

• The signature calculations in these examples use the following example security credentials.

Parameter Value

AWSAccessKeyId AKIAIOSFODNN7EXAMPLE

AWSSecretAccessKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
• All examples use the request time stamp 20130524T000000Z (Fri, 24 May 2013 00:00:00 GMT).
• All examples use examplebucket as the bucket name.
• The bucket is assumed to be in the US East (N. Virginia) Region, and the credential Scope and the
Signing Key calculations use us-east-1 as the Region speciﬁer. For more information, see Regions
and Endpoints in the Amazon Web Services General Reference.
• You can use either path style or virtual-hosted style requests. The following examples use virtual-
hosted style requests, for example:

https://examplebucket.s3.amazonaws.com/photos/photo1.jpg

For more information, see Virtual Hosting of Buckets in the Amazon Simple Storage Service Developer
Guide.

Example: PUT Object

API Version 2006-03-01

813
Amazon Simple Storage Service API Reference
Using an Authorization Header

The following example sends a PUT request to upload an object. The signature calculations assume the
following:

For information about the API action, see PUT Object (p. 1324). The general request syntax is as follows:

PUT /examplebucket/chunkObject.txt HTTP/1.1

The following steps show signature calculations.

1. Seed signature — Create String to Sign

a. CanonicalRequest

PUT
/examplebucket/chunkObject.txt

content-encoding;content-length;host;x-amz-content-sha256;x-amz-date;x-amz-decoded-
content-length;x-amz-storage-class
STREAMING-AWS4-HMAC-SHA256-PAYLOAD

AWS4-HMAC-SHA256
20130524T000000Z
20130524/us-east-1/s3/aws4_request
cee3fed04b70f867d036f722359b0b1f2f0e5dc0efadbc082b76c4c60e316455

Note
For information about each of line in the string to sign, see the diagram that explains
seed signature calculation.

API Version 2006-03-01

814
Amazon Simple Storage Service API Reference
Using an Authorization Header

2. SigningKey

signing key = HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("AWS4" +

"<YourSecretAccessKey>","20130524"),"us-east-1"),"s3"),"aws4_request")

3. Seed Signature

4f232c4386841ef735655705268965c44a0e4690baa4adea153f7db9fa80a0a9

4. Authorization header

The resulting Authorization header is as follows:

5. Chunk 1: (65536 bytes, with value 97 for letter 'a')

a. Chunk string to sign:

ad80c730a21e5b8d04586a2213dd63b9a0e99e0e2307b0ade35a65485a288648

c. Chunk data sent:

10000;chunk-
signature=ad80c730a21e5b8d04586a2213dd63b9a0e99e0e2307b0ade35a65485a288648
<65536-bytes>

6. Chunk 2: (1024 bytes, with value 97 for letter 'a')

a. Chunk string to sign:

b. Chunk signature:

0055627c9e194cb4542bae2aa5492e3c1575bbb81b612b7d234b86a503ef5497

API Version 2006-03-01

815
Amazon Simple Storage Service API Reference
Using Query Parameters

c. Chunk data sent:

400;chunk-
signature=0055627c9e194cb4542bae2aa5492e3c1575bbb81b612b7d234b86a503ef5497
<1024 bytes>

7. Chunk 3: (0 byte data)

a. Chunk string to sign:

b. Chunk signature:

b6c6ea8a5354eaf15b3cb7646744f4275b71ea724fed81ceb9323e279d449df9

c. Chunk data sent:

0;chunk-signature=b6c6ea8a5354eaf15b3cb7646744f4275b71ea724fed81ceb9323e279d449df9

Authenticating Requests: Using Query Parameters

(AWS Signature Version 4)
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

As described in the authentication overview (see Authentication Methods (p. 793)), you can provide
authentication information using query string parameters. Using query parameters to authenticate
requests is useful when you want to express a request entirely in a URL. This method is also referred as
presigning a URL.

The following is an example presigned URL.

In the example URL, note the following:

• The line feeds are added for readability.

API Version 2006-03-01

816
Amazon Simple Storage Service API Reference
Using Query Parameters

• The X-Amz-Credential value in the URL shows the "/" character only for readability. In practice, it
should be encoded as %2F. For example:

&X-Amz-Credential=<your-access-key-id>%2F20130721%2Fus-east-1%2Fs3%2Faws4_request

The following table describes the query parameters in the URL that provide authentication information.

Query String Parameter Name Example Value

X-Amz-Algorithm Identiﬁes the version of AWS Signature and the algorithm that you
used to calculate the signature.

For AWS Signature Version 4, you set this parameter value to

AWS4-HMAC-SHA256. This string identiﬁes AWS Signature Version
4 (AWS4) and the HMAC-SHA256 algorithm (HMAC-SHA256).

<your-access-key-id>/<date>/<AWS-region>/<AWS-service>/
aws4_request

For example:

AKIAIOSFODNN7EXAMPLE/20130721/us-east-1/s3/aws4_request

For Amazon S3, the AWS-service string is s3. For a list of S3 AWS-
region strings, see Regions and Endpoints in the AWS General
Reference.

A presigned URL can be valid for a maximum of seven days because

the signing key you use in signature calculation is valid for up to
seven days.

X-Amz-SignedHeaders Lists the headers that you used to calculate the signature. The
following headers are required in the signature calculations:

• The HTTP host header.

• Any x-amz-* headers that you plan to add to the request.

API Version 2006-03-01

817
Amazon Simple Storage Service API Reference
Using Query Parameters

Query String Parameter Name Example Value

Note
For added security, you should sign all the request headers
that you plan to include in your request.

X-Amz-Signature Provides the signature to authenticate your request. This

signature must match the signature Amazon S3 calculates;
otherwise, Amazon S3 denies the request. For example,
733255ef022bec3f2a8701cd61d4b371f3f28c9f193a1f02279211d48d5193

Signature calculations are described in the following section.

Calculating a Signature

The following diagram illustrates the signature calculation process.

The following table describes the functions that are shown in the diagram. You need to implement code
for these functions.

Function Description

Lowercase() Convert the string to lowercase.

Hex() Lowercase base 16 encoding.

API Version 2006-03-01

818
Amazon Simple Storage Service API Reference
Using Query Parameters

Function Description

SHA256Hash() Secure Hash Algorithm (SHA) cryptographic hash function.

HMAC-SHA256() Computes HMAC by using the SHA256 algorithm with the signing
key provided. This is the ﬁnal signature.

Trim() Remove any leading or trailing whitespace.

UriEncode() URI encode every byte. UriEncode() must enforce the following
rules:

• URI encode every byte except the unreserved characters: 'A'-'Z',

The following is an example UriEncode() function in Java.

public static String UriEncode(CharSequence input, boolean

API Version 2006-03-01

819
Amazon Simple Storage Service API Reference
Using Query Parameters

Payload in a Single Chunk (AWS Signature Version 4) (p. 797). The process is generally the same except
that the creation of CanonicalRequest in a presigned URL diﬀers as follows:

An Example

Suppose you have an object test.txt in your examplebucket bucket. You want to share this object
with others for a period of 24 hours (86400 seconds) by creating a presigned URL.

The following steps illustrate ﬁrst the signature calculations and then construction of the presigned URL.
The example makes the following additional assumptions:

• Request timestamp is Fri, 24 May 2013 00:00:00 GMT.

You can use this example as a test case to verify the signature that your code calculates; however, you
must use the same bucket name, object key, time stamp, and the following example credentials:

Parameter Value

AWSAccessKeyId AKIAIOSFODNN7EXAMPLE

AWSSecretAccessKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

1. StringToSign

a. CanonicalRequest

GET
/test.txt

API Version 2006-03-01

820
Amazon Simple Storage Service API Reference
Examples: Signature Calculations

X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE
%2F20130524%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20130524T000000Z&X-Amz-
Expires=86400&X-Amz-SignedHeaders=host
host:examplebucket.s3.amazonaws.com

host
UNSIGNED-PAYLOAD

b. StringToSign

AWS4-HMAC-SHA256
20130524T000000Z
20130524/us-east-1/s3/aws4_request
3bfa292879f6447bbcda7001decf97f4a54dc650c8942174ae0a9121cf58ad04

2. SigningKey

signing key = HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("AWS4" +

"<YourSecretAccessKey>","20130524"),"us-east-1"),"s3"),"aws4_request")

3. Signature

aeeed9bbccd4d02ee5c0109b86d86835f995330da4c265957d157751f604d404

Now you have all information to construct a presigned URL. The resulting URL for this example is
shown as follows (you can use this to compare your presigned URL):

Examples: Signature Calculations in AWS Signature

Version 4

Topics
• Signature Calculation Examples Using Java (AWS Signature Version 4) (p. 822)
• Examples of Signature Calculations Using C# (AWS Signature Version 4) (p. 823)

For authenticated requests, unless you are using the AWS SDKs, you have to write code to calculate
signatures that provide authentication information in your requests. Signature calculation in AWS
Signature Version 4 (see Authenticating Requests (AWS Signature Version 4) (p. 792)) can be a complex
undertaking, and we recommend that you use the AWS SDKs whenever possible.

API Version 2006-03-01

821
Amazon Simple Storage Service API Reference
Examples: Signature Calculations

• PUT object – Separate examples illustrate both uploading the full payload at once and uploading
the payload in chunks. For information about using the Authorization header for authentication, see
Authenticating Requests: Using the Authorization Header (AWS Signature Version 4) (p. 794).
• GET object – This example generates a presigned URL to get an object. Query parameters provide the
signature and other authentication information. Users can paste a presigned URL in their browser to
retrieve the object, or you can use the URL to create a clickable link. For information about using query
parameters for authentication, see Authenticating Requests: Using Query Parameters (AWS Signature
Version 4) (p. 816).

The rest of this section describes the examples in Java and C#. The topics include instructions for
downloading the samples and for executing them.

Signature Calculation Examples Using Java (AWS Signature

Version 4)

The Java sample that shows signature calculation can be downloaded here. In RunAllSamples.java,
the main() function executes sample requests to create an object, retrieve an object, and create a
presigned URL for the object. The sample creates an object from the text string provided in the code:

PutS3ObjectSample.putS3Object(bucketName, regionName, awsAccessKey, awsSecretKey);

GetS3ObjectSample.getS3Object(bucketName, regionName, awsAccessKey, awsSecretKey);
PresignedUrlSample.getPresignedUrlToS3Object(bucketName, regionName, awsAccessKey,
awsSecretKey);
PutS3ObjectChunkedSample.putS3ObjectChunked(bucketName, regionName, awsAccessKey,
awsSecretKey);

To test the examples on a Linux-based computer

The following instructions are for the Linux operating system.

1. In a terminal, navigate to the directory that contains AWSS3SigV4JavaSamples.zip.

javac -d bin -source 6 -verbose com

5. Change the directory to bin/, and then execute RunAllSamples.

API Version 2006-03-01

822
Amazon Simple Storage Service API Reference
Authenticating HTTP POST Requests

java com.amazonaws.services.s3.sample.RunAllSamples

The code runs all the methods in main(). For each request, the output will show the canonical
request, the string to sign, and the signature.

Examples of Signature Calculations Using C# (AWS Signature

Version 4)

The C# sample that shows signature calculation can be downloaded at https://docs.aws.amazon.com/

AmazonS3/latest/API/samples/AmazonS3SigV4_Samples_CSharp.zip. In Program.cs, the main()
function executes sample requests to create an object, retrieve an object, and create a presigned URL for
the object. The code for signature calculation is in the \Signers folder.

PutS3ObjectSample.Run(awsRegion, bucketName, "MySampleFile.txt");

Console.WriteLine("\n\n************************************************");
PutS3ObjectChunkedSample.Run(awsRegion, bucketName, "MySampleFileChunked.txt");

Console.WriteLine("\n\n************************************************");
GetS3ObjectSample.Run(awsRegion, bucketName, "MySampleFile.txt");

Console.WriteLine("\n\n************************************************");
PresignedUrlSample.Run(awsRegion bucketName, "MySampleFile.txt");

To test the examples with Microsoft Visual Studio 2010 or later

1. Extract the .zip ﬁle.

2. Start Visual Studio, and then open the .sln file.
3. Update the App.config file with valid security credentials.
4. Update the code as follows:
• In Program.cs, provide the bucket name and the AWS region where the bucket resides. The sample
creates an object in this bucket.
5. Execute the code.
6. To verify that the object was created, copy the presigned URL that the program creates, and then
paste it in a browser window.

Authenticating Requests: Browser-Based Uploads

Using POST (AWS Signature Version 4)

API Version 2006-03-01

823
Amazon Simple Storage Service API Reference
Authenticating HTTP POST Requests

Amazon S3 supports HTTP POST requests so that users can upload content directly to Amazon S3. Using
HTTP POST to upload content simpliﬁes uploads and reduces upload latency where users upload data
to store in Amazon S3. This section describes how you authenticate HTTP POST requests. For more
information about HTTP POST requests, how to create a form, create a POST policy, and an example, see
Authenticating Requests in Browser-Based Uploads Using POST (AWS Signature Version 4) (p. 829).

To authenticate an HTTP POST request you do the following:

1. The form must include the following ﬁelds to provide signature and relevant information that Amazon
S3 can use to re-calculate the signature upon receiving the request:

Element Name Description

policy The Base64-encoded security policy that describes what

is permitted in the request. For signature calculation this
policy is the string you sign. Amazon S3 must get this
policy so it can re-calculate the signature.

x-amz-algorithm The signing algorithm used. For AWS Signature Version 4,

the value is AWS4-HMAC-SHA256.

x-amz-credential In addition to your access key ID, this provides scope

information you used in calculating the signing key for
signature calculation.

It is a string of the following form:

<your-access-key-id>/<date>/<aws-
region>/<aws-service>/aws4_request

For example:

AKIAIOSFODNN7EXAMPLE/20130728/us-east-1/s3/
aws4_request. .

For Amazon S3, the aws-service string is s3. For a list

of Amazon S3 aws-region strings, see Regions and
Endpoints in the AWS General Reference.

x-amz-date It is the date value in ISO8601 format. For example,

20130728T000000Z.

It is the same date you used in creating the signing key.

This must also be the same value you provide in the policy
(x-amz-date) that you signed.

x-amz-signature (AWS Signature Version 4) The HMAC-SHA256 hash of the

security policy.

2. The POST policy must include the following elements:

Element Name Description

x-amz-algorithm The signing algorithm that you used to calculation the

signature. For AWS Signature Version 4, the value is
AWS4-HMAC-SHA256.

API Version 2006-03-01

824
Amazon Simple Storage Service API Reference
Authenticating HTTP POST Requests

Element Name Description

x-amz-credential In addition to your access key ID, this provides scope

information you used in calculating the signing key for
signature calculation.

It is a string of the following form:

<your-access-key-id>/<date>/<aws-
region>/<aws-service>/aws4_request

For example,

AKIAIOSFODNN7EXAMPLE/20130728/us-east-1/s3/
aws4_request. .

x-amz-date The date value speciﬁed in the ISO8601 formatted string.

For example, "20130728T000000Z". The date must
be same that you used in creating the signing key for
signature calculation.

3. For signature calculation the POST policy is the string to sign.

Calculating a Signature

The following diagram illustrates the signature calculation process.

To Calculate a signature

1. Create a policy using UTF-8 encoding.

API Version 2006-03-01

825
Amazon Simple Storage Service API Reference
Amazon S3 Signature Version 4
Authentication Speciﬁc Policy Keys

For more information about creating HTML forms, security policies, and an example, see the following
subtopics:

• Creating an HTML Form (Using AWS Signature Version 4) (p. 831)

• Creating a POST Policy (p. 836)
• Example: Browser-Based Upload using HTTP POST (Using AWS Signature Version 4) (p. 842)
• Using POST with Adobe Flash to Upload Objects (p. 844)

Amazon S3 Signature Version 4 Authentication

Speciﬁc Policy Keys
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

The following table shows the policy keys related Amazon S3 Signature Version 4 authentication
that can be in Amazon S3 policies. In a bucket policy, you can add these conditions to enforce speciﬁc
behavior when requests are authenticated by using Signature Version 4. For example policies, see Bucket
Policy Examples Using Signature Version 4 Related Condition Keys (p. 827).

Applicable Keys for s3:* Actions or any of the Amazon S3 Actions

Applicable Keys Description

s3:signatureversion Identiﬁes the version of AWS Signature that you

Valid values:

"AWS" identiﬁes Signature Version 2

"AWS4-HMAC-SHA256" identiﬁes Signature

Version 4

s3:authType Amazon S3 supports various methods of

authentication (see Authenticating Requests
(AWS Signature Version 4) (p. 792). You can
optionally use this condition key to restrict
incoming requests to use a speciﬁc authentication
method. For example, you can allow only the HTTP
Authorization header to be used in request
authentication.

Valid values:

REST-HEADER

REST-QUERY-STRING

POST

API Version 2006-03-01

826
Amazon Simple Storage Service API Reference
Amazon S3 Signature Version 4
Authentication Speciﬁc Policy Keys

Applicable Keys Description

s3:signatureAge The length of time, in milliseconds, that a

signature is valid in an authenticated request.

This condition works only for presigned URLs (the

most restrictive condition wins).

In Signature Version 4, the signing key is valid

for up to seven days (see Introduction to Signing
Requests (p. 793). Therefore, the signatures are
also valid for up to seven days. You can use this
condition to further limit the signature age.

Example value: 100

s3:x-amz-content-sha256 You can use this condition key to disallow

unsigned content in your bucket.

When you use Signature Version 4, for requests

that use the Authorization header, you add the
x-amz-content-sha256 header in the signature
calculation and then set its value to the hash
payload.

You can use this condition key in your bucket

policy to deny any uploads where payloads are not
signed. For example:

• Deny uploads that use presigned URLs. For

more information, see Authenticating Requests:
Using Query Parameters (AWS Signature Version
4) (p. 816).
• Deny uploads that use Authorization header
to authenticate requests but don't sign the
payload. For more information, see Signature
Calculations for the Authorization Header:
Transferring Payload in a Single Chunk (AWS
Signature Version 4) (p. 797).

Valid value: UNSIGNED-PAYLOAD

Bucket Policy Examples Using Signature Version 4 Related

Condition Keys

Deny any Amazon S3 action on the examplebucket to anyone if request is authenticated using
Signature Version 4.

API Version 2006-03-01

827
Amazon Simple Storage Service API Reference
Amazon S3 Signature Version 4
Authentication Speciﬁc Policy Keys

"Version": "2012-10-17",
"Statement": [
{
"Sid": "Test",
"Effect": "Deny",
"Principal": "*",
"Action": "s3:*",
"Resource": "arn:aws:s3:::examplebucket/*",
"Condition": {
"StringEquals": {
"s3:signatureversion": "AWS4-HMAC-SHA256"
}
}
}
]
}

The following bucket policy denies any Amazon S3 presigned URL request on objects in examplebucket
if the signature is more than ten minutes old.

The following bucket policy allows only requests that use the Authorization header for request
authentication. Any POST or presigned URL requests will be denied.

The following bucket policy denies any uploads that use presigned URLs.

API Version 2006-03-01

828
Amazon Simple Storage Service API Reference
Browser-Based Uploads Using POST

Authenticating Requests in Browser-Based

Uploads Using POST (AWS Signature Version 4)
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

This section discusses how to upload ﬁles directly to Amazon S3 through a browser using HTTP POST
requests. It also contains information about how to use the AWS Amplify JavaScript library for browser-
based ﬁle uploads to Amazon S3.

Topics
• Browser-Based Uploads Using HTTP POST (p. 829)
• Calculating a Signature (p. 830)
• Creating an HTML Form (Using AWS Signature Version 4) (p. 831)
• Creating a POST Policy (p. 836)
• Example: Browser-Based Upload using HTTP POST (Using AWS Signature Version 4) (p. 842)
• Using POST with Adobe Flash to Upload Objects (p. 844)
• Browser-Based Uploads to Amazon S3 Using the AWS Amplify Library (p. 845)

Browser-Based Uploads Using HTTP POST

API Version 2006-03-01

829
Amazon Simple Storage Service API Reference
Calculating a Signature

The following ﬁgure shows an Amazon S3 upload using a POST request.

Uploading Using POST

1 The user accesses your page from a web browser.

2 Your webpage contains an HTML form that contains all the information necessary for the
user to upload content to Amazon S3.

3 The user uploads content to Amazon S3 through the web browser.

The process for sending browser-based POST requests is as follows:

Calculating a Signature
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

API Version 2006-03-01

830
Amazon Simple Storage Service API Reference
Creating HTML Forms

For authenticated requests, the HTML form must include ﬁelds for a security policy and a signature.

• A security policy (see Creating a POST Policy (p. 836)) controls what is allowed in the request.
• The security policy is the StringToSign (see Introduction to Signing Requests (p. 793)) in your
signature calculation.

To Calculate a signature

1. Create a policy using UTF-8 encoding.

2. Convert the UTF-8-encoded policy bytes to base64. The result is the StringToSign.
3. Create a signing key.
4. Use the signing key to sign the StringToSign using HMAC-SHA256 signing algorithm.

For more information about creating HTML forms, security policies, and an example, see the following:

• Creating an HTML Form (Using AWS Signature Version 4) (p. 831)

• Creating a POST Policy (p. 836)
• Example: Browser-Based Upload using HTTP POST (Using AWS Signature Version 4) (p. 842)
• Using POST with Adobe Flash to Upload Objects (p. 844)

Creating an HTML Form (Using AWS Signature

Version 4)

Topics
• HTML Form Declaration (p. 832)
• HTML Form Fields (p. 833)

API Version 2006-03-01

831
Amazon Simple Storage Service API Reference
Creating HTML Forms

Following is an example of UTF-8 encoding in a request header.

Content-Type: text/html; charset=UTF-8

Note
The form data and boundaries (excluding the contents of the ﬁle) cannot exceed 20KB.

HTML Form Declaration

The HTML form declaration has the following three attributes:

This is a form declaration for the bucket examplebucket.

<form action="http://examplebucket.s3.amazonaws.com/" method="post"

enctype="multipart/form-data">

API Version 2006-03-01

832
Amazon Simple Storage Service API Reference
Creating HTML Forms

HTML Form Fields

Element Name Description Required

acl An Amazon S3 access control list (ACL). If an No

invalid ACL is speciﬁed, Amazon S3 denies the
request. For more information about ACLs, see
Using Amazon S3 ACLs.

Type: String

Default: private

Valid Values: private | public-read |

public-read-write | aws-exec-read |
authenticated-read | bucket-owner-
read | bucket-owner-full-control

Cache-Control REST-speciﬁc headers. For more information, see No

PUT Object (p. 1324).
Content-Type

Content-Disposition

Content-Encoding

Expires

key The key name of the uploaded object. Yes

To use the ﬁle name provided by the user, use

the ${filename} variable. For example, if you
upload a file photo1.jpg and you specify /
user/user1/${filename} as key name, the
file is stored as /user/user1/photo1.jpg.

API Version 2006-03-01

833
Amazon Simple Storage Service API Reference
Creating HTML Forms

Element Name Description Required

For more information, see Object Key and
Metadata in the Amazon Simple Storage Service
Developer Guide.

policy The base64-encoded security policy that Required for

describes what is permitted in the request. For authenticated
authenticated requests, a policy is required. requests

Requests without a security policy are considered

anonymous and will succeed only on a publicly
writable bucket.

success_action_redirect The URL to which the client is redirected upon No

successful upload.

If success_action_redirect is not speciﬁed,

or Amazon S3 cannot interpret the URL, Amazon
S3 returns the empty document type that is
speciﬁed in the success_action_status ﬁeld.

If the upload fails, Amazon S3 returns an error

and does not redirect the user to another URL.

success_action_status The status code returned to the No

client upon successful upload if
success_action_redirect is not speciﬁed.

Valid values are 200, 201, or 204 (default).

If the value is set to 200 or 204, Amazon S3

returns an empty document with the speciﬁed
status code.

If the value is set to 201, Amazon S3 returns

an XML document with a 201 status code. For
information about the content of the XML
document, see POST Object (p. 1295).

If the value is not set or is invalid, Amazon S3

x-amz-algorithm The signing algorithm used to authenticate the Required for

request. For AWS Signature Version 4, the value authenticated
is AWS4-HMAC-SHA256. requests

This ﬁeld is required if a policy document is

included with the request.

API Version 2006-03-01

834
Amazon Simple Storage Service API Reference
Creating HTML Forms

Element Name Description Required

It is a string of the following form:

<your-access-key-id>/<date>/<aws-
region>/<aws-service>/aws4_request

For example:

x-amz-date It is the date value in ISO8601 format. For Required for

This is required if a policy document is included

with the request.

x-amz-security-token A security token used by Amazon DevPay and No

session credentials

If the request is using Amazon DevPay, it requires

two x-amz-security-token form ﬁelds: one
for the product token and one for the user token.
For more information, see Using DevPay in the
Amazon Simple Storage Service Developer Guide.

If the request is using session credentials, it

requires one x-amz-security-token form.
For more information, see Requesting Temporary
Security Credentials in the IAM User Guide.

x-amz-signature (AWS Signature Version 4) The HMAC-SHA256 Required for

hash of the security policy. authenticated
requests
This ﬁeld is required if a policy document is
included with the request.

API Version 2006-03-01

835
Amazon Simple Storage Service API Reference
Creating a POST Policy

Element Name Description Required

x-amz-meta-* Field names starting with this preﬁx are user- No

deﬁned metadata. Each one is stored and
returned as a set of key-value pairs. Amazon
S3 doesn't validate or interpret user-deﬁned
metadata. For more information, see PUT
Object (p. 1324).

x-amz-* See POST Object (POST Object (p. 1295) for No

other x-amz-* headers.

file File or text content. Yes

The ﬁle or content must be the last ﬁeld in the

form.

You cannot upload more than one ﬁle at a time.

Conditional items are required for authenticated requests and are optional for anonymous requests.

Now that you know how to create forms, next you can create a security policy that you can sign. For
more information, see Creating a POST Policy (p. 836).

Creating a POST Policy

Topics
• Expiration (p. 837)
• Condition Matching (p. 837)
• Conditions (p. 838)
• Character Escaping (p. 840)

This section describes the POST policy. For example signature calculations using POST policy, see
Example: Browser-Based Upload using HTTP POST (Using AWS Signature Version 4) (p. 842).
Note
Although the policy document is optional, we highly recommend that you use one in order to
control what is allowed in the request. If you make the bucket publicly writable, you have no
control at all over which users can write to your bucket.

The following is an example of a POST policy document.

{ "expiration": "2007-12-01T12:00:00.000Z",
"conditions": [

API Version 2006-03-01

836
Amazon Simple Storage Service API Reference
Creating a POST Policy

{"acl": "public-read" },
{"bucket": "johnsmith" },
["starts-with", "$key", "user/eric/"],
]
}

Expiration

The expiration element speciﬁes the expiration date and time of the POST policy in ISO8601 GMT
date format. For example, 2013-08-01T12:00:00.000Z speciﬁes that the POST policy is not valid
after midnight GMT on August 1, 2013.

Condition Matching

Following is a table that describes condition matching types that you can use to specify POST policy
conditions (described in the next section). Although you must specify one condition for each form ﬁeld
that you specify in the form, you can create more complex matching criteria by specifying multiple
conditions for a form ﬁeld.

Condition Description
Match Type

Exact Matches The form ﬁeld value must match the value speciﬁed. This example indicates that
the ACL must be set to public-read:

{"acl": "public-read" }

This example is an alternate way to indicate that the ACL must be set to public-read:

[ "eq", "$acl", "public-read" ]

Starts With The value must start with the speciﬁed value. This example indicates that the object
key must start with user/user1:

["starts-with", "$key", "user/user1/"]

Matching Any To conﬁgure the POST policy to allow any content within a form ﬁeld, use
Content starts-with with an empty value (""). This example allows any value for
success_action_redirect:

API Version 2006-03-01

837
Amazon Simple Storage Service API Reference
Creating a POST Policy

Condition Description
Match Type

["starts-with", "$success_action_redirect", ""]

Specifying For form ﬁelds that accept a range, separate the upper and lower limit with a
Ranges comma. This example allows a ﬁle size from 1 to 10 MiB:

["content-length-range", 1048579, 10485760]

The speciﬁc conditions supported in a POST policy are described in Conditions (p. 838).

Conditions

The conditions in a POST policy is an array of objects, each of which is used to validate the request.
You can use these conditions to restrict what is allowed in the request. For example, the preceding policy
conditions require the following:

• Request must specify the johnsmith bucket name.

• Object key name must have the user/eric preﬁx.
• Object ACL must be set to public-read.

Policy document conditions are described in the following table.

Element Name Description

acl Speciﬁes the ACL value that must be used in the form
submission.

This condition supports exact matching and starts-with

condition match type discussed in the following section.

bucket Speciﬁes the acceptable bucket name.

This condition supports exact matching condition match type.

content-length-range The minimum and maximum allowable size for the uploaded
content.

API Version 2006-03-01

838
Amazon Simple Storage Service API Reference
Creating a POST Policy

Element Name Description

This condition supports content-length-range condition
match type.

Cache-Control REST-speciﬁc headers. For more information, see POST

Object (p. 1295).
Content-Type
This condition supports exact matching and starts-with
Content-Disposition condition match type.

Content-Encoding

Expires

key The acceptable key name or a preﬁx of the uploaded object.

This condition supports exact matching and starts-with

condition match type.

success_action_redirect The URL to which the client is redirected upon successful

upload.
redirect
This condition supports exact matching and starts-with
condition match type.

success_action_status The status code returned to the client upon successful upload if
success_action_redirect is not speciﬁed.

This condition supports exact matching.

x-amz-algorithm The signing algorithm that must be used during signature

calculation. For AWS Signature Version 4, the value is AWS4-
HMAC-SHA256.

This condition supports exact matching.

x-amz-credential The credentials that you used to calculate the signature. It

It is a string of the following form:

<your-access-key-id>/<date>/<aws-region>/<aws-
service>/aws4_request

For example:

AKIAIOSFODNN7EXAMPLE/20130728/us-east-1/s3/
aws4_request

For Amazon S3, the aws-service string is s3. For a list of

Amazon S3 aws-region strings, see Regions and Endpoints
in the AWS General Reference. This is required if a POST policy
document is included with the request.

This condition supports exact matching.

API Version 2006-03-01

839
Amazon Simple Storage Service API Reference
Creating a POST Policy

Element Name Description

x-amz-date The date value speciﬁed in the ISO8601 formatted string. For
example, 20130728T000000Z. The date must be same that you
used in creating the signing key for signature calculation.

This is required if a POST policy document is included with the

request.

This condition supports exact matching.

x-amz-security-token Amazon DevPay security token.

Each request that uses Amazon DevPay requires two x-amz-

For more information about Amazon DevPay, see Using DevPay

in the Amazon Simple Storage Service Developer Guide.

x-amz-meta-* User-speciﬁed metadata.

This condition supports exact matching and starts-with

condition match type.

x-amz-* See POST Object (POST Object (p. 1295) for other x-amz-*
headers.

This condition supports exact matching.

Character Escaping

Characters that must be escaped within a POST policy document are described in the following table.

Escape Description
Sequence

\\ Backslash

\$ Dollar symbol

\b Backspace

API Version 2006-03-01

840
Amazon Simple Storage Service API Reference
Creating a POST Policy

Escape Description
Sequence

\f Form feed

\n New line

\r Carriage return

\t Horizontal tab

\v Vertical tab

\uxxxx All Unicode characters

API Version 2006-03-01

841
Amazon Simple Storage Service API Reference
POST Upload Example

Example: Browser-Based Upload using HTTP POST

(Using AWS Signature Version 4)
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

This section shows an example of using an HTTP POST request to upload content directly to Amazon S3.

Uploading a File to Amazon S3 Using HTTP POST

Parameter Value

AWSAccessKeyId AKIAIOSFODNN7EXAMPLE

AWSSecretAccessKey wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Sample Policy and Form

The following POST policy supports uploads to Amazon S3 with speciﬁc conditions.

{"x-amz-credential": "AKIAIOSFODNN7EXAMPLE/20151229/us-east-1/s3/aws4_request"},
{"x-amz-algorithm": "AWS4-HMAC-SHA256"},

API Version 2006-03-01

842
Amazon Simple Storage Service API Reference
POST Upload Example

{"x-amz-date": "20151229T000000Z" }
]
}

This POST policy sets the following conditions on the request:

• The upload must occur before noon UTC on December 30, 2015.
• The content can be uploaded only to the sigv4examplebucket. The bucket must be in the region
that you speciﬁed in the credential scope (x-amz-credential form parameter), because the
signature you provided is valid only within this scope.
• You can provide any key name that starts with user/user1. For example, user/user1/
MyPhoto.jpg.
• The ACL must be set to public-read.
• If the upload succeeds, the user's browser is redirected to http://
sigv4examplebucket.s3.amazonaws.com/successful_upload.html.
• The object must be an image ﬁle.
• The x-amz-meta-uuid tag must be set to 14365123651274.
• The x-amz-meta-tag can contain any value.

The following is a Base64-encoded version of this POST policy. You use this value as your StringToSign in
signature calculation.

eyAiZXhwaXJhdGlvbiI6ICIyMDE1LTEyLTMwVDEyOjAwOjAwLjAwMFoiLA0KICAiY29uZGl0aW9ucyI6IFsNCiAgICB7ImJ1Y2tldCI

When you copy/paste the preceding policy, it should have carriage returns and new lines for your
computed hash to match this value (ie. ASCII text, with CRLF line terminators).

Using example credentials to create a signature, the signature value is as follows (in signature
calculation, the date is same as the x-amz-date in the policy (20151229):

8afdbf4008c03f22c2cd3cdb72e4afbb1f6a588f3255ac628749a66d7f09699e

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

</head>
<body>

<form action="http://sigv4examplebucket.s3.amazonaws.com/" method="post"

API Version 2006-03-01

843
Amazon Simple Storage Service API Reference
Using POST with Adobe Flash

<input type="input" name="Content-Type" value="image/jpeg" /><br />

Tags for File:

</html>

The post parameters are case insensitive. For example, you can specify x-amz-signature or X-Amz-
Signature.

Using POST with Adobe Flash to Upload Objects

This section discusses uploading objects with an HTTP POST request when using Adobe Flash.

Using POST with Adobe Flash

This section describes how to use POST with Adobe Flash.

Adobe Flash Player Security

By default, the Adobe Flash Player security model prohibits making network connections to servers
outside the domain that serves the Adobe Flash (.swf) ﬁle.

To override the default, you must upload a publicly readable crossdomain.xml ﬁle to the bucket that
will accept POST uploads. Here is a sample crossdomain.xml ﬁle:

<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM
"http://www.macromedia.com/xml/dtds/cross-domain-policy.dtd">

API Version 2006-03-01

844
Amazon Simple Storage Service API Reference
Browser-Based Uploads Using AWS Amplify

<cross-domain-policy>
<allow-access-from domain="*" secure="false" />
</cross-domain-policy>

For more information about the Adobe Flash security model, go to the Adobe web site.

Other Adobe Flash Considerations

['starts-with', '$Filename', '']

Some versions of the Adobe Flash Player do not properly handle HTTP responses that have an
empty body. To conﬁgure POST to return a response that does not have an empty body, set
success_action_status to 201. Then, Amazon S3 will return an XML document with a 201 status
code. For information about using this as an optional element (currently the only allowed value is the
content of the XML document), see POST Object (p. 1295). For information about form ﬁelds, see HTML
Form Fields (p. 833).

Browser-Based Uploads to Amazon S3 Using the AWS

Amplify Library
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

This section describes how to upload ﬁles to Amazon S3 using the AWS Amplify JavaScript library.

For information about setting up the AWS Amplify library, see AWS Amplify Installation and
Conﬁguration.

Using the AWS Amplify JavaScript library to Upload Files to

Amazon S3

The AWS Amplify library Storage module gives a simple browser-based upload mechanism for
managing user content in public or private Amazon S3 storage.

API Version 2006-03-01

845
Amazon Simple Storage Service API Reference
Operations on the Service

Example : AWS Amplify Manual Setup

The following example shows the manual setup for using the AWS Amplify Storage module. The default
implementation of the Storage module uses Amazon S3.

import Amplify from 'aws-amplify';

Example : Put data into Amazon S3

The following example shows how to put public data into Amazon S3.

Storage.put('test.txt', 'Hello')
.then (result => console.log(result))
.catch(err => console.log(err));

The following example shows how to put private data into Amazon S3.

Storage.put('test.txt', 'Private Content', {

level: 'private',
contentType: 'text/plain'
})
.then (result => console.log(result))
.catch(err => console.log(err));

For more information about using the AWS Amplify Storage module, see AWS Amplify Storage.

More Info

AWS Amplify Quick Start

Operations on the Service

API Version 2006-03-01

846
Amazon Simple Storage Service API Reference
GET Service

This section describes operations you can perform on the Amazon S3 service.

Topics
• GET Service (p. 847)

GET Service
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

Description

This implementation of the GET operation returns a list of all buckets owned by the authenticated
sender of the request.

To authenticate a request, you must use a valid AWS Access Key ID that is registered with Amazon S3.
Anonymous requests cannot list buckets, and you cannot list buckets that you did not create.

Requests

Syntax

GET / HTTP/1.1
Host: s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

API Version 2006-03-01

847
Amazon Simple Storage Service API Reference
GET Service

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Elements

Name Description

Bucket Container for bucket information.

Type: Container

Children: Name, CreationDate

Ancestor: ListAllMyBucketsResult.Buckets

Buckets Container for one or more buckets.

Type: Container

Children: Bucket

Ancestor: ListAllMyBucketsResult

API Version 2006-03-01

848
Amazon Simple Storage Service API Reference
GET Service

Name Description

CreationDate Date the bucket was created.

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

API Version 2006-03-01

849
Amazon Simple Storage Service API Reference
GET Service

Examples

Sample Request

The GET operation on the Service endpoint (s3.amazonaws.com) returns a list of all of the buckets owned
by the authenticated sender of the request.

GET / HTTP/1.1
Host: s3.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<Owner>
<ID>bcaf1ffd86f461ca5fb16fd081034f</ID>
<DisplayName>webfile</DisplayName>
</Owner>
<Buckets>
<Bucket>
<Name>quotes</Name>
<CreationDate>2006-02-03T16:45:09.000Z</CreationDate>
</Bucket>
<Bucket>
<Name>samples</Name>
<CreationDate>2006-02-03T16:41:58.000Z</CreationDate>
</Bucket>
</Buckets>
</ListAllMyBucketsResult>

Related Resources

API Version 2006-03-01

850
Amazon Simple Storage Service API Reference
Operations on AWS Accounts

• GET Bucket (List Objects) Version 1 (p. 940)

• GET Object (p. 1248)

Operations on AWS Accounts

This section describes the REST operations related to Amazon S3 that you can perform on Amazon Web
Services accounts.

Topics
• Block Public Access (p. 851)
• Batch Operations (p. 863)

Block Public Access

This section describes how to use Amazon S3 block public access.

Topics
• DELETE PublicAccessBlock (p. 851)
• GET PublicAccessBlock (p. 854)
• PUT PublicAccessBlock (p. 858)

DELETE PublicAccessBlock

Description

This operation removes the PublicAccessBlock conﬁguration for an Amazon Web Services account.
In order to use this operation, you must have the s3:PutAccountPublicAccessBlock permission. For

API Version 2006-03-01

851
Amazon Simple Storage Service API Reference
Block Public Access

more information about Amazon S3 permissions, see Specifying Permissions in a Policy in the Amazon
Simple Storage Service Developer Guide.

Requests

Syntax

DELETE /v20180820/configuration/publicAccessBlock HTTP/1.1

Host: <account-id>.s3-control.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization string> (see Authenticating Requests (AWS Signature Version
4))

Note
For information about locating your AWS account ID, see Finding your AWS Account ID in the
Amazon Web Services General Reference.

Request Parameters

This operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

API Version 2006-03-01

852
Amazon Simple Storage Service API Reference
Block Public Access

This implementation of the operation does not use request elements.

Responses

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

Response Elements

This operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Related Resources

• Using Amazon S3 Block Public Access in the Amazon Simple Storage Service Developer Guide.
• GET PublicAccessBlock (p. 995)
• PUT PublicAccessBlock (p. 1157)
• DELETE PublicAccessBlock (p. 908)
• GET BucketPolicyStatus (p. 1016)
• GET PublicAccessBlock (p. 854)
• PUT PublicAccessBlock (p. 858)

API Version 2006-03-01

853
Amazon Simple Storage Service API Reference
Block Public Access

GET PublicAccessBlock

Description

This operation retrieves the PublicAccessBlock configuration for an Amazon Web Services account.
In order to use this operation, you must have the s3:GetAccountPublicAccessBlock permission. For
more information about Amazon S3 permissions, see Specifying Permissions in a Policy in the Amazon
Simple Storage Service Developer Guide.
Important
When Amazon S3 evaluates the PublicAccessBlock configuration for a bucket or an object, it
checks the PublicAccessBlock configuration for both the bucket (or the bucket that contains
the object) and the bucket owner's account. If the PublicAccessBlock settings are different
between the bucket and the account, Amazon S3 uses the most restrictive combination of the
bucket-level and account-level settings.

For more information about when Amazon S3 considers a bucket or an object public, see The Meaning of
"Public" in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

GET /v20180820/configuration/publicAccessBlock HTTP/1.1

Host: <account-id>.s3-control.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization string> (see Authenticating Requests (AWS Signature Version
4))

Note
For information about locating your AWS account ID, see Finding your AWS Account ID in the
Amazon Web Services General Reference.

API Version 2006-03-01

854
Amazon Simple Storage Service API Reference
Block Public Access

Request Parameters

This operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

Response Elements

API Version 2006-03-01

855
Amazon Simple Storage Service API Reference
Block Public Access

Name Description

A PublicAccessBlock conﬁguration.
PublicAccessBlockConfiguration

Type: Container

Children: BlockPublicAcls, IgnorePublicAcls, BlockPublicPolicy,

RestrictPublicBuckets

BlockPublicAcls Speciﬁes whether Amazon S3 will block public access control lists (ACLs) for
buckets and objects that are owned by this account.

Type: Boolean

Ancestor: PublicAccessBlockConfiguration

Valid values: TRUE | FALSE

IgnorePublicAcls Speciﬁes whether Amazon S3 will ignore public ACLs for buckets and objects
that are owned by this account.

Type: Boolean

Ancestor: PublicAccessBlockConfiguration

Valid values: TRUE | FALSE

BlockPublicPolicy Speciﬁes whether Amazon S3 will block public bucket policies for buckets that
are owned by this account.

Type: Boolean

Ancestor: PublicAccessBlockConfiguration

Valid values: TRUE | FALSE

Speciﬁes whether Amazon S3 will restrict public bucket policies for buckets that
RestrictPublicBuckets
are owned by this account.

Type: Boolean

Ancestor: PublicAccessBlockConfiguration

Valid values: TRUE | FALSE

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

API Version 2006-03-01

856
Amazon Simple Storage Service API Reference
Block Public Access

Examples

Sample Request

The following request gets an account PublicAccessBlock conﬁguration.

GET /v20180820/configuration/publicAccessBlock HTTP/1.1

Host: <account-id>.s3-control.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <signatureValue>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0

Related Resources

API Version 2006-03-01

857
Amazon Simple Storage Service API Reference
Block Public Access

• GET BucketPolicyStatus (p. 1016)

• PUT PublicAccessBlock (p. 858)
• DELETE PublicAccessBlock (p. 851)

PUT PublicAccessBlock

Description

This operation creates or modifies the PublicAccessBlock configuration for an Amazon Web Services
account. In order to use this operation, you must have the s3:PutAccountPublicAccessBlock
permission. For more information about Amazon S3 permissions, see Specifying Permissions in a Policy
in the Amazon Simple Storage Service Developer Guide.
Important
When Amazon S3 evaluates the PublicAccessBlock configuration for a bucket or an object, it
checks the PublicAccessBlock configuration for both the bucket (or the bucket that contains
the object) and the bucket owner's account. If the PublicAccessBlock configurations are
different between the bucket and the account, Amazon S3 uses the most restrictive combination
of the bucket-level and account-level settings.

For more information about when Amazon S3 considers a bucket or object public, see The Meaning of
"Public" in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

PUT /v20180820/configuration/publicAccessBlock HTTP/1.1

Host: <account-id>.s3-control.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization string> (see Authenticating Requests (AWS Signature Version
4))

API Version 2006-03-01

858
Amazon Simple Storage Service API Reference
Block Public Access

Note
For information about locating your AWS account ID, see Finding your AWS Account ID in the
Amazon Web Services General Reference.

Request Parameters

This operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This operation uses the following request elements. You can enable BlockPublicAcls,
IgnorePublicAcls, BlockPublicPolicy, and RestrictPublicBuckets in any combination.

Name Description Required

A PublicAccessBlock conﬁguration. You can enable the

PublicAccessBlockConfiguration Yes
conﬁguration elements in any combination.

Type: Container

Children: BlockPublicAcls, IgnorePublicAcls,

BlockPublicPolicy, RestrictPublicBuckets

BlockPublicAcls Speciﬁes whether Amazon S3 should block public access control lists No
(ACLs) for buckets and objects in this account. Setting this element to
TRUE causes the following behavior:

• PUT Bucket acl (p. 1108) and PUT Object acl (p. 1363) calls fail if
the speciﬁed ACL is public.
• PUT Object (p. 1324) calls fail if the request includes a public ACL.
• PUT Bucket (p. 1095) calls fail if the request includes a public ACL.

Important
Enabling this setting doesn't aﬀect existing policies or ACLs.

API Version 2006-03-01

859
Amazon Simple Storage Service API Reference
Block Public Access

Name Description Required

Type: Boolean

Ancestor: PublicAccessBlockConfiguration

Valid values: TRUE | FALSE

IgnorePublicAclsSpeciﬁes whether Amazon S3 should ignore public ACLs for buckets No

860
Amazon Simple Storage Service API Reference
Block Public Access

Responses

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

Response Elements

This operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

First Sample Request

The following request puts an account PublicAccessBlock conﬁguration that blocks public ACLs for
buckets in the speciﬁed account.

API Version 2006-03-01

861
Amazon Simple Storage Service API Reference
Block Public Access

PUT /v20180820/configuration/publicAccessBlock HTTP/1.1

Host: <account-id>.s3-control.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <signatureValue>

<?xml version="1.0" encoding="UTF-8"?>

First Sample Response

HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0

Second Sample Request

The following request puts an account PublicAccessBlock conﬁguration that ignores public ACLs and
restricts public bucket policies for buckets in the speciﬁed account.

PUT /v20180820/configuration/publicAccessBlock HTTP/1.1

Host: <account-id>.s3-control.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <signatureValue>

<?xml version="1.0" encoding="UTF-8"?>

Second Sample Response

API Version 2006-03-01

862
Amazon Simple Storage Service API Reference
Batch Operations

HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0

Related Resources

Batch Operations
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

This section describes how to use perform batch operations with Amazon S3 accounts.

Topics
• CreateJob (p. 864)
• DescribeJob (p. 868)
• ListJobs (p. 871)
• UpdateJobStatus (p. 874)
• UpdateJobPriority (p. 877)
• Batch Operations Common Elements (p. 879)

API Version 2006-03-01

863
Amazon Simple Storage Service API Reference
Batch Operations

CreateJob
Service: AWS S3 Control

Creates an Amazon S3 batch operations job.

Request Syntax

POST /v20180820/jobs HTTP/1.1

x-amz-account-id: AccountId
<?xml version="1.0" encoding="UTF-8"?>
<CreateJobRequest xmlns="http://awss3control.amazonaws.com/doc/2018-08-20/">
<ClientRequestToken>string</ClientRequestToken>
<ConfirmationRequired>boolean</ConfirmationRequired>
<Description>string</Description>
<Manifest>
<Location>
<ETag>string</ETag>
<ObjectArn>string</ObjectArn>
<ObjectVersionId>string</ObjectVersionId>
</Location>
<Spec>
<Fields>
<INVALID-TYPE-NAME>string</INVALID-TYPE-NAME>
</Fields>
<Format>string</Format>
</Spec>
</Manifest>
<Operation>
<S3PutObjectAcl>
<AccessControlPolicy>
<AccessControlList>
<Grants>
<S3Grant>
<Grantee>
<DisplayName>string</DisplayName>
<Identifier>string</Identifier>
<TypeIdentifier>string</TypeIdentifier>
</Grantee>
<Permission>string</Permission>
</S3Grant>
</Grants>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
</AccessControlList>
<CannedAccessControlList>string</CannedAccessControlList>
</AccessControlPolicy>
</S3PutObjectAcl>
</Operation>
<Priority>integer</Priority>
<Report>
<Bucket>string</Bucket>
<Enabled>boolean</Enabled>
<Format>string</Format>
<Prefix>string</Prefix>
<ReportScope>string</ReportScope>
</Report>
<RoleArn>string</RoleArn>
</CreateJobRequest>

API Version 2006-03-01

864
Amazon Simple Storage Service API Reference
Batch Operations

URI Request Parameters

The request requires the following URI parameters.

x-amz-account-id (p. 864)

Length constraints: Minimum length of 1. Maximum length of 64.

Request Body
The request accepts the following data in XML format.

CreateJobRequest (p. 864)

A root-level tag for the CreateJobRequest parameters.

Required: Yes
ClientRequestToken (p. 864)

An idempotency token to ensure that you don't accidentally submit the same request twice. You can
use any string up to the maximum length.

Type: String

Length constraints: Minimum length of 1. Maximum length of 64.

Required: Yes
ConﬁrmationRequired (p. 864)

Indicates whether conﬁrmation is required before Amazon S3 runs the job. By default,
ConfirmationRequired is false.

Type: Boolean

Required: No
Description (p. 864)

A description for this job. You can use any string within the permitted length. Descriptions don't
need to be unique and can be used for multiple jobs.

Type: String

Length constraints: Minimum length of 1. Maximum length of 256.

Required: No
Manifest (p. 864)

Conﬁguration parameters for the manifest.

Type: JobManifest (p. 577) object

Required: Yes
Operation (p. 864)

API Version 2006-03-01

865
Amazon Simple Storage Service API Reference
Batch Operations

Type: JobOperation (p. 580) object

Required: Yes
Priority (p. 864)

The numerical priority for this job. Higher numbers indicate higher priority.

Type: Integer

Valid range: Minimum value of 0. Maximum value of 2147483647.

Required: Yes
Report (p. 864)

Conﬁguration parameters for the optional job-completion report.

Type: JobReport (p. 582) object

Required: Yes
RoleArn (p. 864)

The Amazon Resource Name (ARN) for the AWS Identity and Access Management (IAM) role that
batch operations use to execute this job's operation on each object in the manifest.

Type: String

Length constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<CreateJobResult>
<JobId>string</JobId>
</CreateJobResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

CreateJobResult (p. 866)

Root level tag for the CreateJobResult parameters.

Required: Yes
JobId (p. 866)

The ID for this job. Amazon S3 generates this ID automatically and returns it after a successful
Create Job request.

Type: String

Length constraints: Minimum length of 5. Maximum length of 36.

API Version 2006-03-01

866
Amazon Simple Storage Service API Reference
Batch Operations

867
Amazon Simple Storage Service API Reference
Batch Operations

DescribeJob
Service: AWS S3 Control

Retrieves the conﬁguration parameters and status for an Amazon S3 batch operations job.

Request Syntax

GET /v20180820/jobs/id HTTP/1.1

x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

id (p. 868)

The ID for the job whose information you want to retrieve.

Length constraints: Minimum length of 5. Maximum length of 36.

x-amz-account-id (p. 868)

Length constraints: Minimum length of 1. Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

API Version 2006-03-01

868
Amazon Simple Storage Service API Reference
Batch Operations

<S3PutObjectAcl>
<AccessControlPolicy>
<AccessControlList>
<Grants>
<S3Grant>
<Grantee>
<DisplayName>string</DisplayName>
<Identifier>string</Identifier>
<TypeIdentifier>string</TypeIdentifier>
</Grantee>
<Permission>string</Permission>
</S3Grant>
</Grants>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
</AccessControlList>
<CannedAccessControlList>string</CannedAccessControlList>
</AccessControlPolicy>
</S3PutObjectAcl>
</Operation>
<Priority>integer</Priority>
<ProgressSummary>
<NumberOfTasksFailed>long</NumberOfTasksFailed>
<NumberOfTasksSucceeded>long</NumberOfTasksSucceeded>
<TotalNumberOfTasks>long</TotalNumberOfTasks>
</ProgressSummary>
<Report>
<Bucket>string</Bucket>
<Enabled>boolean</Enabled>
<Format>string</Format>
<Prefix>string</Prefix>
<ReportScope>string</ReportScope>
</Report>
<RoleArn>string</RoleArn>
<Status>string</Status>
<StatusUpdateReason>string</StatusUpdateReason>
<SuspendedCause>string</SuspendedCause>
<SuspendedDate>timestamp</SuspendedDate>
<TerminationDate>timestamp</TerminationDate>
</Job>
</DescribeJobResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

DescribeJobResult (p. 868)

Root level tag for the DescribeJobResult parameters.

Required: Yes
Job (p. 868)

Contains the conﬁguration parameters and status for the job speciﬁed in the Describe Job
request.

Type: JobDescriptor (p. 571) object

API Version 2006-03-01

869
Amazon Simple Storage Service API Reference
Batch Operations

870
Amazon Simple Storage Service API Reference
Batch Operations

ListJobs
Service: AWS S3 Control

Lists current jobs and jobs that have ended within the last 30 days for the AWS account that is making
the request. The job list that is returned is sorted by creation date, with the newest job ﬁrst.

Request Syntax

GET /v20180820/jobs?jobStatuses=JobStatuses&maxResults=MaxResults&nextToken=NextToken
HTTP/1.1
x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

jobStatuses (p. 871)

The List Jobs request returns jobs that match the statuses listed in this element. If you don't
provide jobStatuses, the API returns all jobs. You can specify one or more jobStatuses as
follows:

https://acct-id.s3-control.us-west-2.amazonaws.com/v20180820/jobs?
jobStatuses=Active&jobStatuses=Complete&maxResults=2

Valid values: Active | Cancelled | Cancelling | Complete | Completing | Failed

The maximum number of jobs that Amazon S3 includes in the List Jobs response. If the number
of jobs is higher than this number, the response includes a pagination token in the NextToken ﬁeld
to enable you to retrieve the next page of results. The operation might return fewer results than
maxResults, but as long as the nextToken returned is not empty, there are more results that you
can fetch.

Valid range: Minimum value of 1. Maximum value of 1000.

nextToken (p. 871)

A pagination token to request the next page of results. Use the token that Amazon S3 returned in
the NextToken element of the ListJobsResult from the previous List Jobs request.

Length constraints: Minimum length of 1. Maximum length of 1024.

x-amz-account-id (p. 871)

Length constraints: Minimum length of 1. Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<ListJobsResult>

API Version 2006-03-01

871
Amazon Simple Storage Service API Reference
Batch Operations

<Jobs>
<JobListDescriptor>
<CreationTime>timestamp</CreationTime>
<Description>string</Description>
<JobId>string</JobId>
<Operation>string</Operation>
<Priority>integer</Priority>
<ProgressSummary>
<NumberOfTasksFailed>long</NumberOfTasksFailed>
<NumberOfTasksSucceeded>long</NumberOfTasksSucceeded>
<TotalNumberOfTasks>long</TotalNumberOfTasks>
</ProgressSummary>
<Status>string</Status>
<TerminationDate>timestamp</TerminationDate>
</JobListDescriptor>
</Jobs>
<NextToken>string</NextToken>
</ListJobsResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in XML format by the service.

ListJobsResult (p. 871)

A root-level tag for the ListJobsResult parameters.

Required: Yes
Jobs (p. 871)

The list of current jobs and jobs that have ended within the last 30 days. This is the list of jobs that
match the job statuses speciﬁed in the request, if any.

Type: Array of JobListDescriptor (p. 575) objects

NextToken (p. 871)

If the List Jobs request produced more than the maximum number of results, you can pass this
value into a subsequent List Jobs request to retrieve the next page of results. As long as the
NextToken is not empty, there are more results you can fetch (regardless of the number of jobs that
the operation produces in comparison to maxResults speciﬁed in the request).

Type: String

Length constraints: Minimum length of 1. Maximum length of 1024.

Errors
InternalServiceException

HTTP Status Code: 500

InvalidNextTokenException

HTTP Status Code: 400

InvalidRequestException

HTTP Status Code: 400

API Version 2006-03-01

872
Amazon Simple Storage Service API Reference
Batch Operations

See Also
For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

873
Amazon Simple Storage Service API Reference
Batch Operations

UpdateJobStatus
Service: AWS S3 Control

Updates the status for the speciﬁed job. Use this operation to conﬁrm that you want to run a job or to
cancel an existing job.

Request Syntax

POST /v20180820/jobs/id/status?
requestedJobStatus=RequestedJobStatus&statusUpdateReason=StatusUpdateReason HTTP/1.1
x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

id (p. 874)

The ID of the job whose status you want to update.

Length constraints: Minimum length of 5. Maximum length of 36.

requestedJobStatus (p. 874)

The status that you want to move the speciﬁed job to. You move the job to the Ready state to
conﬁrm the job. Amazon S3 then makes the job eligible for execution. You move the job to the
Cancelled state to cancel a job. This is a required parameter.

Valid Values: Cancelled | Ready

statusUpdateReason (p. 874)

A description of the reason why you want to change the speciﬁed job's status. This ﬁeld can be any
string up to the maximum length.

Length constraints: Minimum length of 1. Maximum length of 256.

x-amz-account-id (p. 874)

The ID is required.

Length constraints: Minimum length of 1. Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<UpdateJobStatusResult>
<JobId>string</JobId>
<Status>string</Status>
<StatusUpdateReason>string</StatusUpdateReason>
</UpdateJobStatusResult>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

API Version 2006-03-01

874
Amazon Simple Storage Service API Reference
Batch Operations

The following data is returned in XML format by the service.

UpdateJobStatusResult (p. 874)

A root-level tag for the UpdateJobStatusResult parameters.

Required: Yes
JobId (p. 874)

The ID for the job whose status was updated.

Type: String

Length constraints: Minimum length of 5. Maximum length of 36.

Status (p. 874)

The current status for the speciﬁed job.

Type: String

875
Amazon Simple Storage Service API Reference
Batch Operations

• AWS SDK for JavaScript

• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

876
Amazon Simple Storage Service API Reference
Batch Operations

UpdateJobPriority
Service: AWS S3 Control

Updates an existing job's priority.

Request Syntax

POST /v20180820/jobs/id/priority?priority=Priority HTTP/1.1

x-amz-account-id: AccountId

URI Request Parameters

The request requires the following URI parameters.

id (p. 877)

The ID for the job whose priority you want to update. The id is required.

Length constraints: Minimum length of 5. Maximum length of 36.

priority (p. 877)

The priority that you want to assign to this job. The priority is required.

Valid range: Minimum value of 0. Maximum value of 2147483647.

x-amz-account-id (p. 877)

Length constraints: Minimum length of 1. Maximum length of 64.

Request Body
The request does not have a request body.

Response Syntax

HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<UpdateJobPriorityResult>
<JobId>string</JobId>
<Priority>integer</Priority>
</UpdateJobPriorityResult>

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2006-03-01

878
Amazon Simple Storage Service API Reference
Batch Operations

Batch Operations Common Elements

Description

The following tables list common request, response, and special error elements for Amazon S3 control
operations.

Requests

Element Description

AccountId The account ID for the Amazon S3 account that is associated with the batch operations
job.

Type: String

FunctionArn The Amazon Resource Name (ARN) of the AWS Lambda function that you want to
invoke with a batch operations job.

Type: String

Default: None

Restrictions: Max length is 1,024 characters.

LogType The type of log that you want Lambda to produce when invoked by a batch operations
job.

Type: String

Valid values: None | Tail

The arguments that you want to pass to each invocation of a Lambda function by a
UserArguments
batch operations job.

Restrictions: The total length of arguments must be fewer than or equal to 20,480
characters

A container element used to specify the parameters of a batch operations Copy Object
S3CopyObjectAction
request.

API Version 2006-03-01

879
Amazon Simple Storage Service API Reference
Batch Operations

Element Description
Type: Container

Child Elements

Element Type Restrictions

TargetResource S3BucketArnString

AccessControlList S3AccessControlList

CannedAccessControlList
S3CannedAccessControlList

MetadataDirective S3MetadataDirective

TimeStamp
ModifiedSinceConstraint

NewObjectMetadata S3ObjectMetadata

NewObjectTagging S3TagSet

RedirectLocation String Must be between 1 and

2,048 characters

RequesterPays Boolean

StorageClass S3StorageClass

TimeStamp
UnmodifiedSinceConstraint

The ARN of the Amazon S3 bucket that you want to use with a batch operations job.
TargetResource

Type: String

Restrictions: The value must be between 1 and 128 characters long.

A container element that is used to specify the permission grants for an object copied
AccessControlList
as part of a batch operations job.

Type: Container

Child Elements

Element Type Restrictions

Owner S3ObjectOwner Required

Grants S3GrantList Required

API Version 2006-03-01

880
Amazon Simple Storage Service API Reference
Batch Operations

Element Description

Type: Container
S3ObjectOwner

Child Elements

Element Type Restrictions

ID String Required
Maximum length is 1,024
characters

DisplayName String Required

Maximum length is 1,024
characters

S3GrantList Type: List

List Item Type: S3Grant

S3Grant A permission grant for an Amazon S3 resource.

Type: Container

Child Elements

Element Type Restrictions

Grantee S3Grantee Required

Permission S3Permission Required

S3Grantee A grantee for an S3Grant.

Type: Container

Child Elements

Element Type Restrictions

TypeIdentifier S3GranteeTypeIdentiﬁer Required

Identifier String Required

Maximum length is 1,024
characters

DisplayName String Required

Maximum length is 1,024
characters

Identiﬁes the type of grantee that is used to grant permissions for an Amazon S3
S3GranteeTypeIdentifier
resource.

Type: String

Valid values: CANONICAL | EMAIL_ADDRESS | GROUP

API Version 2006-03-01

881
Amazon Simple Storage Service API Reference
Batch Operations

Element Description

S3PermissionSpeciﬁes an access permission to be granted for an Amazon S3 resource.

Type: String

Valid values: FULL_CONTROL | READ | WRITE | READ_ACP | WRITE_ACP

Type: String
S3MetadataDirective

Valid values: COPY | REPLACE

Type: String
S3StorageClass

Valid values: STANDARD | STANDARD_IA | ONEZONE_IA | GLACIER |

INTELLIGENT_TIERING | DEEP_ARCHIVE

JobId The ID of the batch operations job that you want to perform an action on.

Type: String

Restrictions: Must be between 5 and 36 characters long.

JobPriority Type: Integer

Restrictions: The value must be between 0 and 2^31 - 1 (2147483647)

JobReport

JobStatus Type: String

Valid values: Active | Cancelled | Cancelling | Complete | Completing | Failed

Type: String
JobStatusUpdateReason

Restrictions: Maximum length is 256 characters

JobReport Type: Container

Child Elements

Element Type Restrictions

AccountId AccountId

Bucket String Required

Must be between 1 and
128 characters

Format String Required

Valid values:
JobReport_CSV_20180820

Prefix String Required

Must be between 1 and
512 characters long

ReportScope String Required

Valid values: AllTasks |
FailedTasksOnly

API Version 2006-03-01

882
Amazon Simple Storage Service API Reference
Batch Operations

Responses

Element Description

Type: Container
JobDescriptor

Child Elements

Element Type Restrictions

JobId JobId

Name String Must be between 1 and

256 characters

JobArn String Must be between 1 and

1,250 characters

Status JobStatus

Manifest JobManifest

Action JobAction

Priority JobPriority

ProgressSummary JobProgressSummary

StatusUpdateReason JobStatusUpdateReason

FailureReasons JobFailureReasonList

Report JobReport

CreationTime JobCreationTime

TerminationTime JobTerminationTime

Type: Container
JobProgressSummary

Child Elements

Element Type

TotalNumberOfTasks Long

NumberOfTasksSucceeded Long

NumberOfTasksFailed Long

Type: List
JobFailureReasonList

List Item Type: JobFailureReason

API Version 2006-03-01

883
Amazon Simple Storage Service API Reference
Batch Operations

Element Description

Type: String
JobFailureReason

Valid values: ErrorReadingManifest | ErrorWritingReport |

TaskFailureThresholdExceeded

Elements Common to Requests and Responses

Element Description

JobAction A container element that is used to specify what action you want batch operations or
Amazon S3 public lockdown to perform.

Type: Container

Child Elements

Element Type Restrictions

LambdaInvoke LambdaInvokeAction

S3CopyObject S3CopyObjectAction

S3SetObjectAcl S3SetObjectAclAction

S3SetObjectTagging
S3SetObjectTaggingAction

S3InitiateRestoreObject
S3InitiateRestoreObjectAction

Restrictions: Exactly one child element is required when JobAction is used in a

request.

JobManifest Type: Container

Type: Container
JobManifestLocation

Child Elements

Element Type Restrictions

AccountId AccountId

ObjectArn String Required in requests

Must be between 1 and

2,000 characters

ObjectVersionId String Must be between 1 and

2,000 characters

ETag String Must be between 1 and

1,024 characters

Type: String
S3BucketArnString

Restrictions: Must be between 1 and 128 characters

Type: Container
S3AccessControlPolicy

Child Elements

Element Type

AccessControlList S3AccessControlList

CannedAccessControlList S3CannedAccessControlList

Type: Container
S3AccessControlList

Child Elements

Element Type

Owner S3ObjectOwner

Grants S3GrantList

Type: String
S3CannedAccessControlList

Valid values: PRIVATE | PUBLIC_READ | PUBLIC_READ_WRITE | AWS_EXEC_READ |

AUTHENTICATED_READ | BUCKET_OWNER_READ | BUCKET_OWNER_FULL_CONTROL

API Version 2006-03-01

885
Amazon Simple Storage Service API Reference
Batch Operations

Element Description

S3TagSet Type: List

List Item Type: S3Tag

S3Tag Type: Container

Child Elements

Element Type Restrictions

Key String Required

Must be between 1 and

1,024 characters

Value String Required

Must be between 1 and

1,024 characters

Type: Container
S3ObjectMetadata

Child Elements

Element Type Restrictions

CacheControl String Must be between 1 and

1,024 characters

ContentDisposition String Must be between 1 and

1,024 characters

ContentEncoding String Must be between 1 and

1,024 characters

ContentLanguage String Must be between 1 and

1,024 characters

UserMetadata S3UserMetadata

ContentLength Integer Must be greater than or

equal to 0

ContentMD5 String Must be between 1 and

1,024 characters

ContentType String Must be between 1 and

1,024 characters

HttpExpiresDate TimeStamp

RequesterCharged Boolean

Type: Map
S3UserMetadata

Restrictions: The total length of the key + value must be fewer than or equal to 8,192
characters

API Version 2006-03-01

886
Amazon Simple Storage Service API Reference
Batch Operations

Actions

Action Description

A container element that is used to specify the AWS Lambda action that you want to
LambdaInvokeAction
invoke with a batch operations job.

Type: Container

Child Elements

Element Type Restrictions

FunctionArn String Required

Must be between 1 and
1,024 characters

LogType String Required

Valid values: None | Tail

UserArguments UserArguments Required

S3CopyObjectA container element that is used to specify the parameters of a batch operations Copy
Object request.

Type: Container

Child Elements

Element Type Restrictions

TargetResource S3BucketArnString (p. 884)

AccessControlList S3AccessControlList

CannedAccessControlList
S3CannedAccessControlList

MetadataDirective S3MetadataDirective

TimeStamp
ModifiedSinceConstraint

NewObjectMetadata S3ObjectMetadata

NewObjectTagging S3TagSet

RedirectLocation String Must be between 1 and

2,048 characters

RequesterPays Boolean

StorageClass S3StorageClass

TimeStamp
UnmodifiedSinceConstraint

API Version 2006-03-01

887
Amazon Simple Storage Service API Reference
Batch Operations

Action Description

equal to 0

Special Errors

Error Description

Description
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

Deletes the bucket named in the URI. All objects (including all object versions and delete markers) in the
bucket must be deleted before the bucket itself can be deleted.

Requests
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

Syntax

DELETE / HTTP/1.1
Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

API Version 2006-03-01

891
Amazon Simple Storage Service API Reference
DELETE Bucket

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

API Version 2006-03-01

892
Amazon Simple Storage Service API Reference
DELETE Bucket

Sample Request

This request deletes the bucket named "quotes".

DELETE / HTTP/1.1
Host: quotes.s3.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 204 No Content

x-amz-id-2: JuKZqmXuiwFeDQxhD7M8KtsKobSzWA1QEjLbTMTagkKdBX2z7Il/jGhDeJ3j6s80
x-amz-request-id: 32FE2CEB32F5EE25
Date: Wed, 01 Mar 2006 12:00:00 GMT
Connection: close
Server: AmazonS3

Related Resources

• PUT Bucket (p. 1095)

• DELETE Object (p. 1239)

API Version 2006-03-01

893
Amazon Simple Storage Service API Reference
DELETE Bucket analytics

DELETE Bucket analytics

Description

This implementation of the DELETE operation deletes an analytics configuration (identified by the
analytics configuration ID) from the bucket.

For information about Amazon S3 analytics feature, see Amazon S3 Analytics – Storage Class Analysis in
the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

DELETE /?analytics&id=analytics-configuration-ID HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

API Version 2006-03-01

894
Amazon Simple Storage Service API Reference
DELETE Bucket analytics

This implementation of DELETE uses the parameter in the following table.

Parameter Description Required

id The ID that identiﬁes the analytics conﬁguration. Yes

Type: String

Default: None

Valid Characters for id: a-z A-Z 0-9 - _ .

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

API Version 2006-03-01

895
Amazon Simple Storage Service API Reference
DELETE Bucket analytics

Examples

Sample Request

The following DELETE request deletes the analytics conﬁguration with the ID list1.

DELETE ?/analytics&id=list1 HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Wed, 14 May 2014 02:11:22 GMT
Authorization: signatureValue

Sample Response

The following successful response shows Amazon S3 returning a 204 No Content response. The
analytics conﬁguration with the ID list1 for the bucket has been removed.

HTTP/1.1 204 No Content

x-amz-id-2: 0FmFIWsh/PpBuzZ0JFRC55ZGVmQW4SHJ7xVDqKwhEdJmf3q63RtrvH8ZuxW1Bol5
x-amz-request-id: 0CF038E9BCF63097
Date: Wed, 14 May 2014 02:11:22 GMT
Server: AmazonS3

Related Resources

• GET Bucket analytics (p. 959)

• List Bucket Analytics Conﬁgurations (p. 1067)
• PUT Bucket analytics (p. 1117)

API Version 2006-03-01

896
Amazon Simple Storage Service API Reference
DELETE Bucket cors

DELETE Bucket cors

Description

Deletes the cors conﬁguration information set for the bucket.

To use this operation, you must have permission to perform the s3:PutBucketCORS action. The bucket
owner has this permission by default and can grant this permission to others.

For information more about cors, go to Enabling Cross-Origin Resource Sharing in the Amazon Simple
Storage Service Developer Guide.

Requests

Syntax

DELETE /?cors HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

API Version 2006-03-01

897
Amazon Simple Storage Service API Reference
DELETE Bucket cors

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Examples

Example 1: Retrieve cors subresource

API Version 2006-03-01

898
Amazon Simple Storage Service API Reference
DELETE Bucket cors

The following DELETE request deletes the cors subresource from the speciﬁed bucket. This action
removes cors conﬁguration that is stored in the subresource.

Sample Request

DELETE /?cors HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Tue, 13 Dec 2011 19:14:42 GMT
Authorization: signatureValue

Sample Response

HTTP/1.1 204 No Content

x-amz-id-2: 0FmFIWsh/PpBuzZ0JFRC55ZGVmQW4SHJ7xVDqKwhEdJmf3q63RtrvH8ZuxW1Bol5
x-amz-request-id: 0CF038E9BCF63097
Date: Tue, 13 Dec 2011 19:14:42 GMT
Server: AmazonS3
Content-Length: 0

Related Resources

• PUT Bucket cors (p. 1124)

• DELETE Bucket cors (p. 897)
• OPTIONS object (p. 1291)

API Version 2006-03-01

899
Amazon Simple Storage Service API Reference
DELETE Bucket encryption

DELETE Bucket encryption

Description

To use this operation, you must have permissions to perform the s3:PutEncryptionConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple
Storage Service Developer Guide.

Requests

Syntax

DELETE /?encryption HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

API Version 2006-03-01

900
Amazon Simple Storage Service API Reference
DELETE Bucket encryption

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Examples

Sample Request

API Version 2006-03-01

901
Amazon Simple Storage Service API Reference
DELETE Bucket encryption

The following DELETE request deletes default encryption from the bucket.

DELETE ?/encryption HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Wed, 06 Sep 2017 12:00:00 GMT
Authorization: signatureValue

Sample Response

The following successful response shows Amazon S3 returning a 204 No Content response conﬁrming
that default encryption has been removed from the bucket.

HTTP/1.1 204 No Content

x-amz-id-2: 0FmFIWsh/PpBuzZ0JFRC55ZGVmQW4SHJ7xVDqKwhEdJmf3q63RtrvH8ZuxW1Bol5
x-amz-request-id: 0CF038E9BCF63097
Date: Wed, 06 Sep 2017 12:00:00 GMT
Server: AmazonS3

Related Resources

• GET Bucket encryption (p. 971)

• PUT Bucket encryption (p. 1131)

API Version 2006-03-01

902
Amazon Simple Storage Service API Reference
DELETE Bucket inventory

DELETE Bucket inventory

Description

This implementation of the DELETE operation deletes an inventory configuration (identified by the
inventory configuration ID) from the bucket.

For information about the Amazon S3 inventory feature, see Amazon S3 Inventory in the Amazon Simple
Storage Service Developer Guide.

Requests

Syntax

DELETE /?inventory&id=inventory-configuration-ID HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

API Version 2006-03-01

903
Amazon Simple Storage Service API Reference
DELETE Bucket inventory

This implementation of DELETE uses the parameter in the following table.

Parameter Description Required

id The ID that identiﬁes the inventory conﬁguration. Yes

Type: String

Default: None

Valid Characters for id: a-z A-Z 0-9 - _ .

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

API Version 2006-03-01

904
Amazon Simple Storage Service API Reference
DELETE Bucket inventory

Examples

Sample Request

The following DELETE request deletes the inventory conﬁguration with the ID list1.

DELETE ?/inventory&id=list1 HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Wed, 14 May 2014 02:11:22 GMT
Authorization: signatureValue

Sample Response

The following successful response shows Amazon S3 returning a 204 No Content response. The
inventory conﬁguration with the ID list1 for the bucket has been removed.

HTTP/1.1 204 No Content

x-amz-id-2: 0FmFIWsh/PpBuzZ0JFRC55ZGVmQW4SHJ7xVDqKwhEdJmf3q63RtrvH8ZuxW1Bol5
x-amz-request-id: 0CF038E9BCF63097
Date: Wed, 14 May 2014 02:11:22 GMT
Server: AmazonS3

Related Resources

• GET Bucket Inventory (p. 976)

• List Bucket Inventory Conﬁgurations (p. 1073)
• PUT Bucket inventory (p. 1136)

API Version 2006-03-01

905
Amazon Simple Storage Service API Reference
DELETE Bucket lifecycle

DELETE Bucket lifecycle

Description

There is usually some time lag before lifecycle conﬁguration deletion is fully propagated to all the
Amazon S3 systems.

For more information about the object expiration, go to Elements to Describe Lifecycle Actions in the
Amazon Simple Storage Service Developer Guide.

Requests

Syntax

DELETE /?lifecycle HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

API Version 2006-03-01

906
Amazon Simple Storage Service API Reference
DELETE Bucket lifecycle

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Examples

API Version 2006-03-01

907
Amazon Simple Storage Service API Reference
DELETE PublicAccessBlock

Sample Request

The following DELETE request deletes the lifecycle subresource from the speciﬁed bucket. This
removes lifecycle conﬁguration stored in the subresource.

DELETE /?lifecycle HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Wed, 14 Dec 2011 05:37:16 GMT
Authorization: signatureValue

Sample Response

The following successful response shows Amazon S3 returning a 204 No Content response. Objects in
your bucket no longer expire.

HTTP/1.1 204 No Content

x-amz-id-2: Uuag1LuByRx9e6j5OnimrSAMPLEtRPfTaOAa==
x-amz-request-id: 656c76696e672SAMPLE5657374
Date: Wed, 14 Dec 2011 05:37:16 GMT
Connection: keep-alive
Server: AmazonS3

Related Resources

• PUT Bucket lifecycle (p. 1145)

• GET Bucket lifecycle (p. 983)

DELETE PublicAccessBlock

API Version 2006-03-01

908
Amazon Simple Storage Service API Reference
DELETE PublicAccessBlock

Description

This operation removes the PublicAccessBlock conﬁguration for an Amazon S3 bucket. In order
to use this operation, you must have the s3:PutBucketPublicAccessBlock permission. For more
information about Amazon S3 permissions, see Specifying Permissions in a Policy in the Amazon Simple
Storage Service Developer Guide.

Requests

Syntax

DELETE /<bucket-name>?publicAccessBlock HTTP/1.1

Host: <bucket-name>.s3.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization string> (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

API Version 2006-03-01

909
Amazon Simple Storage Service API Reference
DELETE PublicAccessBlock

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

Response Elements

This operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Related Resources

API Version 2006-03-01

910
Amazon Simple Storage Service API Reference
DELETE Bucket metrics

• Using Amazon S3 Block Public Access in the Amazon Simple Storage Service Developer Guide.
• GET PublicAccessBlock (p. 995)
• PUT PublicAccessBlock (p. 1157)
• GET BucketPolicyStatus (p. 1016)
• GET PublicAccessBlock (p. 854)
• PUT PublicAccessBlock (p. 858)
• DELETE PublicAccessBlock (p. 851)

DELETE Bucket metrics

Description

Deletes a metrics configuration for the Amazon CloudWatch request metrics (specified by the metrics
configuration ID) from the bucket. Note that this doesn't include the daily storage metrics.

For information about CloudWatch request metrics for Amazon S3, see Monitoring Metrics with Amazon
CloudWatch in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

DELETE /?metrics&id=Id HTTP/1.1

HOST: BucketName.s3.amazonaws.com

API Version 2006-03-01

911
Amazon Simple Storage Service API Reference
DELETE Bucket metrics

Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

Parameter Description Required

id The ID used to identify the metrics conﬁguration. Yes

Request Headers

This operation uses only Request Headers common to most requests. For more information, see Common
Request Headers (p. 779).

Request Elements

This operation does not use request elements.

Responses

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

API Version 2006-03-01

912
Amazon Simple Storage Service API Reference
DELETE Bucket metrics

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

Delete the metric conﬁguration with a speciﬁed ID, which disables the CloudWatch metrics with the
ExampleMetrics value for the FilterId dimension.

DELETE /?metrics&id=ExampleMetrics HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT
Authorization: signatureValue

Sample Response

Delete the metric conﬁguration with a speciﬁed ID, which disables the CloudWatch metrics with the
ExampleMetrics value for the FilterId dimension.

HTTP/1.1 204 No Content

API Version 2006-03-01

913
Amazon Simple Storage Service API Reference
DELETE Bucket metrics

x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3

Related Resources

• GET Bucket metrics (p. 1004)

• PUT Bucket metrics (p. 1170)
• List Bucket Metrics Conﬁgurations (p. 1079)
• Monitoring Metrics with Amazon CloudWatch in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

914
Amazon Simple Storage Service API Reference
DELETE Bucket policy

DELETE Bucket policy

Description

For more information about bucket policies, see Using Bucket Policies and User Policies in the Amazon
Simple Storage Service Developer Guide.

Requests

Syntax

DELETE /?policy HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

API Version 2006-03-01

915
Amazon Simple Storage Service API Reference
DELETE Bucket policy

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

API Version 2006-03-01

916
Amazon Simple Storage Service API Reference
DELETE Bucket policy

The response elements contain the status of the DELETE operation including the error code if the
request failed.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

This request deletes the bucket named BucketName.

DELETE /?policy HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: Tue, 04 Apr 2010 20:34:56 GMT
Authorization: signatureValue

Sample Response

HTTP/1.1 204 No Content

x-amz-id-2: Uuag1LuByRx9e6j5OnimrSAMPLEtRPfTaOFg==
x-amz-request-id: 656c76696e672SAMPLE5657374
Date: Tue, 04 Apr 2010 20:34:56 GMT
Connection: keep-alive
Server: AmazonS3

API Version 2006-03-01

917
Amazon Simple Storage Service API Reference
DELETE Bucket policy

Related Resources

• PUT Bucket (p. 1095)

• DELETE Object (p. 1239)

API Version 2006-03-01

918
Amazon Simple Storage Service API Reference
DELETE Bucket replication

DELETE Bucket replication

Description

Deletes the replication subresource associated with the speciﬁed bucket. This deletes the replication
conﬁguration from the bucket.

To use this operation, you must have permissions to perform the s3:PutReplicationConfiguration
action. The bucket owner has these permissions by default and can grant it to others. For information
about permissions, see Permissions Related to Bucket Subresource Operations and Managing Access
Permissions to Your Amazon S3 Resources in the Amazon Simple Storage Service Developer Guide.
Note
It can take a while for the deletion of a replication conﬁguration to fully propagate.

For information about replication conﬁguration, see Replication in the Amazon Simple Storage Service
Developer Guide.

Requests

Syntax

DELETE /?replication HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string

For more information about authorization, see Authenticating Requests (AWS Signature Version
4) (p. 792).

API Version 2006-03-01

919
Amazon Simple Storage Service API Reference
DELETE Bucket replication

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Examples

API Version 2006-03-01

920
Amazon Simple Storage Service API Reference
DELETE Bucket replication

The following DELETE request deletes the replication subresource from the speciﬁed bucket. This
removes the replication conﬁguration that is set for the bucket.

DELETE /?replication HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Wed, 11 Feb 2015 05:37:16 GMT
20150211T171320Z

Authorization: authorization string

When the replication subresource has been deleted, Amazon S3 returns a 204 No Content
response. It will not replicate new objects that are stored in the examplebucket bucket.

HTTP/1.1 204 No Content

x-amz-id-2: Uuag1LuByRx9e6j5OnimrSAMPLEtRPfTaOAa==
x-amz-request-id: 656c76696e672example
Date: Wed, 11 Feb 2015 05:37:16 GMT
Connection: keep-alive
Server: AmazonS3

Related Resources

• PUT Bucket replication (p. 1192)

• GET Bucket replication (p. 1040)

API Version 2006-03-01

921
Amazon Simple Storage Service API Reference
DELETE Bucket tagging

DELETE Bucket tagging

Description

This implementation of the DELETE operation uses the tagging subresource to remove a tag set from
the speciﬁed bucket.

To use this operation, you must have permission to perform the s3:PutBucketTagging action. By
default, the bucket owner has this permission and can grant this permission to others.

Requests

Syntax

DELETE /?tagging HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

API Version 2006-03-01

922
Amazon Simple Storage Service API Reference
DELETE Bucket tagging

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Examples

Sample Request

The following DELETE request deletes the tag set from the speciﬁed bucket.

API Version 2006-03-01

923
Amazon Simple Storage Service API Reference
DELETE Bucket tagging

DELETE /?tagging HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Wed, 14 Dec 2011 05:37:16 GMT
Authorization: signatureValue

Sample Response

The following successful response shows Amazon S3 returning a 204 No Content response. The tag set
for the bucket has been removed.

HTTP/1.1 204 No Content

Date: Wed, 25 Nov 2009 12:00:00 GMT
Connection: close
Server: AmazonS3

Related Resources

• GET Bucket tagging (p. 1053)

• PUT Bucket tagging (p. 1207)

API Version 2006-03-01

924
Amazon Simple Storage Service API Reference
DELETE Bucket website

DELETE Bucket website

For more information about hosting websites, go to Hosting Websites on Amazon S3 in the Amazon
Simple Storage Service Developer Guide .

Syntax

DELETE /?website HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

API Version 2006-03-01

925
Amazon Simple Storage Service API Reference
DELETE Bucket website

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of the operation does not return response elements.

Examples

API Version 2006-03-01

926
Amazon Simple Storage Service API Reference
DELETE Bucket website

Sample Request

This request deletes the website conﬁguration on the speciﬁed bucket.

DELETE ?website HTTP/1.1

Host: example-bucket.s3.amazonaws.com
Date: Thu, 27 Jan 2011 12:00:00 GMT
Authorization: signatureValue

Sample Response

HTTP/1.1 204 No Content

x-amz-id-2: aws-s3integ-s3ws-31008.sea31.amazon.com
x-amz-request-id: AF1DD829D3B49707
Date: Thu, 03 Feb 2011 22:10:26 GMT
Server: AmazonS3

Related Resources

• GET Bucket website (p. 1061)

• PUT Bucket website (p. 1218)

API Version 2006-03-01

927
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

GET Bucket (List Objects) Version 2

Description

This implementation of the GET operation 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.

To use this implementation of the operation, you must have READ access to the bucket.

To use this operation in an AWS Identity and Access Management (IAM) policy, you must have
permissions to perform the s3:ListBucket action. The bucket owner has this permission by default
and can grant this permission to others. For more information about permissions, see Permissions
Related to Bucket Operations and Managing Access Permissions to Your Amazon S3 Resources in the
Amazon Simple Storage Service Developer Guide.
Important
This section describes the latest revision of the API. We recommend that you use this
revised API, GET Bucket (List Objects) version 2, for application development. For backward
compatibility, Amazon S3 continues to support the prior version of this API, GET Bucket (List
Objects) version 1. For more information about the previous version, see GET Bucket (List
Objects) Version 1 (p. 940).
Note
To get a list of your buckets, see GET Service (p. 847).

Requests

Syntax

GET /?list-type=2 HTTP/1.1

Host: BucketName.s3.amazonaws.com

API Version 2006-03-01

928
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of GET uses the parameters in the following table.

Parameter Description Required

delimiter A delimiter is a character you use to group keys. No

If you specify a prefix, all of the keys that contain the same string between
the prefix and the ﬁrst occurrence of the delimiter after the preﬁx are
grouped under a single result element called CommonPrefixes. If you don't
specify the prefix parameter, the substring starts at the beginning of the
key. The keys that are grouped under the CommonPrefixes result element
are not returned elsewhere in the response.

Type: String

Default: None

encoding- Requests Amazon S3 to encode the response and speciﬁes the encoding No
type method to use.

An object key can contain any Unicode character. However, XML 1.0 parsers
cannot parse some characters, such as characters with an ASCII value from
0 to 10. For characters that are not supported in XML 1.0, you can add this
parameter to request that Amazon S3 encode the keys in the response.

Type: String

Default: None

Valid value: url

max-keys Sets the maximum number of keys returned in the response body. If you No
want to retrieve fewer than the default 1,000 keys, you can add this to your
request.

The response might contain fewer keys, but it never contains more. If there
are additional keys that satisfy the search criteria, but these keys were
not returned because max-keys was exceeded, the response contains
<IsTruncated>true</IsTruncated>. To return the additional keys, see
NextContinuationToken.

Type: String

Default: 1000

prefix Limits the response to keys that begin with the specified prefix. You can use No
prefixes to separate a bucket into different groupings of keys. (You can think

API Version 2006-03-01

API Version 2006-03-01

930
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

Name Description

Contents Metadata about each object returned.

Children: DisplayName, ID

Ancestor: ListBucketResult.Contents | CommonPreﬁxes

Prefix Keys that begin with the indicated preﬁx.

Type: String

Ancestor: ListBucketResult

Size Size in bytes of the object.

Type: String

Ancestor: ListBucketResult.Contents

API Version 2006-03-01

933
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

Name Description

StorageClass The storage class used to store the object.

Type: String

Ancestor: ListBucketResult.Contents

Valid values: STANDARD | REDUCED_REDUNDANCY | GLACIER

| STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING |
DEEP_ARCHIVE

ContinuationToken If ContinuationToken was sent with the request, it is included in the

response.

Type: String

Ancestor: ListBucketResult

KeyCount Returns the number of keys included in the response. The value is
always less than or equal to the MaxKeys value.

Type: String

Ancestor: ListBucketResult

NextContinuationToken If the response is truncated, Amazon S3 returns this parameter with a

continuation token. You can specify the token as the continuation-
token in your next request to retrieve the next set of keys.

Type: String

Ancestor: ListBucketResult

StartAfter If StartAfter was sent with the request, it is included in the response.

Type: String

Ancestor: ListBucketResult

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

API Version 2006-03-01

934
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

Example 1: Listing Keys

This request returns the objects in BucketName. The request speciﬁes the list-type parameter, which
indicates version 2 of the API.

Sample Request

GET /?list-type=2 HTTP/1.1

Host: bucket.s3.amazonaws.com
x-amz-date: 20160430T233541Z
Authorization: authorization string
Content-Type: text/plain

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

Example 2: Listing Keys Using the max-keys, preﬁx, and start-after Parameters

API Version 2006-03-01

935
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

Sample Request

GET /?list-type=2&max-keys=3&prefix=E&start-after=ExampleGuide.pdf HTTP/1.1

Host: quotes.s3.amazonaws.com
x-amz-date: 20160430T232933Z
Authorization: authorization string

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>quotes</Name>
<Prefix>E</Prefix>
<StartAfter>ExampleGuide.pdf</StartAfter>
<KeyCount>1</KeyCount>
<MaxKeys>3</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>ExampleObject.txt</Key>
<LastModified>2013-09-17T18:07:53.000Z</LastModified>
<ETag>"599bab3ed2c697f1d26842727561fd94"</ETag>
<Size>857</Size>
<StorageClass>REDUCED_REDUNDANCY</StorageClass>
</Contents>
</ListBucketResult>

Example 3: Listing Keys Using the preﬁx and delimiter Parameters

API Version 2006-03-01

936
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

This example illustrates the use of the prefix and the delimiter parameters in the request. For this
example, we assume that you have the following keys in your bucket:

sample.jpg

photos/2006/January/sample.jpg

photos/2006/February/sample2.jpg

photos/2006/February/sample3.jpg

photos/2006/February/sample4.jpg

The following GET request speciﬁes the delimiter parameter with value /.

GET /?list-type=2&delimiter=/ HTTP/1.1

Host: example-bucket.s3.amazonaws.com
x-amz-date: 20160430T235931Z
Authorization: authorization string

The key sample.jpg does not contain the delimiter character, and Amazon S3 returns it in the
Contents element in the response. However, all other keys contain the delimiter character. Amazon S3
groups these keys and returns a single CommonPrefixes element with the prefix value photos/. The
element is a substring that starts at the beginning of these keys and ends at the first occurrence of the
specified delimiter.

The following GET request speciﬁes the delimiter parameter with value /, and the prefix parameter
with value photos/2006/.

GET /?list-type=2&prefix=photos/2006/&delimiter=/ HTTP/1.1

Host: example-bucket.s3.amazonaws.com
x-amz-date: 20160501T000433Z
Authorization: authorization string

In response, Amazon S3 returns only the keys that start with the specified prefix. Further, it uses the
delimiter character to group keys that contain the same substring until the first occurrence of
the delimiter character after the specified prefix. For each such key group Amazon S3 returns one
CommonPrefixes element in the response. The keys grouped under this CommonPrefixes element
are not returned elsewhere in the response. The value returned in the CommonPrefixes element is
a substring that starts at the beginning of the key and ends at the first occurrence of the specified
delimiter after the prefix.

API Version 2006-03-01

937
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

<CommonPrefixes>
<Prefix>photos/2006/February/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/January/</Prefix>
</CommonPrefixes>
</ListBucketResult>

Example 4: Using a Continuation Token

GET /?list-type=2 HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Mon, 02 May 2016 23:17:07 GMT
Authorization: authorization string

The following is a sample response:

API Version 2006-03-01

938
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

<LastModified>2014-11-21T19:40:05.000Z</LastModified>
<ETag>"70ee1738b6b21e2c8a43f3a5ab0eee71"</ETag>
<Size>11</Size>
<StorageClass>STANDARD</StorageClass>
</Contents>
...
</ListBucketResult>

In the following subsequent request, we include a continuation-token query parameter in the

request with value of the <NextContinuationToken> from the preceding response.

GET /?list-type=2 HTTP/1.1

GET /?list-type=2&continuation-token=1ueGcxLPRx1Tr/XYExHnhbYLgveDs2J/wm36Hy4vbOwM= HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Mon, 02 May 2016 23:17:07 GMT
Authorization: authorization string

Amazon S3 returns a list of the next set of keys starting where the previous request ended.

More Info

• GET Object (p. 1248)

• PUT Object (p. 1324)
• PUT Bucket (p. 1095)

API Version 2006-03-01

939
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

GET Bucket (List Objects) Version 1

Description

Important
This API has been revised. We recommend that you use the newer version, GET Bucket (List
Objects) version 2, when developing applications. For more information, see GET Bucket (List
Objects) Version 2 (p. 928). For backward compatibility, Amazon S3 continues to support GET
Bucket (List Objects) version 1.

This implementation of the GET operation 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. Be sure to design your application to parse the
contents of the response and handle it appropriately.

To use this implementation of the operation, you must have READ access to the bucket.
Note
To get a list of your buckets, see GET Service (p. 847).

Requests

Syntax

GET / HTTP/1.1
Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

API Version 2006-03-01

940
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

Request Parameters

This implementation of GET uses the parameters in the following table to return a subset of the objects
in a bucket.

Parameter Description Required

delimiter A delimiter is a character you use to group keys. No

If you specify a prefix, all keys that contain the same string between the
prefix and the ﬁrst occurrence of the delimiter after the preﬁx are grouped
under a single result element called CommonPrefixes. If you don't specify
the prefix parameter, the substring starts at the beginning of the key. The
keys that are grouped under the CommonPrefixes result element are not
returned elsewhere in the response.

Type: String

Default: None

encoding- Requests Amazon S3 to encode the response and speciﬁes the encoding No
type method to use.

Type: String

Default: None

Valid value: url

marker Speciﬁes the key to start with when listing objects in a bucket. Amazon S3 No
returns object keys in UTF-8 binary order, starting with key after the marker
in order.

Type: String

Default: None

max-keys Sets the maximum number of keys returned in the response body. If you No
want to retrieve fewer than the default 1,000 keys, you can add this to your
request.

Type: String

API Version 2006-03-01

941
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

Parameter Description Required

Default: 1,000

prefix Limits the response to keys that begin with the specified prefix. You can use No
prefixes to separate a bucket into different groupings of keys. (You can think
of using prefix to make groups in the same way you would use a folder in a
file system.)

Type: String

Default: None

Request Elements

This implementation of the operation does not use request elements.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

API Version 2006-03-01

942
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

Name Description

Contents Metadata about each object returned.

Type: XML metadata

Ancestor: ListBucketResult

CommonPrefixes All of the keys rolled up in a common preﬁx count as a single return
when calculating the number of returns. See MaxKeys.

• A response can contain CommonPrefixes only if you specify a

delimiter.
• CommonPrefixes contains all (if there are any) keys between
Prefix and the next occurrence of the string speciﬁed by the
delimiter.
• CommonPrefixes lists keys that act like subdirectories in the
directory speciﬁed by Prefix.

For example, if the prefix is notes/ and the delimiter is a slash (/) as in
notes/summer/july, the common prefix is notes/summer/. All of
the keys that roll up into a common prefix count as a single return when
calculating the number of returns. See MaxKeys.

Type: String

Ancestor: ListBucketResult

Type: String

Ancestor: ListBucketResult

DisplayName Object owner's name.

Important
This value is only included in the response in the US East (N.
Virginia), US West (N. California), US West (Oregon), Asia Pacific
(Singapore), Asia Pacific (Sydney), Asia Pacific (Tokyo), Europe
(Ireland), and South America (São Paulo) regions.
For a list of all the Amazon S3 supported regions and
endpoints, see Regions and Endpoints in the AWS General
Reference.

Type: String

Prefix Keys that begin with the indicated preﬁx.

Type: String

Ancestor: ListBucketResult

Size Size in bytes of the object.

Type: String

Ancestor: ListBucketResult.Contents

StorageClass The storage class used to store the object.

Type: String

Ancestor: ListBucketResult.Contents

Valid values: STANDARD | REDUCED_REDUNDANCY | GLACIER

| STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING |
DEEP_ARCHIVE

Special Errors

API Version 2006-03-01

945
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

This request returns the objects in BucketName.

GET / HTTP/1.1
Host: BucketName.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

946
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
</Contents>
</ListBucketResult>

Sample Request Using Request Parameters

This example lists up to 40 keys in the quotes bucket that start with N and occur lexicographically after
Ned.

GET /?prefix=N&marker=Ned&max-keys=40 HTTP/1.1

Host: quotes.s3.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

947
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

<Size>4</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>bcaf1ffd86a5fb16fd081034f</ID>
<DisplayName>webfile</DisplayName>
</Owner>
</Contents>
</ListBucketResult>

Sample Request Using a Preﬁx and Delimiter

For this example, we assume that you have the following keys in your bucket:

sample.jpg

photos/2006/January/sample.jpg

photos/2006/February/sample2.jpg

photos/2006/February/sample3.jpg

photos/2006/February/sample4.jpg

The following GET request speciﬁes the delimiter parameter with value /.

GET /?delimiter=/ HTTP/1.1

Host: example-bucket.s3.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

The key sample.jpg does not contain the delimiter character, and Amazon S3 returns it in the
Contents element in the response. However, all other keys contain the delimiter character. Amazon S3
groups these keys and returns a single CommonPrefixes element with prefix value photos/ that is a
substring from the beginning of these keys to the first occurrence of the specified delimiter.

API Version 2006-03-01

948
Amazon Simple Storage Service API Reference
GET Bucket (List Objects) Version 2

</CommonPrefixes>
</ListBucketResult>

The following GET request speciﬁes the delimiter parameter with the value /, and the prefix
parameter with the value photos/2006/.

GET /?prefix=photos/2006/&delimiter=/ HTTP/1.1

Host: example-bucket.s3.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

In response, Amazon S3 returns only the keys that start with the specified prefix. It uses the
delimiter character to group keys that contain the same substring until the first occurrence of the
delimiter character after the specified prefix. For each such key group, Amazon S3 returns one
<CommonPrefixes> element in the response. The keys grouped under this CommonPrefixes element
are not returned elsewhere in the response. The value returned in the CommonPrefixes element is
a substring that starts at the beginning of the key and ends at the first occurrence of the specified
delimiter after the prefix.

<CommonPrefixes>
<Prefix>photos/2006/February/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/January/</Prefix>
</CommonPrefixes>
</ListBucketResult>

Related Resources

• GET Object (p. 1248)

• PUT Object (p. 1324)
• PUT Bucket (p. 1095)

API Version 2006-03-01

949
Amazon Simple Storage Service API Reference
GET Bucket accelerate

GET Bucket accelerate

Description

To use this operation, you must have permission to perform the s3:GetAccelerateConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple
Storage Service Developer Guide.

You set the Transfer Acceleration state of an existing bucket to Enabled or Suspended by using the PUT
Bucket accelerate (p. 1104) operation.

A GET accelerate request does not return a state value for a bucket that has no transfer acceleration
state. A bucket has no Transfer Acceleration state, if a state has never been set on the bucket.

This implementation of the GET operation returns the following responses:

• If the transfer acceleration state is set to Enabled on a bucket, the response is:

<AccelerateConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
</AccelerateConfiguration>

• If the transfer acceleration state is set to Suspended on a bucket, the response is:

<AccelerateConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Suspended</Status>
</AccelerateConfiguration>

• If the transfer acceleration state on a bucket has never been set to Enabled or Suspended, the
response is:

For more information on transfer acceleration, see Transfer Acceleration in the Amazon Simple Storage
Service Developer Guide.

API Version 2006-03-01

950
Amazon Simple Storage Service API Reference
GET Bucket accelerate

Requests

Syntax

GET /?accelerate HTTP/1.1

Host: bucketname.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

API Version 2006-03-01

951
Amazon Simple Storage Service API Reference
GET Bucket accelerate

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of GET returns the following response elements.

Name Description

AccelerateConfiguration Container for the Status response element.

Type: Container

Ancestor: None

Status The transfer acceleration state of the bucket.

Type: Enum

Valid Values: Suspended | Enabled

Ancestor: AccelerateConﬁguration

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

API Version 2006-03-01

952
Amazon Simple Storage Service API Reference
GET Bucket accelerate

Examples

Example 1: Retrieve the transfer acceleration conﬁguration for a bucket

The following example shows a GET /?accelerate request to retrieve the transfer acceleration state
of the bucket named examplebucket.

GET /?accelerate HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Mon, 11 Apr 2016 12:00:00 GMT
Authorization: authorization string
Content-Type: text/plain

The following is a sample of the response body (only) that shows bucket transfer acceleration is enabled.

<AccelerateConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
</AccelerateConfiguration>

Related Resources

• PUT Bucket accelerate (p. 1104)

API Version 2006-03-01

953
Amazon Simple Storage Service API Reference
GET Bucket acl

GET Bucket acl

Description

Requests

Syntax

GET /?acl HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

API Version 2006-03-01

954
Amazon Simple Storage Service API Reference
GET Bucket acl

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

Name Description

AccessControlList Container for ACL information.

Type: Container

Ancestry: AccessControlPolicy

AccessControlPolicy Container for the response.

Type: Container

API Version 2006-03-01

955
Amazon Simple Storage Service API Reference
GET Bucket acl

Name Description
Ancestry: None

DisplayName Bucket owner's display name. This is returned only if the owner's e-mail
address (or the forum name, if configured) can be determined from the
ID.
Important
This value is only included in the response in the US East
(N. Virginia), US West (N. California), US West (Oregon), Asia
Pacific (Singapore), Asia Pacific (Sydney), Asia Pacific (Tokyo),
Europe (Ireland), and South America (São Paulo) regions.
For a list of all the Amazon S3 supported regions and
endpoints, see Regions and Endpoints in the AWS General
Reference.

Type: String

Ancestry: AccessControlPolicy.Owner

Grant Container for Grantee and Permission.

Type: Container

Ancestry: AccessControlPolicy.AccessControlList

Grantee Container for DisplayName and ID of the person being granted

permissions.

Type: Container

Ancestry: AccessControlPolicy.AccessControlList.Grant

ID Bucket owner's ID.

Type: String

Ancestry: AccessControlPolicy.Owner

Owner Container for bucket owner information.

Type: Container

Ancestry: AccessControlPolicy

Permission Permission given to the Grantee for bucket.

Type: String

Valid Values: FULL_CONTROL | WRITE | WRITE_ACP | READ | READ_ACP

Ancestry: AccessControlPolicy.AccessControlList.Grant

Special Errors

API Version 2006-03-01

956
Amazon Simple Storage Service API Reference
GET Bucket acl

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

The following request returns the ACL of the speciﬁed bucket.

GET ?acl HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response

<AccessControlPolicy>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser">
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>

API Version 2006-03-01

957
Amazon Simple Storage Service API Reference
GET Bucket acl

</AccessControlPolicy>

Related Resources

• GET Bucket Objects (p. 940)

API Version 2006-03-01

958
Amazon Simple Storage Service API Reference
GET Bucket analytics

GET Bucket analytics

Description

This implementation of the GET operation returns an analytics configuration (identified by the analytics
configuration ID) from the bucket.

For information about Amazon S3 analytics feature, see Amazon S3 Analytics – Storage Class Analysis in
the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

GET /?analytics&id=analytics-configuration-ID HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

API Version 2006-03-01

959
Amazon Simple Storage Service API Reference
GET Bucket analytics

This implementation of GET uses the parameter in the following table.

Parameter Description Required

id The ID that identiﬁes the analytics conﬁguration. Limited to Yes

64 characters.

Type: String

Default: None

Valid Characters for id: a-z A-Z 0-9 - _ .

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

API Version 2006-03-01

960
Amazon Simple Storage Service API Reference
GET Bucket analytics

Response Elements

The Examples section shows an example of an analytics conﬁguration XML. The following table describes
the XML elements in the analytics conﬁguration returned by the GET request.

Name Description

AnalyticsConfiguration Contains the conﬁguration and any analyses for the analytics ﬁlter.

Type: Container

Children: Id, Filter, StorageClassAnalysis

Ancestor: None

And A conjunction (logical AND) of predicates, which is used in evaluating an

analytics ﬁlter. The operator must have at least two predicates.

Type: String

Children: Prefix, Tag

Ancestor: Filter

Bucket The Amazon Resource Name (ARN) of the bucket where analytics results
are published.

Type: String

Ancestor: S3BucketDestination

BucketAccountId The ID of the account that owns the destination bucket where the
analytics results are published.

Type: String

Ancestor: S3BucketDestination

DataExport A container used to describe how data related to the storage class
analysis should be exported.

Type: Container

Children: OutputSchemaVersion, Destination

Ancestor: StorageClassAnalysis

Destination Contains information about where to publish the analytics results.

Type: Container

Children: S3BucketDestination

Ancestor: DataExport

API Version 2006-03-01

961
Amazon Simple Storage Service API Reference
GET Bucket analytics

Name Description

Filter Specifies an analytics filter. The analytics only includes objects that meet
the filter's criteria.

Type: Container

Children: And

Ancestor: AnalyticsConfiguration

Format Speciﬁes the output format of the analytics results. Currently, Amazon
S3 supports the comma-separated value (CSV) format.

Type: String

Ancestor: S3BucketDestination

Valid values: CSV

Id The ID that identiﬁes the analytics conﬁguration.

Type: String

Ancestor: AnalyticsConfiguration

Key The key for a tag.

Type: String

Ancestor: Tag

OutputSchemaVersion The version of the output schema to use when exporting data. Must be
V_1.

Type: String

Ancestor: DataExport

Valid values: V_1

Prefix The preﬁx that an object must have to be included in the analytics
results.

Type: String

Ancestor: And

Prefix The preﬁx that is prepended to all analytics results.

Type: String

Ancestor: S3BucketDestination

API Version 2006-03-01

962
Amazon Simple Storage Service API Reference
GET Bucket analytics

Name Description

StorageClassAnalysis If present, it indicates that data related to access patterns is collected

and made available to analyze the tradeoﬀs between diﬀerent storage
classes.

Type: Container

Children: DataExport

Ancestor: AnalyticsConfiguration

S3BucketDestination Contains the bucket ARN, ﬁle format, bucket owner (optional), and preﬁx
(optional) where analytics results are published.

Type: Container

Children: Format, BucketAccountId, Bucket, Prefix

Ancestor: Destination.

Tag The tag to use when evaluating an analytics ﬁlter.

Type: Container

Children: Key, Value

Ancestor: And

Value The value for a tag.

Type: String

Ancestor: Tag

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

API Version 2006-03-01

963
Amazon Simple Storage Service API Reference
GET Bucket analytics

Example: Conﬁgure an Analytics Report

The following GET request for the bucket examplebucket returns the inventory conﬁguration with the
ID list1.

GET /?analytics&id=list1 HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Mon, 31 Oct 2016 12:00:00 GMT
Authorization: authorization string

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A02
Date: Mon, 31 Oct 2016 12:00:00 GMT
Server: AmazonS3
Content-Length: length

<?xml version="1.0" encoding="UTF-8"?>

Related Resources

• DELETE Bucket analytics (p. 894)

API Version 2006-03-01

964
Amazon Simple Storage Service API Reference
GET Bucket analytics

• List Bucket Analytics Conﬁgurations (p. 1067)

• PUT Bucket analytics (p. 1117)

API Version 2006-03-01

965
Amazon Simple Storage Service API Reference
GET Bucket cors

GET Bucket cors

Description

Returns the cors conﬁguration information set for the bucket.

To use this operation, you must have permission to perform the s3:GetBucketCORS action. By default,
the bucket owner has this permission and can grant it to others.

To learn more cors, go to Enabling Cross-Origin Resource Sharing in the Amazon Simple Storage Service
Developer Guide.

Requests

Syntax

GET /?cors HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

API Version 2006-03-01

966
Amazon Simple Storage Service API Reference
GET Bucket cors

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of GET returns the following response elements.

Name Description

CORSConfiguration Container for up to 100 CORSRules elements.

Type: Container

Children: CORSRules

API Version 2006-03-01

967
Amazon Simple Storage Service API Reference
GET Bucket cors

Name Description
Ancestor: None

CORSRule A set of origins and methods (cross-origin access that you want to
allow). You can add up to 100 rules to the conﬁguration.

Type: Container

Children: AllowedOrigin, AllowedMethod, MaxAgeSeconds,

ExposeHeader, ID.

Ancestor: CORSConfiguration

AllowedHeader Speciﬁes which headers are allowed in a pre-ﬂight OPTIONS request

through the Access-Control-Request-Headers header. Each
header name speciﬁed in the Access-Control-Request-Headers
must have a corresponding entry in the rule. Only the headers that
were requested will be sent back. This element can contain at most
one * wildcard character.

A CORSRule can have at most one MaxAgeSeconds element.

Type: Integer (seconds)

Ancestor: CORSRule

AllowedMethod Identiﬁes an HTTP method that the domain/origin speciﬁed in the

rule is allowed to execute.

Each CORSRule must contain at least one AllowedMethod and one

AllowedOrigin element.

Type: Enum (GET, PUT, HEAD, POST, DELETE)

Ancestor: CORSRule

AllowedOrigin One or more response headers that you want customers to be able
to access from their applications (for example, from a JavaScript
XMLHttpRequest object).

Each CORSRule must have at least one AllowedOrigin element.

The string value can include at most one '*' wildcard character, for
example, http://*.example.com". You can also specify only "*" to
allow cross-origin access for all domains/origins.

Type: String

Ancestor: CORSRule

ExposeHeader One or more headers in the response that you want customers to be
able to access from their applications (for example, from a JavaScript
XMLHttpRequest object).

You add one ExposeHeader in the rule for each header.

Type: String

Ancestor: CORSRule

API Version 2006-03-01

968
Amazon Simple Storage Service API Reference
GET Bucket cors

Name Description

ID An optional unique identiﬁer for the rule. The ID value can be

up to 255 characters long. The IDs help you ﬁnd a rule in the
conﬁguration.

Type: String

Ancestor: CORSRule

MaxAgeSeconds The time in seconds that your browser is to cache the preﬂight
response for the speciﬁed resource.

A CORSRule can have at most one MaxAgeSeconds element.

Type: Integer (seconds)

Ancestor: CORSRule

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Example 1: Retrieve cors subresource

The following example gets the cors subresource of a bucket.

Sample Request

GET /?cors HTTP/1.1

API Version 2006-03-01

969
Amazon Simple Storage Service API Reference
GET Bucket cors

Host: examplebucket.s3.amazonaws.com
Date: Tue, 13 Dec 2011 19:14:42 GMT
Authorization: signatureValue

Sample Response

<CORSConfiguration>
<CORSRule>
<AllowedOrigin>http://www.example.com</AllowedOrigin>
<AllowedMethod>GET</AllowedMethod>
<MaxAgeSeconds>3000</MaxAgeSec>
<ExposeHeader>x-amz-server-side-encryption</ExposeHeader>
</CORSRule>
</CORSConfiguration>

Related Resources

• PUT Bucket cors (p. 1124)

• DELETE Bucket cors (p. 897)
• OPTIONS object (p. 1291)

API Version 2006-03-01

970
Amazon Simple Storage Service API Reference
GET Bucket encryption

GET Bucket encryption

Description

This implementation of the GET operation uses the encryption subresource to return the default
encryption conﬁguration for an Amazon S3 bucket. For information about the Amazon S3 default
encryption feature, see Amazon S3 Default Bucket Encryption in the Amazon Simple Storage Service
Developer Guide.

Requests

Syntax

GET /?encryption HTTP/1.1

Host: bucketname.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

API Version 2006-03-01

971
Amazon Simple Storage Service API Reference
GET Bucket encryption

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of GET returns the following response elements.

Name Description

ApplyServerSideEncryptionByDefault Container for

setting server-

API Version 2006-03-01

972
Amazon Simple Storage Service API Reference
GET Bucket encryption

Name Description
side encryption by
default.

Type: Container

Children:
SSEAlgorithm,
KMSMasterKeyID

Ancestor: Rule

KMSMasterKeyID The AWS KMS

master key ID used
for the SSE-KMS
encryption.

Type: String

Ancestor:
ApplyServerSideEncryptionByDefault

Constraint: Can
only be used when
you set the value
of SSEAlgorithm
as aws:kms. The
default aws/s3 AWS
KMS master key is
used if this element
is absent while the
SSEAlgorithm is
aws:kms.

Rule Container for server-

side encryption
by default
conﬁguration.

Type: Container

Children:
ApplyServerSideEncryptionByDefault

Ancestor:
ServerSideEncryptionConfiguration

ServerSideEncryptionConfiguration Container for

the server-side
encryption by
default conﬁguration
rule.

Type: Container

Children: Rule

Ancestor: None

API Version 2006-03-01

973
Amazon Simple Storage Service API Reference
GET Bucket encryption

Name Description

SSEAlgorithm The server-side

encryption algorithm
to use.

Type: String

Valid Values:
AES256, aws:kms

Ancestor:
ApplyServerSideEncryptionByDefault

Constraint: Can
only be used
when you use
ApplyServerSideEncryptionByDefault.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Example 1: Retrieve the Encryption Conﬁguration for an S3 Bucket

The following example shows a GET /?encryption request.

GET /?encryption HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Wed, 06 Sep 2017 12:00:00 GMT
Authorization: authorization string
Content-Length: length

The following is a sample of the response.

API Version 2006-03-01

974
Amazon Simple Storage Service API Reference
GET Bucket encryption

HTTP/1.1 200 OK
x-amz-id-2: kDmqsuw5FDmgLmxQaUkd9A4NJ/PIiE0c1rAU/ue2Yp60toXs4I5k5fqlwZsA6fV+wJQCzRRwygQ=
x-amz-request-id: 5D8706FCB2673B7D
Date: Wed, 06 Sep 2017 12:00:00 GMT
Transfer-Encoding: chunked
Server: AmazonS3

<ServerSideEncryptionConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<ApplyServerSideEncryptionByDefault>
<SSEAlgorithm>aws:kms</SSEAlgorithm>
<KMSMasterKeyID>arn:aws:kms:us-east-1:1234/5678example</KMSMasterKeyID>
</ApplyServerSideEncryptionByDefault>
</Rule>
</ServerSideEncryptionConfiguration>

Related Resources

• PUT Bucket encryption (p. 1131)

• DELETE Bucket encryption (p. 900)

API Version 2006-03-01

975
Amazon Simple Storage Service API Reference
GET Bucket Inventory

GET Bucket Inventory

Description

This implementation of the GET operation returns an inventory configuration (identified by the inventory
configuration ID) from the bucket.

For information about the Amazon S3 inventory feature, see Amazon S3 Inventory in the Amazon Simple
Storage Service Developer Guide.

Requests

Syntax

GET /?inventory&id=inventory-configuration-ID HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

API Version 2006-03-01

976
Amazon Simple Storage Service API Reference
GET Bucket Inventory

This implementation of GET uses the parameter in the following table.

Parameter Description Required

id The ID that identiﬁes the inventory conﬁguration. Yes

Type: String

Default: None

Valid Characters for id: a-z A-Z 0-9 - _ .

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

API Version 2006-03-01

977
Amazon Simple Storage Service API Reference
GET Bucket Inventory

Response Elements

The Examples section shows an example of an inventory conﬁguration XML. The following table
describes the XML elements in the inventory conﬁguration returned by the GET request.

Name Description

AccountId The ID of the account that owns the destination bucket where the
inventory is published.

Although optional, we recommend that the value be set to prevent

problems if the destination bucket ownership changes.

Type: String

Ancestor: S3BucketDestination

Bucket The Amazon Resource Name (ARN) of the bucket where inventory results
are published.

Type: String

Ancestor: S3BucketDestination

Destination Contains information about where to publish the inventory results.

Type: Container

Children: S3BucketDestination

Ancestor: InventoryConfiguration

Encryption Contains the type of server-side encryption used to encrypt the

inventory results.

Type: Container

Children: SSE-KMS, SSE-S3

Ancestor: S3BucketDestination

Field Contains the optional ﬁelds that are included in the inventory results.
Multiple Field elements can be contained in OptionalFields.

Type: String

Ancestor: OptionalFields

Valid values: Size, LastModifiedDate, StorageClass, ETag,

IsMultipartUploaded, ReplicationStatus, EncryptionStatus,
ObjectLockRetainUntilDate, ObjectLockMode,
ObjectLockLegalHoldStatus

API Version 2006-03-01

978
Amazon Simple Storage Service API Reference
GET Bucket Inventory

Name Description

Filter Specifies an inventory filter. The inventory only includes objects that
meet the filter's criteria.

Type: Container

Children: Prefix

Ancestor: InventoryConfiguration

Format Speciﬁes the output format of the inventory results. Currently, Amazon
S3 supports the comma-separated values (CSV) format, the Apache
optimized row columnar (ORC) format, and the Apache Parquet
(Parquet) format.

Type: String

Ancestor: S3BucketDestination

Valid values: CSV, ORC, or Parquet

Frequency Speciﬁes how frequently inventory results are produced.

Type: String

Ancestor: Schedule

Valid values: Daily, or Weekly

Id The ID that identiﬁes the inventory conﬁguration.

Type: String

Ancestor: InventoryConfiguration

IncludedObjectVersions Object versions to include in the inventory list. If set to All, the list
includes all the object versions, which adds the version-related ﬁelds
VersionId, IsLatest, and DeleteMarker to the list. If set to
Current, the list does not contain these version-related ﬁelds.

Type: String

Ancestor: InventoryConfiguration

Valid values: Current or All

InventoryConfiguration Contains the inventory conﬁguration.

Type: Container

Children: Id, IsEnabled, Filter, Destination, Schedule,

IncludedObjectVersions, and OptionalFields elements.

Ancestor: None

API Version 2006-03-01

979
Amazon Simple Storage Service API Reference
GET Bucket Inventory

Name Description

IsEnabled Speciﬁes whether the inventory is enabled or disabled. If set to True, an

inventory list is generated. If set to False, no inventory list is generated.

Type: String

Ancestor: InventoryConfiguration

Valid values: True or False

KeyId The AWS KMS customer master key (CMK) used to encrypt the inventory
ﬁle.

Type: String

Ancestor: SSE-KMS

Valid values: ARN of the CMK

OptionalFields Contains the optional ﬁelds.

Type: Container

Children: Field

Ancestor: InventoryConfiguration

Prefix The preﬁx that an object must have to be included in the inventory
results.

Type: String

Ancestor:Filter

Prefix The preﬁx that is prepended to all inventory results.

Type: String

Ancestor: S3BucketDestination

Schedule Contains the frequency of inventory results generation.

Type: Container

Children: Frequency

Ancestor: Destination.

SSE-KMS Speciﬁes to use server-side encryption with AWS KMS-managed keys

(SSE-KMS) and contains the key that is used to encrypt the inventory ﬁle.

Type: Container

Children: KeyId

Ancestor: Encryption

API Version 2006-03-01

980
Amazon Simple Storage Service API Reference
GET Bucket Inventory

Name Description

SSE-S3 Speciﬁes to use server-side encryption with Amazon S3-managed keys

(SSE-S3) to encrypt the inventory ﬁle.

Type: Container

Ancestor: Encryption

Valid values: empty

S3BucketDestination Contains the bucket ARN, file format, bucket owner (optional), prefix
where inventory results are published (optional), and the type of server-
side encryption that is used to encrypt the file (optional).

Type: Container

Children: Format, AccountId, Bucket, Prefix, Encryption

Ancestor: Destination.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Example: Conﬁgure an Inventory Report

The following GET request for the bucket examplebucket returns the inventory conﬁguration with the
ID list1.

GET /?inventory&id=list1 HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Mon, 31 Oct 2016 12:00:00 GMT
Authorization: authorization string

The following is a sample response.

API Version 2006-03-01

981
Amazon Simple Storage Service API Reference
GET Bucket Inventory

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A02
Date: Mon, 31 Oct 2016 12:00:00 GMT
Server: AmazonS3
Content-Length: length

<?xml version="1.0" encoding="UTF-8"?>

Related Resources

• DELETE Bucket inventory (p. 903)

• List Bucket Inventory Conﬁgurations (p. 1073)
• PUT Bucket inventory (p. 1136)

API Version 2006-03-01

982
Amazon Simple Storage Service API Reference
GET Bucket lifecycle

GET Bucket lifecycle

Description

Note
Bucket lifecycle configuration now supports specifying a lifecycle rule using an object key name
prefix, one or more object tags, or a combination of both. Accordingly, this section describes
the latest API. The response describes the new filter element that you can use to specify a filter
to select a subset of objects to which the rule applies. If you are still using previous version
of the lifecycle configuration, it works. For related API description, see GET Bucket lifecycle
(Deprecated) (p. 1526).

To use this operation, you must have permission to perform the s3:GetLifecycleConfiguration
action. The bucket owner has this permission, by default. The bucket owner can grant this permission to
others. For more information about permissions, see Managing Access Permissions to Your Amazon S3
Resources in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

GET /?lifecycle HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

API Version 2006-03-01

983
Amazon Simple Storage Service API Reference
GET Bucket lifecycle

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of GET returns the following response elements.

API Version 2006-03-01

984
Amazon Simple Storage Service API Reference
GET Bucket lifecycle

Name Description

And Container for specifying Prefix and Tag based ﬁlters.

Child: Prefix and Tag

Type: Container

Ancestor: Filter

AbortIncompleteMultipartUpload Container for specifying when an incomplete multipart

upload becomes eligible for an abort operation.

Child: DaysAfterInitiation

Type: Container

Ancestor: Rule

Date Date when you want Amazon S3 to take the action. For
more information, see Lifecycle Rules: Based on a Speciﬁc
Date in the Amazon Simple Storage Service Developer
Guide.

Type: String

Ancestor: Expiration or Transition

Days Speciﬁes the number of days after object creation when

the speciﬁc rule action takes eﬀect. The object's eligibility
time is calculated as creation time + the number of days,
and rounding the resulting time to the next day midnight
UTC.

Type: Non-negative Integer when used with Transition,

Positive Integer when used with Expiration

Ancestor: Transition or Expiration

DaysAfterInitiation Speciﬁes the number of days after initiating a multipart

upload when the multipart upload must be completed. If
it does not complete by the speciﬁed number of days, it
becomes eligible for an abort operation and Amazon S3
aborts the incomplete multipart upload.

Type: Positive Integer

Ancestor: AbortIncompleteMultipartUpload

Expiration This action speciﬁes a period in the object's lifetime when

Amazon S3 should take the appropriate expiration action.
The expiration action occurs only on objects that are
eligible according to the period speciﬁed in the child Date
or Days element. The action Amazon S3 takes depends on
whether the bucket is versioning enabled.

• If versioning has never been enabled on the bucket,

Amazon S3 deletes the only copy of the object
permanently.

API Version 2006-03-01

985
Amazon Simple Storage Service API Reference
GET Bucket lifecycle

Key Tag key.

Type: String

Ancestor: Tag

API Version 2006-03-01

986
Amazon Simple Storage Service API Reference
GET Bucket lifecycle

Name Description

LifecycleConfiguration Container for lifecycle rules. You can add as many as 1000
rules.

Type: Container

Children: Rule

Ancestor: None

ExpiredObjectDeleteMarker On a versioned bucket (a versioning-enabled or

versioning-suspended bucket), this element indicates
whether Amazon S3 will delete any expired object delete
markers in the bucket. For an example, go to Example
8: Specify Expiration Action to Remove Expired Object
Delete Markers in the Amazon Simple Storage Service
Developer Guide.

Type: String

Valid values: true | false (the value false is allowed, but

it is no-op, which means that Amazon S3 does not take
action if the value is false)

Ancestor: Expiration

NoncurrentDays Speciﬁes the number of days that an object is noncurrent

before Amazon S3 can perform the associated action.
For information about calculating noncurrent days, see
Lifecycle Rules Based on the Number of Days in the
Amazon Simple Storage Service Developer Guide.

Type: Nonnegative Integer when used with

NoncurrentVersionTransition, Positive Integer when
used with NoncurrentVersionExpiration

Ancestor: NoncurrentVersionExpiration or
NoncurrentVersionTransition

NoncurrentVersionExpiration Speciﬁes when noncurrent object versions expire.

Upon expiration, Amazon S3 permanently deletes the
noncurrent object versions.

Set this lifecycle conﬁguration action on a bucket that has

versioning enabled (or suspended) to request that Amazon
S3 delete noncurrent object versions at a speciﬁc period in
the object's lifetime.

Type: Container

Children: NoncurrentDays

Ancestor: Rule

API Version 2006-03-01

987
Amazon Simple Storage Service API Reference
GET Bucket lifecycle

Name Description

NoncurrentVersionTransition Container for the transition rule that describes when

noncurrent objects transition to the STANDARD_IA,
ONEZONE_IA, INTELLIGENT_TIERING, GLACIER, or
DEEP_ARCHIVE storage class.

If your bucket is versioning-enabled (or versioning is

suspended), you can set this action to request that
Amazon S3 transition noncurrent object versions at a
speciﬁc period in the object's lifetime.

Type: Container

Children: NoncurrentDays and StorageClass

Ancestor: Rule

Prefix Object key preﬁx identifying one or more objects to which

the rule applies.

Type: String

Ancestor: Filter or And (if you specify Preﬁx and Tag

child elements in the Filter)

Rule Container for a lifecycle rule.

Type: Container

Ancestor: LifecycleConﬁguration

Status If enabled, Amazon S3 executes the rule as scheduled. If it

is disabled, Amazon S3 ignores the rule.

Type: String

Ancestor: Rule

Valid values: Enabled or Disabled

StorageClass Speciﬁes the Amazon S3 storage class to which you want

to transition the object.

Type: String

Ancestor: Transition and NoncurrentVersionTransition

Valid values: GLACIER | STANDARD_IA | ONEZONE_IA |

INTELLIGENT_TIERING | DEEP_ARCHIVE

Tag Container listing the tag key and value used to ﬁlter
objects to which the rule applies.

Type: String

Ancestor: Filter

API Version 2006-03-01

988
Amazon Simple Storage Service API Reference
GET Bucket lifecycle

Name Description

Transition This action speciﬁes a period in the objects' lifetime when

Amazon S3 should transition them to the STANDARD_IA,
ONEZONE_IA, INTELLIGENT_TIERING, GLACIER,
DEEP_ARCHIVE storage class. When this action is in
eﬀect, what Amazon S3 does depends on whether the
bucket is versioning-enabled.

• If versioning has never been enabled on the bucket,

Amazon S3 transitions the only copy of the object to
the specified storage class.
• If your bucket is versioning-enabled (or versioning is
suspended), Amazon S3 transitions only the current
versions of objects identified in the rule.
Note
A versioning-enabled or versioning-suspended
bucket can contain many versions of
an object. This action has no effect on
noncurrent object versions. To transition
noncurrent objects, you must use the
NoncurrentVersionTransition action.

Type: Container

Children: Days or Date, and StorageClass

Ancestor: Rule

Value Tag key value.

Type: String

Ancestor: Tag

Special Errors

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

The lifecycle conﬁguration does not

NoSuchLifecycleConfiguration 404 Not Client
exist. Found

For general information about Amazon S3 errors and a list of error codes, see Error Responses (p. 783).

API Version 2006-03-01

989
Amazon Simple Storage Service API Reference
GET Bucket lifecycle

Examples

Example 1: Retrieve the Lifecycle Subresource

This example is a GET request to retrieve the lifecycle subresource from the speciﬁed bucket. The
example response returns the lifecycle conﬁguration.

Sample Request

GET /?lifecycle HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Thu, 15 Nov 2012 00:17:21 GMT
Authorization: signatureValue

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<ID>Archive and then delete rule</ID>
<Filter>
<Prefix>projectdocs/</Prefix>
</Filter>
<Status>Enabled</Status>
<Transition>
<Days>30</Days>
<StorageClass>STANDARD_IA</StorageClass>

API Version 2006-03-01

990
Amazon Simple Storage Service API Reference
GET Bucket lifecycle

</Transition>
<Transition>
<Days>365</Days>
<StorageClass>GLACIER</StorageClass>
</Transition>
<Expiration>
<Days>3650</Days>
</Expiration>
</Rule>
</LifecycleConfiguration>

Related Resources

• PUT Bucket lifecycle (p. 1145)

• DELETE Bucket lifecycle (p. 906)

API Version 2006-03-01

991
Amazon Simple Storage Service API Reference
GET Bucket location

GET Bucket location

Description

This implementation of the GET operation uses the location subresource to return a bucket's region.
You set the bucket's region using the LocationConstraint request parameter in a PUT Bucket
request. For more information, see PUT Bucket (p. 1095).

Requests

Syntax

GET /?location HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

API Version 2006-03-01

992
Amazon Simple Storage Service API Reference
GET Bucket location

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

Name Description

LocationConstraint Speciﬁes the region where the bucket resides.

Type: String

Valid Values: For a list of all the Amazon S3 supported location constraints
by region, see Regions and Endpoints in the AWS General Reference.

Ancestry: None

API Version 2006-03-01

993
Amazon Simple Storage Service API Reference
GET Bucket location

When the bucket's region is US East (N. Virginia), Amazon S3 returns an empty string for the bucket's
region:

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

The following request returns the region of the speciﬁed bucket.

GET /?location HTTP/1.1

Host: myBucket.s3.amazonaws.com
Date: Tue, 09 Oct 2007 20:26:04 +0000
Authorization: signatureValue

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

994
Amazon Simple Storage Service API Reference
GET PublicAccessBlock

Related Resources

• GET Bucket Objects (p. 940)

• PUT Bucket (p. 1095)

GET PublicAccessBlock
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

Description

This operation retrieves the PublicAccessBlock configuration for an Amazon S3 bucket. In order
to use this operation, you must have the s3:GetBucketPublicAccessBlock permission. For more
information about Amazon S3 permissions, see Specifying Permissions in a Policy in the Amazon Simple
Storage Service Developer Guide.
Important
When Amazon S3 evaluates the PublicAccessBlock configuration for a bucket or an object, it
checks the PublicAccessBlock configuration for both the bucket (or the bucket that contains
the object) and the bucket owner's account. If the PublicAccessBlock settings are different
between the bucket and the account, Amazon S3 uses the most restrictive combination of the
bucket-level and account-level settings.

For more information about when Amazon S3 considers a bucket or an object public, see The Meaning of
"Public" in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

API Version 2006-03-01

995
Amazon Simple Storage Service API Reference
GET PublicAccessBlock

GET /<bucket-name>?publicAccessBlock HTTP/1.1

Host: <bucket-name>.s3.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization string> (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

API Version 2006-03-01

996
Amazon Simple Storage Service API Reference
GET PublicAccessBlock

Response Elements

Name Description

A PublicAccessBlock conﬁguration.
PublicAccessBlockConfiguration

Type: Container

Children: BlockPublicAcls, IgnorePublicAcls, BlockPublicPolicy,

RestrictPublicBuckets

Ancestor: None

BlockPublicAcls Speciﬁes whether Amazon S3 will block public access control lists (ACLs) for this
bucket and objects in this bucket.

Type: Boolean

Ancestor: PublicAccessBlockConfiguration

Valid values: TRUE | FALSE

IgnorePublicAcls Speciﬁes whether Amazon S3 will ignore public ACLs for this bucket and objects
in this bucket.

Type: Boolean

Ancestor: PublicAccessBlockConfiguration

Valid values: TRUE | FALSE

BlockPublicPolicy Speciﬁes whether Amazon S3 will block public bucket policies for this bucket.

Type: Boolean

Ancestor: PublicAccessBlockConfiguration

Valid values: TRUE | FALSE

Speciﬁes whether Amazon S3 will restrict public bucket policies for this bucket.
RestrictPublicBuckets

Type: Boolean

Ancestor: PublicAccessBlockConfiguration

Valid values: TRUE | FALSE

Special Errors

API Version 2006-03-01

997
Amazon Simple Storage Service API Reference
GET PublicAccessBlock

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

The following request gets a bucket PublicAccessBlock conﬁguration.

GET /<bucket-name>?publicAccessBlock HTTP/1.1

Host: <bucket-name>.s3.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <signatureValue>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0

Related Resources

• Using Amazon S3 Block Public Access in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

998
Amazon Simple Storage Service API Reference
GET PublicAccessBlock

• PUT PublicAccessBlock (p. 1157)

• DELETE PublicAccessBlock (p. 908)
• GET BucketPolicyStatus (p. 1016)
• GET PublicAccessBlock (p. 854)
• PUT PublicAccessBlock (p. 858)
• DELETE PublicAccessBlock (p. 851)

API Version 2006-03-01

999
Amazon Simple Storage Service API Reference
GET Bucket logging

GET Bucket logging

Note
Logging functionality is currently in beta.

Description

This implementation of the GET operation uses the logging subresource to return the logging status
of a bucket and the permissions users have to view and modify that status. To use GET, you must be the
bucket owner.

Requests

Syntax

GET /?logging HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string

Request Parameters

This implementation of the operation does not use request parameters.

API Version 2006-03-01

1000
Amazon Simple Storage Service API Reference
GET Bucket logging

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

Name Description

BucketLoggingStatus Container for the response.

Type: Container

Ancestry: None

EmailAddress E-mail address of the person whose logging permissions are displayed.

Type: String

API Version 2006-03-01

1001
Amazon Simple Storage Service API Reference
GET Bucket logging

Name Description
Ancestry:
BucketLoggingStatus.LoggingEnabled.TargetGrants.Grant.Grantee

Grant Container for Grantee and Permission.

Type: Container

Ancestry: BucketLoggingStatus.LoggingEnabled.TargetGrants

Grantee Container for EmailAddress of the person whose logging permissions

are displayed.

Type: Container

Examples

Sample Request

The following request returns the logging status for mybucket.

GET ?logging HTTP/1.1

Host: mybucket.s3.amazonaws.com
Date: Wed, 25 Nov 2009 12:00:00 GMT
Authorization: authorization string

Sample Response Showing an Enabled Logging Status

HTTP/1.1 200 OK
Date: Wed, 25 Nov 2009 12:00:00 GMT
Connection: close
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

1003
Amazon Simple Storage Service API Reference
GET Bucket metrics

Sample Response Showing a Disabled Logging Status

HTTP/1.1 200 OK
Date: Wed, 25 Nov 2009 12:00:00 GMT
Connection: close
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

Related Resources

• PUT Bucket (p. 1095)

• PUT Bucket logging (p. 1164)

GET Bucket metrics

Description

Gets a metrics configuration for the CloudWatch request metrics (specified by the metrics configuration
ID) from the bucket. Note that this doesn't include the daily storage metrics.

For information about CloudWatch request metrics for Amazon S3, see Monitoring Metrics with Amazon
CloudWatch in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

1004
Amazon Simple Storage Service API Reference
GET Bucket metrics

Requests

Syntax

GET /?metrics&id=id HTTP/1.1

Host: BucketName.s3.amazonaws.com
x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

Parameter Description Required

id The ID used to identify the metrics conﬁguration. Yes

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

API Version 2006-03-01

1005
Amazon Simple Storage Service API Reference
GET Bucket metrics

Responses

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

Response Elements

The Examples section shows an example of a metrics conﬁguration XML. The following table describes
the XML elements in the metrics conﬁguration returned by the GET request.

Name Description

And A conjunction (logical AND) of predicates, which is used in evaluating a

metrics ﬁlter. The operator must have at least two predicates, and an
object must match all of the predicates in order for the ﬁlter to apply.

Type: Container

Children: Prefix, Tag

Ancestor: Filter

Filter Specifies a metrics configuration filter. The metrics configuration only

includes objects that meet the filter's criteria. A filter must be a prefix, a
tag, or a conjunction (MetricsAndOperator).

Type: Container

Children: And

Ancestor: MetricsConfiguration

Id The ID used to identify the metrics conﬁguration.

Type: String

Ancestor: MetricsConfiguration

API Version 2006-03-01

1006
Amazon Simple Storage Service API Reference
GET Bucket metrics

Name Description

Key The name of the tag.

Type: String

Ancestor: Tag

MetricsConfiguration An existing metrics conﬁguration for CloudWatch request metrics on

this bucket.

Type: Container

Children: Filter, Id

Ancestor: None

Prefix A string of text used at the beginning of an object key name.

Type: String

Ancestor: And

Tag A key value name pair, used to organize objects by association.

Type: Container

Children: Key, Value

Ancestor: And

Value The value of the tag.

Type: String

Ancestor: Tag

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

API Version 2006-03-01

1007
Amazon Simple Storage Service API Reference
GET Bucket metrics

First Sample Request

Retrieve a metrics configuration that filters metrics based on a specified prefix.

GET /?metrics&id=Documents HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT
Authorization: signatureValue

First Sample Response

Retrieve a metrics configuration that filters metrics based on a specified prefix.

<?xml version="1.0" encoding="UTF-8"?>

<MetricsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>Documents</Id>
<Filter>
<Prefix>documents/</Prefix>
</Filter>
</MetricsConfiguration>

Second Sample Request

Retrieve a metrics configuration that enables metrics for objects that start with a particular prefix and
also have specific tags applied.

GET /?metrics&id=ImportantBlueDocuments HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT
Authorization: signatureValue

API Version 2006-03-01

1008
Amazon Simple Storage Service API Reference
GET Bucket metrics

Second Sample Response

Retrieve a metrics configuration that enables metrics for objects that start with a particular prefix and
also have specific tags applied.

<?xml version="1.0" encoding="UTF-8"?>

Related Resources

• PUT Bucket metrics (p. 1170)

• DELETE Bucket metrics (p. 911)
• List Bucket Metrics Conﬁgurations (p. 1079)
• Monitoring Metrics with Amazon CloudWatch in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

1009
Amazon Simple Storage Service API Reference
GET Bucket notiﬁcation

GET Bucket notiﬁcation

Description

This implementation of the GET operation uses the notification subresource to return the
notiﬁcation conﬁguration of a bucket.

If notiﬁcations are not enabled on the bucket, the operation returns an empty
NotificationConfiguration element.

Requests

Syntax

GET /?notification HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

API Version 2006-03-01

1010
Amazon Simple Storage Service API Reference
GET Bucket notiﬁcation

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

Name Description

CloudFunction Lambda cloud function ARN that Amazon S3 can

invoke when it detects events of the speciﬁed type.

Type: String

Ancestry: CloudFunctionConfiguration

API Version 2006-03-01

1011
Amazon Simple Storage Service API Reference
GET Bucket notiﬁcation

Name Description

CloudFunctionConfiguration Container for specifying the AWS Lambda

notiﬁcation conﬁguration.

Type: Container

Children: An Id, CloudFunction, and one, or more

Event.

Ancestry: NotificationConfiguration

Event Bucket event for which to send notiﬁcations.

Note
You can add multiple instance
of QueueConfiguration,
TopicConfiguration, or
CloudFunctionConfiguration to the
notiﬁcation conﬁguration.

Type: String

Valid Values: For a list of supported event types, go

to Conﬁguring Event Notiﬁcations in the Amazon
Simple Storage Service Developer Guide.

Ancestry: TopicConfiguration and

QueueConfiguration

Filter Container for S3Key, which contains object key

name filtering rules. For information about key name
filtering, go to Configuring Event Notifications in the
Amazon Simple Storage Service Developer Guide.

Type: Container

Children: S3Key

Ancestor: TopicConfiguration,
QueueConfiguration, or
CloudFunctionConfiguration.

FilterRule Container for key value pair that deﬁnes the criteria
for the ﬁlter rule.

Container S3Key

Type: Container

Children: Name and Value

Ancestor: S3Key

API Version 2006-03-01

1012
Amazon Simple Storage Service API Reference
GET Bucket notiﬁcation

Name Description

Id Optional unique identiﬁer for

each of the conﬁgurations in the
NotificationConfiguration. If you don't
provide, Amazon S3 will assign an ID.

Type: String

Ancestry: TopicConfiguration and

QueueConfiguration

Name Object key name preﬁx or suﬃx identifying

one or more objects to which the filtering rule
applies. Maximum prefix length can be up to 1,024
characters. Overlapping prefixes and suffixes are not
supported. For more information, go to Configuring
Event Notifications in the Amazon Simple Storage
Service Developer Guide.

Type: String

Ancestor: FilterRule

Valid values: prefix or suffix

NotificationConfiguration Container for specifying the notiﬁcation

configuration of the bucket. If this element is empty,
notifications are turned off on the bucket.

Type: Container

Children: one or more TopicConfiguration,

QueueConfiguration, and
CloudFunctionConfiguration elements.

Ancestry: None

Queue Amazon SQS queue ARN to which Amazon S3

will publish a message when it detects events of
speciﬁed type.

Type: String

Ancestry: TopicConfiguration

QueueConfiguration Container for specifying a conﬁguration when you

want Amazon S3 to publish events to an Amazon
Simple Queue Service (Amazon SQS) queue.

Type: Container

Children: An Id, Topic, and one, or more Event.

Ancestry: NotificationConfiguration

API Version 2006-03-01

1013
Amazon Simple Storage Service API Reference
GET Bucket notiﬁcation

Name Description

S3Key Container for object key name preﬁx and suﬃx

ﬁltering rules.

Type: Container

Children: One or more FilterRule

Ancestor: Filter

Topic Amazon SNS topic ARN to which Amazon S3

will publish a message when it detects events of
speciﬁed type.

Type: String

Ancestry: TopicConfiguration

TopicConfiguration Container for specifying the conﬁguration when you

want Amazon S3 to publish events to an Amazon
Simple Notiﬁcation Service (Amazon SNS) topic.

Type: Container

Children: An Id, Topic, and one, or more Event.

Ancestry: NotificationConfiguration

Value Specifies the object key name prefix or suffix to filter

on.

Type: String

Ancestor: FilterRule

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

API Version 2006-03-01

1014
Amazon Simple Storage Service API Reference
GET Bucket notiﬁcation

Sample Request

This request returns the notiﬁcation conﬁguration on the bucket quotes.s3.amazonaws.com.

GET ?notification HTTP/1.1

Host: quotes.s3.amazonaws.com
Date: Wed, 15 Oct 2014 16:59:03 GMT
Authorization: authorization string

Sample Response

This response returns that the notification configuration for the specified bucket.

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A02
Date: Wed, 15 Oct 2014 16:59:04 GMT
Server: AmazonS3
<?xml version="1.0" encoding="UTF-8"?>

Related Resources

• PUT Bucket notiﬁcation (p. 1176)

API Version 2006-03-01

1015
Amazon Simple Storage Service API Reference
GET Bucket object lock conﬁguration

GET Bucket object lock conﬁguration

Service: Amazon Simple Storage Service

Gets the Object Lock configuration for a bucket. The rule specified in the Object Lock configuration will
be applied by default to every new object placed in the specified bucket.

Request Syntax
GET /?object-lock HTTP/1.1
Host: <bucket-name>.s3.amazonaws.com
Date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization-string> (see Authenticating Requests (AWS Signature Version
4))

URI Request Parameters

The request does not use any URI parameters.

Request Body
The request does not have a request body.

Response Syntax
<ObjectLockConfiguration>
<ObjectLockEnabled>string</ObjectLockEnabled>
<Rule>
<DefaultRetention>
<Mode>string</Mode>
<Years>integer</Years>
</DefaultRetention>
</Rule>
</ObjectLockConfiguration>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

For more information about the response elements that this operation returns, see
ObjectLockConﬁguration (p. 1458).

Related Resources
Locking Objects in the Amazon Simple Storage Service Developer Guide.

GET BucketPolicyStatus

API Version 2006-03-01

1016
Amazon Simple Storage Service API Reference
GET BucketPolicyStatus

Description

This operation retrieves the policy status for an Amazon S3 bucket, indicating whether the bucket is
public. In order to use this operation, you must have the s3:GetBucketPolicyStatus permission. For
more information about Amazon S3 permissions, see Specifying Permissions in a Policy in the Amazon
Simple Storage Service Developer Guide.

For more information about when Amazon S3 considers a bucket public, see The Meaning of "Public" in
the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

GET /<bucket-name>?policyStatus HTTP/1.1

Host: <bucket-name>.s3.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization string> (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This operation does not use request parameters.

Request Headers

API Version 2006-03-01

1017
Amazon Simple Storage Service API Reference
GET BucketPolicyStatus

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

Response Elements

Name Description

PolicyStatus Container element for bucket policy status.

Type: Container

Children: IsPublic

IsPublic Indicates whether this bucket currently has a public access policy.

Type: Boolean

Ancestor: PolicyStatus

Valid values: TRUE | FALSE

API Version 2006-03-01

1018
Amazon Simple Storage Service API Reference
GET BucketPolicyStatus

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

The following request gets a bucket policy status.

GET /<bucket-name>?policyStatus HTTP/1.1

Host: <bucket-name>.s3.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <signatureValue>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3
Content-Length: 0

API Version 2006-03-01

1019
Amazon Simple Storage Service API Reference
GET BucketPolicyStatus

Related Resources

Default: 1000

prefix Use this parameter to select only those keys that begin with the No
specified prefix. You can use prefixes to separate a bucket into
different groupings of keys. (You can think of using prefix to
make groups in the same way you'd use a folder in a file system.)
You can use prefix with delimiter to roll up numerous
objects into a single result under CommonPrefixes. Also, see
delimiter.

Type: String

Default: None

API Version 2006-03-01

1022
Amazon Simple Storage Service API Reference
GET Bucket Object versions

Parameter Description Required

version-id- Speciﬁes the object version you want to start listing from. Also, No
marker see key-marker.

Type: String

Default: None

Valid Values: Valid version ID | Default

Constraint: May not be an empty string

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

Name Description

DeleteMarker Container for an object that is a delete marker.

Type: Container

API Version 2006-03-01

1023
Amazon Simple Storage Service API Reference
GET Bucket Object versions

Name Description
Children: Key, VersionId, IsLatest, LastModiﬁed, Owner

Ancestor: ListVersionsResult

DisplayName Object owner's name.

Important
This value is only included in the response in the US East (N.
Virginia), US West (N. California), US West (Oregon), Asia Pacific
(Singapore), Asia Pacific (Sydney), Asia Pacific (Tokyo), Europe
(Ireland), and South America (São Paulo) regions.
For a list of all the Amazon S3 supported regions and
endpoints, see Regions and Endpoints in the AWS General
Reference.

Type: String

Ancestor: ListVersionsResult.Version.Owner |
ListVersionsResult.DeleteMarker.Owner

Encoding-Type Encoding type used by Amazon S3 to encode object key names in the
XML response.

If you specify encoding-type request parameter, Amazon S3 includes

this element in the response, and returns encoded key name values in
the following response elements:

KeyMarker, NextKeyMarker, Prefix, Key, and Delimiter.

Type: String

Ancestor: ListBucketResult

ETag The entity tag is an MD5 hash of the object. The ETag only reﬂects
changes to the contents of an object, not its metadata.

Type: String

Ancestor: ListVersionsResult.Version

ID Object owner's ID.

Type: String

Ancestor: ListVersionsResult.Version.Owner |
ListVersionsResult.DeleteMarker.Owner

IsLatest Speciﬁes whether the object is (true) or is not (false) the current
version of an object.

Type: Boolean

Valid Values: true | false

Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

API Version 2006-03-01

1024
Amazon Simple Storage Service API Reference
GET Bucket Object versions

Name Description

IsTruncated A ﬂag that indicates whether (true) or not (false) Amazon S3 returned
all of the results that satisﬁed the search criteria. If your results were
truncated, you can make a follow-up paginated request using the
NextKeyMarker and NextVersionIdMarker response parameters as
a starting place in another request to return the rest of the results.

Type: Boolean

Valid Values: true | false

Ancestor: ListVersionsResult

Key The object's key.

Type: String

Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

Name Description

NextKeyMarker When the number of responses exceeds the value of MaxKeys,

NextKeyMarker specifies the first key not returned that satisfies the
search criteria. Use this value for the key-marker request parameter in
a subsequent request.

Type: String

Ancestor: ListVersionsResult

NextVersionIdMarker When the number of responses exceeds the value of MaxKeys,

NextVersionIdMarker specifies the first object version not returned
that satisfies the search criteria. Use this value for the version-id-
marker request parameter in a subsequent request.

Type: String

Ancestor: ListVersionsResult

Owner Bucket owner.

Type: String

Children: DisplayName, ID

Ancestor: ListVersionsResult.Version | ListVersionsResult.DeleteMarker

Prefix Selects objects that start with the value supplied by this parameter.

Type: String

Ancestor: ListVersionsResult

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

The following request returns all of the versions of all of the objects in the speciﬁed bucket.

GET /?versions HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 +0000
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Sample Response to GET Versions

<?xml version="1.0" encoding="UTF-8"?>

<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<Name>bucket</Name>
<Prefix>my</Prefix>
<KeyMarker/>

API Version 2006-03-01

1027
Amazon Simple Storage Service API Reference
GET Bucket Object versions

<VersionIdMarker/>
<MaxKeys>5</MaxKeys>
<IsTruncated>false</IsTruncated>
<Version>
<Key>my-image.jpg</Key>
<VersionId>3/L4kqtJl40Nr8X8gdRQBpUMLUo</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2009-10-12T17:50:30.000Z</LastModified>
<ETag>"fba9dede5f27731c9771645a39863328"</ETag>
<Size>434234</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
</Version>
<DeleteMarker>
<Key>my-second-image.jpg</Key>
<VersionId>03jpff543dhffds434rfdsFDN943fdsFkdmqnh892</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2009-11-12T17:50:30.000Z</LastModified>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
</DeleteMarker>
<Version>
<Key>my-second-image.jpg</Key>
<VersionId>QUpfdndhfd8438MNFDN93jdnJFkdmqnh893</VersionId>
<IsLatest>false</IsLatest>
<LastModified>2009-10-10T17:50:30.000Z</LastModified>
<ETag>"9b2cf535f27731c974343645a3985328"</ETag>
<Size>166434</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
</Version>
<DeleteMarker>
<Key>my-third-image.jpg</Key>
<VersionId>03jpff543dhffds434rfdsFDN943fdsFkdmqnh892</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2009-10-15T17:50:30.000Z</LastModified>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
</DeleteMarker>
<Version>
<Key>my-third-image.jpg</Key>
<VersionId>UIORUnfndfhnw89493jJFJ</VersionId>
<IsLatest>false</IsLatest>
<LastModified>2009-10-11T12:50:30.000Z</LastModified>
<ETag>"772cf535f27731c974343645a3985328"</ETag>
<Size>64</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
</Version>
</ListVersionsResult>

API Version 2006-03-01

1028
Amazon Simple Storage Service API Reference
GET Bucket Object versions

Sample Request

The following request returns objects in the order they were stored, returning the most recently stored
object ﬁrst starting with the value for key-marker.

GET /?versions&key-marker=key2 HTTP/1.1

Host: s3.amazonaws.com
Pragma: no-cache
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
Date: Thu, 10 Dec 2009 22:46:32 +0000
Authorization: signatureValue

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

1029
Amazon Simple Storage Service API Reference
GET Bucket Object versions

<ETag>"396fefef536d5ce46c7537ecf978a360"</ETag>
<Size>217</Size>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>
</ListVersionsResult>

Sample Request Using preﬁx

This example returns objects whose keys begin with source.

GET /?versions&prefix=source HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 +0000
Authorization: authorization string

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

1030
Amazon Simple Storage Service API Reference
GET Bucket Object versions

</Version>
</ListVersionsResult>

Sample Request Using key-marker and version-id-marker Parameters

The following example returns objects starting at the speciﬁed key (key-marker) and version ID
(version-id-marker).

GET /?versions&key-marker=key3&version-id-marker=t46ZenlYTZBnj HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 +0000
Authorization: signatureValue

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>mtp-versioning-fresh</Name>
<Prefix/>
<KeyMarker>key3</KeyMarker>
<VersionIdMarker>t46ZenlYTZBnj</VersionIdMarker>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<DeleteMarker>
<Key>sourcekey</Key>
<VersionId>qDhprLU80sAlCFLu2DWgXAEDgKzWarn-HS_JU0TvYqs.</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2009-12-10T16:38:11.000Z</LastModified>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
</DeleteMarker>
<Version>
<Key>sourcekey</Key>
<VersionId>wxxQ7ezLaL5JN2Sislq66Syxxo0k7uHTUpb9qiiMxNg.</VersionId>
<IsLatest>false</IsLatest>
<LastModified>2009-12-10T16:37:44.000Z</LastModified>
<ETag>"396fefef536d5ce46c7537ecf978a360"</ETag>
<Size>217</Size>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>
</ListVersionsResult>

API Version 2006-03-01

1031
Amazon Simple Storage Service API Reference
GET Bucket Object versions

Sample Request Using key-marker, version-id-marker and max-keys

The following request returns up to three (the value of max-keys) objects starting with the key speciﬁed
by key-marker and the version ID speciﬁed by version-id-marker.

GET /?versions&key-marker=key3&version-id-marker=t46Z0menlYTZBnj&max-keys=3
Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 +0000
Authorization: authorization string

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>mtp-versioning-fresh</Name>
<Prefix/>
<KeyMarker>key3</KeyMarker>
<VersionIdMarker>null</VersionIdMarker>
<NextKeyMarker>key3</NextKeyMarker>
<NextVersionIdMarker>d-d309mfjFrUmoQ0DBsVqmcMV15OI.</NextVersionIdMarker>
<MaxKeys>3</MaxKeys>
<IsTruncated>true</IsTruncated>
<Version>
<Key>key3</Key>
<VersionId>8XECiENpj8pydEDJdd-_VRrvaGKAHOaGMNW7tg6UViI.</VersionId>
<IsLatest>false</IsLatest>
<LastModified>2009-12-09T00:18:23.000Z</LastModified>
<ETag>"396fefef536d5ce46c7537ecf978a360"</ETag>
<Size>217</Size>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>
<Version>
<Key>key3</Key>
<VersionId>d-d309mfjFri40QYukDozqBt3UmoQ0DBsVqmcMV15OI.</VersionId>
<IsLatest>false</IsLatest>
<LastModified>2009-12-09T00:18:08.000Z</LastModified>
<ETag>"396fefef536d5ce46c7537ecf978a360"</ETag>
<Size>217</Size>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>
</ListVersionsResult>

API Version 2006-03-01

1032
Amazon Simple Storage Service API Reference
GET Bucket Object versions

Sample Request Using the Delimiter and the Preﬁx Parameters

Assume you have the following keys in your bucket, example-bucket.

photos/2006/January/sample.jpg

photos/2006/February/sample.jpg

photos/2006/March/sample.jpg

videos/2006/March/sample.wmv

sample.jpg

The following GET versions request speciﬁes the delimiter parameter with value "/".

GET /?versions&delimiter=/ HTTP/1.1

Host: example-bucket.s3.amazonaws.com
Date: Wed, 02 Feb 2011 20:34:56 GMT
Authorization: authorization string

The list of keys from the speciﬁed bucket are shown in the following response.

This is a useful scenario if you use key preﬁxes for your objects to create a logical folder like structure. In
this case you can interpret the result as the folders photos/ and videos/ have one or more objects.

API Version 2006-03-01

1033
Amazon Simple Storage Service API Reference
GET Bucket Object versions

<CommonPrefixes>
<Prefix>photos/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>videos/</Prefix>
</CommonPrefixes>
</ListVersionsResult>

In addition to the delimiter parameter you can ﬁlter results by adding a prefix parameter as shown in
the following request.

GET /?versions&prefix=photos/2006/&delimiter=/ HTTP/1.1

Host: example-bucket.s3.amazonaws.com
Date: Wed, 02 Feb 2011 19:34:02 GMT
Authorization: authorization string

In this case the response will include only objects keys that start with the specified prefix. The value
returned in the <CommonPrefixes> element is a substring from the beginning of the key to the first
occurrence of the specified delimiter after the prefix.

<?xml version="1.0" encoding="UTF-8"?>

<ListVersionsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>example-bucket</Name>
<Prefix>photos/2006/</Prefix>
<KeyMarker></KeyMarker>
<VersionIdMarker></VersionIdMarker>
<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<Version>
<Key>photos/2006/</Key>
<VersionId>3U275dAA4gz8ZOqOPHtJCUOi60krpCdy</VersionId>
<IsLatest>true</IsLatest>
<LastModified>2011-02-02T18:47:27.000Z</LastModified>
<ETag>"d41d8cd98f00b204e9800998ecf8427e"</ETag>
<Size>0</Size>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>display-name</DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Version>
<CommonPrefixes>
<Prefix>photos/2006/February/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/January/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/March/</Prefix>
</CommonPrefixes>
</ListVersionsResult>

Related Resources

API Version 2006-03-01

1034
Amazon Simple Storage Service API Reference
GET Bucket Object versions

• GET Bucket Objects (p. 940)

• GET Object (p. 1248)
• PUT Object (p. 1324)
• DELETE Object (p. 1239)

API Version 2006-03-01

1035
Amazon Simple Storage Service API Reference
GET Bucket policy

GET Bucket policy

Description

This implementation of the GET operation uses the policy subresource to return the policy of a
speciﬁed bucket. If you are using an identity other than the root user of the AWS account that owns the
bucket, the calling identity must have the GetBucketPolicy permissions on the speciﬁed bucket and
belong to the bucket owner's account in order to use this operation.

For more information about bucket policies, see Using Bucket Policies and User Policies in the Amazon
Simple Storage Service Developer Guide.

Requests

Syntax

GET /?policy HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

API Version 2006-03-01

1036
Amazon Simple Storage Service API Reference
GET Bucket policy

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

API Version 2006-03-01

1037
Amazon Simple Storage Service API Reference
GET Bucket policy

The response contains the (JSON) policy of the speciﬁed bucket.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

The following request returns the policy of the speciﬁed bucket.

GET ?policy HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: Uuag1LuByru9pO4SAMPLEAtRPfTaOFg==
x-amz-request-id: 656c76696e67SAMPLE57374
Date: Tue, 04 Apr 2010 20:34:56 GMT
Connection: keep-alive
Server: AmazonS3

{
"Version":"2008-10-17",
"Id":"aaaa-bbbb-cccc-dddd",
"Statement" : [
{
"Effect":"Deny",

API Version 2006-03-01

1038
Amazon Simple Storage Service API Reference
GET Bucket policy

"Sid":"1",
"Principal" : {
"AWS":["111122223333","444455556666"]
},
"Action":["s3:*"],
"Resource":"arn:aws:s3:::bucket/*"
}
]
}

Related Resources

• GET Bucket Objects (p. 940)

API Version 2006-03-01

1039
Amazon Simple Storage Service API Reference
GET Bucket replication

GET Bucket replication

Description

Returns a bucket's replication conﬁguration.

Note
It can take a while for PUT Bucket replication and DELETE Bucket replication
requests to fully propagate. If you submit a GET Bucket replication request soon after
submitting either of those requests, might not return the latest replication conﬁguration.

For information about replication conﬁguration, see Replication in the Amazon Simple Storage Service
Developer Guide.

This operation requires permissions for the s3:GetReplicationConfiguration action. For more
information about permissions, see Using Bucket Policies and User Policies in the Amazon Simple Storage
Service Developer Guide.

Requests

Syntax

GET /?replication HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string

For more information about authorization, see Authenticating Requests (AWS Signature Version
4) (p. 792).

API Version 2006-03-01

1040
Amazon Simple Storage Service API Reference
GET Bucket replication

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

API Version 2006-03-01

1041
Amazon Simple Storage Service API Reference
GET Bucket replication

This implementation of GET returns the following response elements.

Element Description

ReplicationConfiguration The container for replication rules.

Type: Container

Children: Rule

Ancestor: None

Rule The container for information about a particular

replication rule.

Type: Container

Ancestor: ReplicationConfiguration

Role The Amazon Resource Name (ARN) of an AWS Identity and

a cross-account scenario, if you tell Amazon S3 to change
replica ownership to the AWS account that owns the
destination bucket, this is the account ID of the owner
of the destination bucket. For more information, see
Replication Additional Conﬁguration: Change Replica
Owner in the Amazon Simple Storage Service Developer
Guide.

If the owner override option is not set in a replication

conﬁguration, the response does include this element.

Type: String

Ancestor: Destination

Bucket The name of the bucket where Amazon S3 stores replicas

of objects identiﬁed by the rule.

Type: String

Ancestor: Destination

StorageClass The storage class for replicated objects. This

ﬁeld is returned only if you set the storage class
when you conﬁgured replication (with PUT Bucket
replication (p. 1192)).

Type: String

Ancestor: Destination

Valid values: STANDARD | REDUCED_REDUNDANCY

AccessControlTranslation If you set the owner override option in the replication

conﬁguration, Amazon S3 returns this element. It
identiﬁes the owner of the replicas.

If this element isn't present, replicas are owned by the

same AWS account that owns the source object.

Type: String

Ancestor: Destination

Owner Identiﬁes the owner of the replicas. Amazon S3 returns

this element only if you conﬁgured owner override option,
in a cross-account scenario.

Type: String

Ancestor: AccessControlTranslation

API Version 2006-03-01

1043
Amazon Simple Storage Service API Reference
GET Bucket replication

Rule Filter Response Elements

A replication configuration rule can specify a filter to identify a subset of source objects to apply the rule
to. The response can return the following additional elements, which are related to filtering.

Element Description

Filter The container that describes the ﬁlters used to identify

the source objects that you want to replicate.

Ancestor: Rule

And The container for the Prefix and one or more Tag
elements. If the And element is present, it includes at
least one child element.

Ancestor: Filter

Prefix The object key prefix that identifies one or more objects
that the rule applies to.
Note
The earlier version of replication configuration
(V1) supported only the key prefix as a rule
filter. In V1, the response returns the Prefix
element as a child of the Rule element.
Amazon S3 supports this behavior for backward
compatibility. For more information, see
Backward Compatibility in the Amazon S3
Developer Guide.

Type: String

Ancestor: Filter, or And (if present), or Rule (if you are

using the earlier version of replication conﬁguration).

Tag A container that provides a tag key and value.

Ancestor: Filter or And (if present)

Key A tag key.

Type: String

Ancestor: Tag

Value A tag value.

Type: String

Ancestor: Tag

API Version 2006-03-01

1044
Amazon Simple Storage Service API Reference
GET Bucket replication

If you include the Filter element in a replication conﬁguration, you must also include the
DeleteMarkerReplication and Priority elements. The response also returns those elements.

Element Description

1045
Amazon Simple Storage Service API Reference
GET Bucket replication

Element Description

Status A ﬂag that tells Amazon S3 whether to replicate objects

created with server-side encryption using an AWS KMS-
managed key.

Type: String

Ancestor: SseKmsEncryptedObjects

EncryptionConfiguration A container that provides information about encryption.

Type: String

Ancestor: Destination

ReplicaKmsKeyID The AWS KMS Key ID—the Key Amazon Resource Name
(ARN) or Alias ARN—of the destination bucket. Amazon
S3 uses this key to encrypt replicas.

Type: String

Ancestor: EncryptionConfiguration

Special Errors

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

There is no replication conﬁguration

NoSuchReplicationConfiguration 404 Not Client
with that name. Found

For general information about Amazon S3 errors and a list of error codes, see Error Responses (p. 783).

Examples

Example 1: Retrieve Replication Conﬁguration Information

1049
Amazon Simple Storage Service API Reference
GET Bucket requestPayment

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

Name Description

Payer Speciﬁes who pays for the download and request fees.

Type: Enum

Valid Values: Requester | BucketOwner

Ancestor: RequestPaymentConﬁguration

RequestPaymentConfiguration Container for Payer.

Type: Container

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

API Version 2006-03-01

1050
Amazon Simple Storage Service API Reference
GET Bucket requestPayment

Examples

Sample Request

The following request returns the payer for the bucket, colorpictures.

GET ?requestPayment HTTP/1.1

Host: colorpictures.s3.amazonaws.com
Date: Wed, 01 Mar 2009 12:00:00 GMT
Authorization: authorization string

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

<RequestPaymentConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Payer>Requester</Payer>
</RequestPaymentConfiguration>

This response shows that the bucket is a Requester Pays bucket, meaning the person requesting a
download from this bucket pays the transfer fees.

Related Resources

• GET Bucket (List Objects) Version 1 (p. 940)

API Version 2006-03-01

1051
Amazon Simple Storage Service API Reference
GET Bucket requestPayment

API Version 2006-03-01

1052
Amazon Simple Storage Service API Reference
GET Bucket tagging

GET Bucket tagging

Description

This implementation of the GET operation uses the tagging subresource to return the tag set
associated with the bucket.

To use this operation, you must have permission to perform the s3:GetBucketTagging action. By
default, the bucket owner has this permission and can grant this permission to others.

Requests

Syntax

GET /?tagging HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

API Version 2006-03-01

1053
Amazon Simple Storage Service API Reference
GET Bucket tagging

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Type: String

Ancestry: Tag

Special Errors

• NoSuchTagSetError - There is no tag set associated with the bucket.

Examples

Sample Request

The following request returns the tag set of the speciﬁed bucket.

GET ?tagging HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT

API Version 2006-03-01

1055
Amazon Simple Storage Service API Reference
GET Bucket tagging

Authorization: authorization string

Sample Response

HTTP/1.1 200 OK
Date: Wed, 25 Nov 2009 12:00:00 GMT
Connection: close
Server: AmazonS3

<Tagging>
<TagSet>
<Tag>
<Key>Project</Key>
<Value>Project One</Value>
</Tag>
<Tag>
<Key>User</Key>
<Value>jsmith</Value>
</Tag>
</TagSet>
</Tagging>

Related Resources

• PUT Bucket tagging (p. 1207)

• DELETE Bucket tagging (p. 922)

API Version 2006-03-01

1056
Amazon Simple Storage Service API Reference
GET Bucket versioning

GET Bucket versioning

Description

This implementation of the GET operation uses the versioning subresource to return the versioning
state of a bucket. To retrieve the versioning state of a bucket, you must be the bucket owner.

This implementation also returns the MFA Delete status of the versioning state, i.e., if the MFA Delete
status is enabled, the bucket owner must use an authentication device to change the versioning state of
the bucket.

There are three versioning states:

• If you enabled versioning on a bucket, the response is:

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
</VersioningConfiguration>

• If you suspended versioning on a bucket, the response is:

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Suspended</Status>
</VersioningConfiguration>

• If you never enabled (or suspended) versioning on a bucket, the response is:

Requests

Syntax

API Version 2006-03-01

1057
Amazon Simple Storage Service API Reference
GET Bucket versioning

GET /?versioning HTTP/1.1

Host: BucketName.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

API Version 2006-03-01

1058
Amazon Simple Storage Service API Reference
GET Bucket versioning

Response Elements

This implementation of GET returns the following response elements.

Name Description

MfaDelete Speciﬁes whether MFA delete is enabled in the bucket versioning

configuration. This element is only returned if the bucket has
been configured with MfaDelete. If the bucket has never been so
configured, this element is not returned.

Type: Enum

Valid Values: Disabled | Enabled

Ancestor: VersioningConﬁguration

Status The versioning state of the bucket.

Type: Enum

Valid Values: Suspended | Enabled

Ancestor: VersioningConﬁguration

VersioningConfiguration Container for the Status response element.

Type: Container

Ancestor: None

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

API Version 2006-03-01

1059
Amazon Simple Storage Service API Reference
GET Bucket versioning

Sample Request

This example returns the versioning state of myBucket.

GET /?versioning HTTP/1.1

Host: myBucket.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain

Sample Response

The following is a sample of the response body (only) that shows bucket versioning is enabled.

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
</VersioningConfiguration>

Related Resources

• GET Object (p. 1248)

• PUT Object (p. 1324)
• DELETE Object (p. 1239)

API Version 2006-03-01

1060
Amazon Simple Storage Service API Reference
GET Bucket website

GET Bucket website

Description

This implementation of the GET operation returns the website configuration associated with a bucket.
To host website on Amazon S3, you can configure a bucket as website by adding a website configuration.
For more information about hosting websites, go to Hosting Websites on Amazon S3 in the Amazon
Simple Storage Service Developer Guide .

This GET operation requires the S3:GetBucketWebsite permission. By default, only the bucket owner
can read the bucket website conﬁguration. However, bucket owners can allow other users to read
the website conﬁguration by writing a bucket policy granting them the S3:GetBucketWebsite
permission.

Requests

Syntax

GET /?website HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

API Version 2006-03-01

1061
Amazon Simple Storage Service API Reference
GET Bucket website

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

The response XML includes same elements that were uploaded when you conﬁgured the bucket as
website. For more information, see PUT Bucket website (p. 1218).

Examples

API Version 2006-03-01

1062
Amazon Simple Storage Service API Reference
GET Bucket website

Sample Request

This request retrieves website conﬁguration on the speciﬁed bucket.

GET ?website HTTP/1.1

Host: example-bucket.s3.amazonaws.com
Date: Thu, 27 Jan 2011 00:49:20 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:n0Nhek72Ufg/u7Sm5C1dqRLs8XX=

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 3848CD259D811111
Date: Thu, 27 Jan 2011 00:49:26 GMT
Content-Length: 240
Content-Type: application/xml
Transfer-Encoding: chunked
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

Related Resources

• DELETE Bucket website (p. 925)

• PUT Bucket website (p. 1218)

API Version 2006-03-01

1063
Amazon Simple Storage Service API Reference
HEAD Bucket

HEAD Bucket
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

Description

To use this operation, you must have permissions to perform the s3:ListBucket action. The bucket
owner has this permission by default and can grant this permission to others. For more information
about permissions, see Permissions Related to Bucket Operations and Managing Access Permissions to
Your Amazon S3 Resources in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

HEAD / HTTP/1.1
Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

API Version 2006-03-01

1064
Amazon Simple Storage Service API Reference
HEAD Bucket

Request Elements

This implementation of the operation does not use request elements.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of the operation does not return response elements.

Special Errors

API Version 2006-03-01

1065
Amazon Simple Storage Service API Reference
HEAD Bucket

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

HEAD / HTTP/1.1
Date: Fri, 10 Feb 2012 21:34:55 GMT
Authorization: authorization string
Host: aws-s3-bucket1.s3.amazonaws.com
Connection: Keep-Alive

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: JuKZqmXuiwFeDQxhD7M8KtsKobSzWA1QEjLbTMTagkKdBX2z7Il/jGhDeJ3j6s80
x-amz-request-id: 32FE2CEB32F5EE25
Date: Fri, 10 2012 21:34:56 GMT
Server: AmazonS3

API Version 2006-03-01

1066
Amazon Simple Storage Service API Reference
List Bucket Analytics Conﬁgurations

List Bucket Analytics Conﬁgurations

Description

This implementation of the GET operation returns a list of analytics conﬁgurations for the bucket. You
can have up to 1,000 analytics conﬁgurations per bucket.

For information about Amazon S3 analytics feature, see Amazon S3 Analytics – Storage Class Analysis in
the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

GET /?analytics HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

API Version 2006-03-01

1067
Amazon Simple Storage Service API Reference
List Bucket Analytics Conﬁgurations

Request Parameters

This implementation of GET uses the parameters in the following table.

Parameter Description Required

continuation- When the Amazon S3 response to this API call is truncated (that is, No
token when the IsTruncated response element value is true), the response
also includes the NextContinuationToken element, the value of
which you can use in the next request as the continuation-token
to list the next page. The continuation token is an opaque value that
Amazon S3 understands.
Type: String

Default: None

Request Elements

This implementation of the operation does not use request elements.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Response Headers

API Version 2006-03-01

1068
Amazon Simple Storage Service API Reference
List Bucket Analytics Conﬁgurations

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

Name Description

ContinuationToken The marker that is used as a starting point for this analytics
conﬁguration list response. This value is present if it was sent
in the request.

Type: String

Ancestor: ListBucketAnalyticsConfigurationsResult

IsTruncated Indicates whether the returned list of analytics conﬁgurations

is complete. A value of true indicates that the list is not
complete and the NextContinuationToken is provided for
a subsequent request.

Type: Boolean

Ancestor: ListAnalyticsConfigurationsResult

AnalyticsConfiguration Contains the analytics conﬁguration. For the XML structure,

see GET Bucket analytics (p. 959).

Type: Container

Ancestor: ListAnalyticsConfigurationsResult

The list of analytics conﬁgurations for a bucket.

ListAnalyticsConfigurationsResult

Type: Container

NextContinuationToken The marker used to continue an analytics conﬁguration listing

that has been truncated. Use the NextContinuationToken
from a previously truncated list response to continue the
listing. The continuation token is an opaque value that
Amazon S3 understands.

Type: String

Ancestor: ListBucketAnalyticsConfigurationsResult

Special Errors

API Version 2006-03-01

1069
Amazon Simple Storage Service API Reference
List Bucket Analytics Conﬁgurations

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Example 1: Listing Analytics Conﬁgurations

The following request returns the analytics conﬁgurations in example-bucket.

Sample Request

GET /?analytics HTTP/1.1

Host: example-bucket.s3.amazonaws.com
x-amz-date: 20160430T233541Z
Authorization: authorization string

Sample Response

API Version 2006-03-01

1070
Amazon Simple Storage Service API Reference
List Bucket Analytics Conﬁgurations

<Key>dog</Key>
<Value>corgi</Value>
</Tag>
</And>
</Filter>
<StorageClassAnalysis>
<DataExport>
<OutputSchemaVersion>V_1</OutputSchemaVersion>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<BucketAccountId>123456789012</BucketAccountId>
<Bucket>arn:aws:s3:::destination-bucket</Bucket>
<Prefix>destination-prefix</Prefix>
</S3BucketDestination>
</Destination>
</DataExport>
</StorageClassAnalysis>
</AnalyticsConfiguration>

<AnalyticsConfiguration>
<Id>report1</Id>
<Filter>
<And>
<Prefix>images/</Prefix>
<Tag>
<Key>dog</Key>
<Value>bulldog</Value>
</Tag>
</And>
</Filter>
<StorageClassAnalysis>
<DataExport>
<OutputSchemaVersion>V_1</OutputSchemaVersion>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<BucketAccountId>123456789012</BucketAccountId>
<Bucket>arn:aws:s3:::destination-bucket</Bucket>
<Prefix>destination-prefix</Prefix>
</S3BucketDestination>
</Destination>
</DataExport>
</StorageClassAnalysis>
</AnalyticsConfiguration>
...
<IsTruncated>false</IsTruncated>

<ContinuationToken>...</ContinuationToken>

<IsTruncated>true</IsTruncated>
<NextContinuationToken>...</NextContinuationToken>
</ListBucketAnalyticsConfigurationResult>

For an example of using the ContinuationToken with a list, see Example 4: Using a Continuation
Token (p. 938).

Related Resources

API Version 2006-03-01

1071
Amazon Simple Storage Service API Reference
List Bucket Analytics Conﬁgurations

• GET Bucket analytics (p. 959)

• DELETE Bucket analytics (p. 894)
• PUT Bucket analytics (p. 1117)

API Version 2006-03-01

1072
Amazon Simple Storage Service API Reference
List Bucket Inventory Conﬁgurations

List Bucket Inventory Conﬁgurations

Description

This implementation of the GET operation returns a list of inventory conﬁgurations for the bucket. You
can have up to 1,000 analytics conﬁgurations per bucket.

For information about the Amazon S3 inventory feature, see Amazon S3 Inventory in the Amazon Simple
Storage Service Developer Guide.

Requests

Syntax

GET /?inventory HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version

API Version 2006-03-01

1073
Amazon Simple Storage Service API Reference
List Bucket Inventory Conﬁgurations

4))

Request Parameters

This implementation of GET uses the parameters in the following table.

Parameter Description Required

continuation- When the Amazon S3 response to this API call is No

token truncated (that is, when the IsTruncated response
element value is true), the response also includes the
NextContinuationToken element. You can use
the value of this element in the next request as the
continuation-token to list the next page. The
continuation token is an opaque value that Amazon S3
understands.
Type: String

Default: None

Request Elements

This implementation of the operation does not use request elements.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Responses

API Version 2006-03-01

1074
Amazon Simple Storage Service API Reference
List Bucket Inventory Conﬁgurations

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

Name Description

ContinuationToken The marker that is used as a starting point for this inventory
conﬁguration list response. This value is present if it was sent
in the request.

Type: String

Ancestor: ListInventoryConfigurationsResult

IsTruncated Tells whether the returned list of inventory conﬁgurations

is complete. A value of true indicates that the list is not
complete and the NextContinuationToken is provided for
a subsequent request.

Type: Boolean

Ancestor: ListInventoryConfigurationsResult

InventoryConfiguration Contains the inventory conﬁguration. For the XML structure,

see GET Bucket Inventory (p. 976).

Type: Container

Ancestor: ListInventoryConfigurationsResult

The list of inventory conﬁgurations for a bucket.

ListInventoryConfigurationsResult

Type: Container

NextContinuationToken The marker that is used to continue an inventory

conﬁguration listing that has been truncated. Use the
NextContinuationToken from a previously truncated list
response to continue the listing. The continuation token is an
opaque value that Amazon S3 understands.

Type: String

Ancestor: ListInventoryConfigurationsResult

API Version 2006-03-01

1075
Amazon Simple Storage Service API Reference
List Bucket Inventory Conﬁgurations

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Example 1: Listing Inventory Conﬁgurations

The following request returns the inventory conﬁgurations in example-bucket.

Sample Request

GET /?inventory HTTP/1.1

Host: example-bucket.s3.amazonaws.com
x-amz-date: 20160430T233541Z
Authorization: authorization string
Content-Type: text/plain

Sample Response

API Version 2006-03-01

1076
Amazon Simple Storage Service API Reference
List Bucket Inventory Conﬁgurations

Connection: close
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

<ListInventoryConfigurationsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<InventoryConfiguration>
<Id>report1</Id>
<IsEnabled>true</IsEnabled>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<AccountId>123456789012</AccountId>
<Bucket>arn:aws:s3:::destination-bucket</Bucket>
<Prefix>prefix1</Prefix>
</S3BucketDestination>
</Destination>
<Schedule>
<Frequency>Daily</Frequency>
</Schedule>
<Filter>
<Prefix>prefix/One</Prefix>
</Filter>
<IncludedObjectVersions>All</IncludedObjectVersions>
<OptionalFields>
<Field>Size</Field>
<Field>LastModifiedDate</Field>
<Field>ETag</Field>
<Field>StorageClass</Field>
<Field>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
</OptionalFields>
</InventoryConfiguration>
<InventoryConfiguration>
<Id>report2</Id>
<IsEnabled>true</IsEnabled>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<AccountId>123456789012</AccountId>
<Bucket>arn:aws:s3:::bucket2</Bucket>
<Prefix>prefix2</Prefix>
</S3BucketDestination>
</Destination>
<Schedule>
<Frequency>Daily</Frequency>
</Schedule>
<Filter>
<Prefix>prefix/Two</Prefix>
</Filter>
<IncludedObjectVersions>All</IncludedObjectVersions>
<OptionalFields>
<Field>Size</Field>
<Field>LastModifiedDate</Field>
<Field>ETag</Field>
<Field>StorageClass</Field>
<Field>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
<Field>ObjectLockRetainUntilDate</Field>
<Field>ObjectLockMode</Field>
<Field>ObjectLockLegalHoldStatus</Field>
</OptionalFields>
</InventoryConfiguration>
<InventoryConfiguration>
<Id>report3</Id>
<IsEnabled>true</IsEnabled>
<Destination>

API Version 2006-03-01

1077
Amazon Simple Storage Service API Reference
List Bucket Inventory Conﬁgurations

<S3BucketDestination>
<Format>CSV</Format>
<AccountId>123456789012</AccountId>
<Bucket>arn:aws:s3:::bucket3</Bucket>
<Prefix>prefix3</Prefix>
</S3BucketDestination>
</Destination>
<Schedule>
<Frequency>Daily</Frequency>
</Schedule>
<Filter>
<Prefix>prefix/Three</Prefix>
</Filter>
<IncludedObjectVersions>All</IncludedObjectVersions>
<OptionalFields>
<Field>Size</Field>
<Field>LastModifiedDate</Field>
<Field>ETag</Field>
<Field>StorageClass</Field>
<Field>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
</OptionalFields>
</InventoryConfiguration>
...
<IsTruncated>false</IsTruncated>

<ContinuationToken>...</ContinuationToken>

<IsTruncated>true</IsTruncated>
<NextContinuationToken>...</NextContinuationToken>
</ListBucketAnalyticsConfigurationResult>
</ListInventoryConfigurationsResult>

For an example of using the ContinuationToken with a list, see Example 4: Using a Continuation
Token (p. 938).

Related Resources

• GET Bucket Inventory (p. 976)

• DELETE Bucket inventory (p. 903)
• PUT Bucket inventory (p. 1136)

API Version 2006-03-01

1078
Amazon Simple Storage Service API Reference
List Bucket Metrics Conﬁgurations

List Bucket Metrics Conﬁgurations

Description

This implementation of the GET operation returns a list of Amazon CloudWatch metrics configurations
for the bucket. The metrics configurations are only for the request metrics of the bucket and do not
provide information on daily storage metrics. You can have up to 1,000 configurations per bucket.

For more information about metrics conﬁgurations and CloudWatch request metrics, see Monitoring
Metrics with Amazon CloudWatch in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

GET /?metrics HTTP/1.1

HOST: BucketName.s3.amazonaws.com

API Version 2006-03-01

1079
Amazon Simple Storage Service API Reference
List Bucket Metrics Conﬁgurations

Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

Parameter Description Required

continuation- When the Amazon S3 response to this API call is truncated (that is, No
token when the IsTruncated response element value is true), the response
also includes the NextContinuationToken element. You can use
the value of that element in the next request as the continuation-
token to list the next page. The continuation token is an opaque
value that Amazon S3 understands.
Type: String

Default: None

Request Headers

This operation uses only Request Headers common to most requests. For more information, see Common
Request Headers (p. 779).

Request Elements

This operation does not use request elements.

Responses

API Version 2006-03-01

1080
Amazon Simple Storage Service API Reference
List Bucket Metrics Conﬁgurations

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

Response Elements

Name Description

IsTruncated Tells whether the returned list of metrics conﬁgurations

is complete. A value of true indicates that the list is not
complete, and the NextContinuationToken is provided for
a subsequent request.

Type: Boolean

Ancestor: ListMetricsConfigurationResult

ContinuationToken The marker that is used as a starting point for this metrics
conﬁguration list response. This value is present if it was sent
in the request.

Type: String

Ancestor: ListMetricsConfigurationResult

NextContinuationToken The marker used to continue a metrics conﬁguration listing

that has been truncated. Use the NextContinuationToken
from a previously truncated list response to continue the
listing. The continuation token is an opaque value that
Amazon S3 understands.

Type: String

Ancestor: ListMetricsConfigurationResult

ListMetricsConfigurationsResultThe list of metrics conﬁgurations for a bucket.

Type: Container

API Version 2006-03-01

1081
Amazon Simple Storage Service API Reference
List Bucket Metrics Conﬁgurations

Examples

Sample Request

GET /?metrics HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT
Authorization: signatureValue

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

1082
Amazon Simple Storage Service API Reference
List Bucket Metrics Conﬁgurations

<IsTruncated>false</IsTruncated>
</ListMetricsConfigurationsResult>

Related Resources

• PUT Bucket metrics (p. 1170)

• DELETE Bucket metrics (p. 911)
• GET Bucket metrics (p. 1004)
• Monitoring Metrics with Amazon CloudWatch in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

1083
Amazon Simple Storage Service API Reference
List Multipart Uploads

List Multipart Uploads

Description

For more information on multipart uploads, see Uploading Objects Using Multipart Upload in the
Amazon Simple Storage Service Developer Guide.

For information on permissions required to use the multipart upload API, see Multipart Upload API and
Permissions in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

GET /?uploads HTTP/1.1

Host: BucketName.s3.amazonaws.com

API Version 2006-03-01

1084
Amazon Simple Storage Service API Reference
List Multipart Uploads

Date: Date
Authorization: authorization string

Request Parameters

Parameter Description Required

delimiter Character you use to group keys. No

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.

Type: String

encoding-type Requests Amazon S3 to encode the response and speciﬁes the No

encoding method to use.

An object key can contain any Unicode character; however, XML 1.0
parser cannot parse some characters, such as characters with an ASCII
value from 0 to 10. For characters that are not supported in XML 1.0,
you can add this parameter to request that Amazon S3 encode the
keys in the response.

Type: String

Default: None

Valid value: url

max-uploads Sets the maximum number of multipart uploads, from 1 to 1,000, No

to return in the response body. 1,000 is the maximum number of
uploads that can be returned in a response.

Type: Integer

Default: 1,000

key-marker Together with upload-id-marker, this parameter speciﬁes the No

multipart upload after which listing should begin.

If upload-id-marker is not speciﬁed, only the keys

lexicographically greater than the speciﬁed key-marker will be
included in the list.

If upload-id-marker is speciﬁed, 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
speciﬁed upload-id-marker.

API Version 2006-03-01

1085
Amazon Simple Storage Service API Reference
List Multipart Uploads

Parameter Description Required

Type: String

prefix Lists in-progress uploads only for those keys that begin with the No
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.)

Type: String

upload-id- Together with key-marker, speciﬁes the multipart upload after No

marker which listing should begin. If key-marker is not speciﬁed, 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
speciﬁed upload-id-marker.

Type: String

Request Headers

This operation uses only Request Headers common to most requests. For more information, see Common
Request Headers (p. 779).

Request Elements

This operation does not use request elements.

Responses

Response Headers

API Version 2006-03-01

1086
Amazon Simple Storage Service API Reference
List Multipart Uploads

This operation uses only response headers that are common to most responses. For more information,
see Common Response Headers (p. 782).

Response Elements

Name Description

ListMultipartUploadsResult Container for the response.

Children: Bucket, KeyMarker, UploadIdMarker,

NextKeyMarker, NextUploadIdMarker, MaxUploads,
Delimiter, Prefix, CommonPrefixes, IsTruncated

Type: Container

Ancestor: None

Bucket Name of the bucket to which the multipart upload was

initiated.

Type: String

Ancestor: ListMultipartUploadsResult

KeyMarker The key at or after which the listing began.

Type: String

Ancestor: ListMultipartUploadsResult

UploadIdMarker Upload ID after which listing began.

Type: String

Ancestor: ListMultipartUploadsResult

NextKeyMarker When a list is truncated, this element speciﬁes the value that
should be used for the key-marker request parameter in a
subsequent request.

Type: String

Ancestor: ListMultipartUploadsResult

NextUploadIdMarker When a list is truncated, this element speciﬁes the value

that should be used for the upload-id-marker request
parameter in a subsequent request.

Type: String

Ancestor: ListMultipartUploadsResult

Encoding-Type Encoding type used by Amazon S3 to encode object key

names in the XML response.

API Version 2006-03-01

1087
Amazon Simple Storage Service API Reference
List Multipart Uploads

Name Description
If you specify encoding-type request parameter, Amazon
S3 includes this element in the response, and returns encoded
key name values in the following response elements:

Delimiter, KeyMarker, Prefix, NextKeyMarker, Key.

Type: String

Ancestor: ListBucketResult

MaxUploads Maximum number of multipart uploads that could have been

included in the response.

Type: Integer

Ancestor: ListMultipartUploadsResult

IsTruncated Indicates whether the returned list of multipart uploads

is truncated. A value of true indicates that the list was
truncated. The list can be truncated if the number of
multipart uploads exceeds the limit allowed or speciﬁed by
MaxUploads.

Type: Boolean

Ancestor: ListMultipartUploadsResult

Upload Container for elements related to a particular multipart

upload. A response can contain zero or more Upload
elements.

Type: Container

Children: Key, UploadId, InitiatorOwner,

StorageClass, Initiated

Ancestor: ListMultipartUploadsResult

Key Key of the object for which the multipart upload was
initiated.

Type: Integer

Ancestor: Upload

UploadId Upload ID that identiﬁes the multipart upload.

Type: Integer

Ancestor: Upload

API Version 2006-03-01

1088
Amazon Simple Storage Service API Reference
List Multipart Uploads

Name Description

Initiator Container element that identiﬁes who initiated the multipart

upload. If the initiator is an AWS account, this element
provides the same information as the Owner element. If the
initiator is an IAM User, then this element provides the user
ARN and display name.

Children: ID, DisplayName

Type: Container

Ancestor: Upload

ID If the principal is an AWS account, it provides the Canonical

User ID. If the principal is an IAM User, it provides a user ARN
value.

Type: String

Ancestor: Initiator, Owner

DisplayName Principal's name.

Type: String

Ancestor: Initiator , Owner

Owner Container element that identiﬁes the object owner, after

the object is created. If multipart upload is initiated by an
IAM user, this element provides a the parent account ID and
display name.

Type: Container

Children: ID, DisplayName

Ancestor: Upload

StorageClass The class of storage (STANDARD or REDUCED_REDUDANCY)

that will be used to store the object when the multipart
upload is complete.

Type: String

Ancestor: Upload

Initiated Date and time at which the multipart upload was initiated.

Type: Date

Ancestor: Upload

When a preﬁx is provided in the request, this ﬁeld contains

ListMultipartUploadsResult.Prefix
the specified prefix. The result contains only keys starting
with the specified prefix.

Type: String

Ancestor: ListMultipartUploadsResult

API Version 2006-03-01

1089
Amazon Simple Storage Service API Reference
List Multipart Uploads

Name Description

Delimiter Contains the delimiter you speciﬁed in the request. If you

don't specify a delimiter in your request, this element is
absent from the response.

Type: String

Ancestor: ListMultipartUploadsResult

CommonPrefixes If you specify a delimiter in the request, then the result

returns each distinct key preﬁx containing the delimiter in
a CommonPrefixes element. The distinct key preﬁxes are
returned in the Prefix child element.

Type: Container

Ancestor: ListMultipartUploadsResult

CommonPrefixes.Prefix If the request does not include the Prefix parameter,

then this element shows only the substring of the key that
precedes the ﬁrst occurrence of the delimiter character. These
keys are not returned anywhere else in the response.

If the request includes the Prefix parameter, then this

element shows the substring of the key from the beginning to
the ﬁrst occurrence of the delimiter after the preﬁx.

Type: String

Ancestor: CommonPrefixes

Examples

Sample Request

The following request lists three multipart uploads. The request speciﬁes the max-uploads request
parameter to set the maximum number of multipart uploads to return in the response body.

GET /?uploads&max-uploads=3 HTTP/1.1

Host: example-bucket.s3.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

API Version 2006-03-01

1090
Amazon Simple Storage Service API Reference
List Multipart Uploads

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

1091
Amazon Simple Storage Service API Reference
List Multipart Uploads

Sample Request Using the Delimiter and the Preﬁx Parameters

Assume you have a multipart upload in progress for the following keys in your bucket, example-
bucket.

photos/2006/January/sample.jpg

photos/2006/February/sample.jpg

photos/2006/March/sample.jpg

videos/2006/March/sample.wmv

sample.jpg

The following list multipart upload request speciﬁes the delimiter parameter with value "/".

GET /?uploads&delimiter=/ HTTP/1.1

Host: example-bucket.s3.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

The following sample response lists multipart uploads on the speciﬁed bucket, example-bucket.

The response returns multipart upload for the sample.jpg key in an <Upload> element.

However, because all the other keys contain the specified delimiter, a distinct substring, from the
beginning of the key to the first occurrence of the delimiter, from each of these keys is returned in a
<CommonPrefixes> element. The key substrings, photos/ and videos/, in the <CommonPrefixes>
element indicate that there are one or more in-progress multipart uploads with these key prefixes.

API Version 2006-03-01

1092
Amazon Simple Storage Service API Reference
List Multipart Uploads

<Bucket>example-bucket</Bucket>
<KeyMarker/>
<UploadIdMarker/>
<NextKeyMarker>sample.jpg</NextKeyMarker>

In addition to the delimiter parameter you can ﬁlter results by adding a prefix parameter as shown in
the following request.

GET /?uploads&delimiter=/&prefix=photos/2006/ HTTP/1.1

Host: example-bucket.s3.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

In this case the response will include only multipart uploads for keys that start with the specified prefix.
The value returned in the <CommonPrefixes> element is a substring from the beginning of the key to the
first occurrence of the specified delimiter after the prefix.

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

1093
Amazon Simple Storage Service API Reference
List Multipart Uploads

</CommonPrefixes>
<CommonPrefixes>
<Prefix>photos/2006/March/</Prefix>
</CommonPrefixes>
</ListMultipartUploadsResult>

Related Actions

• Initiate Multipart Upload (p. 1420)

• Upload Part (p. 1440)
• Complete Multipart Upload (p. 1413)
• Abort Multipart Upload (p. 1409)
• List Parts (p. 1432)

API Version 2006-03-01

1094
Amazon Simple Storage Service API Reference
PUT Bucket

PUT Bucket
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

Description

This implementation of the PUT operation creates a new bucket. To create a bucket, you must register
with Amazon S3 and have a valid AWS Access Key ID to authenticate requests. Anonymous requests are
never allowed to create buckets. By creating the bucket, you become the bucket owner.

Not every string is an acceptable bucket name. For information on bucket naming restrictions, see
Working with Amazon S3 Buckets.

By default, the bucket is created in the US East (N. Virginia) region. You can optionally specify a region in
the request body. You might choose a region to optimize latency, minimize costs, or address regulatory
requirements. For example, if you reside in Europe, you will probably ﬁnd it advantageous to create
buckets in the Europe (Ireland) region. For more information, see How to Select a Region for Your
Buckets.
Note
If you create a bucket in a region other than US East (N. Virginia) region, your application
must be able to handle 307 redirect. For more information, go to Virtual Hosting of Buckets in
Amazon Simple Storage Service Developer Guide.

• Specify a canned ACL using the x-amz-acl request header. For more information, see Canned ACL in
the Amazon Simple Storage Service Developer Guide.
• Specify access permissions explicitly using the x-amz-grant-read, x-amz-grant-write, x-amz-
grant-read-acp, x-amz-grant-write-acp, x-amz-grant-full-control headers. These
headers map to the set of permissions Amazon S3 supports in an ACL. For more information, go to
Access Control List (ACL) Overview in the Amazon Simple Storage Service Developer Guide.

Note
You can use either a canned ACL or specify access permissions explicitly. You cannot do both.

To create a new bucket with support for object lock, you can use the header x-amz-bucket-object-
lock-enabled. For more information, see Locking Objects Using Amazon S3 Object Lock.

Requests

API Version 2006-03-01

1095
Amazon Simple Storage Service API Reference
PUT Bucket

Syntax

PUT / HTTP/1.1
Host: BucketName.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<LocationConstraint>BucketRegion</LocationConstraint>
</CreateBucketConfiguration>

Note
The syntax shows some of the request headers. For a complete list, see the Request Headers
section.
Note
If you send your create bucket request to the s3.amazonaws.com endpoint, the request go
to the us-east-1 region. Accordingly, the signature calculations in Signature Version 4 must
use us-east-1 as region, even if the location constraint in the request speciﬁes another region
where the bucket is to be created.

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation can use the following request headers in addition to the request
headers common to all operations. Request headers are limited to 8 KB in size. For more information, see
Common Request Headers (p. 681).

When creating a bucket, you can grant permissions to individual AWS accounts or predeﬁned groups
deﬁned by Amazon S3. This results in creation of the Access Control List (ACL) on the bucket. For more
information, see Using ACLs. You have the following two ways to grant these permissions:

• Specify a canned ACL — Amazon S3 supports a set of predeﬁned ACLs, known as canned ACLs. Each
canned ACL has a predeﬁned set of grantees and permissions. For more information, go to Canned
ACL.

API Version 2006-03-01

1096
Amazon Simple Storage Service API Reference
PUT Bucket

Name Description Required

x-amz-acl The canned ACL to apply to the bucket you are creating. For more No
information, go to Canned ACL in the Amazon Simple Storage
Service Developer Guide.

Type: String

Valid Values: private | public-read | public-read-

write | aws-exec-read | authenticated-read |
bucket-owner-read | bucket-owner-full-control

• Enable object lock — When creating a bucket, you can use the below header to enable object lock on
the bucket . For more information, see Locking Objects Using Amazon S3 Object Lock.

Name Description Required

x-amz-- Allows requester to enable object lock on a bucket when set to No

object-lock- true.
enabled
Type: Boolean

Default: None

Constraints: None

• Specify access permissions explicitly — If you want to explicitly grant access permissions to specific
AWS accounts or groups, you use the following headers. Each of these headers maps to specific
permissions Amazon S3 supports in an ACL. For more information, go to Access Control List (ACL)
Overview. In the header value, you specify a list of grantees who get the specific permission

Name Description Required

x-amz-grant- Allows grantee to list the objects in the bucket. No

read
Type: String

Default: None

Constraints: None

x-amz-grant- Allows grantee to create, overwrite, and delete any object in the No
write bucket.

Type: String

Default: None

Constraints: None

API Version 2006-03-01

1097
Amazon Simple Storage Service API Reference
PUT Bucket

Name Description Required

x-amz-grant- Allows grantee to read the bucket ACL. No

read-acp
Type: String

Default: None

Constraints: None

x-amz-grant- Allows grantee to write the ACL for the applicable bucket. No
write-acp
Type: String

Default: None

Constraints: None

x-amz-grant- Allows grantee the READ, WRITE, READ_ACP, and WRITE_ACP No

full-control permissions on the bucket.

Type: String

Default: None

Constraints: None

You specify each grantee as a type=value pair, where the type can be one of the following::

• emailAddress — if value speciﬁed is the email address of an AWS account

• id — if value speciﬁed is the canonical user ID of an AWS account
• uri — if granting permission to a predeﬁned group.

For example, the following x-amz-grant-read header grants list objects permission to the AWS
accounts identiﬁed by their email addresses.

x-amz-grant-read: emailAddress="[email protected]", emailAddress="[email protected]"

For more information see, ACL Overview.

Request Elements

Name Description Required

CreateBucketConfiguration Container for bucket conﬁguration settings. No

Type: Container

Ancestor: None

API Version 2006-03-01

1098
Amazon Simple Storage Service API Reference
PUT Bucket

Name Description Required

LocationConstraint Speciﬁes the region where the bucket will be No

created. If you are creating a bucket on the US East
(N. Virginia) region (us-east-1), you do not need to
specify the location constraint.

Type: Enum

Valid Values: For a list of all the Amazon S3

supported location constraints by region, see
Regions and Endpoints in the AWS General
Reference.

Default: US East (N. Virginia) region

Ancestor: CreateBucketConﬁguration

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT

Location: /colorpictures
Content-Length: 0
Connection: close
Server: AmazonS3

Sample Request: Creating a bucket and conﬁguring access permissions explicitly

This request creates a bucket named colorpictures and grants WRITE permission to the AWS account
identiﬁed by an email address.

PUT HTTP/1.1
Host: colorpictures.s3.amazonaws.com

API Version 2006-03-01

1101
Amazon Simple Storage Service API Reference
PUT Bucket

x-amz-date: Sat, 07 Apr 2012 00:54:40 GMT

Authorization: authorization string
x-amz-grant-write: emailAddress="[email protected]", emailAddress="[email protected]"

Sample Response

HTTP/1.1 200 OK

Sample Request: Creating a bucket and and enabling Object Lock on it

This request creates a bucket named colorpictures and enables object lock on it.

PUT / HTTP/1.1
Host: colorpictures.s3.amazonaws.com
Date: Fri, 01 Mar 2019 12:00:00 GMT
Authorization: authorization string
x-amz-bucket-object-lock-enabled: true

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Fri, 01 Mar 2019 12:00:00 GMT
Location: /colorpictures
Content-Length: 0
Connection: close
Server: AmazonS3

Related Resources

• PUT Object (p. 1324)

API Version 2006-03-01

1102
Amazon Simple Storage Service API Reference
PUT Bucket

• DELETE Bucket (p. 891)

API Version 2006-03-01

1103
Amazon Simple Storage Service API Reference
PUT Bucket accelerate

PUT Bucket accelerate

Description

This implementation of the PUT operation uses the accelerate subresource to set the Transfer
Acceleration state of an existing bucket. Amazon S3 Transfer Acceleration is a bucket-level feature that
enables you to perform faster data transfers to Amazon S3.

To use this operation, you must have permission to perform the s3:PutAccelerateConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple
Storage Service Developer Guide.

The Transfer Acceleration state of a bucket can be set to one of the following two values:

• Enabled – Enables accelerated data transfers to the bucket.

• Suspended – Disables accelerated data transfers to the bucket.

The GET Bucket accelerate (p. 950) operation returns the transfer acceleration state of a bucket.

After setting the Transfer Acceleration state of a bucket to Enabled, it might take up to thirty minutes
before the data transfer rates to the bucket increase.

The name of the bucket used for Transfer Acceleration must be DNS-compliant and must not contain
periods (".").

For more information about transfer acceleration, see Transfer Acceleration in the Amazon Simple
Storage Service Developer Guide.

Requests

Syntax

API Version 2006-03-01

1104
Amazon Simple Storage Service API Reference
PUT Bucket accelerate

PUT /?accelerate HTTP/1.1

Host: bucketname.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Transfer acceleration configuration in the request body

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Body

In the request, you specify the acceleration configuration in the request body. The acceleration
configuration is specified as XML. The following is an example of an acceleration configuration used in a
request. The Status indicates whether to set the transfer acceleration state to Enabled or Suspended.

<AccelerateConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>transfer acceleration state</Status>
</AccelerateConfiguration>

The following table describes the XML elements in the acceleration conﬁguration:

Name Description Required

AccelerateConfiguration Container for setting the transfer acceleration state. Yes

Type: Container

Children: Status

Ancestor: None

API Version 2006-03-01

1105
Amazon Simple Storage Service API Reference
PUT Bucket accelerate

Name Description Required

Status Sets the transfer acceleration state of the bucket. Yes

Type: Enum

Valid Values: Enabled | Suspended

Ancestor: AccelerateConﬁguration

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

API Version 2006-03-01

1106
Amazon Simple Storage Service API Reference
PUT Bucket accelerate

Example 1: Add Transfer Acceleration Conﬁguration to Set Acceleration Status

The following is an example of a PUT /?accelerate request that enables transfer acceleration for the
bucket named examplebucket.

PUT /?accelerate HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Mon, 11 Apr 2016 12:00:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: length

<AccelerateConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
</AccelerateConfiguration>

The following is an example response:

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Mon, 11 Apr 2016 12:00:00 GMT
Content-Length: 0
Server: AmazonS3

Related Resources

• GET Bucket accelerate (p. 950)

• PUT Bucket (p. 1095)

API Version 2006-03-01

1107
Amazon Simple Storage Service API Reference
PUT Bucket acl

PUT Bucket acl

Description

This implementation of the PUT operation uses the acl subresource to set the permissions on an existing
bucket using access control lists (ACL). For more information, go to Using ACLs. To set the ACL of a
bucket, you must have WRITE_ACP permission.

You can use one of the following two ways to set a bucket's permissions:

• Specify the ACL in the request body

• Specify permissions using request headers

Note
You cannot specify access permission using both the body and the request headers.

Requests

Syntax

The following request shows the syntax for sending the ACL in the request body. If you want to use
headers to specify the permissions for the bucket, you cannot send the ACL in the request body. Instead,
see Request Headers section for a list of headers you can use.

PUT /?acl HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date

API Version 2006-03-01

1108
Amazon Simple Storage Service API Reference
PUT Bucket acl

Authorization: authorization string (see Authenticating Requests (AWS Signature Version

4))

<AccessControlPolicy>
<Owner>
<ID>ID</ID>
<DisplayName>EmailAddress</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser">
<ID>ID</ID>
<DisplayName>EmailAddress</DisplayName>
</Grantee>
<Permission>Permission</Permission>
</Grant>
...
</AccessControlList>
</AccessControlPolicy>

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

You can use the following request headers in addition to the Common Request Headers (p. 681).

These headers enable you to set access permissions using one of the following methods:

• Specify a canned ACL, or

• Specify the permission for each grantee explicitly

Amazon S3 supports a set of predefined ACLs, known as canned ACLs. Each canned ACL has a predefined
set of grantees and permissions. For more information, see Canned ACL. To grant access permissions by
specifying canned ACLs, you use the following header and specify the canned ACL name as its value. If
you use this header, you cannot use other access control specific headers in your request.

Name Description Required

x-amz-acl Sets the ACL of the bucket using the speciﬁed canned ACL. For No
more information, go to Canned ACL in the Amazon Simple Storage
Service Developer Guide.

Type: String

API Version 2006-03-01

1109
Amazon Simple Storage Service API Reference
PUT Bucket acl

Name Description Required

Valid Values: private | public-read | public-read-write |
authenticated-read

Default: private

If you need to grant individualized access permissions on a bucket, you can use the following "x-amz-
grant-permission" headers. When using these headers you specify explicit access permissions and
grantees (AWS accounts or a Amazon S3 groups) who will receive the permission. If you use these ACL
speciﬁc headers, you cannot use x-amz-acl header to set a canned ACL.
Note
Each of the following request headers maps to speciﬁc permissions Amazon S3 supports in an
ACL. For more information go to Access Control List (ACL) Overview.

Name Description Required

x-amz-grant- Allows the speciﬁed grantee(s) to list the objects in the bucket. No
read
Type: String

Default: None

Constraints: None

x-amz-grant- Allows the speciﬁed grantee(s) to create, overwrite, and delete any No
write object in the bucket.

Type: String

Default: None

Constraints: None

x-amz-grant- Allows the speciﬁed grantee(s) to read the bucket ACL. No

read-acp
Type: String

Default: None

Constraints: None

x-amz-grant- Allows the speciﬁed grantee(s) to write the ACL for the applicable No
write-acp bucket.

Type: String

Default: None

Constraints: None

x-amz-grant- Allows the speciﬁed grantee(s) the READ, WRITE, READ_ACP, and No
full-control WRITE_ACP permissions on the bucket.

Type: String

Default: None

Constraints: None

API Version 2006-03-01

1110
Amazon Simple Storage Service API Reference
PUT Bucket acl

For each of these headers, the value is a comma-separated list of one or more grantees. You specify each
grantee as a type=value pair, where the type can be one of the following:

• emailAddress — if value speciﬁed is the email address of an AWS account

• id — if value speciﬁed is the canonical User ID of an AWS account
• uri — if granting permission to a predeﬁned Amazon S3 group.

x-amz-grant-write: uri="http://acs.amazonaws.com/groups/s3/LogDelivery",
emailAddress="[email protected]", emailAddress="[email protected]"

For more information, go to Access Control List (ACL) Overview. For more information about bucket
logging, go to Server Access Logging.

Request Elements

If you decide to use the request body to specify an ACL, you must use the following elements.
Note
If you request the request body, you cannot use the request headers to set an ACL.

Name Description Required

READ_ACP

Ancestors:
AccessControlPolicy.AccessControlList.Grant

Grantee Values

You can specify the person (grantee) to whom you're assigning access rights (using request elements) in
the following ways:

• By the person's ID:

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser"><ID><replaceable>ID</replaceable></
ID><DisplayName><replaceable>GranteesEmail</replaceable></DisplayName>
</Grantee>

DisplayName is optional and ignored in the request.

• By Email address:

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="AmazonCustomerByEmail"><EmailAddress><replaceable>[email protected]</
replaceable></EmailAddress>lt;/Grantee>

The grantee is resolved to the CanonicalUser and, in a response to a GET Object acl request,
appears as the CanonicalUser.
• By URI:

API Version 2006-03-01

1112
Amazon Simple Storage Service API Reference
PUT Bucket acl

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="Group"><URI><replaceable>http://acs.amazonaws.com/groups/global/
AuthenticatedUsers</replaceable></URI></Grantee>

Responses

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

Response Elements

This operation does not return response elements.

Special Errors

This operation does not return special errors. For general information about Amazon S3 errors and a list
of error codes, see Error Responses (p. 685).

Examples

API Version 2006-03-01

1113
Amazon Simple Storage Service API Reference
PUT Bucket acl

Sample Request: Access permissions speciﬁed in the body

• Grant AllUsers group READ permission on the bucket.

PUT ?acl HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Content-Length: 1660
x-amz-date: Thu, 12 Apr 2012 20:04:21 GMT
Authorization: authorization string

API Version 2006-03-01

1114
Amazon Simple Storage Service API Reference
PUT Bucket acl

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: NxqO3PNiMHXXGwjgv15LLgUoAmPVmG0xtZw2sxePXLhpIvcyouXDrcQUaWWXcOK0
x-amz-request-id: C651BC9B4E1BD401
Date: Thu, 12 Apr 2012 20:04:28 GMT
Content-Length: 0
Server: AmazonS3

Sample Request: Access permissions speciﬁed using headers

Analytics configuration in the request body

Request Parameters

This implementation of PUT uses the parameter in the following table.

Parameter Description Required

id The ID identifying the analytics conﬁguration. This ID must Yes

match the request element id. Limited to 64 characters.

Type: String

Default: None

Valid Characters for id: a-z A-Z 0-9 - _ .

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

In the request, you must specify the analytics configuration in the request body, which is specified as
XML. The Examples section shows an example of an analytics configuration.

The following table describes the XML elements in the analytics conﬁguration:

Name Description Required

Contains the conﬁguration and any analyses for the

AnalyticsConfiguration Yes
analytics ﬁlter.

Type: Container

API Version 2006-03-01

1118
Amazon Simple Storage Service API Reference
PUT Bucket analytics

Name Description Required

Children: Id, Filter, StorageClassAnalysis

Ancestor: None

And A conjunction (logical AND) of predicates, which is No

used in evaluating an analytics ﬁlter. The operator
must have at least two predicates.

Type: String

Children: Prefix, Tag

Ancestor: Filter

Bucket The Amazon Resource Name (ARN) of the bucket Yes

where analytics results are published. This destination
bucket must be in the same region as the bucket used
for the analytics conﬁguration PUT.

Type: String

Ancestor: S3BucketDestination

BucketAccountId The ID of the account that owns the destination No

bucket where the analytics is published.

Although optional, we recommend that the value

be set to prevent problems if the destination bucket
ownership changes.

Type: String

Ancestor: S3BucketDestination

DataExport A container used to describe how data related to the No

storage class analysis should be exported.

Type: Container

Children: OutputSchemaVersion, Destination

Ancestor: StorageClassAnalysis

Destination Contains information about where to publish the Yes

analytics results.

Type: Container

Children: S3BucketDestination

Ancestor: DataExport

API Version 2006-03-01

1119
Amazon Simple Storage Service API Reference
PUT Bucket analytics

Name Description Required

Filter Speciﬁes an analytics ﬁlter. The analytics only includes No

objects that meet the filter's criteria. If no filter
is specified, all of the contents of the bucket are
included in the analysis.

Type: Container

Children: And

Ancestor: AnalyticsConfiguration

Format Speciﬁes the output format of the analytics results. Yes

Currently, Amazon S3 supports the comma-separated
value (CSV) format.

Name Description Required

Indicates that data related to access patterns will be

StorageClassAnalysis Yes
collected and made available to analyze the tradeoﬀs
between diﬀerent storage classes.

Type: Container

Children: DataExport

Ancestor: AnalyticsConfiguration

S3BucketDestinationContains the bucket ARN, ﬁle format, bucket owner Yes

(optional), and preﬁx (optional) where analytics results
are published.

Type: Container

Children: Format, BucketAccountId, Bucket,

Prefix

Ancestor: Destination.

Tag The tag to use when evaluating an analytics ﬁlter. No

Type: Container

Children: Key, Value

Ancestor: And

Value The value for a tag. Yes

Type: String

Ancestor: Tag

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

API Version 2006-03-01

1121
Amazon Simple Storage Service API Reference
PUT Bucket analytics

Response Elements

This implementation of the operation does not return response elements.

Special Errors

Amazon S3 checks the validity of the proposed AnalyticsConfiguration element and veriﬁes
whether the proposed conﬁguration is valid when you call the PUT operation. The following table lists
the errors and possible causes.

HTTP Error Code Cause

HTTP 400 Bad InvalidArgument Invalid argument.

Request

HTTP 400 Bad TooManyConﬁgurations

You are attempting to create a new conﬁguration but have
Request already reached the 1,000-conﬁguration limit.

HTTP 403 AccessDenied You are not the owner of the speciﬁed bucket, or you do
Forbidden not have the s3:PutAnalyticsConfiguration bucket
permission to set the conﬁguration on the bucket.

For general information about Amazon S3 errors and a list of error codes, see Error Responses (p. 783).

Examples

Example 1: Creating an Analytics Conﬁguration

The following PUT request for the bucket examplebucket creates a new or replaces an existing
analytics configuration with the ID report1. The configuration is defined in the request body.

PUT /?analytics&id=report1 HTTP/1.1

API Version 2006-03-01

1122
Amazon Simple Storage Service API Reference
PUT Bucket analytics

Host: examplebucket.s3.amazonaws.com
Date: Mon, 31 Oct 2016 12:00:00 GMT
Authorization: authorization string
Content-Length: length

<?xml version="1.0" encoding="UTF-8"?>

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Mon, 31 Oct 2016 12:00:00 GMT
Content-Length: 0
Server: AmazonS3

Related Resources

• GET Bucket analytics (p. 959)

• DELETE Bucket analytics (p. 894)
• List Bucket Analytics Conﬁgurations (p. 1067)

API Version 2006-03-01

1123
Amazon Simple Storage Service API Reference
PUT Bucket cors

PUT Bucket cors

Description

Sets the cors conﬁguration for your bucket. If the conﬁguration exists, Amazon S3 replaces it.

To use this operation, you must be allowed to perform the s3:PutBucketCORS action. By default, the
bucket owner has this permission and can grant it to others.

• The first CORSRule allows cross-origin PUT, POST and DELETE requests whose origin is http://
www.example.com origins. The rule also allows all headers in a pre-flight OPTIONS request through
the Access-Control-Request-Headers header. Therefore, in response to any pre-flight OPTIONS
request, Amazon S3 will return any requested headers.
• The second rule allows cross-origin GET requests from all the origins. The '*' wildcard character refers
to all origins.

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

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

The cors configuration also allows additional optional configuration parameters as shown in the
following cors configuration on a bucket. For example, this cors configuration allows cross-origin PUT
and POST requests from http://www.example.com.

API Version 2006-03-01

1124
Amazon Simple Storage Service API Reference
PUT Bucket cors

<CORSConfiguration>
<CORSRule>
<AllowedOrigin>http://www.example.com</AllowedOrigin>
<AllowedMethod>PUT</AllowedMethod>
<AllowedMethod>POST</AllowedMethod>
<AllowedMethod>DELETE</AllowedMethod>
<AllowedHeader>*</AllowedHeader>
<MaxAgeSeconds>3000</MaxAgeSeconds>
<ExposeHeader>x-amz-server-side-encryption</ExposeHeader>
</CORSRule>
</CORSConfiguration>

In the preceding conﬁguration, CORSRule includes the following additional optional parameters:

• 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.

For more information about CORS, go to Enabling Cross-Origin Resource Sharing in the Amazon Simple
Storage Service Developer Guide.

Requests

Syntax

PUT /?cors HTTP/1.1

Host: bucketname.s3.amazonaws.com

API Version 2006-03-01

1125
Amazon Simple Storage Service API Reference
PUT Bucket cors

Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))
Content-MD5: MD5

<CORSConfiguration>
<CORSRule>
<AllowedOrigin>Origin you want to allow cross-domain requests from</AllowedOrigin>
<AllowedOrigin>...</AllowedOrigin>
...
<AllowedMethod>HTTP method</AllowedMethod>
<AllowedMethod>...</AllowedMethod>
...
<MaxAgeSeconds>Time in seconds your browser to cache the pre-flight OPTIONS response
for a resource</MaxAgeSeconds>
<AllowedHeader>Headers that you want the browser to be allowed to send</AllowedHeader>
<AllowedHeader>...</AllowedHeader>
...
<ExposeHeader>Headers in the response that you want accessible from client
application</ExposeHeader>
<ExposeHeader>...</ExposeHeader>
...
</CORSRule>
<CORSRule>
...
</CORSRule>
...
</CORSConfiguration>

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Name Description Required

Content-MD5 The base64-encoded 128-bit MD5 digest of the data. This header Yes
must be used as a message integrity check to verify that the request
body was not corrupted in transit. For more information, go to RFC
1864.

Type: String

Default: None

API Version 2006-03-01

1126
Amazon Simple Storage Service API Reference
PUT Bucket cors

Request Elements

Name Description Required

CORSConfiguration Container for up to 100 CORSRules elements. Yes

Type: Container

Children: CORSRules

Ancestor: None

CORSRule A set of origins and methods (cross-origin access that Yes

you want to allow). You can add up to 100 rules to the
conﬁguration.

Type: Container

Children: AllowedOrigin, AllowedMethod,

MaxAgeSeconds, ExposeHeader, ID.

Ancestor: CORSConfiguration

ID A unique identiﬁer for the rule. The ID value can be up to No

255 characters long. The IDs help you ﬁnd a rule in the
conﬁguration.

Type: String

Ancestor: CORSRule

AllowedMethod An HTTP method that you want to allow the origin to Yes
execute.

Each CORSRule must identify at least one origin and one

method.

Type: Enum (GET, PUT, HEAD, POST, DELETE)

Ancestor: CORSRule

AllowedOrigin An origin that you want to allow cross-domain requests from. Yes
This can contain at most one * wild character.

Each CORSRule must identify at least one origin and one

method.

The origin value can include at most one '*' wild character. For
example, "http://*.example.com". You can also specify only *
as the origin value allowing all origins cross-domain access.

Type: String

Ancestor: CORSRule

API Version 2006-03-01

1127
Amazon Simple Storage Service API Reference
PUT Bucket cors

Name Description Required

AllowedHeader Speciﬁes which headers are allowed in a pre-ﬂight OPTIONS No

request via the Access-Control-Request-Headers
header. Each header name speciﬁed in the Access-
Control-Request-Headers header must have a
corresponding entry in the rule. Amazon S3 will send only the
allowed headers in a response that were requested.

This can contain at most one * wild character.

Type: String

Ancestor: CORSRule

MaxAgeSeconds The time in seconds that your browser is to cache the No

preﬂight response for the speciﬁed resource.

A CORSRule can have at most one MaxAgeSeconds element.

Type: Integer (seconds)

Ancestor: CORSRule

ExposeHeader One or more headers in the response that you want No

customers to be able to access from their applications (for
example, from a JavaScript XMLHttpRequest object).

You add one ExposeHeader element in the rule for each

header.

Type: String

Ancestor: CORSRule

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

API Version 2006-03-01

1128
Amazon Simple Storage Service API Reference
PUT Bucket cors

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

The following examples add the cors subresource to a bucket.

Example : Conﬁgure cors

Sample Request

The following PUT request adds the cors subresource to a bucket (examplebucket).

PUT /?cors HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Tue, 21 Aug 2012 17:54:50 GMT
Content-MD5: 8dYiLewFWZyGgV2Q5FNI4W==
Authorization: authorization string
Content-Length: 216

API Version 2006-03-01

1129
Amazon Simple Storage Service API Reference
PUT Bucket cors

<AllowedOrigin>http://www.example.com</AllowedOrigin>
<AllowedMethod>PUT</AllowedMethod>
<AllowedMethod>POST</AllowedMethod>
<AllowedMethod>DELETE</AllowedMethod>
<AllowedHeader>*</AllowedHeader>
<MaxAgeSeconds>3000</MaxAgeSec>
<ExposeHeader>x-amz-server-side-encryption</ExposeHeader>
</CORSRule>
<CORSRule>
<AllowedOrigin>*</AllowedOrigin>
<AllowedMethod>GET</AllowedMethod>
<AllowedHeader>*</AllowedHeader>
<MaxAgeSeconds>3000</MaxAgeSeconds>
</CORSRule>
</CORSConfiguration>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: CCshOvbOPfxzhwOADyC4qHj/Ck3F9Q0viXKw3rivZ+GcBoZSOOahvEJfPisZB7B
x-amz-request-id: BDC4B83DF5096BBE
Date: Tue, 21 Aug 2012 17:54:50 GMT
Server: AmazonS3

Related Resources

• GET Bucket cors (p. 966)

• DELETE Bucket cors (p. 897)
• OPTIONS object (p. 1291)

API Version 2006-03-01

1130
Amazon Simple Storage Service API Reference
PUT Bucket encryption

PUT Bucket encryption

Description

This implementation of the PUT operation uses the encryption subresource to set the default
encryption state of an existing bucket.

This implementation of the PUT operation sets default encryption for a buckets using server-side
encryption with Amazon S3-managed keys SSE-S3 or AWS KMS-managed Keys (SSE-KMS) bucket. For
information about the Amazon S3 default encryption feature, see Amazon S3 Default Bucket Encryption
in the Amazon Simple Storage Service Developer Guide.
Important
This operation requires AWS Signature Version 4. For more information, see Authenticating
Requests (AWS Signature Version 4) (p. 792).

To use this operation, you must have permissions to perform the s3:PutEncryptionConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission
to others. For more information about permissions, see Permissions Related to Bucket Subresource
Operations and Managing Access Permissions to Your Amazon S3 Resources in the Amazon Simple
Storage Service Developer Guide.

Requests

Syntax

PUT /?encryption HTTP/1.1

Host: bucketname.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

API Version 2006-03-01

1131
Amazon Simple Storage Service API Reference
PUT Bucket encryption

default encryption configuration in the request body

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Body

In the request, you specify the encryption configuration in the request body. The encryption
configuration is specified as XML, as shown in the following examples that show setting encryption using
SSE-S3 or SSE-KMS.

The following is an example of the request body for setting SSE-S3.

The following is an example of the request body for setting SSE-KMS.

<ServerSideEncryptionConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<ApplyServerSideEncryptionByDefault>
<SSEAlgorithm>aws:kms</SSEAlgorithm>
<KMSMasterKeyID>arn:aws:kms:us-east-1:1234/5678example</KMSMasterKeyID>
</ApplyServerSideEncryptionByDefault>
</Rule>
</ServerSideEncryptionConfiguration>

The following table describes the XML elements in the encryption conﬁguration:

API Version 2006-03-01

1132
Amazon Simple Storage Service API Reference
PUT Bucket encryption

Name Description Required

Container for setting server-side encryption by

ApplyServerSideEncryptionByDefault No
default.

Type: Container

Children: SSEAlgorithm, KMSMasterKeyID

Ancestor: Rule

KMSMasterKeyID The AWS KMS master key ID used for the SSE-KMS No
encryption.

Type: String

Ancestor:
ApplyServerSideEncryptionByDefault

Constraint: Can only be used when you set the value

of SSEAlgorithm as aws:kms. The default aws/
s3 AWS KMS master key is used if this element is
absent while the SSEAlgorithm is aws:kms.

Rule Container for server-side encryption by default Yes

conﬁguration.

Type: Container

Children:
ApplyServerSideEncryptionByDefault

Ancestor:
ServerSideEncryptionConfiguration

Container for the server-side encryption by default

ServerSideEncryptionConfiguration Yes
conﬁguration rule.

Type: Container

Children: Rule

Ancestor: None

SSEAlgorithm The server-side encryption algorithm to use. Yes

Type: String

Valid Values: AES256, aws:kms

Ancestor:
ApplyServerSideEncryptionByDefault

Constraint: Can only be used when you use

ApplyServerSideEncryptionByDefault.

API Version 2006-03-01

1133
Amazon Simple Storage Service API Reference
PUT Bucket encryption

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Example 1: Set the Default Encryption Conﬁguration for an S3 Bucket

The following is an example of a PUT /?encryption request that speciﬁes to use AWS KMS encryption.

API Version 2006-03-01

1134
Amazon Simple Storage Service API Reference
PUT Bucket encryption

PUT /?encryption HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Wed, 06 Sep 2017 12:00:00 GMT
Authorization: authorization string
Content-Length: length

<ServerSideEncryptionConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Rule>
<ApplyServerSideEncryptionByDefault>
<SSEAlgorithm>aws:kms</SSEAlgorithm>
<KMSMasterKeyID>arn:aws:kms:us-east-1:1234/5678example</KMSMasterKeyID>
</ApplyServerSideEncryptionByDefault>
</Rule>
</ServerSideEncryptionConfiguration>

The following is an example response:

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
x-amz-id-2: B3Z1w/R0GaUCDHStDVuoz+4NSndjUDYuE3jvJ5kvrDroucdFCygEQYEwpC0Lj0Cv
x-amz-request-id: E0DE682C2FDDBCF8
Date: Wed, 06 Sep 2017 12:00:00 GMT
Content-Length: 0
Server: AmazonS3

Related Resources

• GET Bucket encryption (p. 971)

• DELETE Bucket encryption (p. 900)

API Version 2006-03-01

1135
Amazon Simple Storage Service API Reference
PUT Bucket inventory

PUT Bucket inventory

This implementation of the PUT operation adds an inventory configuration (identified by the inventory
ID) to the bucket. You can have up to 1,000 inventory configurations per bucket.

When you configure an inventory for a source bucket, you specify the destination bucket where you
want the inventory to be stored, and whether to generate the inventory daily or weekly. You can also
configure what object metadata to include and whether to inventory all object versions or only current
versions. For more information, see Amazon S3 Inventory in the Amazon Simple Storage Service Developer
Guide.
Important
You must create a bucket policy on the destination bucket to grant permissions to Amazon
S3 to write objects to the bucket in the defined location. For an example policy, see Granting
Permissions for Amazon S3 Inventory and Storage Class Analysis.

Syntax

PUT /?inventory&id=configuration-ID HTTP/1.1

API Version 2006-03-01

1136
Amazon Simple Storage Service API Reference
PUT Bucket inventory

Host: bucketname.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Inventory configuration in the request body

Request Parameters

This implementation of PUT uses the parameter in the following table.

Parameter Description Required

id The ID identifying the inventory conﬁguration. This ID must Yes

match the request element id. Limited to 64 characters.

Type: String

Default: None

Valid Characters for id: a-z A-Z 0-9 - _ .

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

In the request, you must specify the inventory configuration in the request body, which is specified as
XML. The Examples section shows an example of an inventory configuration.

The following table describes the XML elements in the inventory conﬁguration:

Name Description Required

AccountId The ID of the account that owns the destination No

bucket.

API Version 2006-03-01

1137
Amazon Simple Storage Service API Reference
PUT Bucket inventory

Name Description Required

Although optional, we recommend that the value
be set to prevent problems if the destination bucket
ownership changes.

Type: String

Ancestor: S3BucketDestination

Bucket The Amazon Resource Name (ARN) of the bucket Yes

where inventory results are published. This destination
bucket must be in the same AWS Region as the source
bucket.

Type: String

Ancestor: S3BucketDestination

Destination Contains information about where to publish the Yes

inventory results.

Type: Container

Children: S3BucketDestination

Ancestor: InventoryConfiguration

Encryption Contains the type of server-side encryption to use to No

encrypt the inventory.

Type: Container

Children: SSE-KMS, SSE-S3

Ancestor: S3BucketDestination

Field Contains the optional ﬁelds that are included in the No

inventory results. Multiple Field elements can be
contained in OptionalFields.

Type: String

Ancestor: OptionalFields

Valid values: Size, LastModifiedDate,

StorageClass, ETag, IsMultipartUploaded,
ReplicationStatus, EncryptionStatus,
ObjectLockRetainUntilDate, ObjectLockMode,
ObjectLockLegalHoldStatus

Filter Speciﬁes an inventory ﬁlter. The inventory only No

includes objects that meet the filter's criteria. If no
filter is specified, all of the contents of the bucket are
inventoried.

Type: Container

Children: Prefix

Ancestor: InventoryConfiguration

API Version 2006-03-01

1138
Amazon Simple Storage Service API Reference
PUT Bucket inventory

Name Description Required

Format Speciﬁes the output format of the inventory results. Yes

Currently, Amazon S3 supports the comma-separated
values (CSV) format, the Apache optimized row
columnar (ORC) format, and the Apache Parquet
(Parquet) format.

Type: String

Ancestor: S3BucketDestination

Valid values: CSV, ORC, or Parquet

Frequency Speciﬁes how frequently inventory results are Yes

produced.

Contains the inventory conﬁguration.

InventoryConfiguration Yes

Type: Container

Children: Id, IsEnabled, Filter, Destination,

Schedule, IncludedObjectVersions, and
OptionalFields elements.

Ancestor: None

API Version 2006-03-01

1139
Amazon Simple Storage Service API Reference
PUT Bucket inventory

Name Description Required

IsEnabled Speciﬁes whether the inventory is enabled or disabled. Yes

If set to True, inventory results are generated. If set to

False, no inventory is generated.

Type: String

Ancestor: InventoryConfiguration

Valid values: True or False

KeyId The AWS KMS customer master key (CMK) used to No

encrypt the inventory ﬁle.

Type: String

Ancestor: SSE-KMS

Valid values: ARN of the CMK

OptionalFields Contains the optional ﬁelds that are included in the No

inventory results.

Type: Container

Children: Field

Ancestor: InventoryConfiguration

Prefix The preﬁx that an object must have to be included in No

the inventory results.

Type: String

Ancestor: Filter

Prefix The preﬁx that is prepended to all inventory results. No

Type: String

Ancestor: S3BucketDestination

Schedule Contains the frequency for generating inventory Yes

results.

Type: Container

Children: Frequency

Ancestor: Destination

API Version 2006-03-01

Children: Format, AccountId, Bucket, Prefix,

Encryption

Ancestor: Destination

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

API Version 2006-03-01

1141
Amazon Simple Storage Service API Reference
PUT Bucket inventory

Response Elements

This implementation of the operation does not return response elements.

Special Errors

Amazon S3 checks the validity of the proposed InventoryConfiguration element and veriﬁes
whether the proposed conﬁguration is valid when you call the PUT operation. The following table lists
the errors and possible causes.

HTTP Error Code Cause

HTTP 400 Bad InvalidArgument Invalid argument.

Request

HTTP 400 Bad TooManyConﬁgurations

You are attempting to create a new conﬁguration but have
Request already reached the 1,000-conﬁguration limit.

HTTP 403 AccessDenied You are not the owner of the speciﬁed bucket, or you do
Forbidden not have the s3:PutInventoryConfiguration bucket
permission to set the conﬁguration on the bucket.

For general information about Amazon S3 errors and a list of error codes, see Error Responses (p. 783).

Examples

Example 1: Creating an Inventory Conﬁguration

The following PUT request for the bucket examplebucket creates a new or replaces an existing
inventory configuration with the ID report1. The configuration is defined in the request body.

PUT /?inventory&id=report1 HTTP/1.1

API Version 2006-03-01

1142
Amazon Simple Storage Service API Reference
PUT Bucket inventory

Host: examplebucket.s3.amazonaws.com
Date: Mon, 31 Oct 2016 12:00:00 GMT
Authorization: authorization string
Content-Length: length

<?xml version="1.0" encoding="UTF-8"?>

<InventoryConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>report1</Id>
<IsEnabled>true</IsEnabled>
<Filter>
<Prefix>filterPrefix/</Prefix>
</Filter>
<Destination>
<S3BucketDestination>
<Format>CSV</Format>
<AccountId>123456789012</AccountId>
<Bucket>arn:aws:s3:::destination-bucket</Bucket>
<Prefix>prefix1</Prefix>
<Encryption>
<SSE-KMS>
<KeyId>arn:aws:kms:us-
west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab</KeyId>
</SSE-KMS>
</Encryption>
</S3BucketDestination>
</Destination>
<Schedule>
<Frequency>Daily</Frequency>
</Schedule>
<IncludedObjectVersions>All</IncludedObjectVersions>
<OptionalFields>
<Field>Size</Field>
<Field>LastModifiedDate</Field>
<Field>ETag</Field>
<Field>StorageClass</Field>
<Field>IsMultipartUploaded</Field>
<Field>ReplicationStatus</Field>
<Field>EncryptionStatus</Field>
<Field>ObjectLockRetainUntilDate</Field>
<Field>ObjectLockMode</Field>
<Field>ObjectLockLegalHoldStatus</Field>
</OptionalFields>
</InventoryConfiguration>

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Mon, 31 Oct 2016 12:00:00 GMT
Content-Length: 0
Server: AmazonS3

Related Resources

• GET Bucket Inventory (p. 976)

API Version 2006-03-01

1143
Amazon Simple Storage Service API Reference
PUT Bucket inventory

• DELETE Bucket inventory (p. 903)

• List Bucket Inventory Conﬁgurations (p. 1073)

API Version 2006-03-01

1144
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle

PUT Bucket lifecycle

Description

Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration. For
information about lifecycle configuration, go to Object Lifecycle Management in the Amazon Simple
Storage Service Developer Guide.
Note
Bucket lifecycle configuration now supports specifying a lifecycle rule using an object key name
prefix, one or more object tags, or a combination of both. Accordingly, this section describes the
latest API. The previous version of the API supported filtering based only on an object key name
prefix, which is supported for backward compatibility. For the related API description, see PUT
Bucket lifecycle (Deprecated) (p. 1514).

Permissions

• s3:DeleteObject
• s3:DeleteObjectVersion
• s3:PutLifecycleConfiguration

For more information about permissions, see Managing Access Permissions to Your Amazon S3 Resources
in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

1145
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle

Requests

Syntax

PUT /?lifecycle HTTP/1.1

Host: bucketname.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string
Content-MD5: MD5

Lifecycle configuration in the request body

For details about authorization string, see Authenticating Requests (AWS Signature Version
4) (p. 792).

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Name Description Required

Content-MD5 The base64-encoded 128-bit MD5 digest of the Yes

data. This header must be used as a message
integrity check to verify that the request body was
not corrupted in transit. For more information, see
RFC 1864.

Type: String

API Version 2006-03-01

1146
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle

Name Description Required

Default: None

Request Body

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:

For example,

<LifecycleConfiguration>
<Rule>
<Filter>
<Prefix>key-prefix</Prefix>
</Filter>
<Status>rule-status</Status>
One or more Transition/Expiration lifecycle actions.
</Rule>
</LifecycleConfiguration>

For more information, see Object Lifecycle Management in the Amazon Simple Storage Service Developer
Guide.

For more information, see Lifecycle Conﬁguration Elements in the Amazon Simple Storage Service
Developer Guide.

The following table describes the XML elements in the lifecycle conﬁguration:

API Version 2006-03-01

1147
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle

Name Description Required

Container for specifying when an incomplete

AbortIncompleteMultipartUpload Yes, if no
multipart upload becomes eligible for an abort other action
operation. is speciﬁed
for the rule.
When you specify this lifecycle action, the rule
cannot specify a tag-based ﬁlter.

For more information, see Lifecycle Conﬁguration

Elements in the Amazon Simple Storage Service
Developer Guide.

Child: DaysAfterInitiation

Type: Container

Ancestor: Rule.

And Container for specify rule filters. These filters Yes, if you
determine the subset of objects to which the rule specify
applies. more than
one filter
Type: String condition
(for
Ancestor: Rule example,
one prefix
and one or
more tags).

Date Date when you want Amazon S3 to take the Yes, if

action. For more information, see Lifecycle Rules: Days and
Based on a Speciﬁc Date in the Amazon Simple ExpiredObjectDeleteMa
Storage Service Developer Guide. are absent.

The date value must conform to the ISO 8601

format. The time is always midnight UTC.

Type: String

Ancestor: Expiration or Transition

Days Speciﬁes the number of days after object creation Yes, if

when the speciﬁc rule action takes eﬀect. Date and
ExpiredObjectDeleteMa
Type: Nonnegative Integer when used with are absent.
Transition, Positive Integer when used with
Expiration.

Ancestor: Expiration, Transition.

DaysAfterInitiation Speciﬁes the number of days after initiating a Yes, if

multipart upload when the multipart upload ancestor is
must be completed. If it does not complete by speciﬁed.
the speciﬁed number of days, it becomes eligible
for an abort operation and Amazon S3 aborts the
incomplete multipart upload.

Type: Positive Integer.

API Version 2006-03-01

1148
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle

Name Description Required

Ancestor:
AbortIncompleteMultipartUpload.

Expiration This action speciﬁes a period in an object's Yes, if no

lifetime when Amazon S3 should take the other action
appropriate expiration action. The action Amazon is present in
S3 takes depends on whether the bucket is the Rule.
versioning-enabled.

• If versioning has never been enabled on the

bucket, Amazon S3 deletes the only copy of the
object permanently.
• Otherwise, if your bucket is versioning-enabled
(or versioning is suspended), the action applies
only to the current version of the object. A
versioning-enabled bucket can have many
versions of the same object, one current
version, and zero or more noncurrent versions.

Instead of deleting the current version, Amazon

S3 makes it a noncurrent version by adding a
delete marker as the new current version.
Important
If your bucket state is versioning-
suspended, Amazon S3 creates a
delete marker with version ID null.
If you have a version with version ID
null, then Amazon S3 overwrites that
version.
Note
To set expiration for noncurrent
objects, you must use the
NoncurrentVersionExpiration
action.

Type: Container

Children: Days or Date

Ancestor: Rule

Filter Container for elements that describe the ﬁlter Yes

identifying a subset of objects to which the
lifecycle rule applies. If you specify an empty
ﬁlter (<Filter></Filter>), the rule applies to
all objects in the bucket.

Type: String

Children: Preﬁx, Tag

Ancestor: Rule

API Version 2006-03-01

1149
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle

Name Description Required

ID Unique identiﬁer for the rule. The value cannot No

be longer than 255 characters.

Type: String

Ancestor: Rule

Key Specifies the key of a tag. A tag key can be up to Yes, if <Tag>
128 Unicode characters in length. parent is
specified.
Tag keys that you specify in a lifecycle rule filter
must be unique.

For more information, see Object Tagging in the

Amazon Simple Storage Service Developer Guide.

Type: String

Ancestor: Tag

LifecycleConfiguration Container for lifecycle rules. You can add as many Yes
as 1,000 rules.

Type: Container

Children: Rule

Ancestor: None

ExpiredObjectDeleteMarker On a versioned bucket (versioning-enabled or Yes, if Date

versioning-suspended bucket), you can add and Days
this element in the lifecycle conﬁguration to are absent.
direct Amazon S3 to delete expired object
delete markers. For an example, see Example 7:
Removing Expired Object Delete Markers in the
Amazon Simple Storage Service Developer Guide.
On a nonversioned bucket, adding this element
in a policy is meaningless because you cannot
have delete markers and the element doesn't do
anything.

For more information, see Lifecycle Conﬁguration

Elements in the Amazon Simple Storage Service
Developer Guide.

When you specify this lifecycle action, the rule

cannot specify a tag-based ﬁlter.

Type: String

Valid values: true | false (the value false is

allowed, but it is no-op and Amazon S3 does not
take action if the value is false)

Ancestor: Expiration.

API Version 2006-03-01

1150
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle

Name Description Required

NoncurrentDays Speciﬁes the number of days an object is Yes

Type: Nonnegative Integer when used

with NoncurrentVersionTransition,
Positive Integer when used with
NoncurrentVersionExpiration.

Ancestor: NoncurrentVersionExpiration or
NoncurrentVersionTransition

NoncurrentVersionExpiration Speciﬁes when noncurrent object versions expire. Yes, if no

Upon expiration, Amazon S3 permanently deletes other action
the noncurrent object versions. is present in
the Rule.
You set this lifecycle conﬁguration action
on a bucket that has versioning enabled (or
suspended) to request that Amazon S3 delete
noncurrent object versions at a speciﬁc period in
the object's lifetime.

Type: Container

Children: NoncurrentDays

Ancestor: Rule

NoncurrentVersionTransition Container for the transition rule that Yes, if no

describes when noncurrent objects transition other action
to the STANDARD_IA, ONEZONE_IA, is present in
INTELLIGENT_TIERING, GLACIER or the Rule.
DEEP_ARCHIVE storage class.

If your bucket is versioning-enabled (or versioning

is suspended), you can set this action to request
that Amazon S3 transition noncurrent object
versions at a speciﬁc period in the object's
lifetime.

Type: Container

Children: NoncurrentDays and StorageClass

Ancestor: Rule

API Version 2006-03-01

1151
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle

Name Description Required

Prefix Object key preﬁx identifying one or more No

objects to which the rule applies. Empty prefix
(<Prefix></Prefix>) indicates there is no filter
based on key prefix.

There can be at most one Prefix in a lifecycle

rule Filter.

Type: String

Ancestor: Filter or And (if you specify multiple

ﬁlters such as a preﬁx and one or more tags).

Rule Container for a lifecycle rule. A lifecycle Yes

conﬁguration can contain as many as 1,000 rules.

Type: Container

Ancestor: LifecycleConfiguration

Status If Enabled, Amazon S3 executes the rule as Yes

scheduled. If Disabled, Amazon S3 ignores the
rule.

Type: String

Ancestor: Rule

Valid values: Enabled, Disabled.

StorageClass Speciﬁes the Amazon S3 storage class to which Yes

Tag Container for specifying a tag key and value. Each No

tag has a key and a value.

Type: Container

Children: Key and Value

Ancestor: Filter or And (if you specify multiple

ﬁlters such as a preﬁx and one or more tags).

API Version 2006-03-01

1152
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle

Name Description Required

Transition This action speciﬁes a period in the objects' Yes, if no

lifetime when Amazon S3 should transition other action
them to the STANDARD_IA, ONEZONE_IA, is present in
INTELLIGENT_TIERING, GLACIER, or the the Rule.
DEEP_ARCHIVE storage class. When this action
is in eﬀect, what Amazon S3 does depends on
whether the bucket is versioning-enabled.

• If versioning has never been enabled on the

bucket, Amazon S3 transitions the only copy of
the object to the speciﬁed storage class.
• Otherwise, when your bucket is versioning-
enabled (or versioning is suspended), Amazon
S3 transitions only the current versions of
objects identiﬁed in the rule.
Note
A versioning-enabled bucket can have
many versions of an object. This action
has no impact on the noncurrent
object versions. To transition
noncurrent objects, you must use the
NoncurrentVersionTransition
action.

Type: Container

Children: Days or Date, and StorageClass

Ancestor: Rule

Value Speciﬁes the value for a tag key. Each object tag Yes, if <Tag>
is a key-value pair. parent is
speciﬁed.
Tag value can be up to 256 Unicode characters in
length.

Type: String

Ancestor: Tag

Responses

API Version 2006-03-01

1153
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Example 1: Add lifecycle conﬁguration - bucket not versioning-enabled

The following lifecycle conﬁguration speciﬁes two rules, each with one action.

API Version 2006-03-01

1154
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle

The following is a sample PUT /?lifecycle request that adds the preceding lifecycle conﬁguration to
the examplebucket bucket.

PUT /?lifecycle HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Wed, 14 May 2014 02:11:21 GMT
Content-MD5: q6yJDlIkcBaGGfb3QLY69A==
Authorization: authorization string
Content-Length: 415

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: r+qR7+nhXtJDDIJ0JJYcd+1j5nM/rUFiiiZ/fNbDOsd3JUE8NWMLNHXmvPfwMpdc
x-amz-request-id: 9E26D08072A8EF9E

API Version 2006-03-01

1155
Amazon Simple Storage Service API Reference
PUT Bucket lifecycle

Date: Wed, 14 May 2014 02:11:22 GMT

Content-Length: 0
Server: AmazonS3

Example 2: Add lifecycle conﬁguration - bucket is versioning-enabled

• The NoncurrentVersionExpiration action requests Amazon S3 to expire noncurrent versions of

The following is a sample PUT /?lifecycle request that adds the preceding lifecycle conﬁguration to
the examplebucket bucket.

PUT /?lifecycle HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Wed, 14 May 2014 02:21:48 GMT
Content-MD5: 96rxH9mDqVNKkaZDddgnw==
Authorization: authorization string
Content-Length: 598

<LifeCycleConfiguration>
<Rule>
<ID>DeleteAfterBecomingNonCurrent</ID>
<Filter>
<Prefix>logs/</Prefix>

API Version 2006-03-01

1156
Amazon Simple Storage Service API Reference
PUT PublicAccessBlock

</Filter>
<Status>Enabled</Status>
<NoncurrentVersionExpiration>
<NoncurrentDays>1</NoncurrentDays>
</NoncurrentVersionExpiration>
</Rule>
<Rule>
<ID>TransitionSoonAfterBecomingNonCurrent</ID>
<Filter>
<Prefix>documents/</Prefix>
</Filter>
<Status>Enabled</Status>
<NoncurrentVersionTransition>
<NoncurrentDays>0</NoncurrentDays>
<StorageClass>GLACIER</StorageClass>
</NoncurrentVersionTransition>
</Rule>
</LifeCycleConfiguration>

The following is a sample response.

Additional Examples

Lifecycle conﬁguration topic in the developer guide provides additional examples. For more information,
go to Examples of Lifecycle Conﬁguration.

Related Resources

• GET Bucket lifecycle (p. 983)

• DELETE Bucket lifecycle (p. 906)

PUT PublicAccessBlock
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

API Version 2006-03-01

1157
Amazon Simple Storage Service API Reference
PUT PublicAccessBlock

Description

This operation creates or modifies the PublicAccessBlock configuration for an Amazon S3 bucket.
In order to use this operation, you must have the s3:PutBucketPublicAccessBlock permission. For
more information about Amazon S3 permissions, see Specifying Permissions in a Policy in the Amazon
Simple Storage Service Developer Guide.
Important
When Amazon S3 evaluates the PublicAccessBlock configuration for a bucket or an object, it
checks the PublicAccessBlock configuration for both the bucket (or the bucket that contains
the object) and the bucket owner's account. If the PublicAccessBlock configurations are
different between the bucket and the account, Amazon S3 uses the most restrictive combination
of the bucket-level and account-level settings.

For more information about when Amazon S3 considers a bucket or an object public, see The Meaning of
"Public" in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

PUT /<bucket-name>?publicAccessBlock HTTP/1.1

Host: <bucket-name>.s3.amazonaws.com
x-amz-date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization string> (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This operation does not use request parameters.

API Version 2006-03-01

1158
Amazon Simple Storage Service API Reference
PUT PublicAccessBlock

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This operation uses the following request elements. You can enable BlockPublicAcls,
IgnorePublicAcls, BlockPublicPolicy, and RestrictPublicBuckets in any combination.

Name Description Required

A PublicAccessBlock conﬁguration.
PublicAccessBlockConfiguration Yes

Type: Container

Children: BlockPublicAcls, IgnorePublicAcls,

BlockPublicPolicy, RestrictPublicBuckets

BlockPublicAcls Speciﬁes whether Amazon S3 should block public access control No

lists (ACLs) for this bucket. Setting this element to TRUE causes the
following behavior:

• PUT Bucket acl (p. 1108) and PUT Object acl (p. 1363) calls fail if
the speciﬁed ACL is public.
• PUT Object (p. 1324) calls fail if the request includes a public ACL.

Important
Enabling this setting doesn't aﬀect existing policies or ACLs.

Type: Boolean

Ancestor: PublicAccessBlockConfiguration

Valid values: TRUE | FALSE

IgnorePublicAclsSpeciﬁes whether Amazon S3 should ignore public ACLs for this No

bucket. Setting this element to TRUE causes Amazon S3 to ignore all
public ACLs on this bucket and any objects that it contains.
Important
Enabling this setting doesn't aﬀect the persistence of any
existing ACLs and doesn't prevent new public ACLs from
being set.

Type: Boolean

Responses

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

API Version 2006-03-01

1160
Amazon Simple Storage Service API Reference
PUT PublicAccessBlock

Response Elements

1163
Amazon Simple Storage Service API Reference
PUT Bucket logging

PUT Bucket logging

This implementation of the PUT operation uses the logging subresource to set the logging parameters
for a bucket and to specify permissions for who can view and modify the logging parameters. All logs are
saved to buckets in the same AWS Region as the source bucket. To set the logging status of a bucket, you
must be the bucket owner.

To enable logging, you use LoggingEnabled and its children request elements. To disable logging, you
use an empty BucketLoggingStatus request element:

<BucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01" />

For more information about server access logging, see Server Access Logging in the Amazon Simple
Storage Service Developer Guide.

For more information about creating a bucket, see PUT Bucket (p. 1095). For more information about
returning the logging status of a bucket, see GET Bucket logging (p. 1000).

Syntax

PUT /?logging HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

API Version 2006-03-01

1164
Amazon Simple Storage Service API Reference
PUT Bucket logging

Request elements vary depending on what you're setting.

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

Name Description Required

BucketLoggingStatus Container for logging status information. Yes

Type: Container

Children: LoggingEnabled

Ancestry: None

EmailAddress Email address of the person being granted logging No

permissions.

Type: String

Children: None

Ancestry:
BucketLoggingStatus.LoggingEnabled.TargetGrants.Grant.Grantee

Grant Container for the grantee and his/her logging permissions. No

Type: Container

Children: Grantee, Permission

Ancestry:
BucketLoggingStatus.LoggingEnabled.TargetGrants

API Version 2006-03-01

1165
Amazon Simple Storage Service API Reference
PUT Bucket logging

Name Description Required

Grantee Container for EmailAddress of the person being granted No

logging permissions. For more information, see Grantee
Values (p. 1167).

Type: Container

Children: EmailAddress

Ancestry:
BucketLoggingStatus.LoggingEnabled.TargetGrants.Grant

LoggingEnabled Container for logging information. This element is present No

when you are enabling logging (and not present when you are
disabling logging).

Type: Container

Children: Grant, TargetBucket, TargetPrefix

Ancestry: BucketLoggingStatus

Permission Logging permissions given to the Grantee for the bucket. The No
bucket owner is automatically granted FULL_CONTROL to all
logs delivered to the bucket. This optional element enables
you to grant access to others.

Type: String

Valid Values: FULL_CONTROL | READ | WRITE

Children: None

Ancestry:
BucketLoggingStatus.LoggingEnabled.TargetGrants.Grant

TargetBucket Speciﬁes the bucket where you want Amazon S3 to store No

server access logs, which is the target bucket. The bucket
that's being logged is the source bucket. The target bucket
can be any bucket that you own that is in the same Region
as the source bucket, including the source bucket itself. You
can also configure multiple buckets to deliver their logs to the
same target bucket. In this case, you should choose a different
TargetPrefix for each source bucket so that the delivered
log files can be distinguished by key.

Type: String

Children: None

Ancestry: BucketLoggingStatus.LoggingEnabled

TargetGrants Container for granting information. No

Type: Container

Children: Grant, Permission

Ancestry: BucketLoggingStatus.LoggingEnabled

API Version 2006-03-01

1166
Amazon Simple Storage Service API Reference
PUT Bucket logging

Name Description Required

TargetPrefix This element lets you specify a prefix for the keys that the log Yes,
files will be stored under. if the
TargetBucket
Type: String element
is
Children: None specified.
Ancestry: BucketLoggingStatus.LoggingEnabled

Grantee Values

You can specify the person (grantee) to whom you're assigning access rights (using request elements) in
the following ways:

• By the person's ID:

DisplayName is optional and ignored in the request.

• By Email address:

The grantee is resolved to the CanonicalUser and, in a response to a GET Object acl request,
appears as the CanonicalUser.
• By URI:

Responses

API Version 2006-03-01

1167
Amazon Simple Storage Service API Reference
PUT Bucket logging

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

This request enables logging and gives the grantee of the bucket READ access to the logs.

PUT ?logging HTTP/1.1

Host: quotes.s3.amazonaws.com
Content-Length: 214
Date: Wed, 25 Nov 2009 12:00:00 GMT
Authorization: authorization string

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

1168
Amazon Simple Storage Service API Reference
PUT Bucket logging

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT

Sample Request Disabling Logging

This request disables logging on the bucket, quotes.

PUT ?logging HTTP/1.1

Host: quotes.s3.amazonaws.com
Content-Length: 214
Date: Wed, 25 Nov 2009 12:00:00 GMT
Authorization: authorization string

<?xml version="1.0" encoding="UTF-8"?>

Sample Response

HTTP/1.1 200 OK

API Version 2006-03-01

1169
Amazon Simple Storage Service API Reference
PUT Bucket metrics

x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT

Related Resources

• PUT Object (p. 1324)

• DELETE Bucket (p. 891)
• PUT Bucket (p. 1095)
• GET Bucket logging (p. 1000)

PUT Bucket metrics

Description

Sets or updates a metrics configuration for the CloudWatch request metrics (specified by the metrics
configuration ID) from the bucket. You can have up to 1,000 metrics configurations per bucket. If you're
updating an existing metrics configuration, note that this is a full replacement of the existing metrics
configuration. If you don't include the elements you want to keep, they are erased.

For information about CloudWatch request metrics for Amazon S3, see Monitoring Metrics with Amazon
CloudWatch in the Amazon Simple Storage Service Developer Guide.

Requests

API Version 2006-03-01

1170
Amazon Simple Storage Service API Reference
PUT Bucket metrics

Syntax

PUT /?metrics&id=id HTTP/1.1

HOST: BucketName.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))
Metrics configuration in the request body.

Request Parameters

This implementation of PUT uses the parameter in the following table.

Parameter Description Required

id The ID used to identify the metrics conﬁguration. Yes

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

In the request, you must specify the metrics configuration in the request body, which is specified as XML.
The Examples section shows an example of a metrics configuration.

The following table describes the XML elements in the metrics conﬁguration:

API Version 2006-03-01

1171
Amazon Simple Storage Service API Reference
PUT Bucket metrics

Parameter Description Required

And A conjunction (logical AND) of predicates, which is No

used in evaluating a metrics ﬁlter. The operator must
have at least two predicates in any combination, and
an object must match all of the predicates for the
ﬁlter to apply.

Type: Container

Children: Prefix, Tag

Ancestor: Filter

Filter Specifies a metrics configuration filter. The metrics No

configuration includes only objects that meet the
filter's criteria. A filter must be a prefix, a tag, or a
conjunction (And). There's a limit of 11 predicates for
each filter, of which there can be one prefix and up to
ten tags in a single filter.

Type: Container

Children: And

Id The ID used to identify the metrics conﬁguration. Yes

Type: String

Ancestor: MetricsConfiguration

Key The name of the tag. No

Type: String

Ancestor: Tag

Speciﬁes the metrics conﬁguration for CloudWatch

MetricsConfiguration Yes
request metrics on this bucket.

Type: Container

Ancestor: None

Prefix The preﬁx that an object must have to be included in No

the metrics results.

Type: String

Ancestor: And

Tag A key-value name pair, used to organize objects by No

association.

Type: Container

Children: Key, Value,

Ancestor: And

Value The value of the tag. No

API Version 2006-03-01

1172
Amazon Simple Storage Service API Reference
PUT Bucket metrics

Parameter Description Required

Type: String

Ancestor: Tag

Responses

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

Response Elements

This implementation of the operation does not return response elements.

Special Errors

Amazon S3 checks the validity of the proposed MetricsConfiguration element and veriﬁes whether
the proposed conﬁguration is valid when you call the PUT operation. The following table lists the errors
and possible causes.

HTTP Error Code Cause

HTTP 400 Bad TooManyConﬁgurations

You are attempting to create a new conﬁguration but have
Request already reached the 1,000-conﬁguration limit.

For general information about Amazon S3 errors and a list of error codes, see Error Responses (p. 783).

API Version 2006-03-01

1173
Amazon Simple Storage Service API Reference
PUT Bucket metrics

Examples

First Sample Request

Put a metric conﬁguration that enables metrics for an entire bucket.

PUT /?metrics&id=EntireBucket HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Thu, 15 Nov 2016 00:17:21 GMT
Authorization: signatureValue
Content-Length: 159

<?xml version="1.0" encoding="UTF-8"?>

<MetricsConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Id>EntireBucket</Id>
</MetricsConfiguration>

First Sample Response

Put a metric conﬁguration that enables metrics for an entire bucket.

HTTP/1.1 204 No Content

x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:22 GMT
Server: AmazonS3

Second Sample Request

Put a metrics configuration that enables metrics for objects that start with a particular prefix and also
have specific tags applied.

PUT /?metrics&id=ImportantBlueDocuments HTTP/1.1

API Version 2006-03-01

1174
Amazon Simple Storage Service API Reference
PUT Bucket metrics

Host: examplebucket.s3.amazonaws.com
x-amz-date: Thu, 15 Nov 2016 00:17:29 GMT
Authorization: signatureValue
Content-Length: 480

<?xml version="1.0" encoding="UTF-8"?>

Second Sample Response

Put a metrics configuration that enables metrics for objects that start with a particular prefix and also
have specific tags applied.

HTTP/1.1 204 No Content

x-amz-id-2: ITnGT1y4REXAMPLEPi4hklTXouTf0hccUjo0iCPEXAMPLEutBj3M7fPGlWO2SEWp
x-amz-request-id: 51991EXAMPLE5321
Date: Thu, 15 Nov 2016 00:17:29 GMT
Server: AmazonS3

Related Resources

• DELETE Bucket metrics (p. 911)

• GET Bucket metrics (p. 1004)
• List Bucket Metrics Conﬁgurations (p. 1079)
• Monitoring Metrics with Amazon CloudWatch in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

1175
Amazon Simple Storage Service API Reference
PUT Bucket notiﬁcation

PUT Bucket notiﬁcation

Description

The Amazon S3 notification feature enables you to receive notifications when certain events happen in
your bucket. For more information about event notifications, go to Configuring Event Notifications in the
Amazon Simple Storage Service Developer Guide.

By default, your bucket has no event notifications configured. That is, the notification configuration will
be an empty NotificationConfiguration.

This operation replaces the existing notification configuration with the configuration you include in the
request body.

After Amazon S3 receives this request, it first verifies that any Amazon Simple Notification Service
(Amazon SNS) or Amazon Simple Queue Service (Amazon SQS) destination exists, and that the bucket
owner has permission to publish to it by sending a test notification. In the case of AWS Lambda
destinations, Amazon S3 verifies that the Lambda function permissions grant Amazon S3 permission to
invoke the function from the Amazon S3 bucket. For more information, go to Configuring Notifications
for Amazon S3 Events in the Amazon Simple Storage Service Developer Guide.

You can disable notiﬁcations by adding the empty NotificationConfiguration element.

API Version 2006-03-01

1176
Amazon Simple Storage Service API Reference
PUT Bucket notiﬁcation

Requests

Syntax

PUT /?notification HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

<NotificationConfiguration>
<TopicConfiguration>
<Id>ConfigurationId</Id>
<Filter>
<S3Key>
<FilterRule>
<Name>prefix</Name>
<Value>prefix-value</Value>
</FilterRule>
<FilterRule>
<Name>suffix</Name>
<Value>suffix-value</Value>
</FilterRule>
</S3Key>
</Filter>
<Topic>TopicARN</Topic>
<Event>event-type</Event>
<Event>event-type</Event>
...
</TopicConfiguration>
<QueueConfiguration>
<Id>ConfigurationId</Id>
<Filter>
...
</Filter>
<Queue>QueueARN</Queue>
<Event>event-type</Event>
<Event>event-type</Event>
...
</QueueConfiguration>
...
<CloudFunctionConfiguration>
<Id>ConfigurationId</Id>
<Filter>
...
</Filter>
<CloudFunction>cloud-function-arn</CloudFunction>
<Event>event-type</Event>
...
</CloudFunctionConfiguration>

API Version 2006-03-01

1177
Amazon Simple Storage Service API Reference
PUT Bucket notiﬁcation

...
</NotificationConfiguration>

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

Name Description Required

CloudFunction Lambda cloud function ARN that Amazon S3 can invoke Required if
when it detects events of the speciﬁed type. CloudFunctionConfigurat
is added.
Type: String

Ancestor: CloudFunctionConfiguration

Container for specifying the AWS Lambda notiﬁcation

CloudFunctionConfiguration No
conﬁguration.

Type: Container

Children: An Id,Filter, CloudFunction, and one, or more

Event.

Ancestor: NotificationConfiguration

Event Bucket event for which to send notiﬁcations. Required if

TopicConfiguration,
Note
QueueConfiguration
You can add multiple instance of
or
QueueConfiguration, TopicConfiguration,
CloudFunctionConfigurat
or CloudFunctionConfiguration to the
is added.
notiﬁcation conﬁguration.

API Version 2006-03-01

1178
Amazon Simple Storage Service API Reference
PUT Bucket notiﬁcation

Name Description Required

Type: String

Valid Values: For a list of supported event types, go to

Conﬁguring Event Notiﬁcations in the Amazon Simple
Storage Service Developer Guide.

Ancestor: TopicConfiguration, QueueConfiguration,

and CloudFunctionConfiguration.

Filter Container for S3Key, which contains object key name No

filtering rules. For information about key name filtering, go
to Configuring Event Notifications in the Amazon Simple
Storage Service Developer Guide.

Type: Container

Children: S3Key

Ancestor: TopicConfiguration, QueueConfiguration,

or CloudFunctionConfiguration.

FilterRule Container for key value pair that deﬁnes the criteria for the No
ﬁlter rule.

Container S3Key

Type: Container

Children: Name and Value

Ancestor: S3Key

Id Optional unique identiﬁer for each of the conﬁgurations in No

the NotificationConfiguration. If you don't provide,
Amazon S3 will assign an ID.

Type: String

Ancestor: TopicConfiguration and

QueueConfiguration

Name Object key name preﬁx or suﬃx identifying one or more No

objects to which the filtering rule applies. Maximum prefix
length can be up to 1,024 characters. Overlapping prefixes
and suffixes are not supported. For more information, go
to Configuring Event Notifications in the Amazon Simple
Storage Service Developer Guide.

Type: String

Ancestor: FilterRule

Valid values: prefix or suffix

API Version 2006-03-01

Children: An Id, Filter, Topic, and one, or more Event.

Ancestor: NotificationConfiguration

Value Specifies the object key name prefix or suffix to filter on. No

Type: String

Ancestor: FilterRule

API Version 2006-03-01

1180
Amazon Simple Storage Service API Reference
PUT Bucket notiﬁcation

Responses

Response Headers

In addition to the common response headers (see Common Response Headers (p. 782)), if the
conﬁguration in the request body includes only one TopicConfiguration specifying only the
s3:ReducedRedundancyLostObject event type, the response will also include the x-amz-sns-test-message-
id header containing the message ID of the test notiﬁcation sent to topic.

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of the operation does not return response elements.

Special Errors

Amazon S3 checks the validity of the proposed NotificationConfiguration element and veriﬁes
whether the proposed conﬁguration is valid when you call the PUT operation. The following table lists
the errors and possible causes.

HTTP Error Code Cause

HTTP 400 Bad InvalidArgument The following conditions can cause this error:
Request
• A specified event is not supported for notifications.
• A specified destination ARN does not exist or is not well-
formed. Verify the destination ARN.
• A specified destination is in a different region than the
bucket. You must use a destination that resides in the
same region as the bucket.

API Version 2006-03-01

1181
Amazon Simple Storage Service API Reference
PUT Bucket notiﬁcation

HTTP Error Code Cause

• The bucket owner does not have appropriate
permissions on the specified destination.
• An object key name filtering rule defined with
overlapping prefixes, overlapping suffixes, or
overlapping combinations of prefixes and suffixes for
the same event types.

HTTP 403 AccessDenied You are not the owner of the specified bucket, or you
Forbidden do not have the s3:PutBucketNotification bucket
permission to set the notification configuration on the
bucket.

For general information about Amazon S3 errors and a list of error codes, see Error Responses (p. 783).

Examples

Example 1: Conﬁgure Notiﬁcation to Invoke a cloud function in Lambda

The following notification configuration includes CloudFunctionConfiguration, which identifies

the event type for which Amazon S3 can invoke a cloud function and the name of the cloud function to
invoke.

The following PUT uploads the notification configuration. The operation replaces the existing
notification configuration.

PUT http://s3.amazonaws.com/examplebucket?notification= HTTP/1.1

User-Agent: s3curl 2.0
Host: s3.amazonaws.com
Pragma: no-cache
Accept: */*
Proxy-Connection: Keep-Alive
Authorization: authorization string
Date: Mon, 13 Oct 2014 23:14:52 +0000
Content-Length: length

API Version 2006-03-01

1182
Amazon Simple Storage Service API Reference
PUT Bucket notiﬁcation

[request body]

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: 8+FlwagBSoT2qpMaGlfCUkRkFR5W3OeS7UhhoBb17j+kqvpS2cSFlgJ5coLd53d2
x-amz-request-id: E5BA4600A3937335
Date: Fri, 31 Oct 2014 01:49:50 GMT
Content-Length: 0
Server: AmazonS3

Example 2: Conﬁgure a Notiﬁcation with Multiple Destinations

The following notification configuration includes the topic and queue configurations:

PUT http://s3.amazonaws.com/examplebucket?notification= HTTP/1.1

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: SlvJLkfunoAGILZK3KqHSSUq4kwbudkrROmESoHOpDacULy+cxRoR1Svrfoyvg2A

API Version 2006-03-01

1183
Amazon Simple Storage Service API Reference
PUT Bucket notiﬁcation

x-amz-request-id: BB1BA8E12D6A80B7
Date: Mon, 13 Oct 2014 22:58:44 GMT
Content-Length: 0
Server: AmazonS3

Example 3: Conﬁgure a Notiﬁcation with Object Key Name Filtering

The following notification configuration contains a queue configuration identifying an Amazon SQS
queue for Amazon S3 to publish events to of the s3:ObjectCreated:Put type. The events will be
published whenever an object that has a prefix of images/ and a .jpg suffix is PUT to a bucket. For
more examples of notification configurations that use filtering, go to Configuring Event Notifications in
the Amazon Simple Storage Service Developer Guide.

PUT http://s3.amazonaws.com/examplebucket?notification= HTTP/1.1

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: SlvJLkfunoAGILZK3KqHSSUq4kwbudkrROmESoHOpDacULy+cxRoR1Svrfoyvg2A
x-amz-request-id: BB1BA8E12D6A80B7
Date: Mon, 13 Oct 2014 22:58:44 GMT

API Version 2006-03-01

1184
Amazon Simple Storage Service API Reference
PUT Bucket notiﬁcation

Content-Length: 0
Server: AmazonS3

Related Resources

• GET Bucket notiﬁcation (p. 1010)

API Version 2006-03-01

1185
Amazon Simple Storage Service API Reference
PUT Bucket object lock conﬁguration

PUT Bucket object lock conﬁguration

Service: Amazon Simple Storage Service

Places an Object Lock configuration on the specified bucket. The rule specified in the Object Lock
configuration will be applied by default to every new object placed in the specified bucket.

Request Syntax
PUT /?object-lock HTTP/1.1
Host: <bucket-name>.s3.amazonaws.com
Date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization-string> (see Authenticating Requests (AWS Signature Version
4))

Note
DefaultRetention requires either Days or Years. You can't specify both at the same time.

URI Request Parameters

The request does not use any URI parameters.

Request Body
For more information about the request elements that this operation uses, see
ObjectLockConﬁguration (p. 1458).

Example Request Body:

<ObjectLockConfiguration>
<ObjectLockEnabled>Enabled</ObjectLockEnabled>
<Rule>
<DefaultRetention>
<Mode>GOVERNANCE</Mode>
<Days>30</Days>
</DefaultRetention>
</Rule>
</ObjectLockConfiguration>

Response Syntax
HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

API Version 2006-03-01

1186
Amazon Simple Storage Service API Reference
PUT Bucket object lock conﬁguration

Related Resources
Locking Objects in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

1187
Amazon Simple Storage Service API Reference
PUT Bucket policy

PUT Bucket policy

Description

This implementation of the PUT operation uses the policy subresource to return the policy of a
speciﬁed bucket. If you are using an identity other than the root user of the AWS account that owns the
bucket, the calling identity must have the PutBucketPolicy permissions on the speciﬁed bucket and
belong to the bucket owner's account in order to use this operation.

For more information about bucket policies, see Using Bucket Policies and User Policies in the Amazon
Simple Storage Service Developer Guide.

Requests

Syntax

PUT /?policy HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Policy written in JSON

API Version 2006-03-01

1188
Amazon Simple Storage Service API Reference
PUT Bucket policy

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

The body is a JSON string containing the policy contents containing the policy statements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

API Version 2006-03-01

1189
Amazon Simple Storage Service API Reference
PUT Bucket policy

PUT response elements return whether the operation succeeded or not.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

The following request shows the PUT individual policy request for the bucket.

PUT /?policy HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Tue, 04 Apr 2010 20:34:56 GMT
Authorization: authorization string

Sample Response

API Version 2006-03-01

1190
Amazon Simple Storage Service API Reference
PUT Bucket policy

HTTP/1.1 204 No Content

x-amz-id-2: Uuag1LuByR5Onimru9SAMPLEAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732SAMPLE7374
Date: Tue, 04 Apr 2010 20:34:56 GMT
Connection: keep-alive
Server: AmazonS3

Related Resources

• PUT Bucket (p. 1095)

• DELETE Bucket (p. 891)

API Version 2006-03-01

1191
Amazon Simple Storage Service API Reference
PUT Bucket replication

PUT Bucket replication

Description

Creates a replication conﬁguration or replaces one. For more information, see Replication in the Amazon
S3 Developer Guide.
Note
To perform this operation, the user or role performing the operation must have the
iam:PassRole permission.

Requests

Syntax

PUT /?replication HTTP/1.1

Host: bucketname.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string
Content-MD5: MD5

Replication configuration XML in the body

For more information, see the following topics:

• For an overview of replication configuration XML and examples, see Replication Configuration
Overview in the Amazon S3 Developer Guide.
Important
This topic describes all of the XML elements that are supported in the latest version of the
replication configuration XML. For backward compatibility, Amazon S3 also continues to
support earlier versions. For more information, see Backward Compatibility in the Amazon S3
Developer Guide.

API Version 2006-03-01

1192
Amazon Simple Storage Service API Reference
PUT Bucket replication

• For authorization, see Authenticating Requests (AWS Signature Version 4) (p. 792).

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Name Description Required

Content-MD5 The base64-encoded 128-bit MD5 digest of the Yes

data. You must use this header as a message
integrity check to verify that the request body was
not corrupted in transit. For more information, see
RFC 1864.

Type: String

Default: None

x-amz-bucket-object-lock- Use to allow Amazon S3 object lock to be enabled No

token for an existing bucket.

Type: String

Default: None

Request Body

API Version 2006-03-01

1193
Amazon Simple Storage Service API Reference
PUT Bucket replication

You can add other conﬁguration options to rules. For more information, see Replication Conﬁguration
Overview in the Amazon S3 Developer Guide.

The following table describes the XML elements in a replication conﬁguration.

Name Description Required

Account The account ID of the destination bucket owner. Yes, if you

In a cross-account scenario, if you tell Amazon S3 specify the
to change replica ownership to the AWS account AccessControlTranslat
that owns the destination bucket by adding the element
AccessControlTranslation element, this is
the account ID of the destination bucket owner.
For more information, see Replication Additional
Conﬁguration: Change Replica Owner in the
Amazon Simple Storage Service Developer Guide.

Type: String

Ancestor: Destination

Container for replication rules. You can add a

maximum of 1,000 rules. The maximum size of a
replication conﬁguration size is 2 MB.

Type: Container

Children: Rule

Ancestor: None

ReplicationConfiguration A container for replication rules. You can add a Yes

maximum of 1,000 rules. The maximum size of a
replication conﬁguration size is 2 MB.

Type: Container

Children: Rule

Ancestor: None

Role The Amazon Resource Name (ARN) of an Yes

IAM role that Amazon S3 can assume when
replicating the objects.

Type: String

Ancestor: Rule

Rule A container for information about a particular Yes

replication rule. A replication conﬁguration must
include at least one rule, and can contain up to
1,000 rules.

Type: Container

Ancestor:ReplicationConfiguration

ID A unique identiﬁer for the rule. The value is No

limited to 255 characters.

API Version 2006-03-01

1194
Amazon Simple Storage Service API Reference
PUT Bucket replication

Name Description Required

Type: String

Ancestor: Rule

Status If you don't set the Status to Enabled, the rule Yes
is ignored.

Type: String

Ancestor: Rule

Valid values: Enabled, Disabled

Destination A container for destination information. Yes

Type: Container

Ancestor: Rule

Bucket The Amazon Resource Name (ARN) of the bucket Yes

where you want Amazon S3 to store replicas of
the objects identiﬁed by the rule.

If you have multiple rules, all rules must specify

the same bucket as the destination. A replication
conﬁguration can replicate objects to only one
destination bucket.

Type: String

Ancestor: Destination

StorageClass An optional destination storage class override to No

use when replicating objects. If you don't specify
a storage class, Amazon S3 uses the storage class
of the source object for object replicas.

Type: String

Ancestor: Destination

Default: Storage class of the source object

Valid values: STANDARD | REDUCED_REDUNDANCY

Constraints: If you specify the STANDARD_IA

or ONEZONE_IA storage class for object
replicas, there are pricing considerations if the
object replicas are less than 128 KB. For more
information, see https://aws.amazon.com/s3/
pricing/.

API Version 2006-03-01

1195
Amazon Simple Storage Service API Reference
PUT Bucket replication

Name Description Required

AccessControlTranslation Use only in a cross-account scenario, where No

diﬀerent AWS accounts own source and
destination buckets, to change replica ownership
to the AWS account that owns the destination
bucket.

If you don't add this element to the replication

conﬁguration, replicas are owned by same AWS
account that owns the source object.

Type: String

Ancestor: Destination

Owner Identiﬁes the replica owner. Yes, if

AccessControlTranslat
Type: String is speciﬁed
Ancestor: AccessControlTranslation

Default: Storage class of the source object

Valid values: Destination

Specifying a Filter

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. The following table describes the elements for filtering in a Rule.

Name Description Required

Filter A container that describes the ﬁlters that identify Yes.

the source objects that you want to replicate.

You can optionally specify one of these child

elements: Prefix, Tag, or And.

Use the And child element to specify an object

ﬁlter that combines an object key Prefix and
one or more Tags.

An empty Filter element indicates that the rule

applies to all objects.

Ancestor: Rule

And A container element for a Prefix and one or Yes, if you want to specify
more Tag elements. At least one child element is more than one ﬁltering criteria.
required. For example, one object key

API Version 2006-03-01

1196
Amazon Simple Storage Service API Reference
PUT Bucket replication

Name Description Required

Ancestor: Filter preﬁx and one or more object
tags.

Prefix An object key preﬁx that identiﬁes one or more No

objects to which the rule applies. The maximum
length of a Prefix is 1,024 characters. If prefixes
in multiple rules overlap (if multiple rules apply to
the same object), rule priority determines which
rule applies to the object.
Note
In previous versions of replication
configuration, only the object key prefix
could be used as a rule filter (where you
add the Prefix element as a child of
the Rule element). Amazon S3 supports
this for backward compatibility. But in
the latest configuration, Amazon S3
allows you to specify either the Filter
or Prefix as child of the Rule. For more
information, see Backward Compatibility
in the Amazon S3 Developer Guide.

Type: String

Ancestor: Filter

Tag A container that provides a tag key and value. No

Ancestor: Filter

Key Provides an object tag key. The Tag Key and No

Value are case sensitive. A Tag Key can have
1-128 characters.

Type: String

Ancestor: EncryptionConfiguration

Value Provides the object Tag Value. The Tag Key and No
Value are case sensitive. The Tag Value can have
0-256 characters.

Type: String

Ancestor: EncryptionConfiguration

When you add the Filter element in the conﬁguration, you must also add the elements described in
this table.

Name Description Required

A container that describes whether Amazon

DeleteMarkerReplication Yes, if Filter is speciﬁed
S3 replicates the delete markers. If you specify
a Filter, you must specify this element.
However, in the latest version of replication

API Version 2006-03-01

1197
Amazon Simple Storage Service API Reference
PUT Bucket replication

Name Description Required

configuration (when Filter is specified), Amazon
S3 doesn't replicate delete markers. Therefore,
the DeleteMarkerReplication element can
contain only <Status>Disabled</Status>.
For an example configuration, see The Basic Rule
Configuration in the Amazon S3 Developer Guide.
Note
If you don't specify the Filter element,
Amazon S3 assumes that the replication
configuration is the earlier version, V1. In
the earlier version, Amazon S3 handled
replication of delete markers differently.
For more information, see Backward
Compatibility in the Amazon S3 Developer
Guide.

Ancestor: Rule

Status Indicates whether to replicate delete markers. Yes, if

DeleteMarkerReplication
Type: String is speciﬁed
Ancestor: DeleteMarkerReplication

Valid values: Disabled

Priority If you specify multiple rules with overlapping Yes, if Filter is specified
filters, identifies the rule priority. For example,
if two rules apply to the same object based on
the Filter specified, then the rule with higher
priority supersedes. The higher the numerical
value of this element, the higher the rule priority.
For more information, see Backward Compatibility
in the Amazon S3 Developer Guide.

Type: Integer

Ancestor: Rule

Valid values: 0 - INT-MAX.

Handling Replication of Encrypted Objects

By default, Amazon S3 doesn't replicate objects that are stored at rest using server-side encryption
with AWS KMS-managed keys, . To replicate AWS MKS-encrypted objects, add the following optional
conﬁguration. For information about replication conﬁguration, see Replicating Objects Created with SSE
Using AWS KMS-Managed Encryption Keys in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

1198
Amazon Simple Storage Service API Reference
PUT Bucket replication

Name Description Required

SourceSelectionCriteria A container that describes additional ﬁlters that Yes, if

identify the source objects that you want to you want
replicate. Amazon S3
to replicate
Currently, Amazon S3 supports only the ﬁlter for objects
objects created with server-side encryption using created with
an AWS KMS-managed key. You can choose to server-side
enable or disable replication of these objects. encryption
using
Ancestor: Rule AWS KMS-
managed
keys

SseKmsEncryptedObjects A container element for Status. Yes, if

SourceSelectionCriter
Ancestor: SourceSelectionCriteria is speciﬁed

Status A ﬂag that tells Amazon S3 whether to replicate Yes, if

objects created with server-side encryption using SseKmsEncryptedObject
an AWS KMS-managed key. is speciﬁed

Type: String

Ancestor: SseKmsEncryptedObjects

Valid Values: Enabled, Disabled

EncryptionConfiguration A container that provides encryption-related Yes, if

information. SourceSelectionCriter
is speciﬁed
Ancestor: Destination

ReplicaKmsKeyID Provides the AWS KMS Key ID (Key ARN or Alias Yes, if
ARN) of the destination bucket. Amazon S3 uses EncryptionConfigurati
this key to encrypt replicas. is speciﬁed

Type: String

Ancestor: EncryptionConfiguration

Responses

Response Headers

API Version 2006-03-01

1199
Amazon Simple Storage Service API Reference
PUT Bucket replication

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of the operation does not return response elements.

Special Errors

When you call the PUT operation, Amazon S3 checks the validity of the proposed
AnalyticsConfiguration element and veriﬁes that the proposed conﬁguration is valid. The following
table lists errors and possible causes.

HTTP Error Code Cause

HTTP 400 InvalidRequest If the <Owner> in <AccessControlTranslation> has a

value, the <Account> element must be speciﬁed.

HTTP 400 InvalidArgument The <Account> element is empty. It must contain a valid
account ID.

HTTP 400 InvalidArgument The AWS account speciﬁed in the <Account> element
must match the destination bucket owner.

For general information about Amazon S3 errors and a list of error codes, see Error Responses (p. 783).

Examples

The following example shows how to add a replication conﬁguration.

Example 1: Add a Replication Conﬁguration

API Version 2006-03-01

1200
Amazon Simple Storage Service API Reference
PUT Bucket replication

The following is a sample PUT request that creates a replication subresource on the specified bucket
and saves the replication configuration in it. The replication configuration specifies a rule to replicate
objects to the exampletargetbucket bucket. The rule includes a filter to replicate only the objects
created with the key name prefix TaxDocs and that have two specific tags.

PUT /?replication HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Wed, 11 Feb 2015 02:11:21 GMT
Content-MD5: q6yJDlIkcBaGGfb3QLY69A==
Authorization: authorization string
Content-Length: length

<ReplicationConfiguration>
<Role>arn:aws:iam::35667example:role/RegionReplicationRoleForS3</Role>
<Rule>
<ID>rule1</ID>
<Status>Enabled</Status>
<Priority>1</Priority>
<DeleteMarkerReplication>
<Status>Disabled</Status>
</DeleteMarkerReplication>
<Filter>
<And>
<Prefix>TaxDocs</Prefix>
<Tag>
<Key>key1</Key>
<Value>value1</Value>
</Tag>
<Tag>
<Key>key1</Key>
<Value>value1</Value>
</Tag>
</And>
</Filter>
<Destination>
<Bucket>arn:aws:s3:::exampletargetbucket</Bucket>
</Destination>
</Rule>
</ReplicationConfiguration>

The following is a sample response:

HTTP/1.1 200 OK
x-amz-id-2: r+qR7+nhXtJDDIJ0JJYcd+1j5nM/rUFiiiZ/fNbDOsd3JUE8NWMLNHXmvPfwMpdc
x-amz-request-id: 9E26D08072A8EF9E
Date: Wed, 11 Feb 2015 02:11:22 GMT
Content-Length: 0
Server: AmazonS3

Filtering using the <Filter> element is supported in the latest XML configuration. If you are using
an earlier version of the XML configuration, you can filter only on key prefix. In that case, you add the
<Prefix> element as a child of the <Rule>.

For more examples of replication conﬁguration, see Replication Conﬁguration Overview in the Amazon
S3 Developer Guide.

API Version 2006-03-01

1201
Amazon Simple Storage Service API Reference
PUT Bucket replication

Related Resources

• GET Bucket replication (p. 1040).

• DELETE Bucket replication (p. 919).
• For information about enabling versioning on a bucket, see Using Versioning in the Amazon Simple
Storage Service Developer Guide.
• By default, a resource owner, in this case the AWS account that created the bucket, can perform this
operation. The resource owner can also grant others permissions to perform the operation. For more
information, see the following topics in the Amazon Simple Storage Service Developer Guide:
• Specifying Permissions in a Policy
• Managing Access Permissions to Your Amazon S3 Resources

API Version 2006-03-01

1202
Amazon Simple Storage Service API Reference
PUT Bucket requestPayment

PUT Bucket requestPayment

Description

This implementation of the PUT operation uses the requestPayment subresource to set the request
payment conﬁguration of a bucket. By default, the bucket owner pays for downloads from the bucket.
This conﬁguration parameter enables the bucket owner (only) to specify that the person requesting the
download will be charged for the download. For more information, see Requester Pays Buckets.

Requests

Syntax

PUT ?requestPayment HTTP/1.1

Host: BucketName.s3.amazonaws.com
Content-Length: length
Date: date
Authorization:signatureValue

<RequestPaymentConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Payer>payer</Payer>
</RequestPaymentConfiguration>

Request Parameters

API Version 2006-03-01

1203
Amazon Simple Storage Service API Reference
PUT Bucket requestPayment

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

Name Description

Payer Speciﬁes who pays for the download and request fees.

Type: Enum

Valid Values: Requester | BucketOwner

Ancestor: RequestPaymentConﬁguration

RequestPaymentConfiguration Container for Payer.

Type: Container

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

API Version 2006-03-01

1204
Amazon Simple Storage Service API Reference
PUT Bucket requestPayment

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

This request creates a Requester Pays bucket named "colorpictures."

PUT ?requestPayment HTTP/1.1

Host: colorpictures.s3.amazonaws.com
Content-Length: 173
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

<RequestPaymentConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Payer>Requester</Payer>
</RequestPaymentConfiguration>

Sample Response

API Version 2006-03-01

1205
Amazon Simple Storage Service API Reference
PUT Bucket requestPayment

Related Resources

• PUT Bucket (p. 1095)

• GET Bucket requestPayment (p. 1049)

API Version 2006-03-01

1206
Amazon Simple Storage Service API Reference
PUT Bucket tagging

PUT Bucket tagging

Description

This implementation of the PUT operation uses the tagging subresource to add a set of tags to an
existing bucket.

• If you use the PUT Bucket tagging to add a set of tags to an existing bucket, any existing tag
set will be overwritten.
• Within a bucket, if you add a tag that has the same key as an existing tag, the new value
overwrites the old value. For more information, see Using Cost Allocation in Amazon S3
Bucket Tags in AWS Billing and Cost Management.

Requests

Syntax

API Version 2006-03-01

1207
Amazon Simple Storage Service API Reference
PUT Bucket tagging

The following request shows the syntax for sending tagging information in the request body.

PUT /?tagging HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

<Tagging>
<TagSet>
<Tag>
<Key>Tag Name</Key>
<Value>Tag Value</Value>
</Tag>
</TagSet>
</Tagging>

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Content-MD5 will be a required header for this operation.

Request Elements

Name Description Required

Responses

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

Response Elements

This operation does not return response elements.

Special Errors

API Version 2006-03-01

1209
Amazon Simple Storage Service API Reference
PUT Bucket tagging

• InvalidTagError - The tag provided was not a valid tag. This error can occur if the tag did not pass
input validation. For information about tag restrictions, see User-Deﬁned Tag Restrictions and AWS-
Generated Cost Allocation Tag Restrictions in the AWS Billing and Cost Management User Guide.
• MalformedXMLError - The XML provided does not match the schema.
• OperationAbortedError - A conﬂicting conditional operation is currently in progress against this
resource. Please try again.
• InternalError - The service was unable to apply the provided tag to the bucket.

Examples

Sample Request: Add tag set to a bucket

The following request adds a tag set to the existing examplebucket bucket.

PUT ?tagging HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Content-Length: 1660
x-amz-date: Thu, 12 Apr 2012 20:04:21 GMT
Authorization: authorization string

<Tagging>
<TagSet>
<Tag>
<Key>Project</Key>
<Value>Project One</Value>
</Tag>
<Tag>
<Key>User</Key>
<Value>jsmith</Value>
</Tag>
</TagSet>
</Tagging>

Sample Response

HTTP/1.1 204 No Content

x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01

API Version 2006-03-01

1210
Amazon Simple Storage Service API Reference
PUT Bucket tagging

Date: Wed, 01 Oct 2012 12:00:00 GMT

Related Resources

• GET Bucket tagging (p. 1053)

• DELETE Bucket tagging (p. 922)

API Version 2006-03-01

1211
Amazon Simple Storage Service API Reference
PUT Bucket versioning

PUT Bucket versioning

Description

This implementation of the PUT operation uses the versioning subresource to set the versioning state
of an existing bucket. To set the versioning state, you must be the bucket owner.

You can set the versioning state with one of the following values:

• Enabled—Enables versioning for the objects in the bucket

All objects added to the bucket receive a unique version ID.

• Suspended—Disables versioning for the objects in the bucket

All objects added to the bucket receive the version ID null.

If the versioning state has never been set on a bucket, it has no versioning state; a GET versioning
request does not return a versioning state value.

For more information about creating a bucket, see PUT Bucket (p. 1095). For more information about
returning the versioning state of a bucket, see GET Bucket Versioning Status (p. 1057).

Requests

API Version 2006-03-01

1212
Amazon Simple Storage Service API Reference
PUT Bucket versioning

Syntax

PUT /?versioning HTTP/1.1

Host: BucketName.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))
x-amz-mfa: [SerialNumber] [TokenCode]

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>VersioningState</Status>
<MfaDelete>MfaDeleteState</MfaDelete>
</VersioningConfiguration>

Note the space between [SerialNumber] and [TokenCode].

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Name Description Required

x-amz-mfa The value is the concatenation of the authentication device's serial Conditional
number, a space, and the value displayed on your authentication
device.

Type: String

Default: None

Condition: Required to conﬁgure the versioning state if versioning is

conﬁgured with MFA Delete enabled.

API Version 2006-03-01

1213
Amazon Simple Storage Service API Reference
PUT Bucket versioning

Request Elements

Name Description Required

Status Sets the versioning state of the bucket. No

Type: Enum

Valid Values: Suspended | Enabled

Ancestor: VersioningConﬁguration

MfaDelete Speciﬁes whether MFA Delete is enabled in the No

bucket versioning conﬁguration. When enabled, the
bucket owner must include the x-amz-mfa request
header in requests to change the versioning state
of a bucket and to permanently delete a versioned
object.

Type: Enum

Valid Values: Disabled | Enabled

Ancestor: VersioningConﬁguration

Constraint: Can only be used when you use Status.

VersioningConfiguration Container for setting the versioning state. Yes

Type: Container

Children: Status

Ancestor: None

Responses

Response Headers

API Version 2006-03-01

1214
Amazon Simple Storage Service API Reference
PUT Bucket versioning

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

The following request enables versioning for the speciﬁed bucket.

PUT /?versioning HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 124

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
</VersioningConfiguration>

Sample Response

API Version 2006-03-01

1215
Amazon Simple Storage Service API Reference
PUT Bucket versioning

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT

Sample Request

The following request suspends versioning for the speciﬁed bucket.

PUT /?versioning HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 124

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Suspended</Status>
</VersioningConfiguration>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT

Sample Request

The following request enables versioning and MFA Delete on a bucket.

PUT /?versioning HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
x-amz-mfa:[SerialNumber] [TokenCode]
Authorization: authorization string
Content-Type: text/plain
Content-Length: 124

API Version 2006-03-01

1216
Amazon Simple Storage Service API Reference
PUT Bucket versioning

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Status>Enabled</Status>
<MfaDelete>Enabled</MfaDelete>
</VersioningConfiguration>

Note the space between [SerialNumber] and [TokenCode] and that you must include Status
whenever you use MfaDelete.

Sample Response

HTTPS/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar 2006 12:00:00 GMT

Location: /colorpictures
Content-Length: 0
Connection: close
Server: AmazonS3

Related Resources

• DELETE Bucket (p. 891)

• PUT Bucket (p. 1095)

API Version 2006-03-01

1217
Amazon Simple Storage Service API Reference
PUT Bucket website

PUT Bucket website

Description

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. For more information, go to Hosting
Websites on Amazon S3 in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

PUT /?website HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Content-Length: ContentLength
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

API Version 2006-03-01

1218
Amazon Simple Storage Service API Reference
PUT Bucket website

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

You can use a website conﬁguration to redirect all requests to the website endpoint of a bucket, or you
can add routing rules that redirect only speciﬁc requests.

• To redirect all website requests sent to the bucket's website endpoint, you add a website conﬁguration
with the following elements. Because all requests are sent to another website, you don't need to
provide index document name for the bucket.

Name Description Required

WebsiteConfiguration The root element for the website conﬁguration Yes

Type: Container

Ancestors: None

RedirectAllRequestsToDescribes the redirect behavior for every request to this Yes

bucket's website endpoint. If this element is present, no
other siblings are allowed.

Type: Container

Ancestors: WebsiteConﬁguration

HostName Name of the host where requests will be redirected. Yes

Type: String

Ancestors: RedirectAllRequestsTo

API Version 2006-03-01

1219
Amazon Simple Storage Service API Reference
PUT Bucket website

Name Description Required

Protocol Protocol to use (http, https) when redirecting requests. No

The default is the protocol that is used in the original
request.

Type: String

Ancestors: RedirectAllRequestsTo

• If you want granular control over redirects, you can use the following elements to add routing rules
that describe conditions for redirecting requests and information about the redirect destination. In
this case, the website conﬁguration must provide an index document for the bucket, because some
requests might not be redirected.

Name Description Required

WebsiteConfiguration Container for the request Yes

Type: Container

Ancestors: None

IndexDocument Container for the Suffix element. Yes

Type: Container

Ancestors: WebsiteConﬁguration

Suffix A suﬃx that is appended to a request that is for a Yes

directory on the website endpoint (e.g., if the suﬃx is
index.html and you make a request to samplebucket/
images/, the data that is returned will be for the object
with the key name images/index.html)

The suﬃx must not be empty and must not include a

slash character.

Type: String

Ancestors: WebsiteConﬁguration.IndexDocument

ErrorDocument Container for the Key element No

Type: Container

Ancestors: WebsiteConﬁguration

Key The object key name to use when a 4XX class error Conditional
occurs. This key identiﬁes the page that is returned when
such an error occurs.

Type: String

Ancestors: WebsiteConﬁguration.ErrorDocument

Condition: Required when ErrorDocument is speciﬁed.

RoutingRules Container for a collection of RoutingRule elements. No

API Version 2006-03-01

1220
Amazon Simple Storage Service API Reference
PUT Bucket website

Name Description Required

Type: Container

Ancestors:
WebsiteConﬁguration.RoutingRules.RoutingRule

Protocol The protocol to use in the redirect request. No

1222
Amazon Simple Storage Service API Reference
PUT Bucket website

Name Description Required

ReplaceKeyWith The speciﬁc object key to use in the redirect request. For No
example, redirect request to error.html.

Type: String

Ancestors:
WebsiteConﬁguration.RoutingRules.RoutingRule.Redirect

Condition: Not required if one of the sibling is present.

Can be present only if ReplaceKeyPrefixWith is not
provided.

HttpRedirectCode The HTTP redirect code to use on the response. No

Type: String

Ancestors:
WebsiteConﬁguration.RoutingRules.RoutingRule.Redirect

Condition: Not required if one of the siblings is present.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of the operation does not return response elements.

API Version 2006-03-01

1223
Amazon Simple Storage Service API Reference
PUT Bucket website

Examples

Example 1: Conﬁgure bucket as a website (add website conﬁguration)

PUT ?website HTTP/1.1

Host: example.com.s3.amazonaws.com
Content-Length: 256
Date: Thu, 27 Jan 2011 12:00:00 GMT
Authorization: signatureValue

Amazon S3 returns the following sample response.

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMgUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 80CD4368BD211111
Date: Thu, 27 Jan 2011 00:00:00 GMT
Content-Length: 0
Server: AmazonS3

Example 2: Conﬁgure bucket as a website but redirect all requests

The following request configures a bucket www.example.com as a website; however, the configuration
specifies that all GET requests for the www.example.com bucket's website endpoint will be redirected to
host example.com.

PUT ?website HTTP/1.1

API Version 2006-03-01

1224
Amazon Simple Storage Service API Reference
PUT Bucket website

Host: www.example.com.s3.amazonaws.com
Content-Length: length-value
Date: Thu, 27 Jan 2011 12:00:00 GMT
Authorization: signatureValue

This redirect can be useful when you want to serve requests for both http://www.example.com and
http://example.com, but you want to maintain the website content in only one bucket, in this case
example.com. For more information, go to Hosting Websites on Amazon S3 in the Amazon Simple
Storage Service Developer Guide.

Example 3: Conﬁgure bucket as a website and also specify optional redirection

rules

index.html

docs/article1.html

docs/article2.html

In this case, you update the website conﬁguration and add a routing rule as shown in the following
request:

PUT ?website HTTP/1.1

Host: www.example.com.s3.amazonaws.com
Content-Length: length-value
Date: Thu, 27 Jan 2011 12:00:00 GMT
Authorization: signatureValue

API Version 2006-03-01

1225
Amazon Simple Storage Service API Reference
PUT Bucket website

<KeyPrefixEquals>docs/</KeyPrefixEquals>
</Condition>
<Redirect>
<ReplaceKeyPrefixWith>documents/</ReplaceKeyPrefixWith>
</Redirect>
</RoutingRule>
</RoutingRules>
</WebsiteConfiguration>

Example 4: Conﬁgure bucket as a website and redirect errors

You can use a routing rule to specify a condition that checks for a specific HTTP error code. When a page
request results in this error, you can optionally reroute requests. For example, you might route requests
to another host and optionally process the error. The routing rule in the following requests redirects
requests to an EC2 instance in the event of an HTTP error 404. For illustration, the redirect also inserts a
object key prefix report-404/ in the redirect. For example, if you request a page ExamplePage.html
and it results in a HTTP 404 error, the request is routed to a page report-404/testPage.html on
the specified EC2 instance. If there is no routing rule and the HTTP error 404 occurred, then Error.html
would be returned.

PUT ?website HTTP/1.1

Host: www.example.com.s3.amazonaws.com
Content-Length: 580
Date: Thu, 27 Jan 2011 12:00:00 GMT
Authorization: signatureValue

Example 5: Conﬁgure a bucket as a website and redirect folder requests to a

page

API Version 2006-03-01

1226
Amazon Simple Storage Service API Reference
Operations on Objects

Suppose you have the following pages in your bucket:

images/photo1.jpg

images/photo2.jpg

images/photo3.jpg

PUT ?website HTTP/1.1

Host: www.example.com.s3.amazonaws.com
Content-Length: 481
Date: Thu, 27 Jan 2011 12:00:00 GMT
Authorization: signatureValue

Operations on Objects
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

This section describes operations you can perform on Amazon S3 objects.

Topics
• Delete Multiple Objects (p. 1228)
• DELETE Object (p. 1239)
• DELETE Object tagging (p. 1245)
• GET Object (p. 1248)
• GET Object ACL (p. 1264)
• GET Object legal hold (p. 1270)
• GET Object retention (p. 1271)

API Version 2006-03-01

1227
Amazon Simple Storage Service API Reference
Delete Multiple Objects

• GET Object tagging (p. 1272)

• GET Object torrent (p. 1276)
• HEAD Object (p. 1279)
• OPTIONS object (p. 1291)
• POST Object (p. 1295)
• POST Object restore (p. 1308)
• PUT Object (p. 1324)
• PUT Object legal hold (p. 1342)
• PUT Object retention (p. 1343)
• PUT Object - Copy (p. 1344)
• PUT Object acl (p. 1363)
• PUT Object tagging (p. 1373)
• SELECT Object Content (p. 1378)
• Abort Multipart Upload (p. 1409)
• Complete Multipart Upload (p. 1413)
• Initiate Multipart Upload (p. 1420)
• List Parts (p. 1432)
• Upload Part (p. 1440)
• Upload Part - Copy (p. 1447)

Delete Multiple Objects

Description

The Multi-Object Delete 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 (see DELETE Object (p. 1239)), reducing per-
request overhead.

The Multi-Object Delete request contains a list of up to 1000 keys that you want to delete. In the XML,
you provide the object key names, and optionally, version IDs if you want to delete a speciﬁc version of
the object from a versioning-enabled bucket. For each key, Amazon S3 performs a delete operation and
returns the result of that delete, success, or failure, in the response. Note that, if the object speciﬁed in
the request is not found, Amazon S3 returns the result as deleted.

The Multi-Object Delete 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

API Version 2006-03-01

1228
Amazon Simple Storage Service API Reference
Delete Multiple Objects

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.

When performing a Multi-Object Delete operation on an MFA Delete enabled bucket, that attempts
to delete any versioned objects, you must include an MFA token. If you do not provide one, the entire
request will fail, even if there are non versioned objects you are attempting to delete. If you provide
an invalid token, whether there are versioned keys in the request or not, the entire Multi-Object Delete
request will fail. For information about MFA Delete, see MFA Delete.

Finally, the Content-MD5 header is required for all Multi-Object Delete requests. Amazon S3 uses the
header value to ensure that your request body has not been altered in transit.

Requests

Syntax

POST /?delete HTTP/1.1

Host: bucketname.s3.amazonaws.com
Authorization: authorization string
Content-Length: Size
Content-MD5: MD5

<?xml version="1.0" encoding="UTF-8"?>

<Delete>
<Quiet>true</Quiet>
<Object>
<Key>Key</Key>
<VersionId>VersionId</VersionId>
</Object>
<Object>
<Key>Key</Key>
</Object>
...
</Delete>

Request Parameters

The Multi-Object Delete operation requires a single query string parameter called "delete" to distinguish
it from other bucket POST operations.

API Version 2006-03-01

1229
Amazon Simple Storage Service API Reference
Delete Multiple Objects

Request Headers

This operation uses the following Request Headers in addition to the request headers common to most
requests. For more information, see Common Request Headers (p. 779).

Name Description Required

Type: String

Default: None

Content- Length of the body according to RFC 2616. Yes

Length
Type: String

Default: None

x-amz-mfa The value is the concatenation of the authentication device's Conditional

serial number, a space, and the value that is displayed on your
authentication device.

Type: String

Default: None

Condition: Required to permanently delete a versioned object if

versioning is conﬁgured with MFA Delete enabled.

Request Elements

Name Description Required

Delete Container for the request. Yes

Ancestor: None

Type: Container

Children: One or more Object elements and an optional

Quiet element.

API Version 2006-03-01

1230
Amazon Simple Storage Service API Reference
Delete Multiple Objects

Name Description Required

Quiet Element to enable quiet mode for the request. When you No
add this element, you must set its value to true.

Ancestor: Delete

Type: Boolean

Default: false

Object Container element that describes the delete request for an Yes
object.

Ancestor: Delete

Type: Container

Children: Key element and an optional VersionId element.

Key Key name of the object to delete. Yes

Ancestor: Object

Type: String

VersionId VersionId for the speciﬁc version of the object to delete. No

Ancestor: Object

Type: String

Responses

Response Headers

This operation uses only response headers that are common to most responses. For more information,
see Common Response Headers (p. 782).

Response Elements

API Version 2006-03-01

1231
Amazon Simple Storage Service API Reference
Delete Multiple Objects

Name Description

DeleteResult Container for the response.

Children: Deleted, Error

Type: Container

Ancestor: None

Deleted Container element for a successful delete. It identiﬁes the

object that was successfully deleted.

Children: Key, VersionId

Type: Container

Ancestor: DeleteResult

Key Key name for the object that Amazon S3 attempted to

delete.

Type: String

Ancestor: Deleted, or Error

VersionId VersionId for the versioned object in the case of a versioned

delete.

Type: String

Ancestor: Deleted

DeleteMarker DeleteMarker element with a true value indicates that the

request accessed a delete marker.

If a speciﬁc delete request either creates or deletes a delete

marker, Amazon S3 returns this element in the response with
a value of true. This is only the case when your Multi-Object
Delete request is on a bucket that has versioning enabled or
suspended. For more information about delete markers, go
to Object Versioning.

Type: Boolean

Ancestor: Deleted

DeleteMarkerVersionId Version ID of the delete marker accessed (deleted or created)

by the request.

If the speciﬁc delete request in the Multi-Object Delete either

creates or deletes a delete marker, Amazon S3 returns this
element in response with the version ID of the delete marker.
When deleting an object in a bucket with versioning enabled,
this value is present for the following two reasons:

• You send a non-versioned delete request, that is, you

specify only object key and not the version ID. In this case,
Amazon S3 creates a delete marker and returns its version
ID in the response.

API Version 2006-03-01

1232
Amazon Simple Storage Service API Reference
Delete Multiple Objects

Name Description
• You send a versioned delete request, that is, you specify an
object key and a version ID in your request; however, the
version ID identiﬁes a delete marker. In this case, Amazon
S3 deletes the delete marker and returns the speciﬁc
version ID in response. For information about versioning,
go to Object Versioning.

Type: String

Ancestor: Deleted

Error Container for a failed delete operation that describes the

object that Amazon S3 attempted to delete and the error it
encountered.

Children: Key, VersionId, Code, Message.

Type: String

Ancestor: DeleteResult

Key Key for the object Amazon S3 attempted to delete.

Type: String

Ancestor: Error

VersionId Version ID of the versioned object Amazon S3 attempted to

delete. Amazon S3 includes this element only in case of a
versioned-delete request.

Type: String

Ancestor: Deleted, Error

Code Status code for the result of the failed delete. .

Type: String

Values: AccessDenied, InternalError

Ancestor: Error

Message Error description.

Type: String

Ancestor: Error

Examples

API Version 2006-03-01

1233
Amazon Simple Storage Service API Reference
Delete Multiple Objects

Example 1: Multi-Object Delete resulting in mixed success/error response

This example illustrates a Multi-Object Delete request to delete objects that result in mixed success and
errors response.

Sample Request

The following Multi-Object Delete request deletes two objects from a bucket (bucketname). In this
example, the requester does not have permission to delete the sample2.txt object.

POST /?delete HTTP/1.1

Host: bucketname.s3.amazonaws.com
Accept: */*
x-amz-date: Wed, 30 Nov 2011 03:39:05 GMT
Content-MD5: p5/WA/oEr30qrEEl21PAqw==
Authorization: AWS AKIAIOSFODNN7EXAMPLE:W0qPYCLe6JwkZAD1ei6hp9XZIee=
Content-Length: 125
Connection: Keep-Alive

<Delete>
<Object>
<Key>sample1.txt</Key>
</Object>
<Object>
<Key>sample2.txt</Key>
</Object>
</Delete>

Sample Response

API Version 2006-03-01

1234
Amazon Simple Storage Service API Reference
Delete Multiple Objects

Content-Length: 251

<?xml version="1.0" encoding="UTF-8"?>

Example 2: Deleting Object from a Versioned Bucket

If you delete an item from a versioning enabled bucket, all versions of that object remain in the bucket;
however, Amazon S3 inserts a delete marker. For more information, go to Object Versioning.

The following scenarios describe the behavior of a Multi-Object Delete request when versioning is
enabled for your bucket.

Case 1 - Simple Delete

The following sample the Multi-Object Delete request speciﬁes only one key.

POST /?delete HTTP/1.1

<Delete>
<Object>
<Key>SampleDocument.txt</Key>
</Object>
</Delete>

Because versioning is enabled on the bucket, Amazon S3 does not delete the object. Instead, it
adds a delete marker for this object. The response indicates that a delete marker was added (the
DeleteMarker element in the response as a value of true) and the version number of the delete marker
it added.

HTTP/1.1 200 OK

API Version 2006-03-01

1235
Amazon Simple Storage Service API Reference
Delete Multiple Objects

x-amz-id-2: P3xqrhuhYxlrefdw3rEzmJh8z5KDtGzb+/FB7oiQaScI9Yaxd8olYXc7d1111ab+
x-amz-request-id: 264A17BF16E9E80A
Date: Wed, 30 Nov 2011 03:39:32 GMT
Content-Type: application/xml
Server: AmazonS3
Content-Length: 276

<?xml version="1.0" encoding="UTF-8"?>

Case 2 - Versioned Delete

The following Multi-Object Delete attempts to delete a speciﬁc version of an object

POST /?delete HTTP/1.1

<Delete>
<Object>
<Key>SampleDocument.txt</Key>
<VersionId>OYcLXagmS.WaD..oyH4KRguB95_YhLs7</VersionId>
</Object>
</Delete>

In this case, Amazon S3 deletes the speciﬁc object version from the bucket and returns the following
response. In the response, Amazon S3 returns the key and version ID of the object deleted.

HTTP/1.1 200 OK
x-amz-id-2: P3xqrhuhYxlrefdw3rEzmJh8z5KDtGzb+/FB7oiQaScI9Yaxd8olYXc7d1111xx+
x-amz-request-id: 264A17BF16E9E80A
Date: Wed, 30 Nov 2011 03:39:32 GMT
Content-Type: application/xml
Server: AmazonS3
Content-Length: 219

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

1236
Amazon Simple Storage Service API Reference
Delete Multiple Objects

Case 3 - Versioned Delete of a Delete Marker

<?xml version="1.0" encoding="UTF-8"?>

In general, when a Multi-Object Delete request results in Amazon S3 either adding a delete marker or
removing a delete marker, the response returns the following elements.

Example

<DeleteMarker>true</DeleteMarker>
<DeleteMarkerVersionId>NeQt5xeFTfgPJD8B4CGWnkSLtluMr11s</DeleteMarkerVersionId>

Example 3: Malformed XML in the Request

This example shows how Amazon S3 responds to a request that includes a malformed XML document.

Sample Request

The following requests sends a malformed XML document (missing the Delete end element).

API Version 2006-03-01

1237
Amazon Simple Storage Service API Reference
Delete Multiple Objects

POST /?delete HTTP/1.1

Sample Response

The response returns the Error messages that describe the error.

<?xml version="1.0" encoding="UTF-8"?>

Related Actions

• Initiate Multipart Upload (p. 1420)

• Upload Part (p. 1440)
• Complete Multipart Upload (p. 1413)
• Abort Multipart Upload (p. 1409)
• List Parts (p. 1432)

API Version 2006-03-01

1238
Amazon Simple Storage Service API Reference
DELETE Object

DELETE Object
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

The DELETE operation removes the null version (if there is one) of an object and inserts a delete marker,
which becomes the current version of the object. If there isn't a null version, Amazon S3 does not remove
any objects.

Versioning

To remove a speciﬁc version, you must be the bucket owner and you must use the versionId
subresource. Using this subresource permanently deletes the version. If the object deleted is a delete
marker, Amazon S3 sets the response header, x-amz-delete-marker, to true.

For more information about MFA Delete, go to Using MFA Delete. To see sample requests that use
versioning, see Sample Request (p. 1242).

You can delete objects by explicitly calling the DELETE Object API or conﬁgure its lifecycle (see PUT
Bucket lifecycle (p. 1145)) to enable Amazon S3 to remove them for you. If you want to block users or
accounts from removing or deleting objects from your bucket you must deny them s3:DeleteObject,
s3:DeleteObjectVersion and s3:PutLifeCycleConfiguration actions.

Syntax

API Version 2006-03-01

1239
Amazon Simple Storage Service API Reference
DELETE Object

DELETE /ObjectName HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Content-Length: length
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Name Description Required

x-amz-mfa The value is the concatenation of the authentication device's serial Conditional
number, a space, and the value displayed on your authentication
device.

Type: String

Default: None

Condition: Required to permanently delete a versioned object if

versioning is conﬁgured with MFA Delete enabled.

Request Elements

This implementation of the operation does not use request elements.

Responses

API Version 2006-03-01

1240
Amazon Simple Storage Service API Reference
DELETE Object

Response Headers

Header Description

x-amz-delete- Speciﬁes whether the versioned object that was permanently deleted was
marker (true) or was not (false) a delete marker. In a simple DELETE, this header
indicates whether (true) or not (false) a delete marker was created.

Type: Boolean

Valid Values: true | false

Default: false

x-amz-version- Returns the version ID of the delete marker created as a result of the DELETE
id operation. If you delete a speciﬁc object version, the value returned by this
header is the version ID of the object version deleted.

Type: String

Default: None

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

API Version 2006-03-01

1241
Amazon Simple Storage Service API Reference
DELETE Object

Sample Request

The following request deletes the object, my-second-image.jpg.

DELETE /my-second-image.jpg HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain

Sample Response

HTTP/1.1 204 NoContent

Sample Request Deleting a Speciﬁed Version of an Object

The following request deletes the speciﬁed version of the object, my-third-image.jpg.

DELETE /my-third-image.jpg?versionId=UIORUnfndfiufdisojhr398493jfdkjFJjkndnqUifhnw89493jJFJ
HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 0

Sample Response

API Version 2006-03-01

1242
Amazon Simple Storage Service API Reference
DELETE Object

HTTP/1.1 204 NoContent

Sample Response if the Object Deleted is a Delete Marker

HTTP/1.1 204 NoContent

x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
x-amz-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
x-amz-delete-marker: true
Date: Wed, 12 Oct 2009 17:50:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3

Sample Request Deleting a Speciﬁed Version of an Object in an MFA-Enabled

Bucket

The following request deletes the speciﬁed version of the object, my-third-image.jpg, which is stored
in an MFA-enabled bucket.

DELETE /my-third-image.jpg?versionId=UIORUnfndfiuf HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
x-amz-mfa:[SerialNumber] [AuthenticationCode]
Authorization: authorization string
Content-Type: text/plain
Content-Length: 0

Sample Response

HTTP/1.1 204 NoContent

API Version 2006-03-01

1243
Amazon Simple Storage Service API Reference
DELETE Object

Related Resources

• PUT Object (p. 1324)

• DELETE Object (p. 1239)

API Version 2006-03-01

1244
Amazon Simple Storage Service API Reference
DELETE Object tagging

DELETE Object tagging

Description

This implementation of the DELETE operation uses the tagging subresource to remove the entire tag
set from the speciﬁed object. For more information about managing object tags, see Object Tagging in
the Amazon Simple Storage Service Developer Guide.

To use this operation, you must have permission to perform the s3:DeleteObjectTagging action.

To delete tags of a speciﬁc object version, add the versionId query parameter in the request. You will
need permission for the s3:DeleteObjectVersionTagging action.

Requests

Syntax

DELETE /ObjectKey?tagging HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

API Version 2006-03-01

1245
Amazon Simple Storage Service API Reference
DELETE Object tagging

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Examples

Sample Request

The following DELETE request deletes the tag set from the speciﬁed object.

API Version 2006-03-01

1246
Amazon Simple Storage Service API Reference
DELETE Object tagging

DELETE /exampleobject?tagging HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Wed, 25 Nov 2016 12:00:00 GMT
Authorization: signatureValue

Sample Response

The following successful response shows Amazon S3 returning a 204 No Content response. The tag set
for the object has been removed.

HTTP/1.1 204 No Content

Date: Wed, 25 Nov 2016 12:00:00 GMT
Connection: close
Server: AmazonS3

Related Resources

• PUT Object tagging (p. 1373)

• GET Object tagging (p. 1272)

API Version 2006-03-01

1247
Amazon Simple Storage Service API Reference
GET Object

GET Object

Description

This implementation of the GET operation retrieves objects from Amazon S3. To use GET, you must have
READ access to the object. If you grant READ access to the anonymous user, you can return the object
without using an authorization header.

To distribute large ﬁles to many people, you can save bandwidth costs by using BitTorrent. For more
information, see Amazon S3 Torrent in the Amazon Simple Storage Service Developer Guide. For more
information about returning the ACL of an object, see GET Object ACL (p. 1264).

If the object you are retrieving is stored in the GLACIER or DEEP_ARCHIVE storage classes, before you can
retrieve the object you must ﬁrst restore a copy using the POST Object restore (p. 1308) API. Otherwise,
this operation returns an InvalidObjectStateError error. For information about restoring archived
objects, see Restoring Archived Objects in the Amazon Simple Storage Service Developer Guide.

If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-
C) when you store the object in Amazon S3, then when you GET the object, you must use the headers
documented in the section Speciﬁc Request Headers for Server-Side Encryption with Customer-Provided
Encryption Keys (p. 1253). For more information about SSE-C, go to Server-Side Encryption (Using
Customer-Provided Encryption Keys) in the Amazon Simple Storage Service Developer Guide.

Assuming you have permission to read object tags (permission for the s3:GetObjectVersionTagging
action), the response also returns the x-amz-tagging-count header that provides the count of
number of tags associated with the object. You can use the "GET Object tagging" API (see GET Object
tagging (p. 1272)) to retrieve the tag set associated with an object.

API Version 2006-03-01

1248
Amazon Simple Storage Service API Reference
GET Object

Permissions

You need the s3:GetObject permission for this operation. For more information, go to Specifying
Permissions in a Policy in the Amazon Simple Storage Service Developer Guide. If the object you request
does not exist, the error Amazon S3 returns depends on whether you also have the s3:ListBucket
permission.

• If you have the s3:ListBucket permission on the bucket, Amazon S3 will return an HTTP status code
404 ("no such key") error.
• If you don’t have the s3:ListBucket permission, Amazon S3 will return an HTTP status code 403
("access denied") error.
• If your object is encrypted with Server-Side Encryption with AWS KMS-Managed Keys (SSE-KMS) you
will need to grant the kms:Decrypt permission before retrieving the object, else Amazon S3 will
return an HTTP status code 403 ("access denied") error.

Versioning

For more information about versioning, see PUT Bucket versioning (p. 1212) To see sample requests that
use versioning, see Sample Request Getting a Speciﬁed Version of an Object (p. 1260) .

Requests

Syntax

GET /ObjectName HTTP/1.1

API Version 2006-03-01

1249
Amazon Simple Storage Service API Reference
GET Object

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))
Range:bytes=byte_range

Request Parameters

Parameter Description Required

partNumber Part number of the object part being read. This is a No

positive integer between 1 and the maximum number of
parts supported.

Only objects uploaded using the multipart upload API

have part numbers. For information about multipart
uploads, see Multipart Upload Overview in the Amazon
Simple Storage Service Developer Guide.

Eﬀectively performs a 'ranged' GET request for the part

speciﬁed. Useful for downloading just a part of an object.

Type: Integer

Default: None

versionId Version ID used to reference a speciﬁc version of the No

object.

Type: String

Default: None

There are times when you want to override certain response header values in a GET response. For
example, you might override the Content-Disposition response header value in your GET request.

You can override values for a set of response headers using the query parameters listed in the following
table. These response header values are sent only on a successful request, that is, when status code 200
OK is returned. The set of headers you can override using these parameters is a subset of the headers
that Amazon S3 accepts when you create an object. The response headers that you can override for
the GET response are Content-Type, Content-Language, Expires, Cache-Control, Content-
Disposition, and Content-Encoding. To override these header values in the GET response, you use
the request parameters described in the following table.
Note
You must sign the request, either using an Authorization header or a presigned URL, when
using these parameters. They cannot be used with an unsigned (anonymous) request.

Parameter Description Required

Constraints: None

API Version 2006-03-01

Default: None

Constraints: None

Note
Encryption request headers, like x-amz-server-side-encryption, should not be sent for
GET requests if your object uses server-side encryption with AWS KMS–managed encryption
keys (SSE-KMS) or server-side encryption with Amazon S3–managed encryption keys (SSE-S3). If
your object does use these types of keys, you’ll get an HTTP 400 BadRequest error.

Note the following additional considerations about the preceding request headers:

• Consideration 1 – If both of the If-Match and If-Unmodified-Since headers are present in the
request as follows:

If-Match condition evaluates to true, and;

If-Unmodified-Since condition evaluates to false;

API Version 2006-03-01

1252
Amazon Simple Storage Service API Reference
GET Object

then, S3 returns 200 OK and the data requested. For more information about conditional requests, see
RFC 7232.

• Consideration 2 – If both of the If-None-Match and If-Modified-Since headers are present in
the request as follows:

If-None-Match condition evaluates to false, and;

If-Modified-Since condition evaluates to true;

then, S3 returns 304 Not Modified response code. For more information about conditional
requests, see RFC 7232.

Speciﬁc Request Headers for Server-Side Encryption with Customer-Provided Encryption Keys

When you retrieve an object from Amazon S3 that was encrypted by using server-side encryption with
customer-provided encryption keys (SSE-C), you must use the following request headers. For more
information about SSE-C, go to Server-Side Encryption (Using Customer-Provided Encryption Keys) in
the Amazon Simple Storage Service Developer Guide.

Name Description Required

x-amz-server- Speciﬁes the algorithm to use to when decrypting the requested Yes
side-encryption object.
-customer-
algorithm Type: String

Default: None

Valid Values: AES256

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-key and x-amz-server-side-
encryption-customer-key-MD5 headers.

x-amz-server- Speciﬁes the customer-provided base64-encoded encryption Yes

side-encryption key to use to decrypt the requested object. This value is used to
-customer-key perform the decryption and then it is discarded; Amazon does
not store the key. The key must be appropriate for use with the
algorithm speciﬁed in the x-amz-server-side-encryption-
customer-algorithm header.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-side-

encryption-customer-algorithm and x-amz-server-
side-encryption-customer-key-MD5 headers.

API Version 2006-03-01

1253
Amazon Simple Storage Service API Reference
GET Object

Name Description Required

x-amz-server- Speciﬁes the base64-encoded 128-bit MD5 digest of the No

side-encryption customer-provided encryption key according to RFC 1321. If
-customer-key- this header is included in your request, Amazon S3 uses it for a
MD5 message integrity check to ensure that the encryption key was
transmitted without error.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-side-

encryption-customer-algorithm and x-amz-server-
side-encryption-customer-key headers.

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

Header Description

x-amz-delete- Speciﬁes whether the object retrieved was (true) or was not (false) a delete
marker marker. If false, this response header does not appear in the response.

Type: Boolean

Valid Values: true | false

Default: false

API Version 2006-03-01

1254
Amazon Simple Storage Service API Reference
GET Object

Header Description
Amazon S3 does not provide a header to infer when a noncurrent version will
be eligible for permanent deletion. For more information, see PUT Bucket
lifecycle (p. 1145).

Type: String

x-amz-meta-* Headers starting with this prefix are user-defined metadata. Each one is stored
and returned as a set of key-value pairs. Amazon S3 doesn't validate or interpret
user-defined metadata.

Type: String

x-amz- Amazon S3 can return this header if your request involves a bucket that is either
replication- a source or destination in a cross-region replication.
status
In cross-region replication you have a source bucket on which you conﬁgure
replication and destination bucket where Amazon S3 stores object replicas.
When you request an object (GET Object) or object metadata (HEAD Object)
from these buckets, Amazon S3 will return the x-amz-replication-status
header in the response as follow:

• If requesting object from the source bucket — Amazon S3 will return the x-
amz-replication-status header if object in your request is eligible for
replication.

For example, suppose in your replication conﬁguration you specify object

prefix "TaxDocs" requesting Amazon S3 to replicate objects with key prefix
"TaxDocs". Then any objects you upload with this key name prefix, for example
"TaxDocs/document1.pdf", is eligible for replication. For any object request
with this key name prefix Amazon S3 will return the x-amz-replication-
status header with value PENDING, COMPLETED or FAILED indicating object
replication status.
• If requesting object from the destination bucket — Amazon S3 will return the
x-amz-replication-status header with value REPLICA if object in your
request is a replica that Amazon S3 created.

For more information, go to Cross-Region Replication in the Amazon Simple

Storage Service Developer Guide.

Valid Values: PENDING, COMPLETED, FAILED, REPLICA

Type: String

x-amz-server- If the object is stored using server-side encryption either with an AWS KMS or an
side-encryption Amazon S3-managed encryption key, the response includes this header with the
value of the encryption algorithm used.

Type: String

x-amz- If the x-amz-server-side-encryption is present and has the value of

server-side- aws:kms, this header speciﬁes the ID of the AWS Key Management Service
encryption-aws- (KMS) master encryption key that was used for the object.
kms-key-id
Type: String

API Version 2006-03-01

1255
Amazon Simple Storage Service API Reference
GET Object

Header Description

x-amz-server- If server-side encryption with customer-provided encryption keys decryption

side-encryption was requested, the response will include this header conﬁrming the decryption
-customer- algorithm used.
algorithm
Type: String

Valid Values: AES256

x-amz-server- If server-side encryption with customer-provided encryption keys decryption

side-encryption was requested, the response includes this header to provide roundtrip message
-customer-key- integrity veriﬁcation of the customer-provided encryption key.
MD5
Type: String

x-amz-storage- Provides storage class information of the object. Amazon S3 returns this header
class for all objects except for Standard storage class objects.

For more information, go to Storage Classes in Amazon Simple Storage Service

Developer Guide.

Type: String

Default: None

x-amz-restore Provides information about the object restoration operation and expiration time
of the restored object copy.

For more information about archiving objects and restoring them, go to

Transitioning Objects: General Considerations in the Amazon Simple Storage
Service Developer Guide.

Type: String

Default: None

x-amz-tagging- Returns the count of the tags associated with the object. This header is returned
count only if the count is greater than zero.

Type: String

Default: None

x-amz-version- Returns the version ID of the retrieved object if it has a unique version ID.
id
Type: String

Default: None

x-amz-website When a bucket is conﬁgured as a website, you can set this metadata on the
-redirect- object so the website endpoint will evaluate the request for the object as a 301
location redirect to another object in the same bucket or an external URL.

Type: String

Default: None

API Version 2006-03-01

1256
Amazon Simple Storage Service API Reference
GET Object

Header Description

x-amz-object- The Object Lock mode, if any, that's in eﬀect for this object. This header is only
lock-mode returned if the requester has the s3:GetObjectRetention permission. For
more information about S3 Object Lock, see Object Lock in the Amazon Simple
Storage Service Developer Guide.

Type: String

Valid values: GOVERNANCE | COMPLIANCE

x-amz-object- The date and time when the Object Lock retention period expires. This header is
lock-retain- only returned if the requester has the s3:GetObjectRetention permission.
until-date
Type: Timestamp

Format: 2020-01-05T00:00:00.000Z

x-amz-object- Specifies whether a legal hold is in effect for this object. This header is only
lock-legal-hold returned if the requester has the s3:GetObjectLegalHold permission. This
header is not returned if the specified version of this object has never had a legal
hold applied. For more information about legal holds, see Object Lock in the
Amazon Simple Storage Service Developer Guide.

Type: String

Valid values: ON | OFF

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

API Version 2006-03-01

1257
Amazon Simple Storage Service API Reference
GET Object

Sample Request

The following request returns the object, my-image.jpg.

GET /my-image.jpg HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Mon, 3 Oct 2016 22:32:00 GMT
Authorization: authorization string

Sample Response

[434234 bytes of object data]

If the object had tags associated with it, Amazon S3 returns the x-amz-tagging-count header with
tag count.

[434234 bytes of object data]

If the object had expiration set using lifecycle conﬁguration, you get the following response with the x-
amz-expiration header.

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT
x-amz-expiration: expiry-date="Fri, 23 Dec 2012 00:00:00 GMT", rule-id="picture-deletion-
rule"
ETag: "fba9dede5f27731c9771645a39863328"
Content-Length: 434234

API Version 2006-03-01

1258
Amazon Simple Storage Service API Reference
GET Object

Content-Type: text/plain

[434234 bytes of object data]

Sample Response if an Object Is Archived in S3 Glacier

An object archived in S3 Glacier must ﬁrst be restored before you can access it. If you attempt to access
an S3 Glacier object without restoring it, Amazon S3 returns the following error.

HTTP/1.1 403 Forbidden

<Error>
<Code>InvalidObjectState</Code>
<Message>The operation is not valid for the object's storage class</Message>
<RequestId>9FEFFF118E15B86F</RequestId>
<HostId>WVQ5kzhiT+oiUfDCOiOYv8W4Tk9eNcxWi/MK+hTS/av34Xy4rBU3zsavf0aaaaa</HostId>
</Error>

Sample Response if the Latest Object Is a Delete Marker

HTTP/1.1 404 Not Found

Notice that the delete marker returns a 404 Not Found error.

Sample Request for Getting an Object Part

The following request returns the speciﬁed part of the object test.txt.

API Version 2006-03-01

1259
Amazon Simple Storage Service API Reference
GET Object

GET /test.txt?partNumber=1 HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Mon, 3 Oct 2016 22:32:00 GMT
Authorization: authorization string

Sample Response to an Object Part Request

HTTP/1.1 206 Partial Content

x-amz-id-2: 4lJovnctP+tyF27MwR7pAg0Y9Jgf0AVAL+pOhyJlWM4yCxwdbnilC/BlSVFxbmzIvjtgTPqLDrU=
x-amz-request-id: 8AC212BBF9DF3D33
Date: Thu, 28 Jun 2018 20:11:04 GMT
Last-Modified: Thu, 28 Jun 2018 19:16:25 GMT
ETag: "497db513b7b597ec93459bd2f3c9a452"
x-amz--mp-parts-count: 6
Accept-Ranges: bytes
Content-Range: bytes 0-121443838/876536789
Content-Type: binary/octet-stream
Content-Length: 121443839

[121443839 bytes of object data]

Sample Request Getting a Speciﬁed Version of an Object

The following request returns the speciﬁed version of an object.

GET /myObject?versionId=3/L4kqtJlcpXroDTDmpUMLUo HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response to a Versioned Object GET Request

API Version 2006-03-01

1260
Amazon Simple Storage Service API Reference
GET Object

Content-Type: text/plain
Connection: close
Server: AmazonS3
[434234 bytes of object data]

Sample Request with Parameters Altering Response Header Values

The following request speciﬁes all the query string parameters in a GET request overriding the response
header values.

GET /Junk3.txt?response-cache-control=No-cache&response-content-disposition=attachment%3B
%20filename%3Dtesting.txt&response-content-encoding=x-gzip&response-content-language=mi%2C
%20en&response-expires=Thu%2C%2001%20Dec%201994%2016:00:00%20GMT HTTP/1.1
x-amz-date: Sun, 19 Dec 2010 01:53:44 GMT
Accept: */*
Authorization: AWS AKIAIOSFODNN7EXAMPLE:aaStE6nKnw8ihhiIdReoXYlMamW=

Sample Response with Overridden Response Header Values

In the following sample response note, the header values are set to the values speciﬁed in the true
request.

[object data not shown]

Sample Request with a Range Header

API Version 2006-03-01

1261
Amazon Simple Storage Service API Reference
GET Object

The following request speciﬁes the HTTP Range header to retrieve the ﬁrst 10 bytes of an object. For
more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-
sec14.html.

GET /example-object HTTP/1.1

Host: example-bucket.s3.amazonaws.com
x-amz-date: Fri, 28 Jan 2011 21:32:02 GMT
Range: bytes=0-9
Authorization: AWS AKIAIOSFODNN7EXAMPLE:Yxg83MZaEgh3OZ3l0rLo5RTX11o=
Sample Response with Specified Range of the Object Bytes

Note
Amazon S3 doesn't support retrieving multiple ranges of data per GET request.

Sample Response

In the following sample response, note that the header values are set to the values speciﬁed in the true
request.

HTTP/1.1 206 Partial Content

x-amz-id-2: MzRISOwyjmnupCzjI1WC06l5TTAzm7/JypPGXLh0OVFGcJaaO3KW/hRAqKOpIEEp
x-amz-request-id: 47622117804B3E11
Date: Fri, 28 Jan 2011 21:32:09 GMT
x-amz-meta-title: the title
Last-Modified: Fri, 28 Jan 2011 20:10:32 GMT
ETag: "b2419b1e3fd45d596ee22bdf62aaaa2f"
Accept-Ranges: bytes
Content-Range: bytes 0-9/443
Content-Type: text/plain
Content-Length: 10
Server: AmazonS3

[10 bytes of object data]

Sample: Get an Object Stored Using Server-Side Encryption with Customer-

Provided Encryption Keys

If an object is stored in Amazon S3 using server-side encryption with customer-provided encryption

keys, Amazon S3 needs encryption information so that it can decrypt the object before sending it to
you in response to a GET request. You provide the encryption information in your GET request using
the relevant headers (see Speciﬁc Request Headers for Server-Side Encryption with Customer-Provided
Encryption Keys (p. 1253)), as shown in the following example request.

GET /example-object HTTP/1.1

Host: example-bucket.s3.amazonaws.com

API Version 2006-03-01

1262
Amazon Simple Storage Service API Reference
GET Object

Accept: */*
Authorization:authorization string
Date: Wed, 28 May 2014 19:24:44 +0000
x-amz-server-side-encryption-customer-key:g0lCfA3Dv40jZz5SQJ1ZukLRFqtI5WorC/8SEKEXAMPLE
x-amz-server-side-encryption-customer-key-MD5:ZjQrne1X/iTcskbY2m3example
x-amz-server-side-encryption-customer-algorithm:AES256

The following sample response shows some of the response headers Amazon S3 returns. Note that it
includes the encryption information in the response.

Related Resources

• GET Service (p. 847)

• GET Object ACL (p. 1264)

API Version 2006-03-01

1263
Amazon Simple Storage Service API Reference
GET Object ACL

GET Object ACL

Description

This implementation of the GET operation uses the acl subresource to return the access control list
(ACL) of an object. To use this operation, you must have READ_ACP access to the object.

Versioning

By default, GET returns ACL information about the current version of an object. To return ACL
information about a diﬀerent version, use the versionId subresource.

To see sample requests that use Versioning, see Sample Request Getting the ACL of the Speciﬁc Version
of an Object (p. 1268).

Requests

Syntax

GET /ObjectName?acl HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))
Range:bytes=byte_range

API Version 2006-03-01

1264
Amazon Simple Storage Service API Reference
GET Object ACL

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

API Version 2006-03-01

1265
Amazon Simple Storage Service API Reference
GET Object ACL

Name Description

AccessControlList Container for Grant, Grantee, and Permission.

Type: Container

Ancestors: AccessControlPolicy

AccessControlPolicy Contains the elements that set the ACL permissions for an object per
Grantee.

Type: Container

Ancestors: None

DisplayName Screen name of the bucket owner.

Important
This value is only included in the response in the US East (N.
Virginia), US West (N. California), US West (Oregon), Asia Pacific
(Singapore), Asia Pacific (Sydney), Asia Pacific (Tokyo), Europe
(Ireland), and South America (São Paulo) regions.
For a list of all the Amazon S3 supported regions and endpoints,
see Regions and Endpoints in the AWS General Reference.

API Version 2006-03-01

1266
Amazon Simple Storage Service API Reference
GET Object ACL

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

The following request returns information, including the ACL, of the object, my-image.jpg.

GET /my-image.jpg?acl HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response

<AccessControlPolicy>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>

API Version 2006-03-01

1267
Amazon Simple Storage Service API Reference
GET Object ACL

<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser">
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>

Sample Request Getting the ACL of the Speciﬁc Version of an Object

The following request returns information, including the ACL, of the speciﬁed version of the object, my-
image.jpg.

GET /my-image.jpg?versionId=3/L4kqtJlcpXroDVBH40Nr8X8gdRQBpUMLUo&acl HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response Showing the ACL of the Speciﬁc Version

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
x-amz-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
Content-Length: 124
Content-Type: text/plain
Connection: close
Server: AmazonS3

<AccessControlPolicy>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser">
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>

API Version 2006-03-01

1268
Amazon Simple Storage Service API Reference
GET Object ACL

</Grant>
</AccessControlList>
</AccessControlPolicy>

Related Resources

• GET Object (p. 1248)

• PUT Object (p. 1324)
• DELETE Object (p. 1239)

API Version 2006-03-01

1269
Amazon Simple Storage Service API Reference
GET Object legal hold

GET Object legal hold

Service: Amazon Simple Storage Service

Gets an object's current Legal Hold status.

Request Syntax
GET /<object-key>?legal-hold&versionId=<version-id> HTTP/1.1
Host: <bucket-name>.s3.amazonaws.com
Date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization-string> (see Authenticating Requests (AWS Signature Version
4))

URI Request Parameters

versionId

The version ID for the object version whose retention settings you want to retrieve.

Request Body
The request does not have a request body.

Response Syntax
HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<LegalHold>
<Status>string</Status>
</LegalHold>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

For more information about the response elements that this operation returns, see
ObjectLockLegalHold (p. 1459).

Related Resources
Locking Objects in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

1270
Amazon Simple Storage Service API Reference
GET Object retention

GET Object retention

Service: Amazon Simple Storage Service

Retrieves an object's retention settings.

Request Syntax
GET /<object-key>?retention&versionId=<version-id> HTTP/1.1
Host: <bucket-name>.s3.amazonaws.com
Date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization-string> (see Authenticating Requests (AWS Signature Version
4))

URI Request Parameters

versionId

The version ID for the object version whose retention settings you want to retrieve.

Request Body
The request does not have a request body.

Response Syntax
<Retention>
<Mode><value></Mode>
<RetainUntilDate><value></RetainUntilDate>
</Retention>

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

For more information about the response elements this operation returns, see
ObjectLockRetention (p. 1460).

Related Resources
Locking Objects in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

1271
Amazon Simple Storage Service API Reference
GET Object tagging

GET Object tagging

Description

This implementation of the GET operation returns the tags associated with an object. You send the GET
request against the tagging subresource associated with the object.

To use this operation, you must have permission to perform the s3:GetObjectTagging action.
By default, the GET operation returns information about current version of an object. For a
versioned bucket, you can have multiple versions of an object in your bucket. To retrieve tags
of any other version, use the versionId query parameter. You also need permission for the
s3:GetObjectVersionTagging action.

By default, the bucket owner has this permission and can grant this permission to others.

For information about the Amazon S3 object tagging feature, see Object Tagging in the Amazon Simple
Storage Service Developer Guide.

Requests

Syntax

GET /ObjectName?tagging HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

API Version 2006-03-01

1272
Amazon Simple Storage Service API Reference
GET Object tagging

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

API Version 2006-03-01

1273
Amazon Simple Storage Service API Reference
GET Object tagging

Name Description

Tagging Container for the TagSet element.

Type: Container

Ancestors: None

TagSet Contains the tag set.

Type: Container

Ancestors: Tagging

Tag Contains the tag information.

Type: Container

Ancestors: TagSet

Key Name of the tag

Type: String

Ancestors: Tag

Value Value of the tag

Type: String

Ancestors: Tag

Examples

Sample Request

The following request returns the tag set of the speciﬁed object.

GET /example-object?tagging HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Thu, 22 Sep 2016 21:33:08 GMT
Authorization: authorization string

API Version 2006-03-01

1274
Amazon Simple Storage Service API Reference
GET Object tagging

Sample Response

Related Resources

• PUT Object tagging (p. 1373)

API Version 2006-03-01

1275
Amazon Simple Storage Service API Reference
GET Object torrent

GET Object torrent

Description

This implementation of the GET operation uses the torrent subresource to return torrent ﬁles from
a bucket. BitTorrent can save you bandwidth when you're distributing large ﬁles. For more information
about BitTorrent, see Amazon S3 Torrent.
Note
You can get torrent only for objects that are less than 5 GB in size and that are not encrypted
using server-side encryption with customer-provided encryption key.

To use GET, you must have READ access to the object.

Requests

Syntax

GET /ObjectName?torrent HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This implementation of the operation does not use request parameters.

API Version 2006-03-01

1276
Amazon Simple Storage Service API Reference
GET Object torrent

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of the operation does not return response elements.

Special Errors

API Version 2006-03-01

1277
Amazon Simple Storage Service API Reference
GET Object torrent

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Getting Torrent Files in a Bucket

This example retrieves the Torrent ﬁle for the "Nelson" object in the "quotes" bucket.

GET /quotes/Nelson?torrent HTTP/1.0

Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

Sample Response

<body: a Bencoded dictionary as defined by the BitTorrent specification>

Related Resources

• GET Object (p. 1248)

API Version 2006-03-01

1278
Amazon Simple Storage Service API Reference
HEAD Object

HEAD Object

Description

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

A HEAD request has the same options as a GET operation on an object. The response is identical to the
GET response except that there is no response body.

If you encrypt an object by using server-side encryption with customer-provided encryption keys (SSE-
C) when you store the object in Amazon S3, when you retrieve the metadata from the object, you must
use the headers documented in Speciﬁc Request Headers for Server-Side Encryption with Customer-
Provided Encryption Keys (p. 1282). For more information about SSE-C, go to Server-Side Encryption
(Using Customer-Provided Encryption Keys) in the Amazon Simple Storage Service Developer Guide.

Permissions

Versioning

API Version 2006-03-01

1279
Amazon Simple Storage Service API Reference
HEAD Object

By default, the HEAD operation retrieves metadata from the current version of an object. If the current
version is a delete marker, Amazon S3 behaves as if the object was deleted. To retrieve metadata from
a diﬀerent version, use the versionId subresource. For more information, see Versions in the Amazon
Simple Storage Service Developer Guide.

To see sample requests that use versioning, see Sample Request Getting Metadata from a Speciﬁed
Version of an Object (p. 1289).

Requests

Syntax

HEAD /ObjectName HTTP/1.1

Host: BucketName.s3.amazonaws.com
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))
Date: date

Request Parameters

Parameter Description Required

partNumber Part number of the object part being read. This is a No

positive integer between 1 and the maximum number of
parts supported.

Only objects uploaded using the multipart upload API

have part numbers. For information about multipart
uploads, see Multipart Upload Overview in the Amazon
Simple Storage Service Developer Guide.

Eﬀectively performs a 'ranged' HEAD request for the part

speciﬁed. Useful for downloading just a part of an object.

Type: Integer

Default: None

API Version 2006-03-01

See Consideration 1 after the table.

API Version 2006-03-01

1281
Amazon Simple Storage Service API Reference
HEAD Object

Name Description Required

Type: String

Default: None

Constraints: None

If-None-Match Return the object only if its entity tag (ETag) is different from the No
one specified; otherwise, return a 304 (not modified).

See Consideration 2 after the table.

Type: String

Default: None

Constraints: None

Note the following additional considerations about the preceding request headers:

• Consideration 1 – If both of the If-Match and If-Unmodified-Since headers are present in the
request as follows:

If-Match condition evaluates to true, and;

If-Unmodified-Since condition evaluates to false;

then, Amazon S3 returns 200 OK and the data requested. For more information about conditional
requests, see RFC 7232.

• Consideration 2 – If both of the If-None-Match and If-Modified-Since headers are present in
the request as follows:

If-None-Match condition evaluates to false, and;

If-Modified-Since condition evaluates to true;

then, Amazon S3 returns the 304 Not Modified response code. For more information about
conditional requests, see RFC 7232.

Speciﬁc Request Headers for Server-Side Encryption with Customer-Provided Encryption Keys

When you retrieve metadata from an object stored in Amazon S3 that was encrypted by using server-
side encryption with customer-provided encryption keys (SSE-C), you must use the following request

API Version 2006-03-01

1282
Amazon Simple Storage Service API Reference
HEAD Object

headers. For more information about SSE-C, go to Server-Side Encryption (Using Customer-Provided
Encryption Keys) in the Amazon Simple Storage Service Developer Guide.

Name Description Required

x-amz-server- Speciﬁes the algorithm to use to when decrypting the requested Yes
side-encryption object.
-customer-
algorithm Type: String

Default: None

Valid Values: AES256

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-key and x-amz-server-side-
encryption-customer-key-MD5 headers.

x-amz-server- Speciﬁes the customer-provided base64-encoded encryption Yes

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-side-

encryption-customer-algorithm and x-amz-server-
side-encryption-customer-key-MD5 headers.

x-amz-server- Speciﬁes the base64-encoded 128-bit MD5 digest of the No

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-side-

encryption-customer-algorithm and x-amz-server-
side-encryption-customer-key headers.

Request Elements

This implementation of the operation does not use request elements.

x-amz-restore If the object is an archived object (an object whose storage class is
GLACIER), the response includes this header if either the archive
restoration is in progress (see POST Object restore (p. 1308)) or an archive
copy is already restored.

If an archive copy is already restored, the header value indicates when

Amazon S3 is scheduled to delete the object copy. For example,

x-amz-restore: ongoing-request="false", expiry-date="Fri,

23 Dec 2012 00:00:00 GMT"

If the object restoration is in progress, the header returns the value

ongoing-request="true".

For more information about archiving objects, see Transitioning Objects:

General Considerations in the Amazon Simple Storage Service Developer
Guide

Type: String

Default: None

x-amz-server-side- If the object is stored using server-side encryption either with an AWS
encryption KMS or an Amazon S3-managed encryption key, the response includes this
header with the value of the encryption algorithm used.

Type: String

x-amz-server-side- If the x-amz-server-side-encryption is present and has the value of

encryption-aws-kms- aws:kms, this header speciﬁes the ID of the AWS KMS master encryption
key-id key that was used for the object.

Type: String

API Version 2006-03-01

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

The following request returns the metadata of an object.

HEAD /my-image.jpg HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:02236Q3V0RonhpaBX5sCYVf1bNRuU=

Sample Response

API Version 2006-03-01

1287
Amazon Simple Storage Service API Reference
HEAD Object

If the object is scheduled to expire according to a lifecycle conﬁguration set on the bucket, the response
returns the x-amz-expiration tag with information about when Amazon S3 will delete the object.
For more information, see Transitioning Objects: General Considerations in the Amazon Simple Storage
Service Developer Guide.

HTTP/1.1 200 OK
x-amz-id-2: azQRZtQJ2m1P8R+TIsG9h0VuC/DmiSJmjXUMq7snk+LKSJeurtmfzSlGhR46GzSJ
x-amz-request-id: 0EFF61CCE3F24A26
Date: Mon, 17 Dec 2012 02:26:39 GMT
Last-Modified: Mon, 17 Dec 2012 02:14:10 GMT
x-amz-expiration: expiry-date="Fri, 21 Dec 2012 00:00:00 GMT", rule-id="Rule for
testfile.txt"
ETag: "54b0c58c7ce9f2a8b551351102ee0938"
Accept-Ranges: bytes
Content-Type: text/plain
Content-Length: 14
Server: AmazonS3

Sample Request for Getting Metadata from an Object Part

The following request returns the metadata for the speciﬁed part of the object test.txt.

HEAD /test.txt?partNumber=1 HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 12 Jun 2019 16:52:50 GMT
Authorization: authorization string

Sample Response to an Object Part HEAD Request

HTTP/1.1 206 Partial Content

x-amz-id-2: oMGCGCG2SFoQ//zIZ/7zCrGI1bIa+STIEhXLeFVbYnoVszvgXHepSQuJ3U/kFBNiLFhZbqlhevQ=
x-amz-request-id: 82291A7EE7DD9E30
Date: Wed, 12 Jun 2019 16:52:53 GMT
Last-Modified: Mon, 06 Mar 2017 21:21:28 GMT

API Version 2006-03-01

1288
Amazon Simple Storage Service API Reference
HEAD Object

ETag: "46ea6cc5c77a33c569e5700f0ca465d8-2"
x-amz-mp-parts-count: 2
x-amz-version-id: null
Accept-Ranges: bytes
Content-Range: bytes 0-7495543/14990261
Content-Type: binary/octet-stream
Content-Length: 7495544
Server: AmazonS3

Sample Request Getting Metadata from a Speciﬁed Version of an Object

The following request returns the metadata of the speciﬁed version of an object.

HEAD /my-image.jpg?versionId=3HL4kqCxf3vjVBH40Nrjfkd HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:02236Q3V0WpaBX5sCYVf1bNRuU=

Sample Response to a Versioned HEAD Request

Sample Request for a S3 Glacier Object

This implementation of the operation does not use request elements.

Responses

API Version 2006-03-01

1292
Amazon Simple Storage Service API Reference
OPTIONS object

Response Headers

Header Description

Access-Control-Allow- The origin you sent in your request. If the origin in your request is not
Origin allowed, Amazon S3 will not include this header in the response.

Type: String

Access-Control-Max-Age How long, in seconds, the results of the preﬂight request can be
cached.

Type: String

Access-Control-Allow- The HTTP method that was sent in the original request. If the
Methods method in the request is not allowed, Amazon S3 will not include this
header in the response.

Type: String

Access-Control-Expose- A comma-delimited list of HTTP headers. This header provides the

Headers JavaScript client with access to these headers in the response to the
actual request.

Type: String

Response Elements

This implementation of the operation does not return response elements.

Examples

API Version 2006-03-01

1293
Amazon Simple Storage Service API Reference
OPTIONS object

Example : Send a preﬂight OPTIONS request to a cors enabled bucket

A browser can send this preﬂight request to Amazon S3 to determine if it can send the actual PUT
request from http://www.example.com origin to the Amazon S3 bucket named examplebucket.

Sample Request

OPTIONS /exampleobject HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Origin: http://www.example.com
Access-Control-Request-Method: PUT

Sample Response

Related Resources

• GET Bucket cors (p. 966)

• DELETE Bucket cors (p. 897)
• PUT Bucket cors (p. 1124)

API Version 2006-03-01

1294
Amazon Simple Storage Service API Reference
POST Object

POST Object
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

Description

The POST operation adds an object to a specified bucket using HTML forms. POST is an alternate form
of PUT that enables browser-based uploads as a way of putting objects in buckets. Parameters that are
passed to PUT via HTTP Headers are instead passed as form fields to POST in the multipart/form-data
encoded message body. You must have WRITE access on a bucket to add an object to it. Amazon S3
never stores partial objects: if you receive a successful response, you can be confident the entire object
was stored.

Amazon S3 is a distributed system. If Amazon S3 receives multiple write requests for the same object
simultaneously, all but the last object written is overwritten.

Versioning

If you enable versioning for a bucket, POST automatically generates a unique version ID for the object
being added. Amazon S3 returns this ID in the response using the x-amz-version-id response header.

If you suspend versioning for a bucket, Amazon S3 always uses null as the version ID of the object
stored in a bucket.

API Version 2006-03-01

1295
Amazon Simple Storage Service API Reference
POST Object

For more information about returning the versioning state of a bucket, see GET Bucket (Versioning
Status) (p. 1057).

Amazon S3 is a distributed system. If you enable versioning for a bucket and Amazon S3 receives
multiple write requests for the same object simultaneously, all of the objects are stored.

To see sample requests that use versioning, see Sample Request (p. 1305).

Requests

Syntax

POST / HTTP/1.1
Host: destinationBucket.s3.amazonaws.com
User-Agent: browser_data
Accept: file_types
Accept-Language: Regions
Accept-Encoding: encoding
Accept-Charset: character_set
Keep-Alive: 300
Connection: keep-alive
Content-Type: multipart/form-data; boundary=9431149156168
Content-Length: length

--9431149156168
Content-Disposition: form-data; name="key"

acl
--9431149156168
Content-Disposition: form-data; name="tagging"

<Tagging><TagSet><Tag><Key>Tag Name</Key><Value>Tag Value</Value></Tag></TagSet></Tagging>

--9431149156168
Content-Disposition: form-data; name="success_action_redirect"

success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Type"

content_type
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-uuid"

uuid
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-tag"

metadata
--9431149156168

API Version 2006-03-01

1296
Amazon Simple Storage Service API Reference
POST Object

Content-Disposition: form-data; name="AWSAccessKeyId"

access-key-id
--9431149156168
Content-Disposition: form-data; name="Policy"

encoded_policy
--9431149156168
Content-Disposition: form-data; name="Signature"

signature=
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg

file_content
--9431149156168
Content-Disposition: form-data; name="submit"

Upload to Amazon S3
--9431149156168--

Request Parameters

This implementation of the operation does not use request parameters.

Form Fields

This operation can use the following form ﬁelds.

Name Description Required

AWSAccessKeyId The AWS access key ID of the owner of the bucket who Conditional
grants an Anonymous user access for a request that
satisﬁes the set of constraints in the policy.

Type: String

Default: None

Constraints: Required if a policy document is included

with the request.

acl Speciﬁes an Amazon S3 access control list. If an invalid No

access control list is speciﬁed, an error is generated.
For more information on ACLs, go to Access Control
List (ACL) Overview in the Amazon Simple Storage
Service Developer Guide.

API Version 2006-03-01

1297
Amazon Simple Storage Service API Reference
POST Object

Name Description Required

Type: String

Default: private

policy Security Policy describing what is permitted in the Conditional

request. Requests without a security policy are
considered anonymous and work only on publicly
writable buckets. For more information, go to HTML
Forms and Upload Examples.

Type: String

Default: None

Constraints: Policy is required if the bucket is not

publicly writable.

API Version 2006-03-01

1298
Amazon Simple Storage Service API Reference
POST Object

Name Description Required

success_action_redirect, The URL to which the client is redirected upon No

redirect successful upload.

If success_action_redirect is not speciﬁed,

Amazon S3 returns the empty document type speciﬁed
in the success_action_status ﬁeld.

If Amazon S3 cannot interpret the URL, it acts as if the

ﬁeld is not present.

If the upload fails, Amazon S3 displays an error and

does not redirect the user to a URL.

Type: String

Default: None
Note
The redirect ﬁeld name is deprecated, and
support for the redirect ﬁeld name is removed
in the future.

success_action_status If you don't specify success_action_redirect, the No

status code is returned to the client when the upload
succeeds.

Accepts the values 200, 201, or 204 (the default).

If the value is set to 200 or 204, Amazon S3 returns an

empty document with a 200 or 204 status code.

If the value is set to 201, Amazon S3 returns an XML

document with a 201 status code.

If the value is not set or if it is set to an invalid value,

Amazon S3 returns an empty document with a 204
status code.

Type: String

API Version 2006-03-01

1299
Amazon Simple Storage Service API Reference
POST Object

Name Description Required

tagging Speciﬁes set of tags to add to the object using the No

following encoding scheme.

<Tagging>
<TagSet>
<Tag>
<Key>Tag Name</Key>
<Value>Tag Value</Value>
</Tag>
...
</TagSet>
</Tagging>

For more information, see Object Tagging in the

Amazon Simple Storage Service Developer Guide.

Type: String

Name Description Required

x-amz-website-redirect- If the bucket is conﬁgured as a website, redirects No

In the following example, the request header sets the

redirect to an object (anotherPage.html) in the
same bucket:

x-amz-website-redirect-location: /
anotherPage.html

In the following example, the request header sets the

object redirect to another website:

x-amz-website-redirect-location: http://
www.example.com/

For more information about website hosting in

Amazon S3, see Hosting Websites on Amazon S3
and How to Conﬁgure Website Page Redirects in the
Amazon Simple Storage Service Developer Guide.

Type: String

Default: None

Constraints: The value must be preﬁxed by, "/",

"http://" or "https://". The length of the value is
limited to 2 K.

Server-Side Encryption Speciﬁc Request Form Fields

For more information, see Protecting Data Using Server-Side Encryption in the Amazon Simple Storage
Service Developer Guide.

Depending on whether you want to use AWS-managed encryption keys or provide your own encryption
keys, the following form ﬁelds:

• Use AWS-managed encryption keys — If you want Amazon S3 to manage keys used to encrypt data,
specify the following form ﬁelds in the request.

API Version 2006-03-01

1301
Amazon Simple Storage Service API Reference
POST Object

Name Description Required

x-amz-server- Speciﬁes a server-side encryption algorithm to use when Yes

side-encryption Amazon S3 creates an object.

Type: String

Valid Value: aws:kms, AES256

x-amz-server- If the x-amz-server-side-encryption is present and has Yes, if the

x-amz-server- If x-amz-server-side-encryption is present, and if its No

Type: String

Name Description Required

x-amz-server- Speciﬁes the algorithm to use to when encrypting the object. Yes
side-encryption-
customer- Type: String
algorithm
Default: None

Valid Value: AES256

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-key and x-amz-server-
side-encryption-customer-key-MD5 ﬁelds.

x-amz-server- Speciﬁes the customer-provided base64-encoded encryption Yes

API Version 2006-03-01

1302
Amazon Simple Storage Service API Reference
POST Object

Name Description Required

with the algorithm speciﬁed in the x-amz-server-side-
encryption-customer-algorithm header.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key-MD5 ﬁelds.

x-amz-server- Speciﬁes the base64-encoded 128-bit MD5 digest of the Yes

side-encryption- encryption key according to RFC 1321. Amazon S3 uses this
customer-key-MD5 header for a message integrity check to ensure that the
encryption key was transmitted without error.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key ﬁelds.

Responses

Response Headers

Name Description

x-amz-expiration If an Expiration action is conﬁgured for the object

API Version 2006-03-01

1303
Amazon Simple Storage Service API Reference
POST Object

Name Description
Type: String

success_action_redirect, The URL to which the client is redirected on successful

redirect upload.

Type: String

Ancestor: PostResponse

x-amz-server-side-encryption If you speciﬁed server-side encryption either with AWS

KMS encryption or AWS-managed encryption in your
POST request, the response includes this header. It
conﬁrms the encryption algorithm that Amazon S3 used
to encrypt the object.

Type: String

x-amz-server-side-encryption- If the x-amz-server-side-encryption header is

aws-kms-key-id present and has the value of aws:kms, this header
speciﬁes the ID of the AWS KMS master encryption key
that was used for the object.

Type: String

Type: String

API Version 2006-03-01

1304
Amazon Simple Storage Service API Reference
POST Object

Name Description
Ancestor: PostResponse

Type: String

Ancestor: PostResponse

Key The object key name.

Type: String

Ancestor: PostResponse

Location URI of the object.

Type: String

Ancestor: PostResponse

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

POST /Neo HTTP/1.1

Content-Length: 4
Host: quotes.s3.amazonaws.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string
Content-Type: text/plain

API Version 2006-03-01

1305
Amazon Simple Storage Service API Reference
POST Object

Expect: the 100-continue HTTP status code

ObjectContent

Sample Response with Versioning Suspended

The following is a sample response when bucket versioning is suspended:

HTTP/1.1 100 Continue

In this response, the version ID is null.

Sample Response with Versioning Enabled

The following is a sample response when bucket versioning is enabled.

HTTP/1.1 100 Continue

Related Resources

• PUT Object - Copy (p. 1344)

Restoring Archives

To restore a speciﬁc object version, you can provide a version ID. If you don't provide a version ID,
Amazon S3 restores the current version.

The time it takes restore jobs to ﬁnish depends on which storage class the object is being restored from
and which data access tier you specify.

API Version 2006-03-01

1309
Amazon Simple Storage Service API Reference
POST Object restore

When restoring an archived object (or using a select request), you can specify one of the following data
access tier options in the Tier element of the request body:

For more information about archive retrieval options and provisioned capacity for Expedited data
access, see Restoring Archived Objects in the Amazon Simple Storage Service Developer Guide.

After restoring an archived object, you can update the restoration period by reissuing the request with a
new period. Amazon S3 updates the restoration period relative to the current time and charges only for
the request—there are no data transfer charges. You cannot update the restoration period when Amazon
S3 is actively processing your current restore request for the object.

If your bucket has a lifecycle conﬁguration with a rule that includes an expiration action, the object
expiration overrides the life span that you specify in a restore request. For example, if you restore an
object copy for 10 days, but the object is scheduled to expire in 3 days, Amazon S3 deletes the object in
3 days. For more information about lifecycle conﬁguration, see PUT Bucket lifecycle (p. 1145) and Object
Lifecycle Management in Amazon Simple Storage Service Developer Guide.

Requests

API Version 2006-03-01

1310
Amazon Simple Storage Service API Reference
POST Object restore

Syntax

POST /ObjectName?restore&versionId=VersionID HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))
Content-MD5: MD5

request body

Note
The syntax shows some of the request headers. For a complete list, see "Request Headers," later
in this topic.

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Name Description Required

Type: String

Default: None

Request Elements

API Version 2006-03-01

1311
Amazon Simple Storage Service API Reference
POST Object restore

The following is an XML example of a request body for restoring an archive.

The following table explains the XML for archive restoration in the request body.

Name Description Required

RestoreRequest Container for restore information. Yes

Type: Container

Do not use this element with a SELECT type of request.

Type: Positive integer

Ancestors: RestoreRequest

Container for Glacier job parameters.

GlacierJobParameters No

Do not use this element with a SELECT type of request.

Type: Container

Ancestors: RestoreRequest

Tier The data access tier to use when restoring the archive. No
Standard is the default.

Type: Enum

Valid values: Expedited | Standard | Bulk

Ancestors: GlacierJobParameters

The following XML is the request body for a select query on an archived object:

<RestoreRequest>
<Type>SELECT</Type>
<Tier>Expedited</Tier>
<Description>Job description</Description>
<SelectParameters>
<Expression>Select * from Object</Expression>
<ExpressionType>SQL</ExpressionType>
<InputSerialization>
<CSV>
<FileHeaderInfo>IGNORE</FileHeaderInfo>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>

API Version 2006-03-01

1312
Amazon Simple Storage Service API Reference
POST Object restore

<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
<Comments>#</Comments>
</CSV>
</InputSerialization>
<OutputSerialization>
<CSV>
<QuoteFields>ASNEEDED</QuoteFields>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
</CSV>
</OutputSerialization>
</SelectParameters>
<OutputLocation>
<S3>
<BucketName>Name of bucket</BucketName>
<Prefix>Key prefix</Prefix>
<CannedACL>Canned ACL string</CannedACL>
<AccessControlList>
<Grantee>
<Type>Grantee Type</Type>
<ID>Grantee identifier</ID>
<URI>Grantee URI</URI>
<Permission>Granted permission</Permission>
<DisplayNmae>Display Name</DisplayName>
<EmailAddress>email</EmailAddress>
</Grantee>
</AccessControlList>
<Encryption>
<EncryptionType>Encryption type</EncryptionType>
<KMSKeyId>KMS Key ID</KMSKeyId>
<KMSContext>Base64-encoded JSON<KMSContext>
</Encryption>
<UserMetadata>
<MetadataEntry>
<Name>Key</Name>
<Value>Value</Value>
</MetadataEntry>
</UserMetadata>
<Tagging>
<TagSet>
<Tag>
<Key>Tag name</Key>
<Value>Tag value</Value>
</Tag>
</TagSet>
</Tagging>
<StorageClass>Storage class</StorageClass>
</S3>
</OutputLocation>
</RestoreRequest>

The following tables explain the XML for a SELECT type of restoration in the request body.

Name Description Required

RestoreRequest Container for restore information. Yes

Type: Container

Tier The data access tier to use when restoring the archive. No
Standard is the default.

API Version 2006-03-01

1313
Amazon Simple Storage Service API Reference
POST Object restore

Name Description Required

Type: Enum

Valid values: Expedited | Standard | Bulk

Ancestors: RestoreRequest

Description The optional description for the request. No

Type: String

Ancestors: RestoreRequest

Describes the parameters for the select job request.

SelectParameters Yes, if request
type is SELECT
Type: Container

Ancestors: RestoreRequest

OutputLocation Describes the location that receives the results of the select Yes, if request
restore request. type is SELECT

Type: Container for Amazon S3

Ancestors: RestoreRequest

The SelectParameters container element contains the following elements.

Name Description Required

Expression The SQL expression. For example: Yes

• The following SQL expression retrieves the ﬁrst column of the

data from the object stored in CSV format:

SELECT s._1 FROM Object s

• The following SQL expression returns everything from the
object:

SELECT * FROM Object

Type: String

Describes how the results of the select job are serialized.

OutputSerialization Yes

Type: Container for CSV

Ancestors: SelectParameters

The CSV container element in the InputSerialization element contains the following
elements.

Name Description Required

RecordDelimiterA single character used to separate individual records in the No

input. Instead of the default value, you can specify an arbitrary
delimiter.

Type: String

Default: \n

Ancestors: CSV

FieldDelimiter A single character used to separate individual ﬁelds in a record. No

You can specify an arbitrary delimiter.

Type: String

Default: ,

1315
Amazon Simple Storage Service API Reference
POST Object restore

Name Description Required

FileHeaderInfo Describes the ﬁrst line in the input data. It is one of the ENUM No
values.

• NONE: First line is not a header.

Type: Enum

Valid values: NONE | USE | IGNORE

Ancestors: CSV

Comments A single character used to indicate that a row should be ignored No

when the character is present at the start of that row. You can
specify any character to indicate a comment line.

Type: String

Ancestors: CSV

The CSV container element (in the OutputSerialization elements) contains the following
elements.

Name Description Required

QuoteFields Indicates whether to use quotation marks around output ﬁelds. No

• ALWAYS: Always use quotation marks for output ﬁelds.

Type: String

Ancestors: S3

CannedACL The canned access control list (ACL) to apply to the select No
restore results.

Type: String

Valid values: private | public-read | public-read-

write | aws-exec-read | authenticated-read |
bucket-owner-read | bucket-owner-full-control

API Version 2006-03-01

1317
Amazon Simple Storage Service API Reference
POST Object restore

Name Description Required

Ancestors: S3

Encryption Contains encryption information for the stored results. No

Type: Container for Encryption

Ancestors: S3

Prefix The preﬁx that is prepended to the select restore results. The Yes
maximum length for the preﬁx is 512 bytes.

Type: String

Ancestors: S3

StorageClass The class of storage used to store the select request results. No

Type: String

Valid values: STANDARD | REDUCED_REDUNDANCY |

STANDARD_IA | ONEZONE_IA

Ancestors: S3

Tagging Container for tag information. No

Type: Tag structure

Ancestors: S3

UserMetadata Contains a list of metadata to store with the select restore No

results.

Type: MetadataEntry structure

Ancestors: S3

The Grantee container element (in the AccessControlList element) contains the following
elements.

Name Description Required

DisplayName The screen name of the grantee. No

Type: String

Ancestors: Grantee

EmailAddress The email address of the grantee. No

Type: String

Ancestors: Grantee

ID The canonical user ID of the grantee. No

Type: String

API Version 2006-03-01

1318
Amazon Simple Storage Service API Reference
POST Object restore

Name Description Required

Ancestors: Grantee

Type The type of the grantee. No

Type: String

Ancestors: Grantee

Ancestors: Encryption

KMSContext Optional. If the encryption type is aws:kms, you can use this No
value to specify the encryption context for the select restore
results.

Type: String

Ancestors: Encryption

KMSKeyId The AWS Key Management Service (AWS KMS) key ID to use for No
object encryption.

Type: String

Ancestors: Encryption

The TagSet container element (in the Tagging element) contains the following element.

Name Description Required

Tag Contains tags. No

Type: Container

Ancestors: TagSet

API Version 2006-03-01

1319
Amazon Simple Storage Service API Reference
POST Object restore

The Tag container element (in the TagSet element) contains the following elements.

Name Description Required

Key Name of the tag. No

Type: String

Ancestors: Tag

Value Value of the tag. No

Type: String

Ancestors: Tag

The MetadataEntry container element (in the UserMetadata element) contains the
following key-value pair elements to store with an object.

Name Description Required

MetadataKey The metadata key. No

Type: String

Ancestors:

MetadataEntry The metadata value. No

Type: String

Ancestors:

Responses

A successful operation returns either the 200 OK or 202 Accepted status code.

• If the object copy is not previously restored, then Amazon S3 returns 202 Accepted in the response.
• If the object copy is previously restored, Amazon S3 returns 200 OK in the response.

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 782).

API Version 2006-03-01

1320
Amazon Simple Storage Service API Reference
POST Object restore

Response Elements

This operation does not return response elements.

Special Errors

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

RestoreAlreadyInProgress Object restore is already in progress. 409 Conﬂict Client

(This error does not apply to SELECT
type requests.)

Glacier expedited retrievals

Examples

Restore an Object for Two Days Using the Expedited Retrieval Option

The following restore request restores a copy of the photo1.jpg object from S3 Glacier for a period of
two days using the expedited retrieval option.

POST /photo1.jpg?restore HTTP/1.1

Host: examplebucket.s3.amazonaws.com

API Version 2006-03-01

1321
Amazon Simple Storage Service API Reference
POST Object restore

Date: Mon, 22 Oct 2012 01:49:52 GMT

Authorization: authorization string
Content-Length: content length

<RestoreRequest>
<Days>2</Days>
<GlacierJobParameters>
<Tier>Expedited</Tier>
</GlacierJobParameters>
</RestoreRequest>

If the examplebucket does not have a restored copy of the object, Amazon S3 returns the following
202 Accepted response.

HTTP/1.1 202 Accepted

x-amz-id-2: GFihv3y6+kE7KG11GEkQhU7/2/cHR3Yb2fCb2S04nxI423Dqwg2XiQ0B/UZlzYQvPiBlZNRcovw=
x-amz-request-id: 9F341CD3C4BA79E0
Date: Sat, 20 Oct 2012 23:54:05 GMT
Content-Length: 0
Server: AmazonS3

If a copy of the object is already restored, Amazon S3 returns a 200 OK response, and updates only the
restored copy's expiry time.

Query an Archive with a SELECT Request

The following is an example select restore request.

POST /object-one.csv?restore HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Date: Sat, 20 Oct 2012 23:54:05 GMT
Authorization: authorization string
Content-Length: content length

API Version 2006-03-01

1322
Amazon Simple Storage Service API Reference
POST Object restore

<FieldDelimiter>\t</FieldDelimiter>
<QuoteCharacter>\'</QuoteCharacter>
</CSV>
</OutputSerialization>
</SelectParameters>
<OutputLocation>
<S3>
<BucketName>example-output-bucket</BucketName>
<Prefix>test-s3</Prefix>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="AmazonCustomerByEmail">
<EmailAddress>[email protected]</EmailAddress>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
<UserMetadata>
<MetadataEntry>
<Name>test</Name>
<Value>test-value</Value>
</MetadataEntry>
<MetadataEntry>
<Name>other</Name>
<Value>something else</Value>
</MetadataEntry>
</UserMetadata>
<StorageClass>STANDARD</StorageClass>
</S3>
</OutputLocation>
</RestoreRequest>

Amazon S3 returns the following 202 Accepted response.

HTTP/1.1 202 Accepted

More Info

• GET Bucket lifecycle (p. 983)

• PUT Bucket lifecycle (p. 1145)
• SQL Reference for Amazon S3 Select and S3 Glacier Select in the Amazon Simple Storage Service
Developer Guide

API Version 2006-03-01

1323
Amazon Simple Storage Service API Reference
PUT Object

PUT Object
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

This implementation of the PUT operation adds an object to a bucket. You must have WRITE permissions
on a bucket to add an object to it.

Amazon S3 never adds partial objects; if you receive a success response, Amazon S3 added the entire
object to the bucket.

To ensure that data is not corrupted traversing the network, use the Content-MD5 header. When you
use this header, Amazon S3 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 Amazon S3 and
compare the returned ETag to the calculated MD5 value.
Note
To conﬁgure your application to send the request headers before sending the request body,
use the 100-continue HTTP status code. For PUT operations, this helps you avoid sending
the message body if the message is rejected based on the headers (for example, because
authentication fails or a redirect occurs). For more information on the 100-continue HTTP
status code, go to Section 8.2.3 of http://www.ietf.org/rfc/rfc2616.txt.

Versioning
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

If you enable versioning for a bucket, Amazon S3 automatically generates a unique version ID for
the object being stored. Amazon S3 returns this ID in the response using the x-amz-version-id
response header. If versioning is suspended, Amazon S3 always uses null as the version ID for the
object stored. For more information about returning the versioning state of a bucket, see GET Bucket
versioning (p. 1057).

If you enable versioning for a bucket, when Amazon S3 receives multiple write requests for the same
object simultaneously, it stores all of the objects.

API Version 2006-03-01

1324
Amazon Simple Storage Service API Reference
PUT Object

To see sample requests that use versioning, see Sample Request (p. 1337).

Storage Class Options

Access Permissions

When uploading an object, you can optionally specify the accounts or groups that should be granted
speciﬁc permissions on your object. There are two ways to grant the appropriate permissions using the
request headers:

• Specify a canned (predeﬁned) ACL using the x-amz-acl request header. For more information, see
Canned ACL in the Amazon Simple Storage Service Developer Guide.
• Specify access permissions explicitly using the x-amz-grant-read, x-amz-grant-read-acp, and
x-amz-grant-write-acp, x-amz-grant-full-control headers. These headers map to the set
of permissions Amazon S3 supports in an ACL. For more information, go to Access Control List (ACL)
Overview in the Amazon Simple Storage Service Developer Guide.

Note
You can either use a canned ACL or specify access permissions explicitly. You cannot do both.

To change an object's ACLs from the default, the requester must have s3:PutObjectAcl included
in the list of permitted actions in their AWS Identity and Access Management (IAM) policy. For more
information about permissions, see Permissions for Object Operations and Managing Access Permissions
to Your Amazon S3 Resources in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

API Version 2006-03-01

1325
Amazon Simple Storage Service API Reference
PUT Object

PUT /ObjectName HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Note
The syntax shows some of the request headers. For a complete list, see the Request Headers
section.

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Name Description Required

Cache-Control Can be used to specify caching behavior along the request/ No

reply chain. For more information, go to http://www.w3.org/
Protocols/rfc2616/rfc2616-sec14.html#sec14.9.

Type: String

Default: None

Constraints: None

Content- Speciﬁes presentational information for the object. For more No

Disposition information, go to http://www.w3.org/Protocols/rfc2616/
rfc2616-sec19.html#sec19.5.1.

Type: String

Default: None

Constraints: None

Content-Encoding Speciﬁes what content encodings have been applied to the No

object and thus what decoding mechanisms must be applied
to obtain the media-type referenced by the Content-Type

API Version 2006-03-01

1326
Amazon Simple Storage Service API Reference
PUT Object

Name Description Required

header ﬁeld. For more information, go to http://www.w3.org/
Protocols/rfc2616/rfc2616-sec14.html#sec14.11.

Type: String

Default: None

Constraints: None

Content-Length The size of the object, in bytes. For more information, Yes
go to http://www.w3.org/Protocols/rfc2616/rfc2616-
sec14.html#sec14.13.

Type: String

Default: None

Constraints: None

Content-MD5 The base64-encoded 128-bit MD5 digest of the message Required

(without the headers) according to RFC 1864. This header can be if Object
used as a message integrity check to verify that the data is the Lock
same data that was originally sent. Although it is optional, we parameters
recommend using the Content-MD5 mechanism as an end-to- are
end integrity check. For more information about REST request speciﬁed
authentication, see REST Authentication in the Amazon Simple
Storage Service Developer Guide.

Type: String

Default: None

Constraints: None

Content-Type A standard MIME type describing the format of the contents. For No
more information, go to http://www.w3.org/Protocols/rfc2616/
rfc2616-sec14.html#sec14.17.

Type: String

Default: binary/octet-stream

Valid Values: MIME types

Constraints: None

Expect When your application uses 100-continue, it does not send No

the request body until it receives an acknowledgment. If the
message is rejected based on the headers, the body of the
message is not sent.

Type: String

Default: None

Valid Values: 100-continue

Type: Enum

Default: STANDARD

Valid values: STANDARD | REDUCED_REDUNDANCY | GLACIER

| STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING |
DEEP_ARCHIVE

x-amz-tagging Speciﬁes a set of one or more tags to associate with the object. No
These tags are stored in the tagging subresource that is
associated with the object.

To specify tags on an object, the requester must have

s3:PutObjectTagging included in the list of permitted
actions in their IAM policy.

For more information about adding tags to an object, see Object

Tagging Management in the Amazon Simple Storage Service
Developer Guide.

Type: String

Default: None

Constraints: The encoding for tags is URL query parameter

encoding. The maximum size of this header is 2 KB.

API Version 2006-03-01

1328
Amazon Simple Storage Service API Reference
PUT Object

Name Description Required

x-amz-website- If the bucket is conﬁgured as a website, redirects requests No

redirect-location for this object to another object in the same bucket or to an
external URL. Amazon S3 stores the value of this header in the
object metadata. For information about object metadata, see
Object Key and Metadata.

In the following example, the request header sets the redirect to

an object (anotherPage.html) in the same bucket:

x-amz-website-redirect-location: /
anotherPage.html

In the following example, the request header sets the object

redirect to another website:

x-amz-website-redirect-location: http://
www.example.com/

For more information about website hosting in Amazon S3, see

Hosting Websites on Amazon S3 and How to Conﬁgure Website
Page Redirects in the Amazon Simple Storage Service Developer
Guide.

Type: String

Default: None

Constraints: The value must be preﬁxed by, "/", "http://" or

"https://". The length of the value is limited to 2 KB.

x-amz-object- The Object Lock mode, if any, that should be applied to this No
lock-mode object. For more information about S3 Object Lock, see Object
Lock in the Amazon Simple Storage Service Developer Guide.

Type: String

Default: None

Valid values: GOVERNANCE | COMPLIANCE

x-amz-object- The date and time when the Object Lock retention period will Required
lock-retain- expire. if x-amz-
until-date object-
Type: Timestamp lock-
mode is
Default: None speciﬁed
Format: 2020-01-05T00:00:00.000Z

x-amz-object- Speciﬁes whether a legal hold will be applied to this object. No

lock-legal-hold For more information about legal holds, see Object Lock in the
Amazon Simple Storage Service Developer Guide.

Type: String

Default: None

Valid values: ON | OFF

API Version 2006-03-01

1329
Amazon Simple Storage Service API Reference
PUT Object

Access-Control-List-(ACL)-Speciﬁc Request Headers

Default: None

Constraints: None

x-amz-grant- Grants permission to write the ACL for the applicable object. No
write-acp
Type: String

Default: None

Constraints: None

x-amz-grant- Grants READ, READ_ACP, and WRITE_ACP permissions on the No

full-control object.

Type: String

Default: None

Constraints: None

You specify each grantee as a type=value pair, where the type can be one of the following:

• emailAddress – if the speciﬁed value is the email address of an AWS account

Important
Using email addresses to specify a grantee is only supported in the following AWS Regions:
• US East (N. Virginia)
• US West (N. California)
• US West (Oregon)
• Asia Pacific (Singapore)
• Asia Pacific (Sydney)
• Asia Pacific (Tokyo)
• Europe (Ireland)
• South America (São Paulo)
For a list of all the Amazon S3 supported regions and endpoints, see Regions and Endpoints in
the AWS General Reference.
• id – if the specified value is the canonical user ID of an AWS account
• uri – if you are granting permission to a predefined group

For example, the following x-amz-grant-read header grants permission to read object data and its
metadata to the AWS accounts identiﬁed by their email addresses.

x-amz-grant-read: emailAddress="[email protected]", emailAddress="[email protected]"

API Version 2006-03-01

1331
Amazon Simple Storage Service API Reference
PUT Object

Server-Side-Encryption-Speciﬁc Request Headers

You can optionally request Amazon S3 to encrypt data at rest using server-side encryption. Server-side
encryption is for data encryption at rest. Amazon S3 encrypts your data as it writes it to disks in its data
centers and decrypts the date when you access it. The header you use depend on whether you want to
use AWS-managed encryption keys or provide your own encryption keys.

• Use AWS-managed encryption keys — If you want Amazon S3 to manage the keys used to encrypt
data, specify the following headers in the request.

Name Description Required

x-amz-server-side Speciﬁes the server-side encryption algorithm to use when Yes

-encryption Amazon S3 creates an object.

Type: String

Valid Value: aws:kms, AES256

x-amz-server- If the x-amz-server-side-encryption is present and has No. If the

side-encryption- the value of aws:kms, this header speciﬁes the ID of the AWS value of
aws-kms-key-id Key Management Service (AWS KMS) master encryption key x-amz-
that was used for the object. server-
side-
Type: String encryption
is
aws:kms,
this
header
speciﬁes
the ID
of the
AWS Key
Management
Service
(AWS
KMS)
master
encryption
key that
will be
used for
the object.
If you
specify
x-amz-
server-
side-
encryption:aws:kms,
but do not
provide

API Version 2006-03-01

1332
Amazon Simple Storage Service API Reference
PUT Object

Name Description Required

x-amz-
server-
side-
encryption-
aws-kms-
key-id,
Amazon
S3 uses
the
default
AWS KMS
key to
protect
the data.

x-amz-server- If the x-amz-server-side-encryption header is No

side-encryption- present, and if its value is aws:kms, this header speciﬁes the
context encryption context for the object. The value of this header
is a base64-encoded UTF-8 string holding JSON with the
encryption context key-value pairs.

Type: String

For more information on Server-Side Encryption with Amazon KMS-Managed Keys (SSE-KMS), see
Protecting Data Using Server-Side Encryption with AWS KMS-Managed Keys in the Amazon Simple
Storage Service Developer Guide.
• Use customer-provided encryption keys— If you want to manage your own encryption keys, provide all
the following headers in the request.
Note
If you use this feature, the ETag value that Amazon S3 returns in the response is not the MD5
of the object.

Name Description Required

x-amz-server- Speciﬁes the algorithm to use to when encrypting the object. Yes
side-encryption
-customer- Type: String
algorithm
Default: None

Valid Value: AES256

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-key and x-amz-server-
side-encryption-customer-key-MD5 headers.

API Version 2006-03-01

1333
Amazon Simple Storage Service API Reference
PUT Object

Name Description Required

x-amz-server- Speciﬁes the customer-provided base64-encoded encryption Yes

side-encryption- key that Amazon S3 should use to encrypt data. Amazon
customer-key S3 uses this value to store the object and then discards it.
Amazon does not store the encryption key. The key must be
appropriate for use with the algorithm speciﬁed in the x-amz-
server-side-encryption-customer-algorithm header.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key-MD5 headers.

x-amz-server- Speciﬁes the base64-encoded 128-bit MD5 digest of the Yes

side-encryption- encryption key according to RFC 1321. Amazon S3 uses this
customer-key-MD5 header for a message integrity check to ensure that the
encryption key was transmitted without error.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key headers.

For more information on Server-Side Encryption with Customer-Provided Encryption Keys (SSE-C), see
Protecting Data Using Server-Side Encryption with Customer-Provided Encryption Keys (SSE-C) in the
Amazon Simple Storage Service Developer Guide.

Responses

Response Headers

API Version 2006-03-01

1334
Amazon Simple Storage Service API Reference
PUT Object

Name Description

x-amz- If the expiration is conﬁgured for the object (see PUT Bucket lifecycle (p. 1145)),
expiration the response includes this header. It includes the expiry-date and rule-id
key-value pairs that provide information about object expiration. The value of the
rule-id is URL encoded.

Type: String

x-amz- If you speciﬁed server-side encryption either with an AWS KMS-managed or

server-side- Amazon S3-managed encryption key in your PUT request, the response includes
encryption this header. It conﬁrms the encryption algorithm that Amazon S3 used to encrypt
the object.

Type: String

x-amz- If the x-amz-server-side-encryption is present and has the value of

server-side- aws:kms, this header speciﬁes the ID of the AWS KMS master encryption key that
encryption- was used for the object.
aws-kms-key-
id Type: String

x-amz- If server-side encryption with customer-provided encryption keys encryption

server-side was requested, the response includes this header that conﬁrms the encryption
-encryption algorithm that was used.
-customer-
algorithm Type: String

Valid Values: AES256

x-amz- If server-side encryption using customer-provided encryption keys was requested,

server-side the response returns this header to verify the roundtrip message integrity of the
-encryption- customer-provided encryption key.
customer-key-
MD5 Type: String

x-amz- Version of the object.

version-id
Type: String

Response Elements

This implementation of the operation does not return response elements.

Special Errors

API Version 2006-03-01

1335
Amazon Simple Storage Service API Reference
PUT Object

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Example 1: Upload an Object

Sample Request

The following request stores the my-image.jpg image in the myBucket bucket.

PUT /my-image.jpg HTTP/1.1

Host: myBucket.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 11434
x-amz-meta-author: Janet
Expect: 100-continue
[11434 bytes of object data]

Sample Response with Versioning Suspended

HTTP/1.1 100 Continue

API Version 2006-03-01

1336
Amazon Simple Storage Service API Reference
PUT Object

If an expiration rule that was created on the bucket using lifecycle conﬁguration applies to the object,
you get a response with an x-amz-expiration header as shown in the following response. For more
information, see Transitioning Objects: General Considerations in the Amazon Simple Storage Service
Developer Guide.

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
Date: Wed, 12 Oct 2009 17:50:00 GMT
x-amz-expiration: expiry-date="Fri, 23 Dec 2012 00:00:00 GMT", rule-id="1"
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: close
Server: AmazonS3

Sample Response with Versioning Enabled

If the bucket has versioning enabled, the response includes the x-amz-version-id header.

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
x-amz-version-id: 43jfkodU8493jnFJD9fjj3HHNVfdsQUIFDNsidf038jfdsjGFDSIRp
Date: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "fbacf535f27731c9771645a39863328"
Content-Length: 0
Connection: close
Server: AmazonS3

Example 2: Upload an Object (Specify Storage Class)

Sample Request: Specifying the Reduced Redundancy Storage Class

API Version 2006-03-01

1337
Amazon Simple Storage Service API Reference
PUT Object

PUT /my-image.jpg HTTP/1.1

Host: myBucket.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: image/jpeg
Content-Length: 11434
Expect: 100-continue
x-amz-storage-class: REDUCED_REDUNDANCY

Sample Response

HTTP/1.1 100 Continue

Example 3:Upload an Object (Specify Access Permission Explicitly)

Sample Request: Uploading an Object and Specifying Access Permissions Explicitly

The following request stores the TestObject.txt file in the myBucket bucket. The request specifies
various ACL headers to grant permission to AWS accounts that are specified with a canonical user ID and
an email address.

PUT TestObject.txt HTTP/1.1

Host: myBucket.s3.amazonaws.com
x-amz-date: Fri, 13 Apr 2012 05:40:14 GMT
Authorization: authorization string
x-amz-grant-write-acp: id=8a6925ce4adf588a4532142d3f74dd8c71fa124ExampleCanonicalUserID
x-amz-grant-full-control: emailAddress="[email protected]"
x-amz-grant-write: emailAddress="[email protected]",
emailAddress="[email protected]"
Content-Length: 300
Expect: 100-continue

API Version 2006-03-01

1338
Amazon Simple Storage Service API Reference
PUT Object

Connection: Keep-Alive

...Object data in the body...

The version ID of the object version that you want to put a retention period on.

Request Body
For more information about the request elements that this operation uses, see
ObjectLockLegalHold (p. 1459).

Example Request Body:

Response Syntax
HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

Related Resources
Locking Objects in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

1342
Amazon Simple Storage Service API Reference
PUT Object retention

PUT Object retention

Service: Amazon Simple Storage Service

Places an Object Retention conﬁguration on an object.

Request Syntax
PUT /<object-key>?retention&versionId=<version-id> HTTP/1.1
Host: <bucket-name>.s3.amazonaws.com
Date: <Thu, 15 Nov 2016 00:17:21 GMT>
Authorization: <authorization-string> (see Authenticating Requests (AWS Signature Version
4))

URI Request Parameters

versionId

The version ID of the object version that you want to put a retention period on.

Request Body
For more information about the request elements that this operation uses, see
ObjectLockRetention (p. 1460).

Example Request Body:

<Retention>
<Mode>GOVERNANCE</Mode>
<RetainUntilDate>2020-01-05T00:00:00.000Z</RetainUntilDate>
</Retention>

Response Syntax
HTTP/1.1 200

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

Related Resources
Locking Objects in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

1343
Amazon Simple Storage Service API Reference
PUT Object - Copy

PUT Object - Copy

Description

This implementation of the PUT operation creates a copy of an object that is already stored in Amazon
S3. When a PUT copy operation is set on a destination bucket it's the same action as performing a GET
and then a PUT. Adding the request header, x-amz-copy-source, makes the PUT operation copy the
source object into the destination bucket.
Note
You can store individual objects of up to 5 TB in Amazon S3. You create a copy of your object
up to 5 GB in size in a single atomic operation using this API. However, for copying an object
greater than 5 GB, you must use the multipart upload Upload Part - Copy (p. 1447) API. For
conceptual information, see Copy Object Using the REST Multipart Upload API in the Amazon
Simple Storage Service Developer Guide.

When copying an object, you can preserve most of the metadata (default) or specify new metadata.
However, the ACL is not preserved and is set to private for the user making the request.
Important
Amazon S3 Transfer Acceleration does not support cross-region copies. If you request a cross-
region copy using a Transfer Acceleration endpoint, you get a 400 Bad Request error. For
more information about transfer acceleration, see Transfer Acceleration in the Amazon Simple
Storage Service Developer Guide.

All copy requests must be authenticated and cannot contain a message body. Additionally, you
must have READ access to the source object and WRITE access to the destination bucket. For more
information, see REST Authentication. Both the Region that you want to copy the object from and the
Region that you want to copy the object to must be enabled for your account.

To copy an object only under certain conditions, such as whether the ETag matches or whether the
object was modified before or after a specified date, use the request headers x-amz-copy-source-if-
match, x-amz-copy-source-if-none-match, x-amz-copy-source-if-unmodified-since, or
x-amz-copy-source-if-modified-since.
Note
All headers with the x-amz- prefix, including x-amz-copy-source, must be signed.

You can use this operation to change the storage class of an object that is already stored in Amazon S3
using the x-amz-storage-class request header. For more information, see Storage Classes in the
Amazon Simple Storage Service Developer Guide.

The source object that you are copying can be encrypted or unencrypted. If the source object is
encrypted, it can be encrypted by server-side encryption using AWS-managed encryption keys or by
using a customer-provided encryption key. When copying an object, you can request that Amazon S3
encrypt the target object by using either the AWS-managed encryption keys or by using your own

API Version 2006-03-01

1344
Amazon Simple Storage Service API Reference
PUT Object - Copy

encryption key. You can do this regardless of the form of server-side encryption that was used to encrypt
the source, or even if the source object was not encrypted. For more information about server-side
encryption, see Using Server-Side Encryption in the Amazon Simple Storage Service Developer Guide.

A copy request might return an error when Amazon S3 receives the copy request or while Amazon S3 is
copying the ﬁles. If the error occurs before the copy operation starts, you receive a standard Amazon
S3 error. If the error occurs during the copy operation, the error response is embedded in the 200 OK
response. This means that a 200 OK response can contain either a success or an error. Design your
application to parse the contents of the response and handle it appropriately.

The copy request charge is based on the storage class and Region you specify for the destination object.
For pricing information, see Amazon S3 Pricing.

Versioning

If you enable versioning on the target bucket, Amazon S3 generates a unique version ID for the object
being copied. This version ID is diﬀerent from the version ID of the source object. Amazon S3 returns the
version ID of the copied object in the x-amz-version-id response header in the response.

If you do not enable versioning or suspend it on the target bucket, the version ID that Amazon S3
generates is always null.

If the source object's storage class is GLACIER, then you must restore a copy of this object before you can
use it as a source object for the copy operation. For more information, see POST Object restore (p. 1308).

To see sample requests that use versioning, see Sample Request: Copying a speciﬁed version of an
object (p. 1359).

Access Permissions

• Specify a canned ACL with the x-amz-acl request header. For more information, see Canned ACL in
the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

1345
Amazon Simple Storage Service API Reference
PUT Object - Copy

• Specify access permissions explicitly with the x-amz-grant-read, x-amz-grant-read-acp, x-

amz-grant-write-acp, and x-amz-grant-full-control headers. These headers map to the set
of permissions that Amazon S3 supports in an ACL. For more information, go to Access Control List
(ACL) Overview in the Amazon Simple Storage Service Developer Guide.

Note
You can use either a canned ACL or specify access permissions explicitly. You cannot do both.

Requests

Syntax

PUT /destinationObject HTTP/1.1

Host: destinationBucket.s3.amazonaws.com
x-amz-copy-source: /source_bucket/sourceObject
x-amz-metadata-directive: metadata_directive
x-amz-copy-source-if-match: etag
x-amz-copy-source-if-none-match: etag
x-amz-copy-source-if-unmodified-since: time_stamp
x-amz-copy-source-if-modified-since: time_stamp
<request metadata>
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))
Date: date

Note
The syntax shows only some of the request headers. For a complete list, see the Request
Headers section.

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

API Version 2006-03-01

1346
Amazon Simple Storage Service API Reference
PUT Object - Copy

Name Description Required

x-amz-copy-source The name of the source bucket and key name of Yes
the source object, separated by a slash (/).

Type: String

Default: None

Constraints:

This string must be URL-encoded. Additionally,

the source bucket must be valid and you must
have READ access to the valid source object.

If the source object is archived in the GLACIER

or DEEP_ARCHIVE storage class, you must ﬁrst
restore a temporary copy using the POST Object
restore (p. 1308). Otherwise, Amazon S3 returns
the 403 ObjectNotInActiveTierError
error response.

You can also specify the version-id of

the source object in the x-amz-copy-source
request header. This parameter is optional.
For example: x-amz-copy-source: /
bucket/my-image.jpg?versionId=3/
L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo

x-amz-metadata-directive Speciﬁes whether the metadata is copied from No

the source object or is replaced with metadata
provided in the request.

• If the metadata is copied, all of the metadata

except for the version ID remains unchanged.
In addition, the server-side-encryption,
storage-class and website-redirect-
location metadata from the source is not
copied. If you specify this metadata explicitly
in the copy request, Amazon S3 adds this
metadata to the resulting object. If you specify
headers in the request that speciﬁes user-
deﬁned metadata, Amazon S3 ignores these
headers.
• If the metadata is replaced, all of the original
metadata is replaced by the metadata that you
specify.

Type: String

Default: COPY

API Version 2006-03-01

1347
Amazon Simple Storage Service API Reference
PUT Object - Copy

Name Description Required

Valid values: COPY | REPLACE

Constraints: Values other than COPY or REPLACE

result in an immediate 400-based error
response. You can't copy an object to itself
unless you specify the MetadataDirective
header and set its value to REPLACE.

For information on supported metadata, see

Common Request Headers (p. 779)

x-amz-copy-source-if-match Copies the object if its entity tag (ETag) matches No

the speciﬁed tag. Otherwise, the request
returns a 412 HTTP status code error (failed
precondition).

For more information, see Consideration 1 after

this table.

Type: String

Default: None

Constraints: This header can be used with x-

amz-copy-source-if-unmodified-since,
but it cannot be used with other conditional
copy headers.

x-amz-copy-source-if-none- Copies the object if its entity tag (ETag) is No

match diﬀerent than the speciﬁed ETag. Otherwise,
the request returns a 412 HTTP status code error
(failed precondition).

For more information, see Consideration 1 after

this table.

Type: String

Default: None

Constraints: This header can be used with x-

amz-copy-source-if-modified-since, but
it cannot be used with other conditional copy
headers.

API Version 2006-03-01

1348
Amazon Simple Storage Service API Reference
PUT Object - Copy

Name Description Required

x-amz-copy-source-if- Copies the object if it hasn't been modiﬁed No

unmodified-since since the speciﬁed time. Otherwise, the request
returns a 412 HTTP status code error (failed
precondition).

For more information, see Consideration 1 after

this table.

Type: String

Default: None

Constraints: This must be a valid HTTP date.

This header can be used with x-amz-copy-
source-if-match, but cannot be used with
other conditional copy headers.

x-amz-copy-source-if-modified- Copies the object if it has been modiﬁed since No

since the speciﬁed time; otherwise, the request
returns a 412 HTTP status code error (failed
condition).

For more information, see Consideration 2 after

this table.

Type: String

Default: None

Constraints: This must be a valid HTTP date. This

header can be used with x-amz-copy-source-
if-none-match, but cannot be used with other
conditional copy headers.

x-amz-storage-class If you don't specify this header, Amazon S3 uses No

STANDARD, the default, for the storage class.
Amazon S3 supports other storage classes. For
more information, see Storage Classes in the
Amazon Simple Storage Service Developer Guide.

Type: Enum

Default: STANDARD

Valid values: STANDARD |

API Version 2006-03-01

1349
Amazon Simple Storage Service API Reference
PUT Object - Copy

Name Description Required

x-amz-tagging-directive Speciﬁes whether the object tags are copied No

from the source object or replaced with tags
provided in the request.

• If the tags are copied, the tagset remains

unchanged.
• If the tags are replaced, all of the original
tagset is replaced by the tags you specify.

If you don't specify a tagging directive, Amazon

S3 copies tags by default.

If the tagging directive is REPLACE, you specify

any tags in url format in the x-amz-tagging
header, similar to using a PUT object with tags.

If the tagging directive is REPLACE, but you don't

specify the x-amz-tagging in the request, the
destination object won't have tags.

Type: String

Default: COPY

Valid values: COPY | REPLACE

Constraints: Values other than COPY or REPLACE

result in an immediate 400-based error
response.

API Version 2006-03-01

1350
Amazon Simple Storage Service API Reference
PUT Object - Copy

Name Description Required

x-amz-website-redirect- If the bucket is conﬁgured as a website, redirects No

location requests for this object to another object
in the same bucket or to an external URL.
Amazon S3 stores the value of this header in the
object metadata. For information about object
metadata, see Object Key and Metadata.

In the following example, the request header

sets the redirect to an object (anotherPage.html)
in the same bucket:

x-amz-website-redirect-location: /
anotherPage.html

In the following example, the request header

sets the object redirect to another website:

x-amz-website-redirect-location:
http://www.example.com/

For more information about website hosting in

Amazon S3, see Hosting Websites on Amazon S3
and How to Conﬁgure Website Page Redirects
in the Amazon Simple Storage Service Developer
Guide.

Type: String

Default: None

Constraints: The value must be preﬁxed by, "/",

"http://" or "https://". The length of the value is
limited to 2 K.

Consider the following when using request headers:

• Consideration 1 – If both the x-amz-copy-source-if-match and x-amz-copy-source-if-

unmodified-since headers are present in the request and evaluate as follows, Amazon S3 returns
200 OK and copies the data:

x-amz-copy-source-if-match condition evaluates to true

x-amz-copy-source-if-unmodified-since condition evaluates to false

• Consideration 2 – 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 and evaluate as follows, Amazon S3 returns
the 412 Precondition Failed response code:

x-amz-copy-source-if-none-match condition evaluates to false

x-amz-copy-source-if-modified-since condition evaluates to true

API Version 2006-03-01

1351
Amazon Simple Storage Service API Reference
PUT Object - Copy

Server-Side Encryption Speciﬁc Request Headers

To encrypt the target object, you must provide the appropriate encryption-related request headers. The
one you use depends on whether you want to use AWS-managed encryption keys or provide your own
encryption key:

• To encrypt the target object using server-side encryption with an AWS-managed encryption key,
provide the following request headers, as appropriate.

Name Description Required

x-amz-server-side Speciﬁes a server-side encryption algorithm to use when Yes

-encryption Amazon S3 creates an object.

Type: String

Valid Value: aws:kms, AES256

x-amz-server- If the x-amz-server-side-encryption header is present Yes, if the

side-encryption- and has the value of aws:kms, this header speciﬁes the ID value of
aws-kms-key-id of the AWS Key Management Service (AWS KMS) master x-amz-
encryption key that was used for the object. server-
side-
Type: String encryption
is
aws:kms

x-amz-server- If x-amz-server-side-encryption is present and its value No

side-encryption- is aws:kms, this header speciﬁes the encryption context for
context the object. The value of this header is a base64-encoded UTF-8
string holding JSON with the encryption context key-value
pairs.

Type: String

Note
If you specify x-amz-server-side-encryption:aws:kms, but don't provide x-amz-
server-side-encryption-aws-kms-key-id, Amazon S3 uses the default AWS KMS key
to protect the data.
Important
All GET and PUT requests for an object protected by AWS KMS fail if you don't make them
with SSL or by using SigV4.

For more information on Server-Side Encryption with Amazon KMS-Managed Keys (SSE-KMS), see
Protecting Data Using Server-Side Encryption with AWS KMS-Managed Keys in the Amazon Simple
Storage Service Developer Guide.
• To encrypt the target object using server-side encryption with an encryption key that you provide, use
the following headers.

API Version 2006-03-01

1352
Amazon Simple Storage Service API Reference
PUT Object - Copy

Name Description Required

x-amz-server- Speciﬁes the algorithm to use to when encrypting the object. Yes
side-encryption
-customer- Type: String
algorithm
Default: None

Valid Value: AES256

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-key and x-amz-server-
side-encryption-customer-key-MD5 headers.

x-amz-server- Speciﬁes the customer-provided base64-encoded encryption Yes

side-encryption- key for Amazon S3 to use to encrypt data. Amazon S3 uses this
customer-key value to store the object and then discards it. Amazon does
not store the encryption key. The key must be appropriate for
use with the algorithm speciﬁed in the x-amz-server-side-
encryption-customer-algorithm header.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key-MD5 headers.

x-amz-server- Speciﬁes the base64-encoded 128-bit MD5 digest of the Yes

side-encryption- encryption key according to RFC 1321. Amazon S3 uses
customer-key-MD5 this header as a message integrity check to ensure that the
encryption key was transmitted without error.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key headers.

• If the source object is encrypted using server-side encryption with customer-provided encryption keys,
you must use the following headers.

Name Description Required

x-amz-copy- Speciﬁes the algorithm to use when decrypting the source Yes
source-server- object.
side-encryption
-customer- Type: String
algorithm
Default: None

Valid Value: AES256

Constraints: Must be accompanied by valid x-amz-copy-

source-server-side-encryption-customer-key

API Version 2006-03-01

1353
Amazon Simple Storage Service API Reference
PUT Object - Copy

Name Description Required

and x-amz-copy-source-server-side-encryption-
customer-key-MD5 headers.

x-amz-copy-source Speciﬁes the customer-provided base64-encoded encryption Yes

-server-side key for Amazon S3 to use to decrypt the source object.
-encryption- After the copy operation, Amazon S3 discards this key. The
customer-key encryption key provided in this header must be one that was
used when the source object was created.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-copy-

source-server-side-encryption-customer-
algorithm and x-amz-copy-source-server-side-
encryption-customer-key-MD5 headers.

x-amz-copy- Speciﬁes the base64-encoded 128-bit MD5 digest of the Yes

source-server- encryption key according to RFC 1321. Amazon S3 uses this
side-encryption- header for a message integrity check to ensure that the
customer-key-MD5 encryption key was transmitted without error.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-copy-

source-server-side-encryption-customer-
algorithm and x-amz-copy-source-server-side-
encryption-customer-key headers.

Access-Control-List (ACL) Speciﬁc Request Headers

• Specify a canned ACL — Amazon S3 supports a set of predeﬁned ACLs, known as canned ACLs. Each
canned ACL has a predeﬁned set of grantees and permissions. For more information, see Canned ACL.

API Version 2006-03-01

1354
Amazon Simple Storage Service API Reference
PUT Object - Copy

Name Description Required

x-amz-acl The canned ACL to apply to the object. No

Type: String

Default: private

Valid Values: private | public-read | public-read-

write | aws-exec-read | authenticated-read |
bucket-owner-read | bucket-owner-full-control

Constraints: None

• Specify access permissions explicitly — To explicitly grant access permissions to specific AWS
accounts or groups, use the following headers. Each header maps to specific permissions that Amazon
S3 supports in an ACL. For more information, see Access Control List (ACL) Overview. In the header,
you specify a list of grantees who get the specific permission.

Name Description Required

x-amz-grant- Gives the grantee permissions to read the object data and its No
read metadata.

Type: String

Default: None

Constraints: None

x-amz-grant- Not applicable. This header applies only when granting access No
write permissions on a bucket.

Type: String

Default: None

Constraints: None

x-amz-grant- Gives the grantee permissions to read the object ACL. No

read-acp
Type: String

Default: None

Constraints: None

x-amz-grant- Gives the grantee permissions to write the ACL for the applicable No
write-acp object.

Type: String

Default: None

Constraints: None

API Version 2006-03-01

1355
Amazon Simple Storage Service API Reference
PUT Object - Copy

Name Description Required

x-amz-grant- Gives the grantee READ, READ_ACP, and WRITE_ACP permissions No

full-control on the object.

encryption-aws-kms-key-id and has the value of aws:kms, this header speciﬁes the ID of
the AWS KMS master encryption key that was used for the
object.

Type: String

x-amz-server-side- If server-side encryption with customer-provided encryption

encryption-customer- keys (SSE-C) encryption was requested, the response includes
algorithm this header, which conﬁrms the encryption algorithm used for
the destination object.

Type: String

Valid values: AES256

x-amz-server-side- If SSE-C encryption was requested, the response includes this

encryption-customer-key-MD5 header to verify the integrity of the roundtrip message of the
customer-provided encryption key that was used to encrypt the
destination object.

Type: String

x-amz-storage-class Provides information about the object's storage class. Amazon

S3 returns this header for all objects except Standard storage
class objects.

For more information, see Storage Classes in Amazon Simple

Storage Service Developer Guide.

Type: String

Default: None

x-amz-version-id Version of the copied object in the destination bucket.

API Version 2006-03-01

1357
Amazon Simple Storage Service API Reference
PUT Object - Copy

Name Description
Type: String

Response Elements

Name Description

CopyObjectResult Container for all response elements.

Type: Container

Ancestor: None

ETag Returns the ETag of the new object. The ETag reﬂects only changes
to the contents of an object, not its metadata.

Type: String

Ancestor: CopyObjectResult

LastModified Returns the date that the object was last modiﬁed.

Type: String

Ancestor: CopyObjectResult

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

API Version 2006-03-01

1358
Amazon Simple Storage Service API Reference
PUT Object - Copy

Sample Request

This example copies my-image.jpg into the bucket bucket, with the key name my-second-
image.jpg.

PUT /my-second-image.jpg HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-amz-copy-source: /bucket/my-image.jpg
Authorization: authorization string

Sample Response

x-amz-version-id returns the version ID of the object in the destination bucket. x-amz-copy-
source-version-id returns the version ID of the source object.

Sample Request: Copying a Speciﬁed Version of an Object

The following request copies the my-image.jpg key with the speciﬁed version ID, copies it into the
bucket bucket, and gives it the my-second-image.jpg key.

PUT /my-second-image.jpg HTTP/1.1

Host: bucket.s3.amazonaws.com

API Version 2006-03-01

1359
Amazon Simple Storage Service API Reference
PUT Object - Copy

Date: Wed, 28 Oct 2009 22:32:00 GMT

x-amz-copy-source: /bucket/my-image.jpg?versionId=3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
Authorization: authorization string

Success Response: Copying a Versioned Object into a version-enabled Bucket

The following response shows that an object was copied into a target bucket where versioning is
enabled.

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
x-amz-version-id: QUpfdndhfd8438MNFDN93jdnJFkdmqnh893
x-amz-copy-source-version-id: 09df8234529fjs0dfi0w52935029wefdj
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

Success Response: Copying a Versioned Object into a version-suspended Bucket

The following response shows that an object was copied into a target bucket where versioning is
suspended. The parameter <VersionId> does not appear.

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51TnqcoF8eFidJG9Z/2mkiDFu8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
x-amz-copy-source-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

1360
Amazon Simple Storage Service API Reference
PUT Object - Copy

Sample: Copy from Unencrypted Object to an Object Encrypted with Server-side

Encryption with Customer-provided Encryption Keys

The following example speciﬁes the HTTP PUT header to copy an unencrypted object to an object
encrypted with server-side encryption with customer-provided encryption keys (SSE-C).

PUT /exampleDestinationObject HTTP/1.1

Host: example-destination-bucket.s3.amazonaws.com
x-amz-server-side-encryption-customer-algorithm: AES256
x-amz-server-side-encryption-customer-key: Base64(YourKey)
x-amz-server-side-encryption-customer-key-MD5 : Base64(MD5(YourKey))
x-amz-metadata-directive: metadata_directive
x-amz-copy-source: /example_source_bucket/exampleSourceObject
x-amz-copy-source-if-match: etag
x-amz-copy-source-if-none-match: etag
x-amz-copy-source-if-unmodified-since: time_stamp
x-amz-copy-source-if-modified-since: time_stamp
<request metadata>
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))
Date: date

Sample: Copy from an Object Encrypted with SSE-C to an Object Encrypted with
SSE-C

PUT /exampleDestinationObject HTTP/1.1

Host: example-destination-bucket.s3.amazonaws.com
x-amz-server-side-encryption-customer-algorithm: AES256
x-amz-server-side-encryption-customer-key: Base64(NewKey)
x-amz-server-side-encryption-customer-key-MD5: Base64(MD5(NewKey))
x-amz-metadata-directive: metadata_directive
x-amz-copy-source: /source_bucket/sourceObject
x-amz-copy-source-if-match: etag
x-amz-copy-source-if-none-match: etag
x-amz-copy-source-if-unmodified-since: time_stamp
x-amz-copy-source-if-modified-since: time_stamp
x-amz-copy-source-server-side-encryption-customer-algorithm: AES256
x-amz-copy-source-server-side-encryption-customer-key: Base64(OldKey)
x-amz-copy-source-server-side-encryption-customer-key-MD5: Base64(MD5(OldKey))
<request metadata>
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))
Date: date

API Version 2006-03-01

1361
Amazon Simple Storage Service API Reference
PUT Object - Copy

Related Resources

• Copying Objects
• PUT Object (p. 1324)
• GET Object (p. 1248)

API Version 2006-03-01

1362
Amazon Simple Storage Service API Reference
PUT Object acl

PUT Object acl

Description

This implementation of the PUT operation uses the acl subresource to set the access control list (ACL)
permissions for an object that already exists in a bucket. You must have WRITE_ACP permission to set the
ACL of an object.

You can use one of the following two ways to set an object's permissions:

• Specify the ACL in the request body, or

• Specify permissions using request headers

Depending on your application needs, you may choose to set the ACL on an object using either the
request body or the headers. For example, if you have an existing application that updates an object ACL
using the request body, then you can continue to use that approach.

Versioning

The ACL of an object is set at the object version level. By default, PUT sets the ACL of the current version
of an object. To set the ACL of a diﬀerent version, use the versionId subresource.

To see sample requests that use versioning, see Sample Request: Setting the ACL of a speciﬁed object
version (p. 1370).

Requests

API Version 2006-03-01

1363
Amazon Simple Storage Service API Reference
PUT Object acl

Syntax

The following request shows the syntax for sending the ACL in the request body. If you want to use
headers to specify the permissions for the object, you cannot send the ACL in the request body. Instead,
see the Request Headers section for a list of headers you can use.

PUT /ObjectName?acl HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Note
The syntax shows some of the request headers. For a complete list see the Request Headers
section.

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

You can use the following request headers in addition to the Common Request Headers (p. 681).

API Version 2006-03-01

1364
Amazon Simple Storage Service API Reference
PUT Object acl

Access Control List (ACL) Speciﬁc Request Headers

These headers enable you to set access permissions using one of the following methods:

• Specify canned ACL, or

• Specify the permission for each grantee explicitly

Amazon S3 supports a set of predefined ACLs, known as canned ACLs. Each canned ACL has a predefined
a set of grantees and permissions. For more information, see Canned ACL. To grant access permissions by
specifying canned ACLs, you use the following header and specify the canned ACL name as its value. If
you use this header, you cannot use other access control-specific headers in your request.

Name Description Required

x-amz-acl Sets the ACL of the object using the speciﬁed canned ACL. For No
more information, go to Canned ACL in the Amazon Simple Storage
Service Developer Guide.

Constraints: None

x-amz-grant- Allows the speciﬁed grantee the READ, WRITE, READ_ACP, and No
full-control WRITE_ACP permissions on the bucket.

Type: String

Default: None

Constraints: None

For each of these headers, the value is a comma-separated list of one or more grantees. You specify each
grantee as a type=value pair, where the type can be one of the following:

• emailAddress — if value speciﬁed is the email address of an AWS account

• id — if value speciﬁed is the canonical user ID of an AWS account
• uri — if granting permission to a predeﬁned group.

For example, the following x-amz-grant-read header grants list objects permission to the two AWS
accounts identiﬁed by their email addresses.

x-amz-grant-read: emailAddress="[email protected]", emailAddress="[email protected]"

For more information, go to Access Control List (ACL) Overview.

Request Elements

If you decide to use the request body to specify an ACL, you must use the following elements.
Note
If you use the request body, you cannot use the request headers to set an ACL.

API Version 2006-03-01

1366
Amazon Simple Storage Service API Reference
PUT Object acl

Name Description Required

AccessControlList Container for ACL information No

Type: Container

Ancestors: AccessControlPolicy

AccessControlPolicy Contains the elements that set the ACL permissions for an No
object per grantee

Type: Container

Ancestors: None

DisplayName Screen name of the bucket owner No

Type: String

Ancestors: AccessControlPolicy.Owner

Grant Container for the grantee and his or her permissions No

Type: Container

Ancestors: AccessControlPolicy.AccessControlList

Grantee The subject whose permissions are being set. No

Type: String

Valid Values: DisplayName | EmailAddress |

AuthenticatedUser. For more information, see Grantee
Values (p. 1368).

Ancestors: AccessControlPolicy.AccessControlList.Grant

ID ID of the bucket owner, or the ID of the grantee No

Type: String

Ancestors: AccessControlPolicy.Owner or
AccessControlPolicy.AccessControlList.Grant

Owner Container for the bucket owner's display name and ID Yes

Type: Container

Ancestors: AccessControlPolicy

Permission Speciﬁes the permission given to the grantee No

Type: String

Valid Values: FULL_CONTROL | WRITE | WRITE_ACP | READ |

READ_ACP

Ancestors:
AccessControlPolicy.AccessControlList.Grant

API Version 2006-03-01

1367
Amazon Simple Storage Service API Reference
PUT Object acl

Grantee Values

You can specify the person (grantee) to whom you're assigning access rights (using request elements) in
the following ways:

• By the person's ID:

DisplayName is optional and ignored in the request.

• By Email address:

The grantee is resolved to the CanonicalUser and, in a response to a GET Object acl request,
appears as the CanonicalUser.
• By URI:

Responses

Response Headers

API Version 2006-03-01

1368
Amazon Simple Storage Service API Reference
PUT Object acl

Name Description

x-amz- Version of the object whose ACL is being set.

version-id
Type: String

Default: None

Response Elements

This operation does not return response elements.

Special Errors

This operation does not return special errors. For general information about Amazon S3 errors and a list
of error codes, see Error Responses (p. 685).

Examples

Sample Request

PUT /my-image.jpg?acl HTTP/1.1

Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string
Content-Length: 124

API Version 2006-03-01

1369
Amazon Simple Storage Service API Reference
PUT Object acl

<AccessControlPolicy>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
<AccessControlList>
<Grant>
<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser">
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeeExampleCanonicalUserID</ID>
<DisplayName>[email protected]</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>

Sample Response

The following shows a sample response when versioning on the bucket is enabled.

Sample Request: Setting the ACL of a speciﬁed object version

The following request sets the ACL on the speciﬁed version of the object.

PUT /my-image.jpg?acl&versionId=3HL4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nrjfkd
HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string
Content-Length: 124

<AccessControlPolicy>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Owner>
<AccessControlList>
<Grant>

API Version 2006-03-01

1370
Amazon Simple Storage Service API Reference
PUT Object acl

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:type="CanonicalUser">
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>[email protected]</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: eftixk72aD6Ap51u8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC148832E5
x-amz-version-id: 3/L4kqtJlcpXro3vjVBH40Nr8X8gdRQBpUMLUo
Date: Wed, 28 Oct 2009 22:32:00 GMT
Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
Content-Length: 0
Connection: close
Server: AmazonS3

Sample Request: Access permissions speciﬁed using headers

The following request uses ACL-speciﬁc request headers, x-amz-acl, and speciﬁes a canned ACL
(public_read) to grant object read access to everyone.

PUT ExampleObject.txt?acl HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-acl: public-read
Accept: */*
Authorization: authorization string
Host: s3.amazonaws.com
Connection: Keep-Alive

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: w5YegkbG6ZDsje4WK56RWPxNQHIQ0CjrjyRVFZhEJI9E3kbabXnBO9w5G7Dmxsgk
x-amz-request-id: C13B2827BD8455B1

API Version 2006-03-01

1371
Amazon Simple Storage Service API Reference
PUT Object acl

Date: Sun, 29 Apr 2012 23:24:12 GMT

Content-Length: 0
Server: AmazonS3

Related Resources

• PUT Object - Copy (p. 1344)

• POST Object (p. 1295)
• GET Object (p. 1248)

API Version 2006-03-01

1372
Amazon Simple Storage Service API Reference
PUT Object tagging

PUT Object tagging

Description

This implementation of the PUT operation uses the tagging subresource to add a set of tags to an
existing object.

For tagging-related restrictions related to characters and encodings, see Tag Restrictions in the AWS
Billing and Cost Management User Guide. Note that Amazon S3 limits the maximum number of tags to 10
tags per object.

To use this operation, you must have permission to perform the s3:PutObjectTagging action. By
default, the bucket owner has this permission and can grant this permission to others.

To put tags of any other version, use the versionId query parameter. You also need permission for
the s3:PutObjectVersionTagging action.

For information about the Amazon S3 object tagging feature, see Object Tagging in the Amazon Simple
Storage Service Developer Guide.

Requests

Syntax

The following request shows the syntax for sending tagging information in the request body.

PUT /ObjectName?tagging HTTP/1.1

Host: BucketName.s3.amazonaws.com

API Version 2006-03-01

1373
Amazon Simple Storage Service API Reference
PUT Object tagging

Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))
<Tagging>
<TagSet>
<Tag>
<Key>Tag Name</Key>
<Value>Tag Value</Value>
</Tag>
</TagSet>
</Tagging>

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Content-MD5 is a required header for this operation.

Request Elements

Name Description Required

Tagging Container for the TagSet and Tag elements. Yes

Type: String

Ancestors: None

TagSet Container for a set of tags Yes

Type: Container

Ancestors: Tagging

Tag Container for tag information. No

Type: Container

Ancestors: TagSet

API Version 2006-03-01

1374
Amazon Simple Storage Service API Reference
PUT Object tagging

Name Description Required

Key Name of the tag. Yes, if Tag is

speciﬁed.
Type: String

Ancestors: Tag

Value Value of the tag. Yes, if Tag is

speciﬁed.
Type: String

Ancestors: Tag

Responses

Response Headers

The operation returns response headers that are common to most responses. For more information, see
Common Response Headers (p. 683).

Response Elements

This operation does not return response elements.

Requests

Syntax

POST /ObjectName?select&select-type=2 HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (See Authenticating Requests (AWS Signature Version
4))

Request body goes here

Note
The syntax shows some of the request headers. For a complete list, see the "Request Headers"
section of this topic.
Query parameters select and select-type=2 are both required for all requests. select-
type=2 is present in order to enable extensions for future capabilities.

Request Parameters

This implementation of the operation does not use request parameters.

API Version 2006-03-01

1379
Amazon Simple Storage Service API Reference
SELECT Object Content

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Body

The following XML shows the request body for an object in CSV format with results in CSV format:

<?xml version="1.0" encoding="UTF-8"?>

<SelectRequest>
<Expression>Select * from S3Object</Expression>
<ExpressionType>SQL</ExpressionType>
<InputSerialization>
<CompressionType>GZIP</CompressionType>
<CSV>
<FileHeaderInfo>IGNORE</FileHeaderInfo>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
<Comments>#</Comments>
<AllowQuotedRecordDelimiter>FALSE</AllowQuotedRecordDelimiter>
</CSV>
</InputSerialization>
<OutputSerialization>
<CSV>
<QuoteFields>ASNEEDED</QuoteFields>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
</CSV>
</OutputSerialization>
<RequestProgress>
<Enabled>FALSE</Enabled>
</RequestProgress>
</SelectRequest>

The following XML shows the request body for an object in JSON format with results in JSON format:

<?xml version="1.0" encoding="UTF-8"?>

<SelectRequest>
<Expression>Select * from S3Object</Expression>
<ExpressionType>SQL</ExpressionType>
<InputSerialization>
<CompressionType>GZIP</CompressionType>
<JSON>
<Type>DOCUMENT</Type>

API Version 2006-03-01

1380
Amazon Simple Storage Service API Reference
SELECT Object Content

</JSON>
</InputSerialization>
<OutputSerialization>
<JSON>
<RecordDelimiter>\n</RecordDelimiter>
</JSON>
</OutputSerialization>
<RequestProgress>
<Enabled>FALSE</Enabled>
</RequestProgress>
</SelectRequest>

The following XML shows the request body for an object in Parquet format with results in CSV format:

<?xml version="1.0" encoding="UTF-8"?>

Note
In the XML:

• The InputSerialization element describes the format of the data in the object that is
being queried. It must specify CSV, JSON, or Parquet.
• The OutputSerialization element describes the format of the data that you want
Amazon S3 to return in response to the query. It must specify either CSV or JSON. Amazon S3
Select doesn't support outputting data in Parquet format.
• The format of the InputSerialization doesn't need to match the format
of the OutputSerialization. So, for example, you can specify JSON in the
InputSerialization and CSV in the OutputSerialization.

The following tables explain each of the XML elements in the request body.

Name Description Required

Expression The SQL expression. For example: Yes

• The following SQL expression retrieves the ﬁrst column of the

data from the object stored in CSV format.

SELECT s._1 FROM S3Object s

API Version 2006-03-01

1381
Amazon Simple Storage Service API Reference
SELECT Object Content

Name Description Required

• The following SQL expression returns everything from the
object.

SELECT * FROM S3Object

Type: String

is compressed. GZIP and BZIP2 are the only supported
compression types, and are supported only for CSV and JSON
objects. If InputSerialization speciﬁes the Parquet format,
then CompressionType must be NONE, even if the Parquet
object uses columnar compression.

Type: String

Valid values: NONE | GZIP | BZIP2

Default: NONE

Ancestor: InputSerialization

API Version 2006-03-01

1382
Amazon Simple Storage Service API Reference
SELECT Object Content

Name Description Required

CSV | JSON | Speciﬁes the format and certain properties of the Amazon S3 Exactly one
Parquet object that is being queried. of CSV, JSON,
or Parquet is
Type: Container required.

Ancestor: InputSerialization

CSV container element (inside InputSerialization)

Name Description Required

RecordDelimiterThe value used to separate individual records in the input. No

Instead of the default value, you can specify an arbitrary
delimiter, including an octal character. For example, \\036 is
parsed as the "record separator" (non-printing) character.

You can specify up to two characters for a record delimiter. You

can specify two characters, one character and one octal, or two
octals. For example, \r\n is a valid record delimiter.

Type: String

Default: \n

Ancestor: CSV

FieldDelimiter The value used to separate individual ﬁelds in a record. Instead No

of the default value, you can specify an arbitrary delimiter,
including an octal character. For example, \\036 is parsed as
the "record separator" (non-printing) character.

Type: String

Type: Enum

Valid values: NONE | USE | IGNORE

Ancestor: CSV

Comments If the ﬁrst character of a line of text matches the comment No

character, the row is considered a comment and is discarded
from the input. You can specify any character to indicate a
comment line.

Type: String

Default: #

Ancestor: CSV

Speciﬁes that CSV input records might contain record delimiters

AllowQuotedRecordDelimiter No
within quote characters. Setting this option to TRUE could result
in slower performance.

Type: Boolean

Default: FALSE

Ancestor: CSV

JSON container element (inside InputSerialization)

Name Description Required

Type The type of JSON content. LINES means that each line in the Yes
input data contains a single JSON object. DOCUMENT means that

API Version 2006-03-01

1384
Amazon Simple Storage Service API Reference
SELECT Object Content

RecordDelimiterThe value used to separate individual records in the output. No

Instead of the default value, you can specify an arbitrary
delimiter, including an octal character. For example, \\036 is
parsed as the "record separator" (non-printing) character.

You can specify up to two characters for a record delimiter. You

can specify two characters, one character and one octal, or two
octals. For example, \r\n is a valid record delimiter.

Type: String

Default: \n

Ancestor: CSV

FieldDelimiter The value you want Amazon S3 to use to separate individual No

ﬁelds in a record. Instead of the default value, you can specify

API Version 2006-03-01

1385
Amazon Simple Storage Service API Reference
SELECT Object Content

Name Description Required

an arbitrary delimiter, including an octal character. For example,
\\036 is parsed as the "record separator" (non-printing)
character.

Type: String

Default: ,

Ancestor: CSV

QuoteCharacter The value to use for escaping when the ﬁeld delimiter is part No
of the value. For example, if the value is a, b, then Amazon S3
wraps this ﬁeld value in quotation marks as follows: " a , b
".

Type: String

Default: "

Ancestor: CSV

The value to use for escaping the quotation mark character

QuoteEscapeCharacter No
inside an already escaped value. For example, if the value is "
a , b ", then Amazon S3 wraps the value in quotation marks
as follows: """ a , b """.

Type: String

Default: "

Ancestor: CSV

JSON container element (inside OutputSerialization)

Name Description Required

RecordDelimiterThe value used to separate individual records in the output. No

Instead of the default value, you can specify an arbitrary
delimiter, including an octal character. For example, \\036 is
parsed as the "record separator" (non-printing) character.

You can specify up to two characters for a record delimiter. You

can specify two characters, one character and one octal, or two
octals. For example, \r\n is a valid record delimiter.

Type: String

Default: \n

Ancestor: JSON

API Version 2006-03-01

1386
Amazon Simple Storage Service API Reference
SELECT Object Content

RequestProgress container element

Name Description Required

Enabled Speciﬁes whether periodic QueryProgress messages should be No

sent.

Type: Boolean

Default: FALSE

Ancestor: RequestProgress

Responses

A successful operation returns 200 OK status code.

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Body

Because the response size is unknown, Amazon S3 streams the response as a series of messages and
includes a Transfer-Encoding header with chunked as its value in the response. The following
example shows the response format at the top level:

API Version 2006-03-01

1387
Amazon Simple Storage Service API Reference
SELECT Object Content

Total message overhead including the prelude and both checksums is 16 bytes.
Note
All integer values within messages are in network byte order, or big-endian order.

The following diagram shows the components that make up a message and a header. Note that there are
multiple headers per message.

API Version 2006-03-01

1388
Amazon Simple Storage Service API Reference
SELECT Object Content

Payload byte-length calculations (these two calculations are equivalent):

• payload_length = total_length - header_length - sizeOf(total_length) - sizeOf(header_length) -

sizeOf(prelude_crc) - sizeOf(message_crc)
• payload_length = total_length - header_length - 16

Each message contains the following components:

• Prelude: Always ﬁxed size of 8 bytes (two ﬁelds of 4 bytes each):

For Amazon S3 Select, following is a list of header names and the set of valid values depending on the
message type.
• MessageType Header:
• HeaderName => ":message-type"
• Valid HeaderValues => "error", "event"
• EventType Header:
• HeaderName => ":event-type"
• Valid HeaderValues => "Records", "Cont", "Progress", "Stats", "End"
• ErrorCode Header:
• HeaderName => ":error-code"
• Valid HeaderValues => Error Code from the table in the Special Errors (p. 1398) section.
• ErrorMessage Header:
• HeaderName => ":error-message"
• Valid HeaderValues => Error message returned by the service, to help diagnose request-level
errors.
• Payload: Can be anything.
• Message CRC: 4-byte big-endian integer checksum (CRC) from the start of the message to the start of
the checksum (that is, everything in the message excluding the message CRC itself).

Each header contains the following components. There can be multiple headers per message.

• Header Name Byte-Length: Byte-length of the header name.

• Header Name: Name of the header, indicating the header type. Valid values: ":message-type" ":event-
type" ":error-code" ":error-message"
• Header Value Type: Enum indicating the header value type. For Amazon S3 Select, this is always 7.
• Value String Byte-Length: (For Amazon S3 Select) Byte-length of the header value string.
API Version 2006-03-01
1389
Amazon Simple Storage Service API Reference
SELECT Object Content

• Header Value String: (For Amazon S3 Select) Value of the header string. Valid values for this ﬁeld
vary based on the type of the header. See the sections below for valid values for each header type and
message type.

For Amazon S3 Select, responses can be messages of the following types:

• Records message: Can contain a single record, partial records, or multiple records. Depending on the
size of the result, a response can contain one or more of these messages.
• Continuation message: Amazon S3 periodically sends this message to keep the TCP connection open.
These messages appear in responses at random. The client must detect the message type and process
accordingly.
• Progress message: Amazon S3 periodically sends this message, if requested. It contains information
about the progress of a query that has started but has not yet completed.
• Stats message: Amazon S3 sends this message at the end of the request. It contains statistics about
the query.
• End message: Indicates that the request is complete, and no more messages will be sent. You should
not assume that the request is complete until the client receives an End message.
• RequestLevelError message: Amazon S3 sends this message if the request failed for any reason. It
contains the error code and error message for the failure. If Amazon S3 sends a RequestLevelError
message, it doesn't send an End message.

The following sections explain the structure of each message type in more detail.

For sample code and unit tests that use this protocol, see AWS C Event Stream on the GitHub website.

Records Message

Header speciﬁcation

Records messages contain three headers, as follows:

API Version 2006-03-01

1390
Amazon Simple Storage Service API Reference
SELECT Object Content

Example:

<?xml version="1.0" encoding="UTF-8"?>

Stats Message

Header speciﬁcation

Stats messages contain three headers, as follows:

API Version 2006-03-01

1394
Amazon Simple Storage Service API Reference
SELECT Object Content

Payload speciﬁcation

Stats message payload is an XML document containing information about a request's stats when
processing is complete.

• BytesScanned => Number of bytes that have been processed before being uncompressed (if the ﬁle is
compressed).
• BytesProcessed => Number of bytes that have been processed after being uncompressed (if the ﬁle is
compressed).
• BytesReturned => Total number of bytes of records payload data returned by Amazon S3.

For uncompressed ﬁles, BytesScanned and BytesProcessed are equal.

Example:

API Version 2006-03-01

1395
Amazon Simple Storage Service API Reference
SELECT Object Content

<?xml version="1.0" encoding="UTF-8"?>

End Message

Header speciﬁcation

End messages contain two headers, as follows:

API Version 2006-03-01

1396
Amazon Simple Storage Service API Reference
SELECT Object Content

Payload speciﬁcation

End messages have no payload.

Request Level Error Message

Header speciﬁcation

Request-level error messages contain three headers, as follows:

API Version 2006-03-01

1397
Amazon Simple Storage Service API Reference
SELECT Object Content

For a list of possible error codes and error messages, see the table in the Special Errors (p. 1398) section.

Payload speciﬁcation

Request-level error messages have no payload.

Special Errors

The following table contains special errors that SELECT Object Content might return.

API Version 2006-03-01

1398
Amazon Simple Storage Service API Reference
SELECT Object Content

For general information about Amazon S3 errors and a list of error codes, see Error Responses (p. 783).

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

Busy The service is unavailable. Please 503 Client

retry.

UnauthorizedAccess You are not authorized to perform 401 Client

this operation

EmptyRequestBody Request body cannot be empty. 400 Client

ExpressionTooLong The SQL expression is too long: The 400 Client

maximum byte-length for the SQL
expression is 256 KB.

IllegalSqlFunctionArgumentIllegal argument was used in the 400 Client

SQL function.

InternalError Encountered an internal error. 500 Client

InvalidColumnIndex Column index in the SQL expression 400 Client

is invalid.

InvalidKeyPath Key path in the SQL expression is 400 Client

invalid.

ColumnTooLong The length of a column in the result 400 Client

is greater than maxCharsPerColumn
of 1 MB.

OverMaxColumn The number of columns in the 400 Client

result is greater than the maximum
allowable number of columns.

OverMaxRecordSize The length of a record in the 400 Client

input or result is greater than
maxCharsPerRecord of 1 MB.

MissingHeaders Some headers in the query are 400 Client

missing from the ﬁle. Check the ﬁle
and try again.

InvalidCompressionFormat The ﬁle is not in a supported 400 Client

compression format. Only GZIP and
BZIP2 are supported.

TruncatedInput Object decompression failed. 400 Client

Check that the object is properly
compressed using the format
speciﬁed in the request.

InvalidExpressionType The ExpressionType is invalid. Only 400 Client

SQL expressions are supported.

InvalidFileHeaderInfo The FileHeaderInfo is invalid. 400 Client

Only NONE, USE, and IGNORE are
supported.

API Version 2006-03-01

1399
Amazon Simple Storage Service API Reference
SELECT Object Content

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

InvalidJsonType The JsonType is invalid. Only 400 Client

DOCUMENT and LINES are
supported.

InvalidQuoteFields The QuoteFields is invalid. Only 400 Client

ALWAYS and ASNEEDED are
supported.

InvalidRequestParameter The value of a parameter 400 Client

in SelectRequest element is
invalid. Check the service API
documentation and try again.

CSVParsingError Encountered an error parsing the 400 Client

CSV ﬁle. Check the ﬁle and try again.

JSONParsingError Encountered an error parsing the 400 Client

JSON ﬁle. Check the ﬁle and try
again.

ExternalEvalException The query cannot be evaluated. 400 Client

Check the ﬁle and try again.

InvalidDataType The SQL expression contains an 400 Client

invalid data type.

Encountered an invalid record type.

UnrecognizedFormatException 400 Client

InvalidTextEncoding Invalid encoding type. Only UTF-8 400 Client

encoding is supported.

InvalidDataSource Invalid data source type. Only CSV, 400 Client

JSON, and Parquet are supported.

InvalidTableAlias The SQL expression contains an 400 Client

invalid table alias.

MalformedXML The XML provided was not well- 400 Client

formed or did not validate against
our published schema. Check the
service documentation and try
again.

Multiple data sources are not

MultipleDataSourcesUnsupported 400 Client
supported.

MissingRequiredParameter The SelectRequest entity is missing 400 Client

a required parameter. Check the
service documentation and try
again.

API Version 2006-03-01

1400
Amazon Simple Storage Service API Reference
SELECT Object Content

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

InputSerialization speciﬁes more

UnsupportedFunction Encountered an unsupported SQL 400 Client

function.

UnsupportedSqlOperation Encountered an unsupported SQL 400 Client

operation.

UnsupportedSqlStructure Encountered an unsupported SQL 400 Client

structure. Check the SQL Reference.

UnsupportedStorageClass Encountered an invalid storage class. 400 Client

Only STANDARD, STANDARD_IA, and
ONEZONE_IA storage classes are
supported.

UnsupportedSyntax Encountered invalid syntax. 400 Client

UnsupportedRangeHeader Range header is not supported for 400 Client

this operation.

LexerInvalidChar The SQL expression contains an 400 Client

invalid character.

LexerInvalidOperator The SQL expression contains an 400 Client

invalid literal.

LexerInvalidLiteral The SQL expression contains an 400 Client

invalid operator.

LexerInvalidIONLiteral The SQL expression contains an 400 Client

invalid operator.

ParseExpectedWhenClause Did not ﬁnd the expected WHEN 400 Client

clause in the SQL expression. CASE is
not supported.

ParseUnsupportedToken The SQL expression contains an 400 Client

unsupported token.

The SQL expression contains an

ParseUnsupportedLiteralsGroupBy 400 Client
unsupported use of GROUP BY.

ParseExpectedMember The SQL expression contains an 400 Client

unsupported use of MEMBER.

ParseUnsupportedSelect The SQL expression contains an 400 Client

unsupported use of SELECT.

ParseUnsupportedCase The SQL expression contains an 400 Client

unsupported use of CASE.

ParseUnsupportedCaseClauseThe SQL expression contains an 400 Client

unsupported use of CASE.

ParseUnsupportedAlias The SQL expression contains an 400 Client

unsupported use of ALIAS.

ParseUnsupportedSyntax The SQL expression contains 400 Client

unsupported syntax.

ParseUnknownOperator The SQL expression contains an 400 Client

invalid operator.

ParseInvalidPathComponent The SQL expression contains an 400 Client

invalid path component.

ParseMissingIdentAfterAt Did not ﬁnd the expected identiﬁer 400 Client

after the @ symbol in the SQL
expression.

ParseUnexpectedOperator The SQL expression contains an 400 Client

unexpected operator.

ParseUnexpectedTerm The SQL expression contains an 400 Client

unexpected term.

ParseUnexpectedToken The SQL expression contains an 400 Client

unexpected token.

ParseUnExpectedKeyword The SQL expression contains an 400 Client

unexpected keyword.

ParseExpectedExpression Did not ﬁnd the expected SQL 400 Client

expression.

API Version 2006-03-01

1402
Amazon Simple Storage Service API Reference
SELECT Object Content

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

Did not ﬁnd the expected left

ParseExpectedLeftParenAfterCast 400 Client
parenthesis after CAST in the SQL
expression.

Did not ﬁnd expected the left

ParseExpectedLeftParenValueConstructor 400 Client
parenthesis in the SQL expression.

Did not ﬁnd the expected left

ParseExpectedLeftParenBuiltinFunctionCall 400 Client
parenthesis in the SQL expression.

Did not ﬁnd the expected argument

ParseExpectedArgumentDelimiter 400 Client
delimiter in the SQL expression.

ParseCastArity The SQL expression CAST has 400 Client

incorrect arity.

ParseInvalidTypeParam The SQL expression contains an 400 Client

invalid parameter value.

ParseEmptySelect The SQL expression contains an 400 Client

empty SELECT.

ParseSelectMissingFrom The SQL expression contains a 400 Client

missing FROM after SELECT list.

GROUP is not supported in the SQL

ParseExpectedIdentForGroupName 400 Client
expression.

ParseExpectedIdentForAliasDid not ﬁnd the expected identiﬁer 400 Client

for the alias in the SQL expression.

Only COUNT with (*) as a parameter

ParseUnsupportedCallWithStar 400 Client
is supported in the SQL expression.

Only one argument is supported

ParseNonUnaryAgregateFunctionCall 400 Client
for aggregate functions in the SQL
expression.

ParseMalformedJoin JOIN is not supported in the SQL 400 Client

expression.

ParseExpectedIdentForAt Did not ﬁnd the expected identiﬁer 400 Client

for AT name in the SQL expression.

Other expressions are not allowed

ParseAsteriskIsNotAloneInSelectList 400 Client
in the SELECT list when '*' is used
without dot notation in the SQL
expression.

Cannot mix [] and * in the same

ParseCannotMixSqbAndWildcardInSelectList 400 Client
expression in a SELECT list in SQL
expression.

Invalid use of * in SELECT list in the

ParseInvalidContextForWildcardInSelectList 400 Client
SQL expression.

API Version 2006-03-01

1403
Amazon Simple Storage Service API Reference
SELECT Object Content

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

A column name or a path provided

EvaluatorBindingDoesNotExist 400 Client
does not exist in the SQL expression.

ValueParseFailure Time stamp parse failure in the SQL 400 Client

expression.

Incorrect type of arguments in

IncorrectSqlFunctionArgumentType 400 Client
function call in the SQL expression.

AmbiguousFieldName Field name matches to multiple 400 Client

fields in the file. Check the SQL
expression and the file, and try
again.

EvaluatorInvalidArguments Incorrect number of arguments 400 Client

in the function call in the SQL
expression.

Invalid time stamp format string in

EvaluatorInvalidTimestampFormatPattern 400 Client
the SQL expression.

ValueParseFailure Time stamp parse failure in the SQL 400 Client

expression.

IntegerOverflow Integer overﬂow or underﬂow in the 400 Client

SQL expression.

LikeInvalidInputs Invalid argument given to the LIKE 400 Client

clause in the SQL expression.

CastFailed Attempt to convert from one data 400 Client

type to another using CAST failed in
the SQL expression.

InvalidCast Attempt to convert from one data 400 Client

type to another using CAST failed in
the SQL expression.

Time stamp format pattern

EvaluatorInvalidTimestampFormatPattern 400 Client
requires additional ﬁelds in the SQL
expression.

Time stamp format pattern contains 400

EvaluatorInvalidTimestampFormatPatternSymbolForParsing Client
a valid format symbol that cannot
be applied to time stamp parsing in
the SQL expression.

Time stamp format pattern

EvaluatorTimestampFormatPatternDuplicateFields 400 Client
contains multiple format speciﬁers
representing the time stamp ﬁeld in
the SQL expression.

API Version 2006-03-01

1404
Amazon Simple Storage Service API Reference
SELECT Object Content

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

Time stamp format pattern contains

EvaluatorUnterminatedTimestampFormatPatternToken 400 Client
unterminated token in the SQL
expression.

Time stamp format pattern

EvaluatorInvalidTimestampFormatPatternToken 400 Client
contains an invalid token in the SQL
expression.

Time stamp format pattern contains

EvaluatorInvalidTimestampFormatPatternSymbol 400 Client
an invalid symbol in the SQL
expression.

ParquetParsingError Error parsing Parquet ﬁle. Please 400 Client

check the ﬁle and try again.

Examples

Example 1: CSV Object

The following select request retrieves all records from an object with data stored in CSV format. The
OutputSerialization element directs Amazon S3 to return results in CSV.

POST /exampleobject.csv?select&select-type=2 HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Tue, 17 Oct 2017 01:49:52 GMT
Authorization: authorization string
Content-Length: content length

<?xml version="1.0" encoding="UTF-8"?>

<SelectRequest>
<Expression>Select * from S3Object</Expression>
<ExpressionType>SQL</ExpressionType>
<InputSerialization>
<CompressionType>GZIP</CompressionType>
<CSV>

API Version 2006-03-01

1405
Amazon Simple Storage Service API Reference
SELECT Object Content

<FileHeaderInfo>IGNORE</FileHeaderInfo>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
<Comments>#</Comments>
</CSV>
</InputSerialization>
<OutputSerialization>
<CSV>
<QuoteFields>ASNEEDED</QuoteFields>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
</CSV>
</OutputSerialization>
</SelectRequest>

You can try diﬀerent queries in the Expression element:

• Assuming that you are not using column headers, you can identify columns using positional headers:

SELECT s._1, s._2 FROM S3Object s WHERE s._3 > 100

• If you have column headers and you set the FileHeaderInfo to Use, you can identify columns by
name in the expression:

SELECT s.Id, s.FirstName, s.SSN FROM S3Object s

• You can specify functions in the SQL expression:

SELECT count(*) FROM S3Object s WHERE s._1 < 1

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: GFihv3y6+kE7KG11GEkQhU7/2/cHR3Yb2fCb2S04nxI423Dqwg2XiQ0B/UZlzYQvPiBlZNRcovw=
x-amz-request-id: 9F341CD3C4BA79E0
Date: Tue, 17 Oct 2017 23:54:05 GMT

A series of messages

Example 2: JSON Object

The following select request retrieves all records from an object with data stored in JSON format. The
OutputSerialization directs Amazon S3 to return results in CSV.

POST /exampleobject.json?select&select-type=2 HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Tue, 17 Oct 2017 01:49:52 GMT
Authorization: authorization string

API Version 2006-03-01

1406
Amazon Simple Storage Service API Reference
SELECT Object Content

Content-Length: content length

<?xml version="1.0" encoding="UTF-8"?>

<SelectRequest>
<Expression>Select * from S3Object</Expression>
<ExpressionType>SQL</ExpressionType>
<InputSerialization>
<CompressionType>GZIP</CompressionType>
<JSON>
<Type>DOCUMENT</Type>
</JSON>
</InputSerialization>
<OutputSerialization>
<CSV>
<QuoteFields>ASNEEDED</QuoteFields>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
</CSV>
</OutputSerialization>
</SelectRequest>

You can try diﬀerent queries in the Expression element:

• You can ﬁlter by string comparison using record keys:

SELECT s.country, s.city from S3Object s where s.city = 'Seattle'

• You can specify functions in the SQL expression:

SELECT count(*) FROM S3Object s

Example 3: Parquet Object

The following select request retrieves all records from an object with data stored in Parquet format. The
OutputSerialization directs Amazon S3 to return results in CSV.

POST /exampleobject.parquet?select&select-type=2 HTTP/1.1

Host: examplebucket.s3.amazonaws.com
Date: Tue, 17 Oct 2017 01:49:52 GMT
Authorization: authorization string
Content-Length: content length

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

1407
Amazon Simple Storage Service API Reference
SELECT Object Content

<CSV>
<QuoteFields>ASNEEDED</QuoteFields>
<RecordDelimiter>\n</RecordDelimiter>
<FieldDelimiter>,</FieldDelimiter>
<QuoteCharacter>"</QuoteCharacter>
<QuoteEscapeCharacter>"</QuoteEscapeCharacter>
</CSV>
</OutputSerialization>
</SelectRequest>

Notes

The SELECT Object Content operation does not support the following GET Object functionality.
For more information, see GET Object (p. 1248).

• Range: You cannot specify the range of bytes of an object to return.

Related Resources

• GET Object (p. 1248)

• GET Bucket lifecycle (p. 983)
• PUT Bucket lifecycle (p. 1145)

API Version 2006-03-01

1408
Amazon Simple Storage Service API Reference
Abort Multipart Upload

Abort Multipart Upload

Description

For information on permissions required to use the multipart upload API, go to Multipart Upload API and
Permissions in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

DELETE /ObjectName?uploadId=UploadId HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: Date
Authorization: authorization string

Request Parameters

API Version 2006-03-01

1409
Amazon Simple Storage Service API Reference
Abort Multipart Upload

This operation does not use request parameters.

Request Headers

This operation uses only Request Headers common to most requests. For more information, see Common
Request Headers (p. 779).

Request Elements

This operation does not use request elements.

Responses

Response Headers

This operation uses only response headers that are common to most responses. For more information,
see Common Response Headers (p. 782).

Response Elements

This operation does not use response elements.

Special Errors

API Version 2006-03-01

1410
Amazon Simple Storage Service API Reference
Abort Multipart Upload

Error Code Description HTTP Status SOAP

Code Fault Code
Preﬁx

NoSuchUpload The speciﬁed multipart upload does not exist. 404 Not Found Client
The upload ID might be invalid, or the multipart
upload might have been aborted or completed.

For general information about Amazon S3 errors and a list of error codes, see Error Responses (p. 783).

Sample Request

The following request aborts a multipart upload identiﬁed by its upload ID.

DELETE /example-object?uploadId=VXBsb2FkIElEIGZvciBlbHZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZ
HTTP/1.1
Host: example-bucket.s3.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

Sample Response

Related Actions
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

API Version 2006-03-01

1411
Amazon Simple Storage Service API Reference
Abort Multipart Upload

• Initiate Multipart Upload (p. 1420)

• Upload Part (p. 1440)
• Complete Multipart Upload (p. 1413)
• List Parts (p. 1432)
• List Multipart Uploads (p. 1084)

API Version 2006-03-01

1412
Amazon Simple Storage Service API Reference
Complete Multipart Upload

Complete Multipart Upload

Description

This operation completes a multipart upload by assembling previously uploaded parts.

You ﬁrst initiate the multipart upload and then upload all parts using the Upload Parts operation
(see Upload Part (p. 1440)). After successfully uploading all relevant parts of an upload, you call this
operation to complete the upload. Upon receiving this request, Amazon S3 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 the parts list is complete, this operation concatenates the
parts you provide in the list. For each part in the list, you must provide the part number and the ETag
header value, returned after that part was uploaded.

Processing of a Complete Multipart Upload request could take several minutes to complete. After
Amazon S3 begins processing the request, it sends an HTTP response header that speciﬁes a 200 OK
response. While processing is in progress, Amazon S3 periodically sends whitespace characters to keep
the connection from timing out. Because a request could fail after the initial 200 OK response has been
sent, it is important that you check the response body to determine whether the request succeeded.

Note that if Complete Multipart Upload fails, applications should be prepared to retry the failed
requests. For more information, go to Amazon S3 Error Best Practices section of the Amazon Simple
Storage Service Developer Guide.

For more information on multipart uploads, go to Uploading Objects Using Multipart Upload in the
Amazon Simple Storage Service Developer Guide.

For information on permissions required to use the multipart upload API, go to Multipart Upload API and
Permissions in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

API Version 2006-03-01

1413
Amazon Simple Storage Service API Reference
Complete Multipart Upload

POST /ObjectName?uploadId=UploadId HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: Date
Content-Length: Size
Authorization: authorization string

<CompleteMultipartUpload>
<Part>
<PartNumber>PartNumber</PartNumber>
<ETag>ETag</ETag>
</Part>
...
</CompleteMultipartUpload>

Request Parameters

This operation does not use request parameters.

Request Headers

This operation uses only Request Headers common to most requests. For more information, see Common
Request Headers (p. 779)

Request Elements

Name Description Required

CompleteMultipartUpload Container for the request. Yes

Ancestor: None

Type: Container

Children: One or more Part elements

Part Container for elements related to a particular previously Yes

uploaded part.

Ancestor: CompleteMultipartUpload

Type: Container

API Version 2006-03-01

1414
Amazon Simple Storage Service API Reference
Complete Multipart Upload

Name Description Required

Children: PartNumber, ETag

PartNumber Part number that identiﬁes the part. Yes

Ancestor: Part

Type: Integer

ETag Entity tag returned when the part was uploaded. Yes

Ancestor: Part

Type: String

Responses

Response Headers

The operation uses the following response header, in addition to the response headers common to most
requests. For more information, see Common Response Headers (p. 782).

Header Description

x-amz- Amazon S3 returns this header if an Expiration action is conﬁgured for the
expiration object as part of the bucket's lifecycle conﬁguration. The header value includes
an "expiry-date" component and a URL-encoded "rule-id" component. Note that
for versioning-enabled buckets, this header applies only to current versions;
Amazon S3 does not provide a header to infer when a noncurrent version will
be eligible for permanent deletion. For more information, see PUT Bucket
lifecycle (p. 1145).

Type: String

x-amz-server- If you speciﬁed server-side encryption either with an AWS KMS or Amazon S3-
side-encryption managed encryption key in your initiate multipart upload request, the response
includes this header. It conﬁrms the encryption algorithm that Amazon S3 used
to encrypt the object.

Type: String

x-amz- If the x-amz-server-side-encryption is present and has the value of

server-side- aws:kms, this header speciﬁes the ID of the AWS Key Management Service
(KMS) master encryption key that was used for the object.

API Version 2006-03-01

1415
Amazon Simple Storage Service API Reference
Complete Multipart Upload

Header Description
encryption-aws- Type: String
kms-key-id

x-amz-server- If encryption by using server-side encryption with customer-provided encryption

side-encryption keys was requested, the response will include this header conﬁrming the
-customer- encryption algorithm used.
algorithm
Type: String

Valid Value: AES256

x-amz-version- Version ID of the newly created object, in case the bucket has versioning turned
id on.

Type: String

Response Elements

Name Description

CompleteMultipartUploadResult Container for the response

Type: Container

Children: Location, Bucket, Key, ETag

Sample Response

The following response indicates that an object was successfully assembled.

<?xml version="1.0" encoding="UTF-8"?>

<CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Location>http://Example-Bucket.s3.amazonaws.com/Example-Object</Location>
<Bucket>Example-Bucket</Bucket>
<Key>Example-Object</Key>
<ETag>"3858f62230ac3c915f300c664312c11f-9"</ETag>
</CompleteMultipartUploadResult>

Sample Response with Error Speciﬁed in Header

The following response indicates that an error occurred before the HTTP response header was sent.

HTTP/1.1 403 Forbidden

x-amz-id-2: Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732072657175657374

API Version 2006-03-01

1418
Amazon Simple Storage Service API Reference
Complete Multipart Upload

Date: Mon, 1 Nov 2010 20:34:56 GMT

Content-Length: 237
Connection: keep-alive
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>

Sample Response with Error Speciﬁed in Body

<?xml version="1.0" encoding="UTF-8"?>

Related Actions

• Initiate Multipart Upload (p. 1420)

• Upload Part (p. 1440)
• Abort Multipart Upload (p. 1409)
• List Parts (p. 1432)
• List Multipart Uploads (p. 1084)

API Version 2006-03-01

1419
Amazon Simple Storage Service API Reference
Initiate Multipart Upload

Initiate Multipart Upload

Description

This operation initiates a multipart upload and returns an upload ID. This upload ID is used to associate
all of the parts in the speciﬁc multipart upload. You specify this upload ID in each of your subsequent
upload part requests (see Upload Part (p. 1440)). You also include this upload ID in the ﬁnal request to
either complete or abort the multipart upload request.

For more information about multipart uploads, see Multipart Upload Overview in the Amazon Simple
Storage Service Developer Guide.

For information about the permissions required to use the multipart upload API, see Multipart Upload
API and Permissions in the Amazon Simple Storage Service Developer Guide.

For request signing, multipart upload is just a series of regular requests. You initiate a multipart upload,
send one or more requests to upload parts, and then complete the multipart upload process. You sign
each request individually. There is nothing special about signing multipart upload requests. For more
information about signing, see Authenticating Requests (AWS Signature Version 4) (p. 792).
Note
After you initiate a multipart upload and upload one or more parts, to stop being charged for
storing the uploaded parts, you must either complete or abort the multipart upload. Amazon S3
frees up the space used to store the parts and stop charging you for storing them only after you
either complete or abort a multipart upload.

You can optionally request server-side encryption. For server-side encryption, Amazon S3 encrypts your
data as it writes it to disks in its data centers and decrypts it when you access it. You can provide your
own encryption key, or use AWS Key Management Service (AWS KMS) encryption keys or Amazon S3-
managed encryption keys. If you choose to provide your own encryption key, the request headers you
provide in Upload Part (p. 1440) and Upload Part - Copy (p. 1447) requests must match the headers you
used in the request to initiate the upload by using Initiate Multipart Upload (p. 1420).

To perform a multipart upload with encryption using an AWS KMS key, the requester must have
permission to the kms:Encrypt, kms:Decrypt, kms:ReEncrypt*, kms:GenerateDataKey*, and
kms:DescribeKey actions on the key. These permissions are required because Amazon S3 must decrypt
and read data from the encrypted ﬁle parts before it completes the multipart upload.

If your AWS Identity and Access Management (IAM) user or role is in the same AWS account as the AWS
KMS key, then you must have these permissions on the key policy. If your IAM user or role belongs to a

API Version 2006-03-01

1420
Amazon Simple Storage Service API Reference
Initiate Multipart Upload

diﬀerent account than the key, then you must have the permissions on both the key policy and your IAM
user or role.

For more information, see Protecting Data Using Server-Side Encryption in the Amazon Simple Storage
Service Developer Guide.

Requests

Syntax

POST /ObjectName?uploads HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

This operation does not use request parameters.

Request Headers

Name Description Required

Cache-Control Can be used to specify caching behavior along the request/reply No

chain. For more information, see http://www.w3.org/Protocols/
rfc2616/rfc2616-sec14.html#sec14.9.

Type: String

Default: None

API Version 2006-03-01

1421
Amazon Simple Storage Service API Reference
Initiate Multipart Upload

Name Description Required

Content- Speciﬁes presentational information for the object. For more No

Disposition information, see http://www.w3.org/Protocols/rfc2616/rfc2616-
sec19.html#sec19.5.1.

Type: String

Default: None

Content-Encoding Speciﬁes the content encodings that have been applied to the No
object and which decoding mechanisms must be applied to
obtain the media-type referenced by the Content-Type header
ﬁeld. For more information, see http://www.w3.org/Protocols/
rfc2616/rfc2616-sec14.html#sec14.11.

Type: String

Default: None

Content-Type A standard MIME type that describes the format of the object No
data. For more information, see http://www.w3.org/Protocols/
rfc2616/rfc2616-sec14.html#sec14.17.

Type: String

Default: binary/octet-stream

Constraints: MIME types only

Expires The date and time at which the object should no longer be No
cached. For more information, see http://www.w3.org/Protocols/
rfc2616/rfc2616-sec14.html#sec14.21.

Type: String

Default: None

x-amz-meta- Headers starting with this prefix are user-defined metadata. Each No
one is stored and returned as a set of key-value pairs. Amazon
S3 doesn't validate or interpret user-defined metadata. For more
information, see PUT Object (p. 1324).

Type: String

Default: None

x-amz-storage- The type of storage to use for the object that is created after a No
class successful multipart upload. If you don't specify a class, Amazon
S3 uses the default storage class, Standard. Amazon S3 supports
other storage classes. For more information, see Storage Classes
in the Amazon Simple Storage Service Developer Guide.

Type: Enum

Default: STANDARD

Valid values: STANDARD | REDUCED_REDUNDANCY | GLACIER

| STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING |
DEEP_ARCHIVE

API Version 2006-03-01

1422
Amazon Simple Storage Service API Reference
Initiate Multipart Upload

Name Description Required

x-amz-tagging Speciﬁes a set of one or more tags you want associated with No
the object. These tags are stored in the tagging subresource
associated with the object.

For more information about adding tags to an object, see Object

Tagging Management in the Amazon Simple Storage Service
Developer Guide.

Type: String

Default: None

Constraints: The encoding for tags will be URL query parameter

encoding. The maximum size of this header is limited to 2 K.

x-amz-website If the bucket is conﬁgured as a website, redirects requests for No

-redirect- this object to another object in the same bucket or to an external
location URL. Amazon S3 stores the value of this header in the object
metadata. For information about object metadata, see Object Key
and Metadata.

In the following example, the request header sets the redirect to

an object (anotherPage.html) in the same bucket:

x-amz-website-redirect-location: /
anotherPage.html

In the following example, the request header sets the object

redirect to another website:

x-amz-website-redirect-location: http://
www.example.com/

For more information about website hosting in Amazon S3, see

Hosting Websites on Amazon S3 and How to Conﬁgure Website
Page Redirects in the Amazon Simple Storage Service Developer
Guide.

Type: String

Default: None

Constraints: The value must be preﬁxed by, "/", "http://" or

"https://". The length of the value is limited to 2 K.

API Version 2006-03-01

1423
Amazon Simple Storage Service API Reference
Initiate Multipart Upload

Name Description Required

>Speciﬁes the AWS KMS Encryption Context to use for object

SSEKMSEncryptionContext No
encryption. The value of this header is a base64-encoded UTF-8
string holding JSON with the encryption context key-value pairs.

In the following example, the request header sets the redirect to

an object (anotherPage.html) in the same bucket:

x-amz-website-redirect-location: /
anotherPage.html

In the following example, the request header sets the object

redirect to another website:

x-amz-website-redirect-location: http://
www.example.com/

For more information about website hosting in Amazon S3, see

Hosting Websites on Amazon S3 and How to Conﬁgure Website
Page Redirects in the Amazon Simple Storage Service Developer
Guide.

Type: String

Default: None

Constraints: The value must be preﬁxed by, "/", "http://" or

"https://". The length of the value is limited to 2 K.

Access Control List (ACL) Speciﬁc Request Headers

Additionally, you can use the following access control-related headers with this operation. By default, all
objects are private and only the owner has full access control. When adding a new object, you can grant
permissions to individual AWS accounts or predeﬁned groups deﬁned by Amazon S3. These permissions
are then added to the Access Control List (ACL) on the object. For more information, see Access Control
List (ACL) Overview in the Amazon Simple Storage Service Developer Guide. This operation enables you to
grant access permissions using one of the following methods:

• Specify canned ACL – Amazon S3 supports a set of predeﬁned ACLs, known as canned ACLs. Each
canned ACL has a predeﬁned set of grantees and permissions. For more information, see Canned ACL.

Name Description Required

Default: None

Constraints: None

x-amz-grant-read- Allows the grantee to read the object ACL. No

acp
Type: String

Default: None

Constraints: None

x-amz-grant-write- Allows the grantee to write the ACL for the applicable No
acp object.

Type: String

Default: None

Constraints: None

x-amz-grant-full- Grants the grantee the READ, READ_ACP, and WRITE_ACP No

control permissions on the object.

Type: String

Default: None

Constraints: None

API Version 2006-03-01

1425
Amazon Simple Storage Service API Reference
Initiate Multipart Upload

You specify each grantee as a type=value pair, where the type can be one of the following:

• emailAddress – If the speciﬁed value is the email address of an AWS account.

• id – If the speciﬁed value is the canonical user ID of an AWS account.
• uri – If you are granting permission to a predeﬁned group.

For example, the following x-amz-grant-read header grants read object data and its metadata
permissions to the AWS accounts identiﬁed by their email addresses:

x-amz-grant-read: emailAddress="[email protected]", emailAddress="[email protected]"

Server-Side Encryption–Speciﬁc Request Headers

• Use encryption keys managed by AWS KMS or Amazon S3 – If you want AWS to manage the keys used
to encrypt data, specify the following headers in the request.

Name Description Required

x-amz-server-side Speciﬁes a server-side encryption algorithm to use when Yes

-encryption Amazon S3 creates an object.

Type: String

Valid Value: aws:kms, AES256

x-amz-server- If the x-amz-server-side-encryption is present and has Yes, if the

x-amz-server- If x-amz-server-side-encryption is present, and if its No

Type: String

API Version 2006-03-01

1426
Amazon Simple Storage Service API Reference
Initiate Multipart Upload

Note
If you specify x-amz-server-side-encryption:aws:kms, but do not provide x-amz-
server-side- encryption-aws-kms-key-id, Amazon S3 uses the default AWS KMS key
to protect the data.

For more information on Server-Side Encryption with Amazon KMS-Managed Keys (SSE-KMS), see
Protecting Data Using Server-Side Encryption with AWS KMS-Managed Keys in the Amazon Simple
Storage Service Developer Guide.
• Use customer-provided encryption keys – If you want to manage your own encryption keys, provide all
the following headers in the request.

Name Description Required

x-amz-server- Speciﬁes the algorithm to use to when encrypting the object. Yes
side-encryption
-customer- Type: String
algorithm
Default: None

Valid Value: AES256

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-key and x-amz-server-
side-encryption-customer-key-MD5 headers

x-amz-server- Speciﬁes the customer-provided base64-encoded encryption Yes

side-encryption- key that Amazon S3 uses in encrypting data. This value stores
customer-key the object and then is discarded. Amazon does not store
the encryption key. The key must be appropriate for use
with the algorithm speciﬁed in the x-amz-server-side-
encryption-customer-algorithm header.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key-MD5 headers

x-amz-server- Speciﬁes the base64-encoded 128-bit MD5 digest of the Yes

side-encryption- encryption key according to RFC 1321. Amazon S3 uses this
customer-key-MD5 header for a message integrity check to ensure that the
encryption key was transmitted without error.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key headers

API Version 2006-03-01

1427
Amazon Simple Storage Service API Reference
Initiate Multipart Upload

Request Elements

This operation does not use request elements.

Responses

Response Headers

Name Description

x-amz-abort- If the bucket has a lifecycle rule conﬁgured with an action to abort incomplete
date multipart uploads and the preﬁx in the lifecycle rule matches the object name
in the request, the response includes this header. The header indicates when the
initiated multipart upload becomes eligible for an abort operation. For more
information, see Aborting Incomplete Multipart Uploads Using a Bucket Lifecycle
Policy in the Amazon Simple Storage Service Developer Guide.

The response also includes the x-amz-abort-rule-id header that provides the
ID of the lifecycle conﬁguration rule that deﬁnes this action.

Type: String

x-amz-abort- This header is returned along with the x-amz-abort-date header. It identifies
rule-id the applicable lifecycle configuration rule that defines the action to abort
incomplete multipart uploads.

Type: String

x-amz- If you speciﬁed server-side encryption either with an AWS KMS key or an Amazon
server-side- S3-managed encryption key in your initiate multipart upload request, the
encryption response includes this header. It conﬁrms the encryption algorithm that Amazon
S3 used to encrypt the part that you uploaded.

Type: String

API Version 2006-03-01

1428
Amazon Simple Storage Service API Reference
Initiate Multipart Upload

Name Description

x-amz- If x-amz-server-side-encryption is present and has the value of aws:kms,

server-side- this header speciﬁes the ID of the AWS KMS master encryption key that was used
encryption- for the object.
aws-kms-key-
id Type: String

x-amz- If server-side encryption with customer-provided encryption keys was requested,

server-side the response includes this header to conﬁrm which encryption algorithm was
-encryption used.
-customer-
algorithm Type: String

Valid Values: AES256

x-amz- If server-side encryption using a customer-provided encryption key was requested,

server-side the response returns this header to verify the integrity of the roundtrip message
-encryption- of the customer-provided encryption key.
customer-key-
MD5 Type: String

Response Elements

Name Description

InitiateMultipartUploadResult Container for the response.

Type: Container

Children: Bucket, Key, UploadId

Ancestors: None

Bucket Name of the bucket to which the multipart upload was

initiated.

Type: String

Ancestors: InitiateMultipartUploadResult

Key Object key for which the multipart upload was initiated.

Type: String

Ancestors: InitiateMultipartUploadResult

UploadId ID for the initiated multipart upload.

Type: String

Ancestors: InitiateMultipartUploadResult

API Version 2006-03-01

1429
Amazon Simple Storage Service API Reference
Initiate Multipart Upload

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Sample Request

This operation initiates a multipart upload for the example-object object.

POST /example-object?uploads HTTP/1.1

Host: example-bucket.s3.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

1430
Amazon Simple Storage Service API Reference
Initiate Multipart Upload

Sample: Initiate a Multipart Upload Using Server-side Encryption with

Customer-provided Encryption Keys

This example, which initiates a multipart upload request, speciﬁes server-side encryption with customer-
provided encryption keys by adding relevant headers.

POST /example-object?uploads HTTP/1.1

Host: example-bucket.s3.amazonaws.com
Authorization:authorization string
Date: Wed, 28 May 2014 19:34:57 +0000
x-amz-server-side-encryption-customer-key: g0lCfA3Dv40jZz5SQJ1ZukLRFqtI5WorC/8SEEXAMPLE
x-amz-server-side-encryption-customer-key-MD5: ZjQrne1X/iTcskbY2example
x-amz-server-side-encryption-customer-algorithm: AES256

In the response, Amazon S3 returns an UploadId. In addition, Amazon S3 returns the encryption
algorithm and the MD5 digest of the encryption key that you provided in the request.

<?xml version="1.0" encoding="UTF-8"?>

<InitiateMultipartUploadResult
xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Bucket>example-bucket</Bucket>
<Key>example-object</Key>

<UploadId>EXAMPLEJZ6e0YupT2h66iePQCc9IEbYbDUy4RTpMeoSMLPRp8Z5o1u8feSRonpvnWsKKG35tI2LB9VDPiCgTy.Gq2VxQ
</UploadId>
</InitiateMultipartUploadResult>

Related Actions

• Upload Part (p. 1440)

• Complete Multipart Upload (p. 1413)
• Abort Multipart Upload (p. 1409)
• List Parts (p. 1432)
• List Multipart Uploads (p. 1084)

API Version 2006-03-01

1431
Amazon Simple Storage Service API Reference
List Parts

List Parts

Description

This operation lists the parts that have been uploaded for a speciﬁc multipart upload.

This operation must include the upload ID, which you obtain by sending the initiate multipart upload
request (see Initiate Multipart Upload (p. 1420)). This request returns a maximum of 1,000 uploaded
parts. The default number of parts returned is 1,000 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 ﬁeld with the value of true, and a
NextPartNumberMarker element. In subsequent List Parts requests you can include the part-
number-marker query string parameter and set its value to the NextPartNumberMarker ﬁeld value
from the previous response.

For more information on multipart uploads, see Uploading Objects Using Multipart Upload in the
Amazon Simple Storage Service Developer Guide.

For information on permissions required to use the multipart upload API, see Multipart Upload API and
Permissions in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

GET /ObjectName?uploadId=UploadId HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: Date
Authorization: authorization string

API Version 2006-03-01

1432
Amazon Simple Storage Service API Reference
List Parts

Request Parameters

This implementation of GET uses the parameters in the following table to return a subset of the objects
in a bucket.

Parameter Description Required

encoding-type Requests Amazon S3 to encode the response and speciﬁes the No

encoding method to use.

Type: String

Default: None

Valid value: url

uploadId Upload ID identifying the multipart upload whose parts are being Yes
listed.

Type: String

Default: None

max-parts Sets the maximum number of parts to return in the response body. No

Type: String

Default: 1,000

part-number- Speciﬁes the part after which listing should begin. Only parts with No
marker higher part numbers will be listed.

Type: String

Default: None

Request Headers

This operation uses only Request Headers common to most requests. For more information, see Common
Request Headers (p. 779).

API Version 2006-03-01

1433
Amazon Simple Storage Service API Reference
List Parts

Request Elements

This operation does not use request elements.

Response Headers

This operation uses only response headers that are common to most responses. For more information,
see Common Response Headers (p. 782).

Response Elements

Name Description

x-amz-abort-date If the bucket has a lifecycle rule conﬁgured with an action to abort
incomplete multipart uploads and the preﬁx in the lifecycle rule
matches the object name in the request, then the response includes
this header indicating when the initiated multipart upload will become
eligible for abort operation. For more information, see Aborting
Incomplete Multipart Uploads Using a Bucket Lifecycle Policy in the
Amazon Simple Storage Service Developer Guide.

The response will also include the x-amz-abort-rule-id header

that will provide the ID of the lifecycle conﬁguration rule that deﬁnes
this action.

Type: String

x-amz-abort-rule-id This header is returned along with the x-amz-abort-date header. It

identifies applicable lifecycle configuration rule that defines the action
to abort incomplete multipart uploads.

Type: String

API Version 2006-03-01

1434
Amazon Simple Storage Service API Reference
List Parts

Name Description

ListPartsResult Container for the response.

Children: Bucket, Key, UploadId, Initiator, Owner,

StorageClass, PartNumberMarker, NextPartNumberMarker,
MaxParts, IsTruncated, Part

Type: Container

Bucket Name of the bucket to which the multipart upload was initiated.

Type: String

Ancestor: ListPartsResult

Encoding-Type Encoding type used by Amazon S3 to encode object key names in the
XML response.

If you specify encoding-type request parameter, Amazon S3 includes

this element in the response, and returns encoded key name values in
the Key element.

Type: String

Ancestor: ListBucketResult

Key Object key for which the multipart upload was initiated.

Type: String

Ancestor: ListPartsResult

UploadId Upload ID identifying the multipart upload whose parts are being
listed.

Ancestor: Part

Examples

Sample Request

Assume you have uploaded parts with sequential part numbers starting with 1. The following List Parts
request speciﬁes max-parts and part-number-marker query parameters. The request lists the ﬁrst
two parts that follow part number 1, that is, you will get parts 2 and 3 in the response. If more parts
exist , the result is a truncated result and therefore the response will return an IsTruncated element
with the value true. The response will also return the NextPartNumberMarker element with the value
3, which should be used for the value of the part-number-marker request query string parameter in
the next List Parts request.

GET /example-object?
uploadId=XXBsb2FkIElEIGZvciBlbHZpbmcncyVcdS1tb3ZpZS5tMnRzEEEwbG9hZA&max-parts=2&part-
number-marker=1 HTTP/1.1
Host: example-bucket.s3.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: authorization string

API Version 2006-03-01

1437
Amazon Simple Storage Service API Reference
List Parts

Sample Response

The following is a sample response.

<?xml version="1.0" encoding="UTF-8"?>

Related Actions

• Initiate Multipart Upload (p. 1420)

• Upload Part (p. 1440)

API Version 2006-03-01

1438
Amazon Simple Storage Service API Reference
List Parts

• Complete Multipart Upload (p. 1413)

• Abort Multipart Upload (p. 1409)
• List Multipart Uploads (p. 1084)

API Version 2006-03-01

1439
Amazon Simple Storage Service API Reference
Upload Part

Upload Part

Description

This operation uploads a part in a multipart upload.

You must initiate a multipart upload (see Initiate Multipart Upload (p. 1420)) before you can upload any
part. In response to your initiate request, Amazon S3 returns an upload ID, a unique identiﬁer, that you
must include in your upload part request.

To ensure that data is not corrupted when traversing the network, specify the Content-MD5 header in
the upload part request. Amazon S3 checks the part data against the provided MD5 value. If they do not
match, Amazon S3 returns an error.
Note
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 the multipart upload, Amazon S3 frees up the parts storage
and stops charging you for it.

For more information on multipart uploads, go to Multipart Upload Overview in the Amazon Simple
Storage Service Developer Guide .

For information on the permissions required to use the multipart upload API, go to Multipart Upload API
and Permissions in the Amazon Simple Storage Service Developer Guide.

You can optionally request server-side encryption where Amazon S3 encrypts your data as it writes it to
disks in its data centers and decrypts it for you when you access it. You have the option of providing your
own encryption key, or you can use the AWS-managed encryption keys. If you choose to provide your
own encryption key, the request headers you provide in the request must match the headers you used in
the request to initiate the upload by using Initiate Multipart Upload (p. 1420). For more information, go
to Using Server-Side Encryption in the Amazon Simple Storage Service Developer Guide.

API Version 2006-03-01

1440
Amazon Simple Storage Service API Reference
Upload Part

Syntax

PUT /ObjectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1

Host: BucketName.s3.amazonaws.com
Date: date
Content-Length: Size
Authorization: authorization string

Request Parameters

This operation does not use request parameters.

Request Headers

Name Description Required

Content-Length The size of the part, in bytes. For more information, go to http:// Yes
www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.13.

Type: Integer

Default: None

Content-MD5 The base64-encoded 128-bit MD5 digest of the part data. This No
header can be used as a message integrity check to verify that the
part data is the same data that was originally sent. Although it is
optional, we recommend using the Content-MD5 mechanism as an
end-to-end integrity check. For more information, see RFC 1864.

API Version 2006-03-01

1441
Amazon Simple Storage Service API Reference
Upload Part

Name Description Required

Type: String

Default: None

Expect When your application uses 100-continue, it does not send the No
request body until it receives an acknowledgment. If the message
is rejected based on the headers, the body of the message is not
sent. For more information, go to RFC 2616.

Type: String

Default: None

Valid Values: 100-continue

Server-Side Encryption Speciﬁc Request Headers

Server-side encryption is supported by the S3 Multipart Upload actions. Unless you are using a
customer-provided encryption key, you don't need to specify the encryption parameters in each
UploadPart request. Instead, you only need to specify the server side encryption parameters in the initial
Initiate Multipart request. For more information, see Initiate Multipart Upload (p. 1420).

Name Description Required

x-amz-server- Speciﬁes the algorithm to use to when encrypting the object. Yes
side-encryption
-customer- Type: String
algorithm
Default: None

Valid Value: AES256

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-key and x-amz-server-
side-encryption-customer-key-MD5 headers.

x-amz-server- Speciﬁes the customer-provided base64-encoded encryption Yes

side-encryption- key for Amazon S3 to use in encrypting data. This value is used
customer-key to store the object and then is discarded; Amazon does not
store the encryption key. The key must be appropriate for use
with the algorithm speciﬁed in the x-amz-server-side-
encryption-customer-algorithm header.

Type: String

Default: None

API Version 2006-03-01

1442
Amazon Simple Storage Service API Reference
Upload Part

Name Description Required

Constraints: Must be accompanied by valid x-amz-server-
side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key-MD5 headers.

x-amz-server- Speciﬁes the base64-encoded 128-bit MD5 digest of the Yes

side-encryption- encryption key according to RFC 1321. Amazon S3 uses this
customer-key-MD5 header for a message integrity check to ensure the encryption
key was transmitted without error.

Type: String

Default: None

Constraints: Must be accompanied by valid x-amz-server-

side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key headers.

Request Elements

This operation does not use request elements.

Responses

Response Headers

Name Description

x-amz- If you speciﬁed server-side encryption either with an AWS KMS or Amazon S3-
server-side- managed encryption key in your initiate multipart upload request, the response
encryption includes this header. It conﬁrms the encryption algorithm that Amazon S3 used to
encrypt the object.

Type: String

API Version 2006-03-01

1443
Amazon Simple Storage Service API Reference
Upload Part

Name Description

x-amz- If the x-amz-server-side-encryption is present and has the value of

server-side- aws:kms, this header speciﬁes the ID of the AWS Key Management Service (KMS)
encryption- master encryption key that was used for the object.
aws-kms-key-
id Type: String

x-amz- If server-side encryption with customer-provided encryption keys(SSE-C)

server-side encryption was requested, the response will include this header conﬁrming the
-encryption encryption algorithm used.
-customer-
algorithm Type: String

Valid Values: AES256

x-amz- If SSE-C encryption was requested, the response includes this header to provide
server-side roundtrip message integrity veriﬁcation of the customer-provided encryption key.
-encryption-
customer-key- Type: String
MD5

x-amz- Provides storage class information of the object. Amazon S3 returns this header
storage-class for all objects except for Standard storage class objects.

For more information, go to Storage Classes in Amazon Simple Storage Service

Developer Guide.

Type: String

Default: None

Response Elements

This operation does not use response elements.

Special Errors

Error Code Description HTTP Status SOAP Fault

PUT /ObjectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1

Host: BucketName.s3.amazonaws.com
x-amz-copy-source: /source_bucket/sourceObject
x-amz-copy-source-range:bytes=first-last
x-amz-copy-source-if-match: etag
x-amz-copy-source-if-none-match: etag
x-amz-copy-source-if-unmodified-since: time_stamp
x-amz-copy-source-if-modified-since: time_stamp
Date: date
Authorization: authorization string

Request Parameters

This operation does not use request parameters.

Request Headers

Name Description Required

x-amz-copy-source The name of the source bucket and the source object key Yes
name separated by a slash ('/').

Type: String

Default: None

x-amz-copy-source- The range of bytes to copy from the source object. The No
range range value must use the form bytes=first-last,
where the first and last are the zero-based byte offsets to
copy. For example, bytes=0-9 indicates that you want to
copy the first ten bytes of the source.

This request header is not required when copying an

entire source object.

Type: Integer

Default: None

The following conditional headers are based on the object that the x-amz-copy-source header
speciﬁes.

API Version 2006-03-01

1448
Amazon Simple Storage Service API Reference
Upload Part - Copy

Name Description Required

x-amz-copy-source-if-match Perform a copy if the source object entity tag No

(ETag) matches the speciﬁed value. If the value
does not match, Amazon S3 returns an HTTP status
code 412 precondition failed error.

See Consideration 1 after the table.

Type: String

Default: None

x-amz-copy-source-if-none- Perform a copy if the source object entity tag No

match (ETag) is diﬀerent than the value speciﬁed using
this header. If the values match, Amazon S3 returns
an HTTP status code 412 precondition failed error.

See Consideration 2 after the table.

Type: String

Default: None

x-amz-copy-source-if- Perform a copy if the source object is not modiﬁed No

unmodified-since after the time speciﬁed using this header. If the
source object is modiﬁed, Amazon S3 returns an
HTTP status code 412 precondition failed error.

See Consideration 1 after the table.

Type: String

Default: None

x-amz-copy-source-if- Perform a copy if the source object is modiﬁed No

modified-since after the time speciﬁed using this header. If the
source object is not modiﬁed, Amazon S3 returns
an HTTP status code 412 precondition failed error.

See Consideration 2 after the table.

Type: String

Default: None

Note the following additional considerations about the preceding request headers:

• Consideration 1 – 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, S3 returns 200 OK and copies the data.

API Version 2006-03-01

1449
Amazon Simple Storage Service API Reference
Upload Part - Copy

• Consideration 2 – 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;

then, S3 returns 412 Precondition Failed response code.

Server-Side Encryption Speciﬁc Request Headers

Name Description Required

x-amz-server- Speciﬁes the algorithm to use to when encrypting the object. Yes
side-encryption
-customer- Type: String
algorithm
Default: None

Valid Value: AES256

Constraints: Must be accompanied by a valid x-amz-server-

side-encryption-customer-key and x-amz-server-
side-encryption-customer-key-MD5 headers.

x-amz-server- Speciﬁes the customer provided base64-encoded encryption key Yes

side-encryption- for Amazon S3 to use in encrypting data. This must be the same
customer-key encryption key speciﬁed in the initiate multipart upload request.

Type: String

Default: None

Constraints: Must be accompanied by a valid x-amz-server-

side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key-MD5 headers.

x-amz-server- Speciﬁes the base64-encoded 128-bit MD5 digest of the Yes

side-encryption- encryption key according to RFC 1321. Amazon S3 uses this
customer-key-MD5 header as a message integrity check to ensure the encryption
key was transmitted without error.

Type: String

Default: None

Constraints: Must be accompanied by a valid x-amz-server-

side-encryption-customer-algorithm and x-amz-
server-side-encryption-customer-key headers.

API Version 2006-03-01

1450
Amazon Simple Storage Service API Reference
Upload Part - Copy

If the source object is encrypted using server-side encryption with a customer-provided encryption key,
you must use the following headers providing encryption information so that Amazon S3 can decrypt
the object for copying.

Name Description Required

x-amz-copy- Speciﬁes algorithm to use when decrypting the source object. Yes
source-server-
side-encryption Type: String
-customer-
algorithm Default: None

Valid Value: AES256

Constraints: Must be accompanied by a valid x-amz-copy-

source-server-side-encryption-customer-key and x-
amz-copy-source-server-side-encryption-customer-
key-MD5 headers.

x-amz-copy-source Speciﬁes the customer provided base-64 encoded encryption Yes

-server-side key for Amazon S3 to use to decrypt the source object. The
-encryption- encryption key provided in this header must be one that was
customer-key used when the source object was created.

Type: String

Default: None

Constraints: Must be accompanied by a valid x-amz-copy-

source-server-side-encryption-customer-algorithm
and x-amz-copy-source-server-side-encryption-
customer-key-MD5 headers.

x-amz-copy- Speciﬁes the base64-encoded 128-bit MD5 digest of the Yes

source-server- encryption key according to RFC 1321. Amazon S3 uses this
side-encryption- header for a message integrity check to ensure the encryption
customer-key-MD5 key was transmitted without error.

Type: String

Default: None

Constraints: Must be accompanied by a valid x-amz-copy-

source-server-side-encryption-customer-algorithm
and x-amz-copy-source-server-side-encryption-
customer-key headers.

Request Elements

This operation does not use request elements.

API Version 2006-03-01

1451
Amazon Simple Storage Service API Reference
Upload Part - Copy

Versioning

You can optionally specify a speciﬁc version of the source object to copy by adding the versionId
subresource as shown in the following example:

x-amz-copy-source: /bucket/object?versionId=version id

Responses

Type: String

Ancestor: CopyPartResult

LastModified Returns the date the part was last modiﬁed.

Type: String

Ancestor: CopyPartResult

Important
Part boundaries are factored into ETag calculations, so if the part boundary on the source is
diﬀerent than on the destination, then the ETag data will not match between the two. However,
data integrity checks are performed with each copy to ensure that the data written to the
destination matches the data at the source.

API Version 2006-03-01

1453
Amazon Simple Storage Service API Reference
Upload Part - Copy

Special Errors

Error Code Description HTTP Status

Code

NoSuchUpload The speciﬁed multipart upload does not exist. The upload 404 Not Found
ID might be invalid, or the multipart upload might have
been aborted or completed.

InvalidRequest The speciﬁed copy source is not supported as a byte- 400 Bad Request
range copy source.

For general information about Amazon S3 errors and a list of error codes, see Error Responses (p. 783).

Examples

As the following examples illustrate, when a request succeeds, Amazon S3 returns <CopyPartResult>
in the body. If you included versionId in the request, Amazon S3 returns the version ID in the x-amz-
copy-source-version-id response header.

Sample Request

PUT /newobject?
partNumber=2&uploadId=VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR HTTP/1.1
Host: target-bucket.s3.amazonaws.com
Date: Mon, 11 Apr 2011 20:34:56 GMT
x-amz-copy-source: /source-bucket/sourceobject
x-amz-copy-source-range:bytes=500-6291456
Authorization: authorization string

API Version 2006-03-01

1454
Amazon Simple Storage Service API Reference
Upload Part - Copy

Sample Response

The response includes the ETag value. You need to retain this value to use when you send the Complete
Multipart Upload request.

HTTP/1.1 200 OK
x-amz-id-2: Vvag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732072657175657374
Date: Mon, 11 Apr 2011 20:34:56 GMT
Server: AmazonS3

Sample Request

The following PUT request uploads a part (part number 2) in a multipart upload. The request does not
specify the optional byte range header, but requests the entire source object copy as part 2. The request
includes the upload ID that you got in response to your Initiate Multipart Upload request.

PUT /newobject?
partNumber=2&uploadId=VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR HTTP/1.1
Host: target-bucket.s3.amazonaws.com
Date: Mon, 11 Apr 2011 20:34:56 GMT
x-amz-copy-source: /source-bucket/sourceobject
Authorization: authorization string
Sample Response

The response structure is similar to the one speciﬁed in the preceding example.

Sample Request

The following PUT request uploads a part (part number 2) in a multipart upload. The request speciﬁes
a speciﬁc version of the source object to copy by adding the versionId subresource. The byte range
requests 6 MB of data, starting with byte 500, as the part to be uploaded.

PUT /newobject?
partNumber=2&uploadId=VCVsb2FkIElEIGZvciBlbZZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZR HTTP/1.1

API Version 2006-03-01

1455
Amazon Simple Storage Service API Reference
Data Types

Host: target-bucket.s3.amazonaws.com
Date: Mon, 11 Apr 2011 20:34:56 GMT
x-amz-copy-source: /source-bucket/sourceobject?versionId=3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY
+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo
x-amz-copy-source-range:bytes=500-6291456
Authorization: authorization string

Sample Response

The response includes the ETag value. You need to retain this value to use when you send the Complete
Multipart Upload request.

Related Actions

• Initiate Multipart Upload (p. 1420)

• Upload Part (p. 1440)
• Complete Multipart Upload (p. 1413)
• Abort Multipart Upload (p. 1409)
• List Parts (p. 1432)
• List Multipart Uploads (p. 1084)

Data Types
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

API Version 2006-03-01

1456
Amazon Simple Storage Service API Reference
DefaultRetention

DefaultRetention
Service: Amazon Simple Storage Service

The container element for specifying the default Object Lock retention settings for new objects placed in
the speciﬁed bucket.

Contents
Mode

The default Object Lock retention mode you want to apply to new objects placed in the speciﬁed
bucket.

Type: String

Valid Values: GOVERNANCE | COMPLIANCE

Required: Yes
Days

The number of days that you want to specify for the default retention period.

Type: Integer

Required: No
Years

The number of years that you want to specify for the default retention period.

Type: Integer

Required: No

Note
Either Days or Years must be speciﬁed, but not both.

API Version 2006-03-01

1457
Amazon Simple Storage Service API Reference
ObjectLockConﬁguration

ObjectLockConﬁguration
Service: Amazon Simple Storage Service

The container element for Object Lock conﬁguration parameters.

Contents
ObjectLockEnabled

Indicates whether this bucket has an Object Lock conﬁguration enabled.

Type: String

Valid Values: Enabled

Required: Yes
Rule

The Object Lock rule in place for the speciﬁed bucket.

Type: ObjectLockRule (p. 1461) object

Required: No

API Version 2006-03-01

1458
Amazon Simple Storage Service API Reference
ObjectLockLegalHold

ObjectLockLegalHold
Service: Amazon Simple Storage Service

A Legal Hold conﬁguration for an object.

Contents
Status

Indicates whether the speciﬁed object has a Legal Hold in place.

Type: String

Valid Values: ON | OFF

Required: Yes

API Version 2006-03-01

1459
Amazon Simple Storage Service API Reference
ObjectLockRetention

ObjectLockRetention
Service: Amazon Simple Storage Service

A Retention conﬁguration for an object.

Contents
Mode

Indicates the Retention mode for the speciﬁed object.

Type: String

Valid Values: GOVERNANCE | COMPLIANCE

Required: Yes
RetainUntilDate

Type: Timestamp

Format: 2020-01-05T00:00:00.000Z

Required: Yes

API Version 2006-03-01

1460
Amazon Simple Storage Service API Reference
ObjectLockRule

ObjectLockRule
Service: Amazon Simple Storage Service

The container element for an Object Lock rule.

Contents
DefaultRetention

The default retention period that you want to apply to new objects placed in the speciﬁed bucket.

Type: DefaultRetention (p. 1457) object

Required: No

Amazon S3 Resources
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

Following is a table that lists related resources that you'll ﬁnd useful as you work with this service.

Resource Description

Amazon Simple Storage Service The getting started guide provides a quick tutorial of the
Getting Started Guide service based on a simple use case.

Amazon Simple Storage Service The developer guide describes how to accomplish tasks using
Developer Guide Amazon S3 operations.

Amazon S3 Technical FAQ The FAQ covers the top 20 questions developers have asked
about this product.

Amazon S3 Release Notes The Release Notes give a high-level overview of the current
release. They speciﬁcally note any new features, corrections,
and known issues.

Tools for Amazon Web Services A central starting point to ﬁnd documentation, code
samples, release notes, and other information to help you
build innovative applications with AWS SDKs and tools.

AWS Management Console The console allows you to perform most of the functions of
Amazon S3 without programming.

Discussion Forums A community-based forum for developers to discuss

technical questions related to Amazon Web Services.

AWS Support Center The home page for AWS Technical Support, including access
to our Developer Forums, Technical FAQs, Service Status
page, and Premium Support.

AWS Premium Support The primary web page for information about AWS Premium
Support, a one-on-one, fast-response support channel to

API Version 2006-03-01

1461
Amazon Simple Storage Service API Reference
Document History

Resource Description
help you build and run applications on AWS Infrastructure
Services.

Amazon S3 product information The primary web page for information about Amazon S3.

Contact Us A central contact point for inquiries concerning AWS billing,

account, events, abuse, etc.

Conditions of Use Detailed information about the copyright and trademark

usage at Amazon.com and other topics.

Document History
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

The following table describes the important changes to the documentation since the last release of the
Amazon Simple Storage Service API Reference.

• API version: 2006-03-01

• Latest documentation update: March 27, 2019

Change Description Release

Date

The following APIs were updated accordingly:

• GET Bucket Inventory (p. 976)

• PUT Bucket inventory (p. 1136)

The following APIs were updated accordingly:

API Version 2006-03-01

1462
Amazon Simple Storage Service API Reference
Document History

Change Description Release

Date
• PUT Object (p. 1324)
• POST Object (p. 1295)
• PUT Object - Copy (p. 1344)
• Initiate Multipart Upload (p. 1420)

The following APIs were updated for S3 Object Lock:

• PUT Object (p. 1324)

• GET Object (p. 1248)
• HEAD Object (p. 1279)
• PUT Bucket (p. 1095)
• HEAD Bucket (p. 1064)

The following new APIs were added for S3 Object Lock:

• GET Bucket object lock conﬁguration (p. 1016)

• PUT Bucket object lock conﬁguration (p. 1186)
• GET Object retention (p. 1271)
• PUT Object retention (p. 1343)
• GET Object legal hold (p. 1270)
• PUT Object legal hold (p. 1342)

The following APIs were updated accordingly:

• PUT Object (p. 1324)

• POST Object (p. 1295)
• PUT Object - Copy (p. 1344)
• Initiate Multipart Upload (p. 1420)

API Version 2006-03-01

1463
Amazon Simple Storage Service API Reference
Document History

Change Description Release

Date

The following new APIs have been added:

• GET BucketPolicyStatus (p. 1016)

• PUT PublicAccessBlock (p. 1157) (Bucket)
• GET PublicAccessBlock (p. 995) (Bucket)
• DELETE PublicAccessBlock (p. 908) (Bucket)
• PUT PublicAccessBlock (p. 858) (Account)
• GET PublicAccessBlock (p. 854) (Account)
• DELETE PublicAccessBlock (p. 851) (Account)

The following APIs are updated accordingly:

• PUT Bucket replication (p. 1192)

• GET Bucket replication (p. 1040)
• DELETE Bucket replication (p. 919)

The following API has been updated:

• SELECT Object Content (p. 1378)

API Version 2006-03-01

1464
Amazon Simple Storage Service API Reference
Document History

Change Description Release

Date

The following API changed:

• POST Object restore (p. 1308)

The following API has been added:

• SELECT Object Content (p. 1378)

The following APIs are updated accordingly:

• GET Bucket Inventory (p. 976)

• PUT Bucket inventory (p. 1136)

The following APIs are updated accordingly:

• DELETE Bucket encryption (p. 900)

• GET Bucket encryption (p. 971)
• PUT Bucket encryption (p. 1131)

API Version 2006-03-01

1465
Amazon Simple Storage Service API Reference
Document History

Change Description Release

Date

Encryption status in Amazon S3 now supports including encryption status in November

The following APIs are updated accordingly:

• GET Bucket Inventory (p. 976)

• PUT Bucket inventory (p. 1136)

The following APIs are updated accordingly:

• GET Bucket replication (p. 1040)

• PUT Bucket replication (p. 1192)

API Version 2006-03-01

1466
Amazon Simple Storage Service API Reference
Document History

Change Description Release

Date

Object tagging support Amazon S3 now supports object tagging. The following new November
API operations support object tagging: 29, 2016

• PUT Object tagging (p. 1373)

• GET Object tagging (p. 1272)
• DELETE Object tagging (p. 1245)

In addition, other API operations are updated to support

object tagging. For more information, see Object Tagging in
the Amazon Simple Storage Service Developer Guide.

S3 lifecycle now Amazon S3 now supports tag-based ﬁltering in lifecycle November

Amazon S3 now supports Expedited and Bulk data retrievals

in addition to Standard retrievals when restoring objects
archived to S3 Glacier.

CloudWatch request Amazon S3 now supports CloudWatch metrics for requests November
metrics for buckets made on buckets. The following new API operations support 29, 2016
conﬁguring request metrics:

• DELETE Bucket metrics (p. 911)

• GET Bucket metrics (p. 1004)
• PUT Bucket metrics (p. 1170)
• List Bucket Metrics Conﬁgurations (p. 1079)

For more information, see Monitoring Metrics with Amazon

CloudWatch in the Amazon Simple Storage Service Developer
Guide.

Amazon S3 Inventory Amazon S3 now supports storage inventory. Amazon S3 November

The following new API operations are for storage inventory:

Renamed the US Changed the region name string from US Standard to US East December
Standard region (N. Virginia). This is only a region name update, there is no 11, 2015
change in the functionality.

Lifecycle conﬁguration feature updates now allow you to

transition objects to the STANDARD_IA storage class. For
more information, see Object Lifecycle Management in the
Amazon Simple Storage Service Developer Guide.

Previously, the cross-region replication feature used the

Event notifications Amazon S3 event notifications have been updated to add July 28,
notifications when objects are deleted and to add filtering on 2015
object names with prefix and suffix matching. For the relevant
API operations, see PUT Bucket notification (p. 1176), and
GET Bucket notification (p. 1010). For more information, see
Configuring Amazon S3 Event Notifications in the Amazon
Simple Storage Service Developer Guide.

Cross-region replication Amazon S3 now supports cross-region replication. Cross- March 24,
region replication is the automatic, asynchronous copying 2015
of objects across buckets in diﬀerent AWS regions. For the
relevant API operations, see PUT Bucket replication (p. 1192),
GET Bucket replication (p. 1040) and DELETE Bucket
replication (p. 919). For more information, see Enabling Cross-
Region Replication in the Amazon Simple Storage Service
Developer Guide.

API Version 2006-03-01

1470
Amazon Simple Storage Service API Reference
Document History

Change Description Release

Date

Event notifications Amazon S3 now supports new event types and November
destinations in a bucket notification configuration. 13, 2014
Prior to this release, Amazon S3 supported only the
s3:ReducedRedundancyLostObject event type and an
Amazon SNS topic as the destination. For more information
about the new event types, go to Setting Up Notification of
Bucket Events in the Amazon Simple Storage Service Developer
Guide. For the relevant API operations, see PUT Bucket
notification (p. 1176) and GET Bucket notification (p. 1010).

For more information about server-side encryption with

KMS, see Protecting Data Using Server-Side Encryption with
AWS Key Management Service in the Amazon Simple Storage
Service Developer Guide.

The following Amazon S3 REST API operations support

headers related to KMS.

• PUT Object (p. 1324)

• PUT Object - Copy (p. 1344)
• POST Object (p. 1295)
• Initiate Multipart Upload (p. 1420)
• Upload Part (p. 1440)

EU (Frankfurt) region Amazon S3 is now available in the EU (Frankfurt) region. October 23,
2014

API Version 2006-03-01

1471
Amazon Simple Storage Service API Reference
Document History

Change Description Release

Date

For more information about SSE-C, go to Server-Side

Encryption (Using Customer-Provided Encryption Keys) in the
Amazon Simple Storage Service Developer Guide.

The following Amazon S3 REST API operations support

headers related to SSE-C.

• GET Object (p. 1248)

• HEAD Object (p. 1279)
• PUT Object (p. 1324)
• PUT Object - Copy (p. 1344)
• POST Object (p. 1295)
• Initiate Multipart Upload (p. 1420)
• Upload Part (p. 1440)
• Upload Part - Copy (p. 1447)

For more information, go to Object Lifecycle Management in

the Amazon Simple Storage Service Developer Guide.

The related API operations, see PUT Bucket lifecycle (p. 1145),
GET Bucket lifecycle (p. 983), and DELETE Bucket
lifecycle (p. 906).

Amazon S3 now Amazon S3 now supports Signature Version 4 (SigV4) in January 30,
supports Signature all regions, the latest speciﬁcation for how to sign and 2014
Version 4 authenticate AWS requests.

For more information, see Authenticating Requests (AWS

Signature Version 4) (p. 792).

API Version 2006-03-01

1472
Amazon Simple Storage Service API Reference
Document History

Change Description Release

Date

Amazon S3 list The following Amazon S3 list actions now support November
actions now support encoding-type optional request parameter. 1, 2013
encoding-type
request parameter GET Bucket (List Objects) Version 1 (p. 940)

GET Bucket Object versions (p. 1021)

List Multipart Uploads (p. 1084)

List Parts (p. 1432)

An object key can contain any Unicode character; however,

For an example walkthrough, go to Example: Setting Up a

API Version 2006-03-01

1473
Amazon Simple Storage Service API Reference
Document History

Change Description Release

Date

To support data archival rules, Amazon S3 lifecycle

management API has been updated. For more information,
see PUT Bucket lifecycle (p. 1145).

After you archive objects, you must ﬁrst restore a copy before
you can access the data. Amazon S3 oﬀers a new API for you
to initiate a restore. For more information, see POST Object
restore (p. 1308).

For conceptual information, go to Object Lifecycle

Management in the Amazon Simple Storage Service Developer
Guide.

The object upload API operations PUT Object (p. 1324),

Initiate Multipart Upload (p. 1420), and POST Object (p. 1295)
allow you to conﬁgure the x-amz-website-redirect-
location object metadata.

For conceptual information, go to How to Conﬁgure Website

Page Redirects in the Amazon Simple Storage Service
Developer Guide.

API Version 2006-03-01

1474
Amazon Simple Storage Service API Reference
Document History

Change Description Release

Date

For more information about the API see, see Delete Multiple
Objects (p. 1228).

For conceptual information about the delete operation,

see Deleting Objects in the Amazon Simple Storage Service
Developer Guide.

New region supported Amazon S3 now supports the US West (Oregon) region. For November
more information, see Buckets and Regions in the Amazon 8, 2011
Simple Storage Service Developer Guide.

Multipart Upload API Prior to this release, Amazon S3 API supported copying June 21,
extended to enable objects (see PUT Object - Copy (p. 1344)) of up to 5 GB in 2011
copying objects up to 5 size. To enable copying objects larger than 5 GB, Amazon
TB S3 extends the multipart upload API with a new operation,
Upload Part (Copy). You can use this multipart upload
operation to copy objects up to 5 TB in size. For conceptual
information about multipart upload, go to Uploading Objects
Using Multipart Upload in the Amazon Simple Storage Service
Developer Guide. To learn more about the new API, see Upload
Part - Copy (p. 1447).

SOAP API calls over To increase security, SOAP API calls over HTTP are disabled. June 6,
HTTP disabled Authenticated and anonymous SOAP requests must be sent to 2011
Amazon S3 using SSL.

API Version 2006-03-01

1475
Amazon Simple Storage Service API Reference
Document History

Change Description Release

Date

• PUT Bucket website (p. 1218)

• GET Bucket website (p. 1061)
• DELETE Bucket website (p. 925)

For conceptual overview, go to Hosting Websites on Amazon

S3 in the Amazon Simple Storage Service Developer Guide.

Large Object Support Amazon S3 has increased the maximum size of an object December
you can store in an S3 bucket from 5 GB to 5 TB. If you are 9, 2010
using the REST API you can upload objects of up to 5 GB
size in a single PUT operation. For larger objects, you must
use the Multipart Upload REST API to upload objects in
parts. For conceptual information, go to Uploading Objects
Using Multipart Upload in the Amazon Simple Storage Service
Developer Guide. For multipart upload API information, see
Initiate Multipart Upload (p. 1420), Upload Part (p. 1440),
Complete Multipart Upload (p. 1413), List Parts (p. 1432), and
List Multipart Uploads (p. 1084)

Multipart upload Multipart upload enables faster, more ﬂexible uploads into November
Amazon S3. It allows you to upload a single object as a set of 10, 2010
parts. For conceptual information, go to Uploading Objects
Using Multipart Upload in the Amazon Simple Storage Service
Developer Guide. For multipart upload API information, see
Initiate Multipart Upload (p. 1420), Upload Part (p. 1440),
Complete Multipart Upload (p. 1413), List Parts (p. 1432), and
List Multipart Uploads (p. 1084)

Notifications The Amazon S3 notifications feature enables you to configure July 14,
a bucket so that Amazon S3 publishes a message to an 2010
Amazon Simple Notification Service (SNS) topic when Amazon
S3 detects a key event on a bucket. For more information,
see GET Bucket notification (p. 1010) and PUT Bucket
notification (p. 1010).

API Version 2006-03-01

1476
Amazon Simple Storage Service API Reference
Appendix

Change Description Release

Date

Reduced Redundancy Amazon S3 now enables you to reduce your storage costs by May 12,
storing objects in Amazon S3 with reduced redundancy. For 2010
more information, see PUT Object (p. 1324).

Object Versioning This release introduces object Versioning. All objects now February 8,
have a key and a version. If you enable versioning for a 2010
bucket, Amazon S3 gives all objects added to a bucket a
unique version ID. This feature enables you to recover from
unintended overwrites and deletions. For more information,
see GET Object (p. 1248), DELETE Object (p. 1239), PUT
Object (p. 1324), PUT Object Copy (p. 1344), or POST
Object (p. 1295). The SOAP API does not support versioned
objects.

Appendix
The following content is an archived version of the Amazon S3 API Reference. The archive is current
as of September 30, 2019, and will not be updated after that date. You can view the current version
of the Amazon S3 API Reference at Amazon S3 REST API Introduction (p. 1).

Topics

API Version 2006-03-01

1477
Amazon Simple Storage Service API Reference
Appendix: SOAP API

• Appendix: SOAP API (p. 1478)

• Appendix: Lifecycle Conﬁguration APIs (Deprecated) (p. 1512)

Appendix: SOAP API

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The latest Amazon S3 WSDL is available at http://doc.s3.amazonaws.com/2006-03-01/AmazonS3.wsdl.

Topics
• Operations on the Service (SOAP API) (p. 1478)
• Operations on Buckets (SOAP API) (p. 1480)
• Operations on Objects (SOAP API) (p. 1491)
• SOAP Error Responses (p. 1511)

Operations on the Service (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

This section describes operations you can perform on the Amazon S3 service.

Topics
• ListAllMyBuckets (SOAP API) (p. 1478)

ListAllMyBuckets (SOAP API)

API Version 2006-03-01

1478
Amazon Simple Storage Service API Reference
Appendix: SOAP API

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The ListAllMyBuckets operation returns a list of all buckets owned by the sender of the request.

Example

Sample Request

Sample Response

Response Body

• Owner:

This provides information that Amazon S3 uses to represent your identity for purposes of
authentication and access control. ID is a unique and permanent identiﬁer for the developer who
made the request. DisplayName is a human-readable name representing the developer who made
the request. It is not unique, and might change over time.We recommend that you match your
DisplayName to your Forum name.
• Name:

The name of a bucket. Note that if one of your buckets was recently deleted, the name of the deleted
bucket might still be present in this list for a period of time.
• CreationDate:

The time that the bucket was created.

API Version 2006-03-01

1479
Amazon Simple Storage Service API Reference
Appendix: SOAP API

Access Control

You must authenticate with a valid AWS Access Key ID. Anonymous requests are never allowed to list
buckets, and you can only list buckets for which you are the owner.

Operations on Buckets (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

This section describes operations you can perform on Amazon S3 buckets.

Topics
• CreateBucket (SOAP API) (p. 1480)
• DeleteBucket (SOAP API) (p. 1482)
• ListBucket (SOAP API) (p. 1483)
• GetBucketAccessControlPolicy (SOAP API) (p. 1486)
• SetBucketAccessControlPolicy (SOAP API) (p. 1488)
• GetBucketLoggingStatus (SOAP API) (p. 1489)
• SetBucketLoggingStatus (SOAP API) (p. 1490)

CreateBucket (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

API Version 2006-03-01

1480
Amazon Simple Storage Service API Reference
Appendix: SOAP API

indicates that someone else owns the bucket, and a Success response indicates that you own the
bucket or have permission to access it.

Example Create a bucket named "quotes"

Sample Request

Sample Response

<CreateBucketResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<CreateBucketResponse>
<Bucket>quotes</Bucket>
</CreateBucketResponse>
</CreateBucketResponse>

Elements

• Bucket: The name of the bucket you are trying to create.

• AccessControlList: The access control list for the new bucket. This element is optional. If not
provided, the bucket is created with an access policy that give the requester FULL_CONTROL access.

Access Control

You must authenticate with a valid AWS Access Key ID. Anonymous requests are never allowed to create
buckets.

Related Resources

• ListBucket (SOAP API) (p. 1483)

API Version 2006-03-01

1481
Amazon Simple Storage Service API Reference
Appendix: SOAP API

DeleteBucket (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The DeleteBucket operation deletes a bucket. All objects in the bucket must be deleted before the
bucket itself can be deleted.

Example

This example deletes the "quotes" bucket.

Sample Request

Sample Response

Elements

• Bucket: The name of the bucket you want to delete.

Access Control

Only the owner of a bucket is allowed to delete it, regardless the access control policy on the bucket.

API Version 2006-03-01

1482
Amazon Simple Storage Service API Reference
Appendix: SOAP API

ListBucket (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The ListBucket operation returns information about some of the items in the bucket.

For a general introduction to the list operation, see the Listing Object Keys.

Requests

This example lists up to 1000 keys in the "quotes" bucket that have the preﬁx "notes."

Syntax

Parameters

Name Description Required

API Version 2006-03-01

1483
Amazon Simple Storage Service API Reference
Appendix: SOAP API

Name Description Required

Type: String

Default: None

marker Indicates where in the bucket to begin listing. The list will only No
include keys that occur lexicographically after marker. This is
convenient for pagination: To get the next page of results use the
last key of the current page as the marker.

Type: String

Default: None

max-keys The maximum number of keys you'd like to see in the response No
body. The server might return fewer than this many keys, but will
not return more.

Type: String

Default: None

Type: String

Default: None

Success Response

This response assumes the bucket contains the following keys:

notes/todos.txt
notes/2005-05-23/customer_mtg_notes.txt
notes/2005-05-23/phone_notes.txt
notes/2005-05-28/sales_notes.txt

Syntax

<?xml version="1.0" encoding="UTF-8"?>

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>backups</Name>
<Prefix>notes/</Prefix>

API Version 2006-03-01

1484
Amazon Simple Storage Service API Reference
Appendix: SOAP API

<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>notes/todos.txt</Key>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
<Size>5126</Size>
<StorageClass>STANDARD</StorageClass>
<Owner>
<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
<DisplayName>webfile</DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
</Contents>
<CommonPrefixes>
<Prefix>notes/2005-05-23/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>notes/2005-05-28/</Prefix>
</CommonPrefixes>
</ListBucketResult>

As you can see, many of the ﬁelds in the response echo the request parameters. IsTruncated,
Contents, and CommonPrefixes are the only response elements that can contain new information.

Response Elements

Name Description

Contents Metadata about each object returned.

Type: XML metadata

Ancestor: ListBucketResult

CommonPrefixes A response can contain CommonPrefixes only if you specify a delimiter.

Type: String

Ancestor: ListBucketResult

Type: String

Ancestor: ListBucketResult

API Version 2006-03-01

1485
Amazon Simple Storage Service API Reference
Appendix: SOAP API

Name Description

IsTruncated Speciﬁes whether (true) or not (false) all of the results were returned. All of the
results may not be returned if the number of results exceeds that speciﬁed by
MaxKeys.

Type: String

Ancestor: boolean

Marker Indicates where in the bucket to begin listing.

Type: String

Ancestor: ListBucketResult

MaxKeys The maximum number of keys returned in the response body.

Type: String

Ancestor: ListBucketResult

Name Name of the bucket.

Type: String

Ancestor: ListBucketResult

Prefix Keys that begin with the indicated preﬁx.

Type: String

Ancestor: ListBucketResult

Response Body

For information about the list response, see Listing Keys Response.

Access Control

To list the keys of a bucket you need to have been granted READ access on the bucket.

GetBucketAccessControlPolicy (SOAP API)

API Version 2006-03-01

1486
Amazon Simple Storage Service API Reference
Appendix: SOAP API

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The GetBucketAccessControlPolicy operation fetches the access control policy for a bucket.

Example
This example retrieves the access control policy for the "quotes" bucket.

Sample Request

Sample Response

Response Body

The response contains the access control policy for the bucket. For an explanation of this response, see
SOAP Access Policy .

Access Control

API Version 2006-03-01

1487
Amazon Simple Storage Service API Reference
Appendix: SOAP API

You must have READ_ACP rights to the bucket in order to retrieve the access control policy for a bucket.

SetBucketAccessControlPolicy (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

Example

Give the speciﬁed user (usually the owner) FULL_CONTROL access to the "quotes" bucket.

Sample Request

Sample Response

Access Control

You must have WRITE_ACP rights to the bucket in order to set the access control policy for a bucket.

API Version 2006-03-01

1488
Amazon Simple Storage Service API Reference
Appendix: SOAP API

GetBucketLoggingStatus (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The GetBucketLoggingStatus retrieves the logging status for an existing bucket.

For a general introduction to this feature, see Server Logs.

Example

Sample Request

<?xml version="1.0" encoding="utf-8"?>

Sample Response

<?xml version="1.0" encoding="utf-8"?>

API Version 2006-03-01

1489
Amazon Simple Storage Service API Reference
Appendix: SOAP API

Access Control

Only the owner of a bucket is permitted to invoke this operation.

SetBucketLoggingStatus (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The SetBucketLoggingStatus operation updates the logging status for an existing bucket.

For a general introduction to this feature, see Server Logs.

Example
This sample request enables server access logging for the 'mybucket' bucket, and conﬁgures the logs to
be delivered to 'mylogs' under preﬁx 'access_log-'

Sample Request

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/
XMLSchema">
<soap:Body>
<SetBucketLoggingStatus xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>myBucket</Bucket>
<AWSAccessKeyId>YOUR_AWS_ACCESS_KEY_ID</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>YOUR_SIGNATURE_HERE</Signature>
<BucketLoggingStatus>
<LoggingEnabled>
<TargetBucket>mylogs</TargetBucket>
<TargetPrefix>mybucket-access_log-</TargetPrefix>
</LoggingEnabled>
</BucketLoggingStatus>
</SetBucketLoggingStatus>
</soap:Body>
:</soap:Envelope>

Sample Response

<?xml version="1.0" encoding="utf-8"?>

API Version 2006-03-01

1490
Amazon Simple Storage Service API Reference
Appendix: SOAP API

<soapenv:Header>
</soapenv:Header>
<soapenv:Body>
<SetBucketLoggingStatusResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01"/>
</soapenv:Body>
</soapenv:Envelope>

Access Control

Only the owner of a bucket is permitted to invoke this operation.

Operations on Objects (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

This section describes operations you can perform on Amazon S3 objects.

Topics
• PutObjectInline (SOAP API) (p. 1491)
• PutObject (SOAP API) (p. 1494)
• CopyObject (SOAP API) (p. 1496)
• GetObject (SOAP API) (p. 1502)
• GetObjectExtended (SOAP API) (p. 1507)
• DeleteObject (SOAP API) (p. 1508)
• GetObjectAccessControlPolicy (SOAP API) (p. 1509)
• SetObjectAccessControlPolicy (SOAP API) (p. 1510)

PutObjectInline (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

API Version 2006-03-01

1491
Amazon Simple Storage Service API Reference
Appendix: SOAP API

The PutObjectInline operation adds an object to a bucket. The data for the object is provided in the
body of the SOAP message.

To ensure an object is not corrupted over the network, you can calculate the MD5 of an object, PUT it to
Amazon S3, and compare the returned Etag to the calculated MD5 value.

Example

Sample Request

<PutObjectInline xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>quotes</Bucket>
<Key>Nelson</Key>
<Metadata>
<Name>Content-Type</Name>
<Value>text/plain</Value>
</Metadata>
<Metadata>
<Name>family</Name>
<Value>Muntz</Value>
</Metadata>
<Data>aGEtaGE=</Data>
<ContentLength>5</ContentLength>
<AccessControlList>
<Grant>
<Grantee xsi:type="CanonicalUser">
<ID>a9a7b886d6fde241bf9b1c61be666e9</ID>
<DisplayName>chriscustomer</DisplayName>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
<Grant>
<Grantee xsi:type="Group">
<URI>http://acs.amazonaws.com/groups/global/AllUsers</URI>
</Grantee>
<Permission>READ</Permission>
</Grant>
</AccessControlList>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</PutObjectInline>

Sample Response

API Version 2006-03-01

1492
Amazon Simple Storage Service API Reference
Appendix: SOAP API

Elements

• Bucket: The bucket in which to add the object.

• Key: The key to assign to the object.
• Metadata: You can provide name-value metadata pairs in the metadata element. These will be stored
with the object.
• Data: The base 64 encoded form of the data.
• ContentLength: The length of the data in bytes.
• AccessControlList: An Access Control List for the resource. This element is optional. If omitted,
the requester is given FULL_CONTROL access to the object. If the object already exists, the preexisting
access control policy is replaced.

Responses

• ETag: The entity tag is an MD5 hash of the object that you can use to do conditional fetches of the
object using GetObjectExtended. The ETag only reﬂects changes to the contents of an object, not
its metadata.
• LastModified: The Amazon S3 timestamp for the saved object.

Access Control

You must have WRITE access to the bucket in order to put objects into the bucket.

Related Resources

• PutObject (SOAP API) (p. 1494)

API Version 2006-03-01

1493
Amazon Simple Storage Service API Reference
Appendix: SOAP API

• CopyObject (SOAP API) (p. 1496)

PutObject (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The PutObject operation adds an object to a bucket. The data for the object is attached as a DIME
attachment.

To ensure an object is not corrupted over the network, you can calculate the MD5 of an object, PUT it to
Amazon S3, and compare the returned Etag to the calculated MD5 value.

Example

This example puts some data and metadata in the "Nelson" object of the "quotes" bucket, give a user
(usually the owner) FULL_CONTROL access to the object, and make the object readable by anonymous
parties. In this sample, the actual attachment is not shown.

Sample Request

API Version 2006-03-01

1494
Amazon Simple Storage Service API Reference
Appendix: SOAP API

</Grant>
</AccessControlList>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2007-05-11T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</PutObject>

Sample Response

Elements

• Bucket: The bucket in which to add the object.

• Key: The key to assign to the object.
• Metadata: You can provide name-value metadata pairs in the metadata element. These will be stored
with the object.
• ContentLength: The length of the data in bytes.
• AccessControlList: An Access Control List for the resource. This element is optional. If omitted,
the requester is given FULL_CONTROL access to the object. If the object already exists, the preexisting
Access Control Policy is replaced.

Responses

Access Control

To put objects into a bucket, you must have WRITE access to the bucket.

API Version 2006-03-01

1495
Amazon Simple Storage Service API Reference
Appendix: SOAP API

Related Resources

• CopyObject (SOAP API) (p. 1496)

CopyObject (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

Description

The CopyObject operation creates a copy of an object when you specify the key and bucket of a source
object and the key and bucket of a target destination.

All copy requests must be authenticated. Additionally, you must have read access to the source object
and write access to the destination bucket. For more information, see Using Auth Access.

To only copy an object under certain conditions, such as whether the Etag matches or
whether the object was modified before or after a specified date, use the request parameters
CopySourceIfUnmodifiedSince, CopyIfUnmodifiedSince, CopySourceIfMatch, or
CopySourceIfNoneMatch.
Note
You might need to configure the SOAP stack socket timeout for copying large objects.

Request Syntax

API Version 2006-03-01

1496
Amazon Simple Storage Service API Reference
Appendix: SOAP API

<SourceBucket>source_bucket</SourceBucket>
<SourceObject>source_object</SourceObject>
<DestinationBucket>destination_bucket</DestinationBucket>
<DestinationObject>destination_object</DestinationObject>
<MetadataDirective>{REPLACE | COPY}</MetadataDirective>
<Metadata>
<Name>metadata_name</Name>
<Value>metadata_value</Value>
</Metadata>
...
<AccessControlList>
<Grant>
<Grantee xsi:type="user_type">
<ID>user_id</ID>
<DisplayName>display_name</DisplayName>
</Grantee>
<Permission>permission</Permission>
</Grant>
...
</AccessControlList>
<CopySourceIfMatch>etag</CopySourceIfMatch>
<CopySourceIfNoneMatch>etag</CopySourceIfNoneMatch>
<CopySourceIfModifiedSince>date_time</CopySourceIfModifiedSince>
<CopySourceIfUnmodifiedSince>date_time</CopySourceIfUnmodifiedSince>
<AWSAccessKeyId>AWSAccessKeyId</AWSAccessKeyId>
<Timestamp>TimeStamp</Timestamp>
<Signature>Signature</Signature>
</CopyObject>

Request Parameters

Name Description Required

SourceBucket The name of the source bucket. Yes

Type: String

Default: None

Constraints: A valid source bucket.

SourceKey The key name of the source object. Yes

Type: String

Default: None

Constraints: The key for a valid source object

to which you have READ access.

DestinationBucket The name of the destination bucket. Yes

Type: String

Default: None

API Version 2006-03-01

1497
Amazon Simple Storage Service API Reference
Appendix: SOAP API

Name Description Required

Constraints: You must have WRITE access to
the destination bucket.

DestinationKey The key of the destination object. Yes

Type: String

Default: None

Constraints: You must have WRITE access to

the destination bucket.

MetadataDirective Speciﬁes whether the metadata is copied No

from the source object or replaced with
metadata provided in the request.

Type: String

Default: COPY

Valid values: COPY | REPLACE

Default: None

Constraints: None. If the Etag does not

match, the object is not copied.

API Version 2006-03-01

Response Syntax

Response Elements

Following is a list of response elements.

Note
The SOAP API does not return extra whitespace. Extra whitespace is only returned by the REST
API.

API Version 2006-03-01

1499
Amazon Simple Storage Service API Reference
Appendix: SOAP API

Name Description

Etag Returns the etag of the new object. The ETag only
reﬂects changes to the contents of an object, not its
metadata.

Type: String

Ancestor: CopyObjectResult

LastModified Returns the date the object was last modiﬁed.

Type: String

Ancestor: CopyObjectResult

For information about general response elements, see Using REST Error Response Headers.

Special Errors

There are no special errors for this operation. For information about general Amazon S3 errors, see List
of Error Codes (p. 785).

Examples

This example copies the flotsam object from the pacific bucket to the jetsam object of the
atlantic bucket, preserving its metadata.

Sample Request

API Version 2006-03-01

1500
Amazon Simple Storage Service API Reference
Appendix: SOAP API

Sample Response

This example copies the "tweedledee" object from the wonderland bucket to the "tweedledum" object of
the wonderland bucket, replacing its metadata.

Sample Request

<CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<SourceBucket>wonderland</SourceBucket>
<SourceObject>tweedledee</SourceObject>
<DestinationBucket>wonderland</DestinationBucket>
<DestinationObject>tweedledum</DestinationObject>
<MetadataDirective >REPLACE</MetadataDirective >
<Metadata>
<Name>Content-Type</Name>
<Value>text/plain</Value>
</Metadata>
<Metadata>
<Name>relationship</Name>
<Value>twins</Value>
</Metadata>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2008-02-18T13:54:10.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature>
</CopyObject>

Sample Response

API Version 2006-03-01

1501
Amazon Simple Storage Service API Reference
Appendix: SOAP API

</CopyObjectResponse>

Related Resources

• PutObject (SOAP API) (p. 1494)

• PutObjectInline (SOAP API) (p. 1491)

GetObject (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

Example

This example gets the "Nelson" object from the "quotes" bucket.

Sample Request

Sample Response

API Version 2006-03-01

1502
Amazon Simple Storage Service API Reference
Appendix: SOAP API

<Name>Content-Type</Name>
<Value>text/plain</Value>
</Metadata>
<Metadata>
<Name>family</Name>
<Value>Muntz</Value>
</Metadata>
<Data>aGEtaGE=</Data>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
</GetObjectResponse>
</GetObjectResponse>

Elements

• Bucket: The bucket from which to retrieve the object.

• Key: The key that identifies the object.
• GetMetadata: The metadata is returned with the object if this is true.
• GetData: The object data is returned if this is true.
• InlineData: If this is true, then the data is returned, base 64-encoded, as part of the SOAP body of
the response. If false, then the data is returned as a SOAP attachment. The InlineData option is not
suitable for use with large objects. The system limits this operation to working with 1MB of data or
less. A GetObject request with the InlineData flag set will fail with the InlineDataTooLargeError
status code if the resulting Data parameter would have encoded more than 1MB. To download large
objects, consider calling GetObject without setting the InlineData flag, or use the REST API instead.

Returned Elements

• Metadata: The name-value paired metadata stored with the object.

• Data: If InlineData was true in the request, this contains the base 64 encoded object data.
• LastModified: The time that the object was stored in Amazon S3.
• ETag: The object's entity tag. This is a hash of the object that can be used to do conditional gets. The
ETag only reﬂects changes to the contents of an object, not its metadata.

Access Control

You can read an object only if you have been granted READ access to the object.

API Version 2006-03-01

1503
Amazon Simple Storage Service API Reference
Appendix: SOAP API

SOAP Chunked and Resumable Downloads

To provide GET ﬂexibility, Amazon S3 supports chunked and resumable downloads.

Select from the following:

• For large object downloads, you might want to break them into smaller chunks. For more information,
see Range GETs (p. 1504)
• For GET operations that fail, you can design your application to download the remainder instead of the
entire ﬁle. For more information, see REST GET Error Recovery (p. 1507)

Range GETs

For some clients, you might want to break large downloads into smaller downloads. To break a GET into
smaller units, use Range.

Before you can break a GET into smaller units, you must determine its size. For example, the following
request gets the size of the bigﬁle object.

Amazon S3 returns the following response.

API Version 2006-03-01

1504
Amazon Simple Storage Service API Reference
Appendix: SOAP API

</ListBucketResult>

Following is a request that downloads the ﬁrst megabyte from the bigﬁle object.

Amazon S3 returns the first megabyte of the file and the Etag of the file.

<GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<GetObjectResponse>
<Status>
<Code>200</Code>
<Description>OK</Description>
</Status>
<Metadata>
<Name>Content-Type</Name>
<Value>text/plain</Value>
</Metadata>
<Metadata>
<Name>family</Name>
<Value>Muntz</Value>
</Metadata>
<Data>--first megabyte of bigfile--</Data>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
</GetObjectResponse>
</GetObjectResponse>

The following is a request that gets the remainder of the ﬁle, using the IfMatch request header.

<GetObject xmlns="http://doc.s3.amazonaws.com/2006-03-01">
<Bucket>bigbucket</Bucket>
<Key>bigfile</Key>
<GetMetadata>true</GetMetadata>
<GetData>true</GetData>
<InlineData>true</InlineData>
<ByteRangeStart>10485761</ByteRangeStart>
<ByteRangeEnd>2023276</ByteRangeEnd>
<IfMatch>"828ef3fdfa96f00ad9f27c383fc9ac7f"</IfMatch>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</GetObject>

Amazon S3 returns the following response and the remainder of the ﬁle.

API Version 2006-03-01

1505
Amazon Simple Storage Service API Reference
Appendix: SOAP API

<GetObjectResponse xmlns="http://s3.amazonaws.com/doc/2006-03-01">
<GetObjectResponse>
<Status>
<Code>200</Code>
<Description>OK</Description>
</Status>
<Metadata>
<Name>Content-Type</Name>
<Value>text/plain</Value>
</Metadata>
<Metadata>
<Name>family</Name>
<Value>>Muntz</Value>
</Metadata>
<Data>--remainder of bigfile--</Data>
<LastModified>2006-01-01T12:00:00.000Z</LastModified>
<ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag>
</GetObjectResponse>
</GetObjectResponse>

Versioned GetObject

The following request returns the speciﬁed version of the object in the bucket.

Sample Response

API Version 2006-03-01

1506
Amazon Simple Storage Service API Reference
Appendix: SOAP API

</GetObjectResponse>

REST GET Error Recovery

Related Resources

Operations on Objects (SOAP API) (p. 1491)

GetObjectExtended (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

GetObjectExtended is exactly like GetObject (SOAP API) (p. 1502), except that it supports the
following additional elements that can be used to accomplish much of the same functionality provided
by HTTP GET headers (go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).

GetObjectExtended supports the following elements in addition to those supported by GetObject:

• ByteRangeStart, ByteRangeEnd: These elements specify that only a portion of the object data
should be retrieved. They follow the behavior of the HTTP byte ranges (go to http://www.w3.org/
Protocols/rfc2616/rfc2616-sec14.html#sec14.35).
• IfModifiedSince: Return the object only if the object's timestamp is later than the specified
timestamp. (http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25)
• IfUnmodifiedSince: Return the object only if the object's timestamp is earlier than or equal to the
specified timestamp. (go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.28)
• IfMatch: Return the object only if its ETag matches the supplied tag(s). (go to http://www.w3.org/
Protocols/rfc2616/rfc2616-sec14.html#sec14.24)
• IfNoneMatch: Return the object only if its ETag does not match the supplied tag(s). (go to http://
www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26)
• ReturnCompleteObjectOnConditionFailure:ReturnCompleteObjectOnConditionFailure: If
true, then if the request includes a range element and one or both of IfUnmodifiedSince/IfMatch

API Version 2006-03-01

1507
Amazon Simple Storage Service API Reference
Appendix: SOAP API

elements, and the condition fails, return the entire object rather than a fault. This enables the If-Range
functionality (go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.27).

DeleteObject (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

Example

This example deletes the "Nelson" object from the "quotes" bucket.

Sample Request

Sample Response

Elements

• Bucket: The bucket that holds the object.

• Key: The key that identiﬁes the object.

API Version 2006-03-01

1508
Amazon Simple Storage Service API Reference
Appendix: SOAP API

Access Control

You can delete an object only if you have WRITE access to the bucket, regardless of who owns the object
or what rights are granted to it.

GetObjectAccessControlPolicy (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

The GetObjectAccessControlPolicy operation fetches the access control policy for an object.

Example

This example retrieves the access control policy for the "Nelson" object from the "quotes" bucket.

Sample Request

Sample Response

API Version 2006-03-01

1509
Amazon Simple Storage Service API Reference
Appendix: SOAP API

</Grant>
</AccessControlList>
</AccessControlPolicy>

Response Body

The response contains the access control policy for the bucket. For an explanation of this response, SOAP
Access Policy .

Access Control

You must have READ_ACP rights to the object in order to retrieve the access control policy for an object.

SetObjectAccessControlPolicy (SOAP API)

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

Example

This example gives the speciﬁed user (usually the owner) FULL_CONTROL access to the "Nelson" object
from the "quotes" bucket.

Sample Request

API Version 2006-03-01

1510
Amazon Simple Storage Service API Reference
Appendix: SOAP API

</Grant>
</AccessControlList>
<AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId>
<Timestamp>2006-03-01T12:00:00.183Z</Timestamp>
<Signature>Iuyz3d3P0aTou39dzbqaEXAMPLE=</Signature>
</SetObjectAccessControlPolicy>

Sample Response

Access Control

You must have WRITE_ACP rights to the object in order to set the access control policy for a bucket.

SOAP Error Responses

Note
SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3
features will not be supported for SOAP. We recommend that you use either the REST API or the
AWS SDKs.

For example, if you attempt to delete the object "Fred", which does not exist, the body of the SOAP
response contains a "NoSuchKey" SOAP fault.

The following example shows a sample SOAP error response.

<soapenv:Body>
<soapenv:Fault>
<Faultcode>soapenv:Client.NoSuchKey</Faultcode>
<Faultstring>The specified key does not exist.</Faultstring>
<Detail>
<Key>Fred</Key>
</Detail>
</soapenv:Fault>

API Version 2006-03-01

1511
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

</soapenv:Body>

The following table explains the SOAP error response elements

Name Description

Detail Container for the key involved in the error

Type: Container

Ancestor: Body.Fault

Fault Container for error information.

Type: Container

Ancestor: Body

Type: String

Ancestor: Body.Fault

Type: String

Ancestor: Body.Fault

Key Identiﬁes the key involved in the error

Type: String

Ancestor: Body.Fault

Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Bucket lifecycle configuration is updated to support filters based on object tags. That is, you can now
specify a rule that specifies key name prefix, one or more object tags, or both to select a subset of
objects to which the rule applies. The APIs have been updated accordingly. The following topics describes
the prior version of the PUT and GET bucket lifecycle operations for backward compatibility.

Topics
• PUT Bucket lifecycle (Deprecated) (p. 1514)

API Version 2006-03-01

1512
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

• GET Bucket lifecycle (Deprecated) (p. 1526)

API Version 2006-03-01

1513
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

PUT Bucket lifecycle (Deprecated)

Description

Important
For an updated version of this API, see PUT Bucket lifecycle (p. 1145). This version has been
deprecated. Existing lifecycle conﬁgurations will work. For new lifecycle conﬁgurations, use the
updated API.

Permissions

• s3:DeleteObject
• s3:DeleteObjectVersion
• s3:PutLifecycleConfiguration

For more information about permissions, see Managing Access Permissions to Your Amazon S3 Resources
in the Amazon Simple Storage Service Developer Guide.

Requests

API Version 2006-03-01

1514
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Syntax

PUT /?lifecycle HTTP/1.1

Host: bucketname.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string
Content-MD5: MD5

Lifecycle configuration in the request body

For details about authorization strings, see Authenticating Requests (AWS Signature Version 4) (p. 792).

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Name Description Required

Content-MD5 The base64-encoded 128-bit MD5 digest of the Yes

data. You must use this header as a message
integrity check to verify that the request body was
not corrupted in transit. For more information, see
RFC 1864.

Type: String

Default: None

Request Body

API Version 2006-03-01

1515
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

In the request, you specify the lifecycle configuration in the request body. The lifecycle configuration
is specified as XML. The following is an example of a basic lifecycle configuration. It specifies one rule.
The Prefix in the rule identifies objects to which the rule applies. The rule also specifies two actions
(Transitionand Expiration). Each action specifies a timeline when Amazon S3 should perform the
action. The Status indicates whether the rule is enabled or disabled.

API Version 2006-03-01

1516
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

</LifecycleConfiguration>

The following table describes the XML elements in the lifecycle conﬁguration.

Name Description Required

Container for specifying when an incomplete

AbortIncompleteMultipartUpload Yes, if no
multipart upload becomes eligible for an abort other action
operation. is speciﬁed
for the rule
Child: DaysAfterInitiation

Type: Container

Ancestor: Rule

Date Date when you want Amazon S3 to take the Yes, if

action. For more information, see Lifecycle Rules: Days and
Based on a Speciﬁc Date in the Amazon Simple ExpiredObjectDeleteMa
Storage Service Developer Guide. are absent

The date value must conform to ISO 8601

format. The time is always midnight UTC.

Type: String

Ancestor: Expiration or Transition

Days Speciﬁes the number of days after object creation Yes, if

when the speciﬁc rule action takes eﬀect. Date and
ExpiredObjectDeleteMa
Type: Nonnegative Integer when used with are absent
Transition, Positive Integer when used with
Expiration

Ancestor: Expiration, Transition

DaysAfterInitiation Speciﬁes the number of days after initiating a Yes, if a

Type: Positive Integer

Ancestor: AbortIncompleteMultipartUpload

Expiration This action speciﬁes a period in an object's Yes, if no

lifetime when Amazon S3 should take the other action
appropriate expiration action. The action Amazon is present in
S3 takes depends on whether the bucket is the Rule.
versioning-enabled.

• If versioning has never been enabled on the

bucket, Amazon S3 deletes the only copy of the
object permanently.
• If the bucket is versioning-enabled (or
versioning is suspended), the action applies

API Version 2006-03-01

1517
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Name Description Required

only to the current version of the object. A
versioning-enabled bucket can have many
versions of the same object: one current version
and zero or more noncurrent versions.

Instead of deleting the current version, Amazon

Type: Container

Children: Days or Date

Ancestor: Rule

ID Unique identiﬁer for the rule. The value cannot No

be longer than 255 characters.

Type: String

Ancestor: Rule

LifecycleConfiguration Container for lifecycle rules. You can add as many Yes
as 1000 rules.

Type: Container

Children: Rule

Ancestor: None

API Version 2006-03-01

1518
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Name Description Required

ExpiredObjectDeleteMarker On a versioned bucket (a versioning-enabled Yes, if Date

Type: String

Valid values: true | false (the value false is

allowed, but it is no-op, which means that
Amazon S3 will not take action)

Ancestor: Expiration

NoncurrentDays Speciﬁes the number of days an object is Yes

Type: Nonnegative Integer when used

with NoncurrentVersionTransition,
Positive Integer when used with
NoncurrentVersionExpiration

Ancestor: NoncurrentVersionExpiration or
NoncurrentVersionTransition

NoncurrentVersionExpiration Speciﬁes when noncurrent object versions expire. Yes, if no

Type: Container

Children: NoncurrentDays

Ancestor: Rule

API Version 2006-03-01

1519
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Name Description Required

NoncurrentVersionTransition Container for the transition rule that describes Yes, if no

when noncurrent objects transition to the other action
STANDARD_IA, ONEZONE_IA, or GLACIER storage is present in
class. the Rule

If your bucket is versioning-enabled (or if

versioning is suspended), you can set this action
to tell Amazon S3 to transition noncurrent
object versions at a speciﬁc period in the object's
lifetime.

Type: Container

Children: NoncurrentDays and StorageClass

Ancestor: Rule

Prefix Object key preﬁx that identiﬁes one or more Yes

objects to which the rule applies.

Type: String

Ancestor: Rule

Rule Container for a lifecycle rule. A lifecycle Yes

conﬁguration can contain as many as 1000 rules.

Type: Container

Ancestor:LifecycleConﬁguration

Status If enabled, Amazon S3 executes the rule as Yes

scheduled. If it is disabled, Amazon S3 ignores the
rule.

Type: String

Ancestor: Rule

Valid values: Enabled, Disabled

StorageClass Speciﬁes the Amazon S3 storage class to which Yes

API Version 2006-03-01

1520
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Name Description Required

Transition This action speciﬁes a period in the objects' Yes, if no

• If versioning has never been enabled on the

Type: Container

Children: Days or Date, and StorageClass

Ancestor: Rule

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

API Version 2006-03-01

1521
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about
Amazon S3 errors and a list of error codes, see Error Responses (p. 685).

Examples

Example 1: Add Lifecycle Conﬁguration to a Bucket That Is Not Versioning-enabled

The following lifecycle conﬁguration speciﬁes two rules, each with one action.

The following is a sample PUT /?lifecycle request that adds the preceding lifecycle conﬁguration to
the examplebucket bucket.

API Version 2006-03-01

1522
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

PUT /?lifecycle HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Wed, 14 May 2014 02:11:21 GMT
Content-MD5: q6yJDlIkcBaGGfb3QLY69A==
Authorization: authorization string
Content-Length: 415

The following is a sample response.

HTTP/1.1 200 OK
x-amz-id-2: r+qR7+nhXtJDDIJ0JJYcd+1j5nM/rUFiiiZ/fNbDOsd3JUE8NWMLNHXmvPfwMpdc
x-amz-request-id: 9E26D08072A8EF9E
Date: Wed, 14 May 2014 02:11:22 GMT
Content-Length: 0
Server: AmazonS3

Example 2: Add Lifecycle Conﬁguration to a Versioning-enabled Bucket

• The NoncurrentVersionExpiration action tells Amazon S3 to expire noncurrent versions of

<LifeCycleConfiguration>
<Rule>
<ID>DeleteAfterBecomingNonCurrent</ID>
<Prefix>logs/</Prefix>
<Status>Enabled</Status>
<NoncurrentVersionExpiration>
<NoncurrentDays>100</NoncurrentDays>

API Version 2006-03-01

1523
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

</NoncurrentVersionExpiration>
</Rule>
<Rule>
<ID>TransitionAfterBecomingNonCurrent</ID>
<Prefix>documents/</Prefix>
<Status>Enabled</Status>
<NoncurrentVersionTransition>
<NoncurrentDays>30</NoncurrentDays>
<StorageClass>GLACIER</StorageClass>
</NoncurrentVersionTransition>
</Rule>
</LifeCycleConfiguration>

The following is a sample PUT /?lifecycle request that adds the preceding lifecycle conﬁguration to
the examplebucket bucket.

PUT /?lifecycle HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Wed, 14 May 2014 02:21:48 GMT
Content-MD5: 96rxH9mDqVNKkaZDddgnw==
Authorization: authorization string
Content-Length: 598

<LifeCycleConfiguration>
<Rule>
<ID>DeleteAfterBecomingNonCurrent</ID>
<Prefix>logs/</Prefix>
<Status>Enabled</Status>
<NoncurrentVersionExpiration>
<NoncurrentDays>1</NoncurrentDays>
</NoncurrentVersionExpiration>
</Rule>
<Rule>
<ID>TransitionSoonAfterBecomingNonCurrent</ID>
<Prefix>documents/</Prefix>
<Status>Enabled</Status>
<NoncurrentVersionTransition>
<NoncurrentDays>0</NoncurrentDays>
<StorageClass>GLACIER</StorageClass>
</NoncurrentVersionTransition>
</Rule>
</LifeCycleConfiguration>

The following is a sample response.

Additional Examples

For more examples of transitioning objects to storage classes such as STANDARD_IA or ONEZONE_IA, see
Examples of Lifecycle Conﬁguration.

API Version 2006-03-01

1524
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Related Resources

• GET Bucket lifecycle (p. 983)

• POST Object restore (p. 1308)
• By default, a resource owner—in this case, a bucket owner, which is the AWS account that created the
bucket—can perform any of the operations. A resource owner can also grant others permission to
perform the operation. For more information, see the following topics in the Amazon Simple Storage
Service Developer Guide:
• Specifying Permissions in a Policy
• Managing Access Permissions to Your Amazon S3 Resources

API Version 2006-03-01

1525
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

GET Bucket lifecycle (Deprecated)

Description

Important
For an updated version of this API, see GET Bucket lifecycle (p. 983). If you conﬁgured a bucket
lifecycle using the <ﬁlter> element, you should see an updated version of this topic. This topic is
provided for backward compatibility.

To use this operation, you must have permission to perform the s3:GetLifecycleConfiguration
action. The bucket owner has this permission by default. The bucket owner can grant this permission to
others. For more information about permissions, see Managing Access Permissions to Your Amazon S3
Resources in the Amazon Simple Storage Service Developer Guide.

Requests

Syntax

GET /?lifecycle HTTP/1.1

Host: bucketname.s3.amazonaws.com
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
4))

Request Parameters

API Version 2006-03-01

1526
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

This implementation of the operation does not use request parameters.

Request Headers

This implementation of the operation uses only request headers that are common to all operations. For
more information, see Common Request Headers (p. 681).

Request Elements

This implementation of the operation does not use request elements.

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses.
For more information, see Common Response Headers (p. 683).

Response Elements

This implementation of GET returns the following response elements.

Name Description Required

Container for specifying when an incomplete

AbortIncompleteMultipartUpload Yes, if no
multipart upload becomes eligible for an abort other action
operation. is speciﬁed
for the rule
Child: DaysAfterInitiation

API Version 2006-03-01

1527
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Name Description Required

Type: Container

Ancestor: Rule

Date Date when you want Amazon S3 to take the Yes, if

action. For more information, see Lifecycle Rules: Days and
Based on a Speciﬁc Date in the Amazon Simple ExpiredObjectDeleteMa
Storage Service Developer Guide. are absent

The date value must conform to the ISO 8601

format. The time is always midnight UTC.

Type: String

Ancestor: Expiration or Transition

Days Speciﬁes the number of days after object creation Yes, if

Type: Non-negative Integer when used with

Transition, Positive Integer when used with
Expiration.

Ancestor: Transition or Expiration

DaysAfterInitiation Speciﬁes the number of days after initiating a Yes, if Date

Type: Positive Integer

Ancestor: AbortIncompleteMultipartUpload

API Version 2006-03-01

1528
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Name Description Required

Expiration This action speciﬁes a period in the object's Yes, if the

• If versioning has never been enabled on the

Instead of deleting the current version, Amazon

Type: Container

Children: Days or Date

Ancestor: Rule

ID Unique identiﬁer for the rule. The value cannot No

be longer than 255 characters.

Type: String

Ancestor: Rule

API Version 2006-03-01

1529
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Name Description Required

LifecycleConfiguration Container for lifecycle rules. You can add as many Yes
as 1000 rules.

Type: Container

Children: Rule

Ancestor: None

ExpiredObjectDeleteMarker On a versioned bucket (versioning-enabled or Yes, if Date

Type: String

Valid values: true | false (the value false is

allowed but it is no-op, Amazon S3 doesn't take
action if the value is false)

Ancestor: Expiration

NoncurrentDays Speciﬁes the number of days that an object Yes, only if

Type: Nonnegative Integer when used

with NoncurrentVersionTransition,
Positive Integer when used with
NoncurrentVersionExpiration

Ancestor: NoncurrentVersionExpiration or
NoncurrentVersionTransition

NoncurrentVersionExpiration Speciﬁes when noncurrent object versions expire. Yes, if no

Upon expiration, Amazon S3 permanently deletes other action
the noncurrent object versions. is present in
the Rule
Set this lifecycle conﬁguration action on a bucket
that has versioning enabled (or suspended)
to request that Amazon S3 delete noncurrent
object versions at a speciﬁc period in the object's
lifetime.

Type: Container

Children: NoncurrentDays

Ancestor: Rule

API Version 2006-03-01

1530
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Name Description Required

NoncurrentVersionTransition Container for the transition rule that describes Yes, if no

when noncurrent objects transition to the other action
STANDARD_IA, ONEZONE_IA, or the GLACIER is present in
storage class. the Rule

If your bucket is versioning-enabled (or

versioning is suspended), you can set this action
to request Amazon S3 to transition noncurrent
object versions to the GLACIER storage class at a
speciﬁc period in the object's lifetime.

Type: Container

Children: NoncurrentDays and StorageClass

Ancestor: Rule

Prefix Object key preﬁx identifying one or more objects Yes

to which the rule applies.

Type: String

Ancestor: Rule

Rule Container for a lifecycle rule. Yes

Type: Container

Ancestor: LifecycleConﬁguration

Status If Enabled, Amazon S3 executes the rule as Yes

scheduled. If Disabled, Amazon S3 ignores the
rule.

Type: String

Ancestor: Rule

Valid values: Enabled or Disabled

StorageClass Speciﬁes the Amazon S3 storage class to which Yes

you want to transition the object.

Type: String

Ancestor: Transition and

NoncurrentVersionTransition

Valid values: STANDARD_IA | ONEZONE_IA |

GLACIER

API Version 2006-03-01

1531
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Name Description Required

Transition This action speciﬁes a period in the objects' Yes, if no

• If versioning has never been enabled on the

Type: Container

Children: Days or Date, and StorageClass

Ancestor: Rule

Special Errors

Error Code Description HTTP Status SOAP Fault

Code Code Preﬁx

The lifecycle conﬁguration does not

NoSuchLifecycleConfiguration 404 Not Client
exist. Found

For general information about Amazon S3 errors and a list of error codes, see Error Responses (p. 783).

Examples

API Version 2006-03-01

1532
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Example 1: Retrieve a Lifecycle Subresource

This example is a GET request to retrieve the lifecycle subresource from the speciﬁed bucket, and an
example response with the returned lifecycle conﬁguration.

Sample Request

GET /?lifecycle HTTP/1.1

Host: examplebucket.s3.amazonaws.com
x-amz-date: Thu, 15 Nov 2012 00:17:21 GMT
Authorization: signatureValue

Sample Response

<?xml version="1.0" encoding="UTF-8"?>

API Version 2006-03-01

1533
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Related Resources

• PUT Bucket lifecycle (p. 1145)

• DELETE Bucket lifecycle (p. 906)

Glossary

100-continue A method that enables a client to see if a server can accept a request
before actually sending it. For large PUTs, this can save both time and
bandwidth charges.

account AWS account associated with a particular developer.

authentication The process of proving your identity to the system.

bucket A container for objects stored in Amazon S3. Every object is

contained within a bucket. For example, if the object named photos/
puppy.jpg is stored in the johnsmith bucket, then it is addressable
using the URL http://johnsmith.s3.amazonaws.com/photos/
puppy.jpg

canonicalization The process of converting data into a standard format that will be
recognized by a service such as Amazon S3.

consistency model The method through which Amazon S3 achieves high availability,
which involves replicating data across multiple servers within
Amazon's data centers. After a "success" is returned, your data is
safely stored. However, information about the changes might not
immediately replicate across Amazon S3.

key The unique identiﬁer for an object within a bucket. Every object in a
bucket has exactly one key. Since a bucket and key together uniquely
identify each object, Amazon S3 can be thought of as a basic data
map between "bucket + key" and the object itself. Every object in

API Version 2006-03-01

1534
Amazon Simple Storage Service API Reference
Appendix: Lifecycle Conﬁguration APIs (Deprecated)

Amazon S3 can be uniquely addressed through the combination

of the web service endpoint, bucket name, and key, as in http://
doc.s3.amazonaws.com/2006-03-01/AmazonS3.wsdl, where "doc" is
the name of the bucket, and "2006-03-01/AmazonS3.wsdl" is the key.

metadata The metadata is a set of name-value pairs that describe the object.
These include default metadata such as the date last modiﬁed and
standard HTTP metadata such as Content-Type. The developer can
also specify custom metadata at the time the Object is stored.

object The fundamental entities stored in Amazon S3. Objects consist of

object data and metadata. The data portion is opaque to Amazon S3.

part The fundamental entities stored in Amazon S3. Objects consist of

object data and metadata. The data portion is opaque to Amazon S3.

service endpoint The host and port with which you are trying to communicate
within the destination URL. For virtual hosted-style requests, this
is mybucket.s3.amazonaws.com. For path-style requests, this is
s3.amazonaws.com

API Version 2006-03-01

1535

American - Family and Friends Grade.3 Lesson - Plans PDF
100% (1)
American - Family and Friends Grade.3 Lesson - Plans PDF
363 pages
Lecture - Developing Storage Solutions With Amazon S3
No ratings yet
Lecture - Developing Storage Solutions With Amazon S3
37 pages
s3 Api
No ratings yet
s3 Api
798 pages
Amazon Simple Storage Service: Developer Guide API Version 2006-03-01
No ratings yet
Amazon Simple Storage Service: Developer Guide API Version 2006-03-01
924 pages
Amazon Aws
No ratings yet
Amazon Aws
665 pages
AWS s3 DG
No ratings yet
AWS s3 DG
749 pages
s3 1 DG
No ratings yet
s3 1 DG
633 pages
Introduction To Amazon s3
No ratings yet
Introduction To Amazon s3
32 pages
Amazon Simple Storage Service: User Guide API Version 2006-03-01
No ratings yet
Amazon Simple Storage Service: User Guide API Version 2006-03-01
1,069 pages
s3 Userguide
No ratings yet
s3 Userguide
1,167 pages
Amazon S3 (API Version 2006-03-01)
100% (1)
Amazon S3 (API Version 2006-03-01)
171 pages
s3 Userguide
No ratings yet
s3 Userguide
1,104 pages
s3 DG 20060301
100% (4)
s3 DG 20060301
100 pages
Amazon Simple Storage Service: API Reference API Version 2006-03-01
No ratings yet
Amazon Simple Storage Service: API Reference API Version 2006-03-01
243 pages
00 03 Chapter Three Amazon Simple Storage Service (S3)
No ratings yet
00 03 Chapter Three Amazon Simple Storage Service (S3)
22 pages
AWS S3 - Integration - of - SFG
No ratings yet
AWS S3 - Integration - of - SFG
8 pages
1.amazon Web Services-Basics
No ratings yet
1.amazon Web Services-Basics
81 pages
Building Amazon s3 Client Apex4 208629
No ratings yet
Building Amazon s3 Client Apex4 208629
25 pages
Aws S3
No ratings yet
Aws S3
16 pages
AWS S3 - Properties
No ratings yet
AWS S3 - Properties
16 pages
Cloud API: What Is AWS?
No ratings yet
Cloud API: What Is AWS?
7 pages
Storage in AWS
No ratings yet
Storage in AWS
42 pages
Cc Unit 4 Lecturer Ppt
No ratings yet
Cc Unit 4 Lecturer Ppt
62 pages
Amazon_S3_Technical_Deep_Dive
No ratings yet
Amazon_S3_Technical_Deep_Dive
30 pages
Amazon's AWS S3 Java API 2.0 (Using Spring Boot As Client) - CodeProject
No ratings yet
Amazon's AWS S3 Java API 2.0 (Using Spring Boot As Client) - CodeProject
60 pages
Module-6-Cloud Storage
No ratings yet
Module-6-Cloud Storage
26 pages
VND - Ms Powerpoint&Rendition 1
No ratings yet
VND - Ms Powerpoint&Rendition 1
26 pages
Amazon Simple Storage Service (Amazon S3)
No ratings yet
Amazon Simple Storage Service (Amazon S3)
4 pages
Certified Developer Slides 1462373421
50% (2)
Certified Developer Slides 1462373421
170 pages
Aws - S3
No ratings yet
Aws - S3
10 pages
Module 6 - Simple Storage Service(S3)
No ratings yet
Module 6 - Simple Storage Service(S3)
48 pages
digitalcloud.training-Amazon S3 and Glacier
No ratings yet
digitalcloud.training-Amazon S3 and Glacier
18 pages
Amazon Simple Storage Service AWS
No ratings yet
Amazon Simple Storage Service AWS
1,614 pages
HyperStoreAWS APIs v 8.1
No ratings yet
HyperStoreAWS APIs v 8.1
142 pages
ACAv3 EN M04 AddingAStorageLayerWithAmazonS3 Instructor Deck
No ratings yet
ACAv3 EN M04 AddingAStorageLayerWithAmazonS3 Instructor Deck
76 pages
S3 and Glacier64
No ratings yet
S3 and Glacier64
29 pages
AWS S3 Quizet
No ratings yet
AWS S3 Quizet
51 pages
DevOps - Module 2 Notes
No ratings yet
DevOps - Module 2 Notes
49 pages
Aws s3 Guide
No ratings yet
Aws s3 Guide
4 pages
Amazon Simple Storage Service
No ratings yet
Amazon Simple Storage Service
7 pages
Aws S3
No ratings yet
Aws S3
11 pages
What Is S3 V1
No ratings yet
What Is S3 V1
11 pages
Using Amazon S3
No ratings yet
Using Amazon S3
6 pages
Amazon S3 Notes
No ratings yet
Amazon S3 Notes
10 pages
AWS S3 Bootcamp
100% (1)
AWS S3 Bootcamp
48 pages
AWS Free Tier
No ratings yet
AWS Free Tier
105 pages
Case Study: Amazon AWS: CSE 40822 - Cloud Compu0ng Prof. Douglas Thain University of Notre Dame
No ratings yet
Case Study: Amazon AWS: CSE 40822 - Cloud Compu0ng Prof. Douglas Thain University of Notre Dame
34 pages
Amazon S3: Prepared by
No ratings yet
Amazon S3: Prepared by
42 pages
Aws S3
No ratings yet
Aws S3
22 pages
AWS S3 Configuration Steps
No ratings yet
AWS S3 Configuration Steps
5 pages
Amazon AWS: Functional Specification
No ratings yet
Amazon AWS: Functional Specification
8 pages
Aws Lab Manual
No ratings yet
Aws Lab Manual
44 pages
Amazon S3: An Storage Service
No ratings yet
Amazon S3: An Storage Service
14 pages
Case Study: Amazon AWS: CSE 40822 - Cloud Computing Prof. Douglas Thain University of Notre Dame
No ratings yet
Case Study: Amazon AWS: CSE 40822 - Cloud Computing Prof. Douglas Thain University of Notre Dame
33 pages
Case Study: Amazon AWS: CSE 40822 - Cloud Computing Prof. Douglas Thain University of Notre Dame
No ratings yet
Case Study: Amazon AWS: CSE 40822 - Cloud Computing Prof. Douglas Thain University of Notre Dame
33 pages
Storage
No ratings yet
Storage
7 pages
AWS Academy Resource - Content Resources
No ratings yet
AWS Academy Resource - Content Resources
7 pages
Azure For Starters
From Everand
Azure For Starters
Chinmoy Mukherjee
No ratings yet
10K Blueprint
From Everand
10K Blueprint
Cian O Farrell
5/5 (2)
Blog Smarter, Not Harder: SEO, Blogging, and AI Strategies to Skyrocket Your Traffic
From Everand
Blog Smarter, Not Harder: SEO, Blogging, and AI Strategies to Skyrocket Your Traffic
Jay Nans
No ratings yet
Cloud Computing : Beginners And Intermediate User Guide
From Everand
Cloud Computing : Beginners And Intermediate User Guide
David comer
No ratings yet
Politeness: Towers and Mr. Bean, Are British
No ratings yet
Politeness: Towers and Mr. Bean, Are British
2 pages
Research Manuscript
No ratings yet
Research Manuscript
131 pages
VANDANA KOTTHALA_Bench_Sales
No ratings yet
VANDANA KOTTHALA_Bench_Sales
3 pages
Quiz 1
No ratings yet
Quiz 1
2 pages
How To Write A Research Proposal
0% (1)
How To Write A Research Proposal
4 pages
DLP For Demonstration
No ratings yet
DLP For Demonstration
9 pages
CH 4 - Semantic Analysis PDF
100% (1)
CH 4 - Semantic Analysis PDF
36 pages
Feelings and Gestures
No ratings yet
Feelings and Gestures
5 pages
Selenium Automation Lab Programs 3-8 (6 Programs)
No ratings yet
Selenium Automation Lab Programs 3-8 (6 Programs)
12 pages
5.5 - Little Red Riding Hood - Story
No ratings yet
5.5 - Little Red Riding Hood - Story
4 pages
Intersectional Risographics - Lesson Plan-Compressed
No ratings yet
Intersectional Risographics - Lesson Plan-Compressed
14 pages
Bow English 10 - 24 25
No ratings yet
Bow English 10 - 24 25
15 pages
Check Your English Vocabulary For TOEIC
No ratings yet
Check Your English Vocabulary For TOEIC
83 pages
Ishtla Singh - Language, Thought and Representation
No ratings yet
Ishtla Singh - Language, Thought and Representation
5 pages
SA818 Programming Manual
No ratings yet
SA818 Programming Manual
32 pages
AI Tools 7.17
No ratings yet
AI Tools 7.17
38 pages
8th Shaaban - HASSAN UL HIND
No ratings yet
8th Shaaban - HASSAN UL HIND
19 pages
Introduction To NS2: - Network Simulator
No ratings yet
Introduction To NS2: - Network Simulator
54 pages
DeveloperReference 3
No ratings yet
DeveloperReference 3
100 pages
Corrected Copy of CALENDAR FOR 2024-2025 Academic Year
No ratings yet
Corrected Copy of CALENDAR FOR 2024-2025 Academic Year
14 pages
A Triumph of Surgery-NBW
No ratings yet
A Triumph of Surgery-NBW
2 pages
Ace It with Quotes Essential Exam Quotes for Class 10 English
No ratings yet
Ace It with Quotes Essential Exam Quotes for Class 10 English
10 pages
Introduction To Operating System
No ratings yet
Introduction To Operating System
59 pages
Essay On Gabriel Marcel's Existential Fulcrum, Primary and Secondary Reflection
No ratings yet
Essay On Gabriel Marcel's Existential Fulcrum, Primary and Secondary Reflection
3 pages
AP Assessment Test Syllabus for Techno Final
No ratings yet
AP Assessment Test Syllabus for Techno Final
2 pages
What Is DNS - How DNS Works - Cloudflare
No ratings yet
What Is DNS - How DNS Works - Cloudflare
11 pages
Agam DSA Project
No ratings yet
Agam DSA Project
24 pages
Grammar Lesson 2 280918
No ratings yet
Grammar Lesson 2 280918
2 pages
All Document Reader 1712320385842
No ratings yet
All Document Reader 1712320385842
2 pages