Initiate a resumable upload

Initiates a resumable upload with a POST request. This initial request generates a session URI for use in subsequent PUT requests which upload the data. The initial request also allows you to specify metadata for the object. Once a resumable upload completes, the uploaded object replaces any existing object with the same name.

For simple uploads with the XML API, you make a PUT Object request instead of using POST Object.

Query string parameters

This request does not typically include query string parameters.

See signed URL query string parameters for information on the parameters you include when creating and using signed URLs.

Request headers

The following request headers can be used.

HeaderDescriptionRequired
AuthorizationThe authentication string for the request.Yes
Cache-ControlThe conditions under which a publicly accessible object should be cached. Cache-Control is also used to determine whether an object can be transformed.No
Content-DispositionA header that specifies presentational information about how the object data is to be transmitted.No
Content-EncodingThe compression algorithm that was used to compress the object you are uploading.No
Content-LanguageThe language code of the content.No
Content-Length

The length of the request body without headers (in bytes). For initiating a resumable upload, this value is 0.

Yes
Content-TypeThe MIME type of the object to be uploaded. If you do not specify a content type, Cloud Storage defaults to application/octet-stream when it serves the object.No (recommended)
DateThe date and time of the request.Yes
HostThe URI for Cloud Storage. For more information, see Request Endpoints.Yes
x-goog-aclThe predefined ACL that you want to apply to the object.No
x-goog-custom-timeA user-specified date and time.No
x-goog-encryption-kms-key-nameThe customer-managed encryption key to use to encrypt the object.No
x-goog-if-generation-matchIf the generation you specify is the same as the object you're replacing, then the object is replaced. You can also specify 0 as a special value to indicate that the new object is only created if there is no existing object.No
x-goog-if-metageneration-matchIf the metageneration you specify is the same as the object you're trying to update, then the object metadata is updated. This is only allowed if x-goog-if-generation is specified. By combining these two generation properties, you can implement safe read-modify-write updates.No
x-goog-meta-An extension header that can be used to store custom metadata.No
x-goog-object-lock-mode

Mode of the object's retention configuration. GOVERNANCE corresponds to unlocked mode, and COMPLIANCE corresponds to locked mode.

If this header is specified, x-goog-object-lock-retain-until-date must also be specified.

No
x-goog-object-lock-retain-until-date

A date and time represented in RFC 3339 UTC format that determines the time until which the object is retained as immutable.

If this header is specified, x-goog-object-lock-mode must also be specified.

No
x-goog-resumableIndicates that this request initiates the resumable upload. This header must use the value startYes
x-goog-storage-classGives an object a storage class besides the default storage class of the associated bucket.No
x-goog-user-projectThe project to be billed for charges associated with the request. Note that the project specified in the initial request is used in all future requests associated with the resumable upload.No

To provide a customer-supplied encryption key along with the object upload, use the headers listed on the Customer-Supplied Encryption Key page in your request.

Request body elements

This request does not include an XML document in the request body.

Response headers

The response includes a Location header that indicates the session URI to use when uploading the object data.

Response body elements

The response does not include an XML document in the response body.

Example

The following sample uploads an object named paris.jpg to a bucket named travel-maps.

Request

POST /paris.jpg HTTP/2
Host: travel-maps.storage.googleapis.com
Date: Thu, 10 Dec 2020 18:11:50 GMT
Content-Type: image/jpg
Content-Length: 0
X-Goog-Resumable: start
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Response

HTTP/2 201
Content-Type: text/plain; charset=utf-8
X-Guploader-Uploadid: ABf5-UxjuGIOxcy0OpOLoAHbmo5rYKWx3XfrZFTjowNwPT9JYiopVZW2gPFrusVKO5kaSZ7fNrDWkb9sT_lKxOssUTE
Location: https://storage.googleapis.com/travel-maps/paris.jpg?upload_id=ABf5-UxjuGIOxcy0OpOLoAHbmo5rYKWx3XfrZFTjowNwPT9JYiopVZW2gPFrusVKO5kaSZ7fNrDWkb9sT_lKxOssUTE
Content-Length: 0
Date: Thu, 10 Dec 2020 18:11:53 GMT
Server: UploadServer