POST Object

Uploads objects by using HTML forms. For tips on uploading to Cloud Storage, see best practices.

Unless you need to use HTML forms (usually through a web browser) to upload objects, we strongly recommend using PUT object instead of POST.

Note: The POST object method does not support signed URLs, except in the case of resumable uploads.

For information about POST Object requests using the legacy signing process, see POST Object with the V2 signing process.

Query string parameters

This request does not include query string parameters.

Form fields

Field	Description	Required
acl	The predefined ACL that you want to apply to the object that is being uploaded. If you do not specify this field the bucket's default ACL is applied.	No
bucket	The name of the bucket that you want to upload to. Alternatively, you can include the bucket name in the key field or in the URI (for example, storage.googleapis.com/<bucket>).	No
Cache-Control	The cache control for the object. You can only set cache control for an object that is accessible to all users. For instance, an object's ACL must be public-read or public-read-write to be able to set the cache-control.	No
Content-Disposition	Specifies how the object data should be transmitted. For example, a Content-Disposition value of inline means that the object should be displayed immediately.	No
Content-Encoding	The compression algorithm for the object, such as gzip.	No
Content-Length	The size of the uploaded file, in bytes.	No
Content-Type	The MIME type of the file you are uploading via the form. If you do not specify a content type, the Cloud Storage system defaults to application/octet-stream when it serves the content.	No
Expires	An ISO8601 timestamp that specifies the date and time before an object is considered stale by the browser.	No
file	The file you are uploading. Must be the last field in the form. You can upload only one object per request.	Yes
key	The name of the object that you are uploading. If you specify the object name without the bucket name, you must append the bucket name to the URI (for example, storage.googleapis.com/<bucket>). If you specify the bucket name and object name (for example, bucket/object), you must specify only the URI (for example, storage.googleapis.com). You can also use the ${filename} variable if a user is providing a file name. Also, if you are using a bucket name that is a CNAME redirect, be sure that the bucket name is specified only once in your request.	Yes
policy	The security policy that describes what can and cannot be uploaded in the form. The policy document must be Base64 encoded. See policy documents for more information. *If you do not provide a security policy, requests are considered to be anonymous and will only work with buckets that have granted WRITE or FULL_CONTROL permission to anonymous users.	No*
success_action_redirect	A URL that users are redirected to when an upload is successful. If you do not provide a URL, Cloud Storage responds with the status code that you specified in success_action_status.	No
success_action_status	The status code that you want Cloud Storage to respond with when an upload is successful. The default is 204, but you can change this to 200 or 201. If you choose 200 or 204, Cloud Storage returns an empty document with those status codes. If you choose 201, Cloud Storage returns an XML document with the elements that are described in Response Body Elements. Note: The Adobe Flash player might not handle responses with an empty document body. You should use status code 201 if this is the case.	No
x-goog-algorithm	The signing algorithm used to create the signature associated with your policy document. Possible values are ??	Only if you specify a policy
x-goog-credential	The credentials used to create the signature associated with your policy document. x-goog-credential has the form AccessKeyId/CredentialScope, where: AccessKeyId is the email address of the entity responsible for creating the signature. This entity is typically a service account, but may also be a user account. CredentialScope is the credential scope used in the signature.	Only if you specify a policy
x-goog-date	The current date, in the format YYYYMMDD.	Only if you specify a policy
x-goog-signature	The signature associated with your policy document.	Only if you specify a policy
x-goog-meta-*	A field for custom metadata. You can use this to specify any additional metadata that is not provided by the other form fields. For example, x-goog-meta-reviewer: jane or x-goog-meta-project-manager: john is custom metadata.	No

Response body elements

The following response body elements are returned in an XML document only if you set success_action_redirect to 201.

Element	Description
Bucket	Bucket in which the object was stored.
ETag	HTTP 1.1 entity tag for the object.
Key	The object's name.
Location	The URI for the object.

Usage and examples

The form must be UTF-8 encoded. You can specify form encoding in the form's HTML head tag or by using the Content-Type request header.

Your form tag must specify the following three items:

• An action.

  The action attribute specifies the bucket that you want the form to upload an object to.

• A method.

  The method attribute specifies the method that you are using to submit the form. It must be post.

• An enclosure type.

  The enctype attribute specifies the enclosure type you are using and must always be multipart/form-data.

The following is an example HTML using a policy document:

<form action="http://travel-maps.storage.googleapis.com" method="post" enctype="multipart/form-data">
<input type="text" name="key" value="">
<input type="hidden" name="bucket" value="travel-maps">
<input type="hidden" name="Content-Type" value="image/jpeg">
<input type="hidden" name="GoogleAccessId" value="[e-mail]">
<input type="hidden" name="acl" value="bucket-owner-read">
<input type="hidden" name="success_action_redirect" value="http://www.example.com/success_notification.html">
<input type="hidden" name="policy" value="eyJleHBpcmF0aW9uIjogIjIwMTAtMDYtMTZUMTE6MTE6MTFaIiwNCiAiY29uZGl0aW9ucyI6IFsNCiAgWyJzdGFydHMtd2l0aCIsICJrZXkiLCAiIiBdLA0KICB7ImFjbCI6ICJidWNrZXQtb3duZXItcmVhZCIgfSwNCiAgeyJidWNrZXQiOiAidHJhdmVsLW1hcHMifSwNCiAgeyJzdWNjZXNzX2FjdGlvbl9yZWRpcmVjdCI6ICJodHRwOi8vd3d3LmV4YW1wbGUuY29tL3N1Y2Nlc3Nfbm90aWZpY2F0aW9uLmh0bWwiIH0sDQogIFsiZXEiLCAiQ29udGVudC1UeXBlIiwgImltYWdlL2pwZWciIF0sDQogIFsiY29udGVudC1sZW5ndGgtcmFuZ2UiLCAwLCAxMDAwMDAwXQ0KICBdDQp9">
<input type="hidden" name="signature" value="BSAMPLEaASAMPLE6SAMPLE+SAMPPLEqSAMPLEPSAMPLE+SAMPLEgSAMPLEzCPlgWREeF7oPGowkeKk7J4WApzkzxERdOQmAdrvshKSzUHg8Jqp1lw9tbiJfE2ExdOOIoJVmGLoDeAGnfzCd4fTsWcLbal9sFpqXsQI8IQi1493mw=">

<input name="file" type="file">
<input type="submit" value="Upload">
</form>

As a best practice you should use the Expect: 100-continue header with POST requests. This allows you to verify that the server will handle the request before you send the object. If you receive a status code 100 Continue you should proceed with the request. If you receive a status code 417 Expectation Failed then you should not send the object.