Amazon Simple Storage Service
API Reference (API Version 2006-03-01)
AWS services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon AWS.

PUT Object

Description

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.

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

To configure 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.

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 in the Amazon Simple Storage Service Developer Guide.

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.

Access Permissions

When uploading an object, you can optionally specify the accounts or groups that should be granted specific permissions on your object. There are two ways to grant the appropriate permissions using the request headers:

  • Specify a canned (predefined) 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

PUT /ObjectName HTTP/1.1 Host: BucketName.s3.amazonaws.com.cn 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

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.

Name Description Required
Cache-Control

Can be used to specify caching behavior along the request/reply chain. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9.

Type: String

Default: None

Constraints: None

No
Content-Disposition

Specifies presentational information for the object. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1.

Type: String

Default: None

Constraints: None

No
Content-Encoding

Specifies 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 field. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11.

Type: String

Default: None

Constraints: None

No
Content-Length

The size of the object, in bytes. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.13.

Type: String

Default: None

Constraints: None

Yes
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, see REST Authentication in the Amazon Simple Storage Service Developer Guide.

Type: String

Default: None

Constraints: None

No
Content-Type

A standard MIME type describing the format of the contents. For 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

No
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.

Type: String

Default: None

Valid Values: 100-continue

Constraints: None

No
Expires

The date and time at which the object is no longer able to be cached. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21.

Type: String

Default: None

Constraints: None

No

x-amz-meta-

Headers starting with this prefix are user-defined metadata. Within the PUT request header, the user-defined metadata is limited to 2 KB in size. User-defined metadata is a set of key-value pairs. The size of user-defined metadata is the sum of the number of bytes in the UTF-8 encoding of each key and value. Amazon S3 doesn't validate or interpret user-defined metadata.

Type: String

Default: None

Constraints: None

No
x-amz-storage-class

If you don't specify, Standard is the default 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 | STANDARD_IA | ONEZONE_IA | INTELLIGENT_TIERING | GLACIER | REDUCED_REDUNDANCY

No
x-amz-tagging

Specifies a set of one or more tags to associate with the object. 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.

No
x-amz-website​-redirect-location

If the bucket is configured 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. 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 Configure Website Page Redirects in the Amazon Simple Storage Service Developer Guide.

Type: String

Default: None

Constraints: The value must be prefixed by, "/", "http://" or "https://". The length of the value is limited to 2 KB.

No
x-amz-object-lock-mode The Object Lock mode, if any, that should be applied to this 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

No
x-amz-object-lock-retain-until-date The date and time when the Object Lock retention period will expire.

Type: Timestamp

Default: None

Format: 2020-01-05T00:00:00.000Z

Required if x-amz-object-lock-mode is specified
x-amz-object-lock-legal-hold Specifies whether a legal hold will be applied to this object. 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

No

Access-Control-List-(ACL)-Specific Request Headers

Additionally, you can use the following access control–related headers with this operation. By default, all objects are private: only the owner has full control. When adding a new object, you can grant permissions to individual AWS accounts or predefined Amazon S3 groups. These permissions are then used to create the Access Control List (ACL) on the object. For more information, see Using ACLs.

To grant these permissions, you can use one of the following methods:

  • Specify a canned 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, go to Canned ACL.

    Name Description Required
    x-amz-acl

    The canned ACL to apply to the object. For more information, see Canned ACL 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

    Constraints: None

    No
  • Specify access permissions explicitly — To explicitly grant access permissions to specific AWS accounts or a group, use the following headers. Each maps to specific permissions that Amazon S3 supports in an ACL. For more information, see 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-read

    Grants permission to read the object data and its metadata.

    Type: String

    Default: None

    Constraints: None

    No
    x-amz-grant-write

    Not applicable. This header applies only when granting permission on a bucket.

    Type: String

    Default: None

    Constraints: None

    No
    x-amz-grant-read-acp

    Grants permission to read the object ACL.

    Type: String

    Default: None

    Constraints: None

    No
    x-amz-grant-write-acp

    Grants permission to write the ACL for the applicable object.

    Type: String

    Default: None

    Constraints: None

    No
    x-amz-grant-full-control

    Grants READ, READ_ACP, and WRITE_ACP permissions on the object.

    Type: String

    Default: None

    Constraints: None

    No

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

  • emailAddress – if the specified 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)

    • 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 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 identified by their email addresses.

x-amz-grant-read: emailAddress="xyz@amazon.com", emailAddress="abc@amazon.com"

Server-Side-Encryption-Specific 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​-encryption

    Specifies the server-side encryption algorithm to use when Amazon S3 creates an object.

    Type: String

    Valid Value: aws:kms, AES256

    Yes
    x-amz-server-side-encryption-aws-kms-key-id

    If the x-amz-server-side-encryption is present and has the value of aws:kms, this header specifies the ID of the AWS Key Management Service (AWS KMS) master encryption key that was used for the object.

    Type: String

    Yes, if the value of x-amz-server-side-encryption is aws:kms
    x-amz-server-side-encryption-context

    If the x-amz-server-side-encryption header is present, and if its value is aws:kms, this header specifies the 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

    No

    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.

    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.

  • 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-side​-encryption​-customer-algorithm

    Specifies the algorithm to use to when encrypting the object.

    Type: String

    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.

    Yes
    x-amz-server-side​-encryption​-customer-key

    Specifies the customer-provided base64-encoded encryption key that Amazon S3 should use to encrypt data. Amazon 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 specified 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.

    Yes
    x-amz-server-side​-encryption​-customer-key-MD5

    Specifies the base64-encoded 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.

    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.

    Yes

    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

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.

Name Description
x-amz-expiration

If the expiration is configured for the object (see PUT Bucket lifecycle), 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-server-side​-encryption

If you specified server-side encryption either with an AWS KMS-managed or Amazon S3-managed encryption key in your PUT request, the response includes this header. It confirms the encryption algorithm that Amazon S3 used to encrypt the object.

Type: String

x-amz-server-side-encryption-aws-kms-key-id

If the x-amz-server-side-encryption is present and has the value of aws:kms, this header specifies the ID of the AWS KMS master encryption key that was used for the object.

Type: String

x-amz-server-side​-encryption​-customer-algorithm

If server-side encryption with customer-provided encryption keys encryption was requested, the response includes this header that confirms the encryption algorithm that was used.

Type: String

Valid Values: AES256

x-amz-server-side​-encryption​-customer-key-MD5

If server-side encryption using customer-provided encryption keys was requested, the response returns this header to verify the roundtrip message integrity of the customer-provided encryption key.

Type: String

x-amz-version-id

Version of the object.

Type: String

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.

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.cn 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 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 ETag: "1b2cf535f27731c974343645a3985328" Content-Length: 0 Connection: close Server: AmazonS3

If an expiration rule that was created on the bucket using lifecycle configuration 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

The following request stores the image, my-image.jpg, in the myBucket bucket. The request specifies 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.amazonaws.com.cn 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 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 ETag: "1b2cf535f27731c974343645a3985328" Content-Length: 0 Connection: close Server: AmazonS3

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.cn 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="ExampleUser@amazon.com" x-amz-grant-write: emailAddress="ExampleUser1@amazon.com", emailAddress="ExampleUser2@amazon.com" 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: 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: Upload an Object (Specify Access Permission Using Canned ACL)

Sample Request: Using a Canned ACL to Set Access Permissions

The following request stores the TestObject.txt file 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.amazonaws.com.cn 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.amazonaws.com.cn 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 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 specified 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 specifies the optional x-amz-tagging header to add tags to the object.

PUT /example-object HTTP/1.1 Host: example-bucket.s3.amazonaws.com.cn Accept: */* Authorization:authorization string Date: Thu, 22 Sep 2016 21:58:13 GMT x-amz-tagging: tag1=value1&tag2=value2 [... bytes of object data]

After the object is created, Amazon S3 stores the specified object tags in the tagging subresource that is associated with the object.

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