Amazon Simple Storage Service
API Reference (API Version 2006-03-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

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 will be 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 prior to 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 (e.g., 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.

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 option of providing your own encryption key or you can use the AWS-managed encryption keys. For more information, go to Using Server-Side Encryption in the Amazon Simple Storage Service Developer Guide.

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="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 fields.

NameDescriptionRequired
AWSAccessKeyId

The AWS access key ID of the owner of the bucket who grants an Anonymous user access for a request that satisfies the set of constraints in the policy.

Type: String

Default: None

Constraints: Required if a policy document is included with the request.

Conditional

acl

Specifies an Amazon S3 access control list. If an invalid access control list is specified, 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 | authenticated-read | bucket-owner-read | bucket-owner-full-control

No

Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires

REST-specific headers. For more information, see PUT Object.

Type: String

Default: None

No

file

File or text content.

The file or text content must be the last field in the form.

You cannot upload more than one file at a time.

Type: File or text content

Default: None

Yes

key

The name of the uploaded key.

To use the file name provided by the user, use the ${filename} variable. For example, if the user Betty uploads the file lolcatz.jpg and you specify /user/betty/${filename}, the key name will be /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

Yes

policy

Security Policy describing what is permitted in the request. Requests without a security policy are considered anonymous and only work 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.

Conditional

success_action_redirect, redirect

The URL to which the client is redirected upon successful upload.

If success_action_redirect is not specified, Amazon S3 returns the empty document type specified in the success_action_status field.

If Amazon S3 cannot interpret the URL, it acts as if the field 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 field name is deprecated and support for the redirect field name will be removed in the future.

No

success_action_status

The status code returned to the client upon successful upload if success_action_redirect is not specified.

Accepts the values 200, 201, or 204 (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.

No

x-amz-storage-class

Storage class to use for storing the object.

Type: String

Default: STANDARD

Valid Values: STANDARD | REDUCED_REDUNDANCY

Constraints: You cannot specify GLACIER as the storage class. To transition objects to the GLACIER storage class you can use lifecycle configuration.

No

x-amz-meta-*

Field names prefixed with x-amz-meta- contain user-specified metadata.

Amazon S3 does not validate or use this data.

For more information, see PUT Object.

Type: String

Default: None

No

x-amz-security-token

Amazon DevPay security token.

Each request that uses Amazon DevPay requires two x-amz-security-token form fields: one for the product token and one for the user token.

For more information, go to Using DevPay.

Type: String

Default: None

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, go to 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, go to sections 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 K.

No

Server-Side Encryption Specific Request Form Fields

You can optionally request Amazon S3 to encrypt data at rest using server-side encryption. Server-side encryption is about data encryption at rest, that is, Amazon S3 encrypts your data as it writes it to disks in its data centers and decrypts it for you when you access it. Depending on whether you want to use AWS-managed encryption keys or provide your own encryption keys, you use the following form fields:

  • Use AWS-managed encryption keys — If you want Amazon S3 to manage keys used to encrypt data, you specify the following form fields in the request.

    Name Description Required
    x-amz-server-side​-encryption

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

    Type: String

    Valid Value: AES256

    Yes
  • Use customer-provided encryption keys — If you want to manage your own encryption keys, you must provide all the following form fields in the request.

    Note

    If you use this feature, the ETag value that Amazon S3 returns in the response will not be 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 fields.

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

    Specifies the customer provided base-64 encoded encryption key for Amazon S3 to use in encrypting data. This value is used 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 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 fields.

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

    Yes

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

Amazon S3 will return this header if an Expiration action is configured for the object as part of the bucket's lifecycle configuration.  The header value includes an "expiry-date" component and a URL encoded "rule-id" component.  Note that for version-enabled buckets, this header only applies 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.

Type: String

success_action_redirect, redirect

The URL to which the client is redirected on successful upload.

Type: String

Ancestor: PostResponse

x-amz-server-side-encryption

If you request server-side encryption when adding an object, the response includes this header confirming the encryption algorithm used.

Type: String

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

If server-side encryption with customer-provided encryption keys (SSE-C) encryption was requested, the response will include this header confirming the encryption algorithm used.

Type: String

Valid Values: AES256

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

If SSE-C encryption was requested, the response includes this header to provide round trip message integrity verification of the customer provided encryption key.

Type: String

x-amz-version-id

Version of the object.

Type: String

Response Elements

Name Description
Bucket

Name of the bucket the object was stored in.

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. The ETag reflects changes to only 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

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

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 shows 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

Notice in this response the version ID is null.

Sample Response with Versioning Enabled

The following shows 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