Initiate a resumable upload
Initiates aresumable upload with aPOST request. This initial requestgenerates a session URI for use in subsequentPUT requests whichupload the data. The initial request also allows you to specify metadatafor the object. Once a resumable upload completes, the uploaded object replacesany existing object with the same name.
For simple uploads with the XML API, you make aPUT Object requestinstead of usingPOST Object.
Query string parameters
This request does not typically include query string parameters.
Seesigned URL query string parameters for information on the parametersyou include when creating and usingsigned URLs.
Request headers
The following request headers can be used.
| Header | Description | Required |
|---|---|---|
Authorization | The authentication string for the request. | Yes |
Cache-Control | The 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-Disposition | A header that specifies presentational information about how the object data is to be transmitted. | No |
Content-Encoding | The compression algorithm that was used to compress the object you are uploading. | No |
Content-Language | The 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-Type | The MIME type of the object to be uploaded. If you do not specify a content type, Cloud Storage defaults toapplication/octet-stream when it serves the object. | No (recommended) |
Date | The date and time of the request. | Yes |
Host | The URI for Cloud Storage. For more information, seeRequest Endpoints. | Yes |
x-goog-acl | The predefined ACL that you want to apply to the object. | No |
x-goog-custom-time | A user-specified date and time. | No |
x-goog-encryption-kms-key-name | Thecustomer-managed encryption key to use to encrypt the object. | No |
x-goog-if-generation-match | If 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-match | If 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 ifx-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 storecustom metadata. | No |
x-goog-object-lock-mode | Mode of the object'sretention configuration. If this header is specified, | No |
| A date and time represented inRFC 3339 UTC format that determines the time until which the object is retained as immutable. If this header is specified, | No |
x-goog-resumable | Indicates that this request initiates the resumable upload. This header must use the valuestart | Yes |
x-goog-storage-class | Gives an object a storage class besides the default storage class of the associated bucket. | No |
x-goog-user-project | The 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, usetheheaders listed on the Customer-Supplied Encryption Key page in yourrequest.
Request body elements
This request does not include an XML document in the request body.
Response headers
The response includes aLocation header that indicates thesession 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 namedtravel-maps.
Request
POST /paris.jpg HTTP/2Host: travel-maps.storage.googleapis.comDate: Thu, 10 Dec 2020 18:11:50 GMTContent-Type: image/jpgContent-Length: 0X-Goog-Resumable: startAuthorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
Response
HTTP/2 201Content-Type: text/plain; charset=utf-8X-Guploader-Uploadid: ABf5-UxjuGIOxcy0OpOLoAHbmo5rYKWx3XfrZFTjowNwPT9JYiopVZW2gPFrusVKO5kaSZ7fNrDWkb9sT_lKxOssUTELocation: https://storage.googleapis.com/travel-maps/paris.jpg?upload_id=ABf5-UxjuGIOxcy0OpOLoAHbmo5rYKWx3XfrZFTjowNwPT9JYiopVZW2gPFrusVKO5kaSZ7fNrDWkb9sT_lKxOssUTEContent-Length: 0Date: Thu, 10 Dec 2020 18:11:53 GMTServer: UploadServer
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-17 UTC.