Stores a new object and metadata. The uploaded object replaces any existing object
with the same name. For an overview of uploading to Cloud Storage, see
[About object uploads](https://docs.cloud.google.com/storage/docs/uploads.md.txt).

This method accepts uploaded object data with the following characteristics:

- **Maximum file size:** 5 TiB
- **Accepted Media MIME types:** `*/*`

This method generally requires the following headers be included in a request:

- [`Content-Length`](https://docs.cloud.google.com/storage/docs/json_api/v1/parameters.md.txt#contentlength)
- [`Content-Type`](https://docs.cloud.google.com/storage/docs/json_api/v1/parameters.md.txt#contenttype)

Note: Metadata-only requests are **not** allowed. To change an object's metadata,
use the [patch](https://docs.cloud.google.com/storage/docs/json_api/v1/objects/patch.md.txt) method.

## Required permissions

The authenticated user must have the `storage.objects.create` IAM
permission to use this method. If the object being inserted has the same name as an existing
object, the user must also have the `storage.objects.delete` permission to overwrite the
existing object. If the request body includes the `retention` property, the
authenticated user must also have the `storage.objects.setRetention` IAM
permission. If the request body includes a non-empty `contexts.custom` property, the authenticated user must also have the `storage.objects.createContext` IAM permission.

## Request

### HTTP request

Note: The [request endpoint](https://docs.cloud.google.com/storage/docs/request-endpoints.md.txt) for this method
differs from typical Cloud Storage JSON API endpoints.

```
POST https://storage.googleapis.com/upload/storage/v1/b/bucket/o
```

In addition to [standard query parameters](https://docs.cloud.google.com/storage/docs/json_api/v1/parameters.md.txt#query),
the following query parameters apply to this method. Note that for
[resumable uploads](https://docs.cloud.google.com/storage/docs/resumable-uploads.md.txt), these headers can be used in the
initial `POST` request but are ignored in the subsequent `PUT` requests.

To see an example of how to include query parameters in a request, see the
[JSON API Overview](https://docs.cloud.google.com/storage/docs/json_api.md.txt#query_parameters) page.

### Parameters

| Parameter name | Value | Description |
|---|---|---|
| **Path parameters** |||
| `bucket` | `string` | Name of the bucket in which to store the new object. Overrides the provided object metadata's `bucket` value, if any. |
| **Required query parameters** |||
| `name` | `string` | Name of the object. Not required if the request body contains object metadata that includes a `name` value. Overrides the object metadata's `name` value, if any. For information about how to URL encode object names to be path safe, see [Encoding URI path parts](https://docs.cloud.google.com/storage/docs/request-endpoints.md.txt#encoding). |
| `uploadType` | `string` | The [type of upload request](https://docs.cloud.google.com/storage/docs/uploads.md.txt#uploads) to the **/upload** URI. Acceptable values are: - `media` - Data-only upload. Upload the object data only, without any metadata. - `multipart` - Multipart upload. Upload both the object data and its metadata, in a single request. - `resumable` - Resumable upload. Upload the object data in a resumable fashion, using a series of at least two requests where the first request includes the metadata. |
| **Optional query parameters** |||
| `contentEncoding` | `string` | If set, sets the `contentEncoding` property of the final object to this value. Setting this parameter is equivalent to setting the `contentEncoding` metadata property. This can be useful when uploading an object with `uploadType=media` to indicate the encoding of the content being uploaded. |
| `ifGenerationMatch` | `long` | Makes the operation conditional on whether the object's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the object. For more information, see [Request preconditions](https://docs.cloud.google.com/storage/docs/request-preconditions.md.txt). |
| `ifGenerationNotMatch` | `long` | Makes the operation conditional on whether the object's current generation does not match the given value. If no live object exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the object. For more information, see [Request preconditions](https://docs.cloud.google.com/storage/docs/request-preconditions.md.txt). |
| `ifMetagenerationMatch` | `long` | Makes the operation conditional on whether the object's current metageneration matches the given value. For more information, see [Request preconditions](https://docs.cloud.google.com/storage/docs/request-preconditions.md.txt). |
| `ifMetagenerationNotMatch` | `long` | Makes the operation conditional on whether the object's current metageneration does not match the given value. For more information, see [Request preconditions](https://docs.cloud.google.com/storage/docs/request-preconditions.md.txt). |
| `kmsKeyName` | `string` | [Resource name of the Cloud KMS key](https://docs.cloud.google.com/kms/docs/resource-hierarchy.md.txt#retrieve_resource_id) that will be used to encrypt the object. If not specified, the request uses the bucket's default Cloud KMS key, if any, or else it uses [standard Cloud Storage encryption](https://docs.cloud.google.com/storage/docs/encryption/default-keys.md.txt). |
| `predefinedAcl` | `string` | Apply a predefined set of access controls to this object. <br /> Acceptable values are: - `authenticatedRead`: Object owner gets `OWNER` access, and `allAuthenticatedUsers` get `READER` access. - `bucketOwnerFullControl`: Object owner gets `OWNER` access, and project team owners get `OWNER` access. - `bucketOwnerRead`: Object owner gets `OWNER` access, and project team owners get `READER` access. - `private`: Object owner gets `OWNER` access. - `projectPrivate`: Object owner gets `OWNER` access, and project team members get access according to their roles. - `publicRead`: Object owner gets `OWNER` access, and `allUsers` get `READER` access. If `iamConfiguration.uniformBucketLevelAccess.enabled` is set to `true`, requests that include this parameter fail with a `400 Bad Request` response. |
| `projection` | `string` | Set of properties to return. Defaults to `noAcl`, unless the object resource specifies the `acl` property, when it defaults to `full`. <br /> Acceptable values are: - `full`: Include all properties. - `noAcl`: Omit the `owner`, `acl` property. |
| **Optional extension headers** |||
| [`X-Goog-Encryption-Algorithm`](https://docs.cloud.google.com/storage/docs/json_api/v1/parameters.md.txt#xgoogencryptionalgorithm) | `string` | The encryption algorithm to use, which must be `AES256`. Used when encrypting the uploaded object with a [customer-supplied encryption key](https://docs.cloud.google.com/storage/docs/encryption/customer-supplied-keys.md.txt). |
| [`X-Goog-Encryption-Key`](https://docs.cloud.google.com/storage/docs/json_api/v1/parameters.md.txt#xgoogencryptionkey) | `string` | An [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648#section-4) Base64-encoded string of your AES-256 encryption key. Used when encrypting the uploaded object with a [customer-supplied encryption key](https://docs.cloud.google.com/storage/docs/encryption/customer-supplied-keys.md.txt). |
| [`X-Goog-Encryption-Key-Sha256`](https://docs.cloud.google.com/storage/docs/json_api/v1/parameters.md.txt#xgoogencryptionkeysha256) | `string` | An [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648#section-4) Base64-encoded string of the SHA256 hash of your encryption key. Used when encrypting the uploaded object with a [customer-supplied encryption key](https://docs.cloud.google.com/storage/docs/encryption/customer-supplied-keys.md.txt). |
| [`X-Goog-Meta-KEY`](https://docs.cloud.google.com/storage/docs/json_api/v1/parameters.md.txt#xgoogmeta) | `string` | Applicable only when used the final request of a [resumable upload](https://docs.cloud.google.com/storage/docs/resumable-uploads.md.txt). An optional way to set [custom metadata](https://docs.cloud.google.com/storage/docs/metadata.md.txt#custom-metadata) for the uploaded object. |

### Request body

When performing a [simple upload](https://docs.cloud.google.com/storage/docs/uploading-objects.md.txt), provide the
object data in the request body. When performing a
[multipart upload](https://docs.cloud.google.com/storage/docs/uploading-objects.md.txt) or when
initiating a [resumable upload](https://docs.cloud.google.com/storage/docs/resumable-uploads.md.txt), both of which allow
you to include object metadata as part of the request, supply the following properties. If you
do not wish to provide object metadata in a resumable upload, the request body can be empty.

| Property name | Value | Description | Notes |
|---|---|---|---|
| **Optional Properties** ||||
| `acl[]` | `list` | Access controls on the object, containing one or more [objectAccessControls Resources](https://docs.cloud.google.com/storage/docs/json_api/v1/objectAccessControls.md.txt). Do not supply this field if `iamConfiguration.uniformBucketLevelAccess.enabled` is `true` for the bucket to which you are uploading the object. | writable |
| `cacheControl` | `string` | [Cache-Control](https://datatracker.ietf.org/doc/html/rfc7234#section-5.2) directive for the object data. If omitted, and the object is accessible to all anonymous users, the default will be `"public, max-age=3600"`. | writable |
| `contentDisposition` | `string` | [Content-Disposition](https://datatracker.ietf.org/doc/html/rfc6266) of the object data. | writable |
| `contentEncoding` | `string` | [Content-Encoding](https://datatracker.ietf.org/doc/html/rfc7231#section-3.1.2.2) of the object data. | writable |
| `contentLanguage` | `string` | [Content-Language](https://docs.cloud.google.com/storage/docs/metadata.md.txt#content-language) of the object data. | writable |
| `contentType` | `string` | [Content-Type](https://datatracker.ietf.org/doc/html/rfc7231#section-3.1.1.5) of the object data. If an object is stored without a Content-Type, it is served as application/octet-stream. | writable |
| `contexts` | `object` | [Contexts](https://docs.cloud.google.com/storage/docs/object-contexts.md.txt) attached to an object, in key-value pairs. | writable |
| `crc32c` | `string` | CRC32c checksum, as described in [RFC 4960, Appendix B](https://datatracker.ietf.org/doc/html/rfc4960#appendix-B); encoded using [base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4) in big-endian byte order. For more information about using the CRC32c checksum, see [Data validation](https://docs.cloud.google.com/storage/docs/data-validation.md.txt). | writable |
| `customTime` | `datetime`^1^ | A user-specified timestamp for the object in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. | writable |
| `eventBasedHold` | `boolean` | Whether or not the object is subject to an [event-based hold](https://docs.cloud.google.com/storage/docs/object-holds.md.txt#hold-types). | writable |
| `md5Hash` | `string` | MD5 hash of the data; encoded using [base64](https://datatracker.ietf.org/doc/html/rfc4648#section-4). For more information about using the MD5 hash, see [Data validation](https://docs.cloud.google.com/storage/docs/data-validation.md.txt). | writable |
| `metadata` | `object` | User-provided metadata, in key/value pairs. | writable |
| `metadata.(key)` | `string` | An individual metadata entry. | writable |
| `name` | `string` | The name of the object. Required if not specified by URL parameter. | writable |
| `retention` | `object` | The object's [retention configuration](https://docs.cloud.google.com/storage/docs/object-lock.md.txt), which defines the earliest datetime that the object can be deleted or replaced. | writable |
| `retention.mode` | `string` | The mode of the retention configuration, which can be either `Unlocked` or `Locked`. If set to `Locked`, `retention.mode` cannot be changed, the retention configuration cannot be removed, and `retention.retainUntilTime` cannot be reduced. | writable |
| `retention.retainUntilTime` | `datetime`^1^ | The earliest time that the object can be deleted or replaced, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. This property has a maximum value of 3,155,760,000 seconds (100 years) from the current date and time. | writable |
| `storageClass` | `string` | Storage class of the object. | writable |
| `temporaryHold` | `boolean` | Whether or not the object is subject to a [temporary hold](https://docs.cloud.google.com/storage/docs/object-holds.md.txt#hold-types). | writable |

^1^ This property is a string formatted as the specified value type.

## Response

If successful, this method returns an
[object resource](https://docs.cloud.google.com/storage/docs/json_api/v1/objects.md.txt#resource) in the response
body.

For information about status and error codes returned by this API, see the
[reference page](https://docs.cloud.google.com/storage/docs/json_api/v1/status-codes.md.txt).