Upload an object using HTML forms
A POST 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
through HTTP Headers are instead passed as form fields to POST in the
multipart/form-data encoded message body. All objects are limited to 10TB in size. This operation
does not make use of operation specific query parameters. If versioning is enabled on the bucket,
objects will be versioned up to 1,000 times per object in vault mode only.
Container mode does not have a limit on how many versions you can have per object.
Syntax
POST https://{endpoint}/{bucket-name}/{object-name} # path style
POST https://{bucket-name}.{endpoint}/{object-name} # virtual host style
Form fields
| 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. Type: String Default: None |
Yes, if a policy document is included with the request |
acl |
Specifies an access control list. If an invalid access control list is specified, an error is generated. Type: String Default: Read Valid Values: |
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 Jerry uploads the file Type: String Default: None |
Yes |
policy |
Security Policy describing what is permitted in the request. Requests without a security policy are considered anonymous and work only on anonymously writable buckets. Type: String Default: None |
Yes, if the bucket is not publicly writable |
success_action_status |
The status code returned to the client upon successful upload if
Accepts the values 200, 201, or 204 (default). If the value is set to 200 or 204, the API returns an empty document with a 200 or 204 status code. If the value is set to 201, the API returns an XML document with a 201 status code. If the value is not set or if it is set to an invalid value, the API 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 |
No |
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. The API doesn't validate or interpret user-defined metadata. For more information, see PUT Object. Type: String Default: None |
No |
| x-amz-object-lock-mode |
The object lock mode to be applied to the uploaded object.
Note: Objects uploaded to an Object
Lock enabled bucket with a default configuration rule OR uploaded with Object Lock specific headers
require a Content-MD5 header (or use of V4 signature with content signing) or with a x-am-checksum-
header included as a confirmation of request payload integrity.
|
Required if RetainUntilDate header is used; otherwise, no. |
| x-amz-object-lock-retain-until-date |
The date and time when the uploaded object’s Object Lock is to expire.
Note: Objects uploaded to an Object
Lock enabled bucket with a default configuration rule OR uploaded with Object Lock specific headers
require a Content-MD5 header (or use of V4 signature with content signing) or with a x-am-checksum-
header included as a confirmation of request payload integrity.
|
Required if Mode header is used; otherwise, no. |
| x-amz-object-lock-legal-hold |
The Legal Hold state to be applied to the object.
Note: Objects uploaded to an Object
Lock enabled bucket with a default configuration rule OR uploaded with Object Lock specific headers
require a Content-MD5 header (or use of V4 signature with content signing) or with a x-am-checksum-
header included as a confirmation of request payload integrity.
|
No |
Specific headers for SSE-C
Common SSE-C headers are available for buckets using Server Side Encryption with Customer-Provided Keys (SSE-C) enabled.
Other headers
Upload an object with tagging by adding the x-amz-tagging header to an object upload request. For more information, see: Other headers.
Sample request
POST /example-bucket HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20160825T183001Z
x-amz-content-sha256: 309721641329cf441f3fa16ef996cf24a2505f91be3e752ac9411688e3435429
x-amz-tagging: tag1=value1&tag2=value2
Content-Type: text/plain; charset=utf-8
Host: 67.228.254.193
Content-Type: multipart/form-data; boundary=---------------------------2393619733680
Content-Length: 639
-----------------------------2393619733680
Content-Disposition: form-data; name="key"
uploads/${filename}
-----------------------------2393619733680
Content-Disposition: form-data; name="Content-Type"
text/plain
-----------------------------2393619733680
Content-Disposition: form-data; name="file"; filename="queen-bee.txt"
Content-Type: text/plain
The 'queen' bee is developed from larvae selected by worker bees and fed a
substance referred to as 'royal jelly'. After a short while the 'queen' is
the mother of nearly every bee in the hive, and the colony will fight
fiercely to protect her.
-----------------------------2393619733680--
Sample response
HTTP/1.1 204 No Content
Date: Thu, 25 Aug 2016 18:30:02 GMT
X-Clv-Request-Id: 9f0ca49a-ae13-4d2d-925b-117b157cf5c3
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.121
X-Clv-S3-Version: 2.5
x-amz-request-id: 9f0ca49a-ae13-4d2d-925b-117b157cf5c3
ETag: "3ca744fa96cb95e92081708887f63de5"
Content-Length: 0