To perform a single-request upload with the XML API, you make a `PUT` request
that is scoped with a bucket name and the object's name, and you put the object
data into the request body. 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 a quick guide to simple uploads using tools such as
the XML API, see [Uploading Objects](https://docs.cloud.google.com/storage/docs/uploading-objects.md.txt).

The PUT Object request uses several standard HTTP headers. `Content-Length`
specifies the object's size in bytes and is required unless you are using
chunked transfer encoding. Optional headers include `Content-Type`,
`Content-MD5`, and those listed below. Cloud Storage stores these
headers as part of the [object's metadata](https://docs.cloud.google.com/storage/docs/metadata.md.txt), except for `Content-MD5`, which
Cloud Storage uses to check for data integrity. See
[Editing object metadata](https://docs.cloud.google.com/storage/docs/viewing-editing-metadata.md.txt#edit) for information on changing metadata values for
objects.

You also use a PUT Object request when you want to change the [storage class](https://docs.cloud.google.com/storage/docs/storage-classes.md.txt)
of an existing object, because you must rewrite the existing object to do so.
The request should contain the [`x-goog-storage-class` request header](https://docs.cloud.google.com/storage/docs/xml-api/reference-headers.md.txt#xgoogstorageclass),
as well as the object in the request body.

> [!NOTE]
> **Note:** Some types of uploads, such as [resumable uploads](https://docs.cloud.google.com/storage/docs/resumable-uploads.md.txt), use a [`POST` Object request](https://docs.cloud.google.com/storage/docs/xml-api/post-object.md.txt).

## Query string parameters

This request does not typically include query string parameters.

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

In addition to [common request headers](https://docs.cloud.google.com/storage/docs/xml-api/put-object.md.txt#request-headers), the
following can be used.

| Header | Description | Required |
|---|---|---|
| `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 |
| `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` | A valid [storage class](https://docs.cloud.google.com/storage/docs/storage-classes.md.txt). | 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

The request body contains the data.

## Request syntax

The following syntax applies to PUT Object requests that don't use any query
string parameters and excludes the `x-goog-copy-source` request
header.

```
PUT /OBJECT_NAME HTTP/1.1
Host: BUCKET_NAME.storage.googleapis.com
Date: DATE
Content-Length: REQUEST_BODY_LENGTH
Content-Type: MIME_TYPE
Content-MD5: MD5_DIGEST
Authorization: AUTHENTICATION_STRING
x-goog-storage-class: STORAGE_CLASS
```

## Response headers

The request can return a variety of response headers depending on the request headers you use.

## 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**

```
PUT /paris.jpg HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Sat, 20 Feb 2010 16:31:08 GMT
Content-Type: image/jpg
Content-MD5: iB94gawbwUSiZy5FuruIOQ==
Content-Length: 554
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
```

**Response**

```
HTTP/1.1 200 OK
ETag: "881f7881ac1bc144a2672e45babb8839"
Date: Sat, 20 Feb 2010 16:31:09 GMT
Content-Length: 0
Content-Type: text/html
```

## Common error codes

If you try to upload an object into a bucket that does not exist, you get a
[404 Not Found](https://docs.cloud.google.com/storage/docs/xml-api/reference-status.md.txt) status code and the body of the error response has
`NoSuchBucket` in the `Code` element.

If the supplied MD5 digest is malformed, you get a [400 Bad Request](https://docs.cloud.google.com/storage/docs/xml-api/reference-status.md.txt) status
code and the body of the error response has `InvalidDigest` in the `Code`
element.

If the digest does not match the digest we compute from the body, you get a
[400 Bad Request](https://docs.cloud.google.com/storage/docs/xml-api/reference-status.md.txt) status code and the body of the error response has
`BadDigest` in the `Code` element.