Initiates a [XML API multipart upload](https://docs.cloud.google.com/storage/docs/multipart-uploads.md.txt) with a `POST` request. This initial request generates an upload ID for use in subsequent `PUT` requests to [upload the data in parts](https://docs.cloud.google.com/storage/docs/xml-api/put-object-multipart.md.txt) and in the final `POST` request to [complete the upload](https://docs.cloud.google.com/storage/docs/xml-api/post-object-complete.md.txt). There is no limit to the number of multipart uploads that can be underway for a given object. This initial request allows you to specify metadata for the completed object. Once a multipart upload completes, the uploaded object replaces any existing object with the same name. For tips on uploading to Cloud Storage, see [best practices](https://docs.cloud.google.com/storage/docs/best-practices.md.txt#uploading). For simple uploads with the XML API, you make a [`PUT` Object](https://docs.cloud.google.com/storage/docs/xml-api/put-object-upload.md.txt) request instead of using `POST` Object. ## Query string parameters | Parameter | Description | Required | |---|---|---| | `uploads` | Indicates the request is to initiate a multipart upload. | Yes | See [signed URL query string parameters](https://docs.cloud.google.com/storage/docs/authentication/canonical-requests.md.txt#required-query-parameters) for information on the parameters you include when creating and using [signed URLs](https://docs.cloud.google.com/storage/docs/access-control/signed-urls.md.txt). ## 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 the resulting object should be cached if it is publicly accessible. `Cache-Control` is also used to determine whether the resulting object can be transformed. | No | | `Content-Disposition` | A header that specifies presentational information about how the resulting object data is to be transmitted. | No | | `Content-Encoding` | The compression algorithm that was used to compress the data 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 multipart upload, this value is 0. | Yes | | `Content-Type` | The MIME type of the data you are uploading. If you do not specify a content type, Cloud Storage defaults to [`application/octet-stream`](https://datatracker.ietf.org/doc/html/rfc2046#section-4.5.1) when it serves the uploaded object. | No (recommended) | | `Date` | The date and time of the request. | Yes | | `Host` | The URI for Cloud Storage. For more information, see [Request Endpoints](https://docs.cloud.google.com/storage/docs/request-endpoints.md.txt). | 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` | The [customer-managed encryption key](https://docs.cloud.google.com/storage/docs/encryption/customer-managed-keys.md.txt) to use to encrypt the object. | No | | `x-goog-meta-` | An extension header that can be used to store [custom metadata](https://docs.cloud.google.com/storage/docs/metadata.md.txt#custom-metadata). | No | | `x-goog-object-lock-mode` | Mode of the object's [retention configuration](https://docs.cloud.google.com/storage/docs/object-lock.md.txt). `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](https://datatracker.ietf.org/doc/html/rfc3339) 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-storage-class` | Gives each part of the upload and the resulting 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 this request. | No | To provide a customer-supplied encryption key along with the object upload, use the [headers listed on the Customer-Supplied Encryption Key page](https://docs.cloud.google.com/storage/docs/encryption/customer-supplied-keys.md.txt#headers) in your request. ## Request body elements This request does not include an XML document in the request body. ## Response headers The request can return a variety of response headers depending on the request headers you use. ## Response body elements The following response body elements apply to POST Object requests that use the `uploads` query string parameter. | Element | Description | |---|---| | `InitiateMultipartUploadResult` | Container for the response to the upload initiation request. | | `Bucket` | The name of the bucket the multipart upload was initiated in. | | `Key` | The name of the object the multipart upload was initiated for. | | `UploadId` | The upload ID of the initiated multipart upload. | ## Example The following sample initiates a multipart upload for an object named `paris.jpg` in a bucket named `travel-maps`. **Request** ``` POST /paris.jpg?uploads HTTP/2 Host: travel-maps.storage.googleapis.com Date: Wed, 24 Mar 2021 18:11:50 GMT Content-Type: image/jpg Content-Length: 0 Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg ``` **Response** ``` HTTP/2 200 Date: Wed, 24 Mar 2021 18:11:53 GMT Content-Length: 280 Content-Type: application/xml Server: UploadServer travel-maps paris.jpg VXBsb2FkIElEIGZvciBlbHZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZA ```