POST Object

The POST request operation adds an object to a bucket using forms.

	Note
	For information about forms and constructing requests using `POST`, see Browser-Based Uploads Using POST.

The response indicates that the object is successfully stored. Amazon S3 never stores partial objects: if you receive a successful response, the entire object was stored.

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.

If you specify a location constraint when creating a bucket, all objects added to the bucket are stored in the bucket's location. For example, if you specify a Europe (EU) location constraint for a bucket, all of that bucket's objects are stored in Europe. For more information on location constraints, see Location Selection.

Example

This request assumes that the image uploaded is 117,108 bytes; the image data is not included.

POST / HTTP/1.1
Host: johnsmith.s3.amazonaws.com
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.10) Gecko/20071115 Firefox/2.0.0.10
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive: 300
Connection: keep-alive
Content-Type: multipart/form-data; boundary=---------------------------9431149156168
Content-Length: 2661134

-----------------------------9431149156168
Content-Disposition: form-data; name="key"

user/eric/MyPicture.jpg
-----------------------------9431149156168
Content-Disposition: form-data; name="acl"

public-read
-----------------------------9431149156168
Content-Disposition: form-data; name="success_action_redirect"

http://johnsmith.s3.amazonaws.com/successful_upload.html
-----------------------------9431149156168
Content-Disposition: form-data; name="Content-Type"

image/jpeg
-----------------------------9431149156168
Content-Disposition: form-data; name="x-amz-meta-uuid"

14365123651274
-----------------------------9431149156168
Content-Disposition: form-data; name="x-amz-meta-tag"

Some,Tag,For,Picture
-----------------------------9431149156168
Content-Disposition: form-data; name="AWSAccessKeyId"

15B4D3461F177624206A
-----------------------------9431149156168
Content-Disposition: form-data; name="Policy"

eyAiZXhwaXJhdGlvbiI6ICIyMDA3LTEyLTAxVDEyOjAwOjAwLjAwMFoiLAogICJjb25kaXRpb25zIjogWwogICAgeyJidWNrZXQiOiAiam9obnNtaXRoIn0sCiAgICBbInN0YXJ0cy13aXRoIiwgIiRrZXkiLCAidXNlci9lcmljLyJdLAogICAgeyJhY2wiOiAicHVibGljLXJlYWQifSwKICAgIHsic3VjY2Vzc19hY3Rpb25fcmVkaXJlY3QiOiAiaHR0cDovL2pvaG5zbWl0aC5zMy5hbWF6b25hd3MuY29tL3N1Y2Nlc3NmdWxfdXBsb2FkLmh0bWwifSwKICAgIFsic3RhcnRzLXdpdGgiLCAiJENvbnRlbnQtVHlwZSIsICJpbWFnZS8iXSwKICAgIHsieC1hbXotbWV0YS11dWlkIjogIjE0MzY1MTIzNjUxMjc0In0sCiAgICBbInN0YXJ0cy13aXRoIiwgIiR4LWFtei1tZXRhLXRhZyIsICIiXQogIF0KfQo=
-----------------------------9431149156168
Content-Disposition: form-data; name="Signature"

0RavWzkygo6QX9caELEqKi9kDbU=
-----------------------------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--

Sample Response

HTTP/1.1 303 Redirect
x-amz-request-id: 1AEE782442F35865
x-amz-id-2: cxzFLJRatFHy+NGtaDFRR8YvI9BHmgLxjvJzNiGGICARZ/mVXHj7T+qQKhdpzHFh
Content-Type: application/xml
Date: Wed, 14 Nov 2007 21:21:33 GMT
Connection: close
Location: http://johnsmith.s3.amazonaws.com/successful_upload.html?bucket=johnsmith&key=user/eric/MyPicture.jpg&etag=&quot;39d459dfbc0faabbb5e179358dfb94c3&quot;
Server: AmazonS3

Request Headers

Content-Type: This must be set to multipart/form-data. For more information, go to RFC 1867.

Form Data

Following is a table that describes form data parts.

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 (\) will be used (e.g., "C:\Program Files\directory1\file.txt" will be interpreted as "file.txt"). If no file or filename is provided, the variable is replaced with an empty string.

Element Name Description Required?

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. This is required if a policy document is included with the request.

Conditional

acl

Specifies an Amazon S3 access control list. Options include private, public-read, public-read-write, authenticated-read.

The default setting is private.

If an invalid access control list is specified, an error is generated.

For more information on ACLs, see Access Control Lists.

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

REST-specific headers.

For more information, see PUT Object.

key

The name of the uploaded key.

To use the filename provided by the user, use the ${filename} variable. For example, if the user Betty uploads the file the file lolcatz.jpg and you specify /user/betty/${filename}, the file will be stored as /user/betty/lolcatz.jpg.

For more information, see Keys.

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, see Policy Construction

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.

For more information, see Redirection.

	Note
	The redirect field name is deprecated and support for the redirect field name will be removed in the future.

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. For information on the content of the XML document, see POST Response Body.

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.

	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-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, see Using Amazon DevPay with Amazon S3.

Other field names prefixed with x-amz-meta-

User-specified metadata.

Amazon S3 does not validate or use this data.

For more information, see PUT Object.

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.

Yes

POST Response Body

If success_action_status is set to 200, 204, or is not specified, the response body will be empty. If success_action_status is set to 201, Amazon S3 returns a PostResponse XML document which contains the location of the object, the bucket in which it is stored, the key associated with the object, and its Etag.

Following is a sample PostResponse XML document.

<PostResponse>
    <Location>http://johnsmith.s3.amazonaws.com/user/eric/MyPicture.jpg</Location>
    <Bucket>johnsmith</Bucket>
    <Key>user/eric/MyPicture.jpg</Key>
    <ETag>"39d459dfbc0faabbb5e179358dfb94c3"</ETag>
</PostResponse>

Request Body

The multipart form data. For more information, go to RFC 1867.

Response Headers

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.

success_action_redirect, redirect: The URL to which the client is redirected on successful upload.

Access Control

The signer of the policy must have WRITE access to the bucket to add an object. If there is no policy, Anonymous must have write access to the bucket. This is not recommended.