[Yandex Cloud documentation](../../../../index.md) > [Yandex Object Storage](../../../index.md) > API reference > [AWS S3 REST](../../index.md) > [REST](../index.md) > Object > PutObject # Object Storage API, Amazon S3-compatible REST: PutObject Uploads an object and its metadata to Yandex Object Storage. {% note info %} Object Storage does not block objects for writes and can accept multiple write requests to the same object at once. However, the user can only get the last written object from Object Storage by default. Enable [versioning](../../../concepts/versioning.md) to ensure that the history is saved when objects are overwritten or deleted. {% endnote %} To make sure an object has been delivered via the network uncorrupted, use the `Content-MD5` header. Object Storage will calculate the `MD5` value for the saved object. If this `MD5` value does not match the value provided in the header, it will return an error. You can also perform this check on the client side by comparing the `ETag` from the Object Storage response with the precalculated `MD5` value. {% note warning %} If [default object locks](../../../concepts/object-lock.md#default) are configured in the bucket, the `Content-MD5` header is required. {% endnote %} For more information on getting started with the API and the general request format, see [How to use the S3 API](../../index.md). ## Request {#request} ```http PUT /{bucket}/{key} HTTP/2 ``` ### Path parameters {#path-parameters} Parameter | Description ----- | ----- `bucket` | Bucket name. `key` | Object key, which is the ID the object is saved with in Object Storage. ### Headers {#request-headers} Use the appropriate [common headers](../common-request-headers.md) in your request. You can also use the headers listed in the table below. Header | Description ----- | ----- `If-Match` | Defines the condition for performing an operation. The operation will only be performed if the current version of the object matching the specified key exists and its `ETag` is identical to the value in the `If-Match` header. `If-None-Match` | Defines the condition for performing an operation. The operation will only be performed if there is no object with the same key in the bucket. Specify `*` in the header value. `X-Amz-Meta-*` | User-defined metadata.

Object Storage transforms all headers starting with `X-Amz-Meta-` as follows: `X-Amz-Meta-foo-bar_baz` → `X-Amz-Meta-Foo-Bar_baz`.

Total user-defined header size must not exceed 2 KB. The size of user-defined data is determined as the length of the UTF-8 encoded string. The size includes header names and their values. `X-Amz-Storage-Class` | Object [storage class](../../../concepts/storage-class.md).

Possible values:If the header is not specified, the object is stored in the storage defined in the bucket settings. `X-Amz-Server-Side-Encryption` | Upload object's encrypion algorithm that takes the `aws:kms` value. `X-Amz-Server-Side-Encryption-Aws-Kms-Key-Id` | ID of the [KMS key](../../../../kms/concepts/key.md) for encrypting an uploaded object. `X-Amz-Object-Lock-Mode` |

Type of [retention](../../../concepts/object-lock.md) put on the object (if the bucket is [versioned](../../../concepts/versioning.md) and object lock is enabled in it):

For an object version, you can use only retention (the `X-Amz-Object-Lock-Mode` and `X-Amz-Object-Lock-Retain-Until-Date` headers), only legal hold (`X-Amz-Object-Lock-Legal-Hold`), or both at the same time. For more information about their combined use, see [Object lock types](../../../concepts/object-lock.md#types).

`X-Amz-Object-Lock-Retain-Until-Date` | Retention end date and time in any format described in the [HTTP standard](https://www.rfc-editor.org/rfc/rfc9110#name-date-time-formats), e.g., `Mon, 12 Dec 2022 09:00:00 GMT`. Specify it only with the `X-Amz-Object-Lock-Mode` header. `X-Amz-Object-Lock-Legal-Hold` |

Type of [legal hold](../../../concepts/object-lock.md) put on the object (if the bucket is [versioned](../../../concepts/versioning.md) and object lock is enabled in it):

For an object version, you can use only retention (the `X-Amz-Object-Lock-Mode` and `X-Amz-Object-Lock-Retain-Until-Date` headers), only legal hold (`X-Amz-Object-Lock-Legal-Hold`), or both at the same time. For more information about their combined use, see [Object lock types](../../../concepts/object-lock.md#types).

The headers below enable you to set the [ACL](../../../concepts/acl.md) for the object being uploaded. Header | Description --- | --- `X-Amz-Acl` | Sets a [predefined ACL](../../../concepts/acl.md#predefined-acls) for an object. `X-Amz-Grant-Read` | Grants the access grantee object read permission. `X-Amz-Grant-Read-Acp` | Grants the access grantee object ACL read permission. `X-Amz-Grant-Write-Acp` | Grants the access grantee object ACL write permission. `X-Amz-Grant-Full-Control` | Grants the access grantee the `READ`, `WRITE`, `READ_ACP`, and `WRITE_ACP` permissions for the object. The value for the `X-Amz-Grant-*` header is a comma-separated list of access grantees. Each access grantee is identified as `:`. Object Storage supports the following types of access grantees: * `id`: Access grantee is a cloud user. * `uri`: Access grantee is a public group. Example: ```http X-Amz-Grant-Read: uri="http://acs.amazonaws.com/groups/s3/AuthenticatedUsers" ``` ## Response {#response} ### Headers {#response-headers} Responses can only contain [common headers](../common-response-headers.md). ### Response codes {#response-codes} For a list of possible responses, see [Responses](../response-codes.md). #### Related articles {#related-articles} * [Object](../../../concepts/object.md) * [Uploading an object](../../../operations/objects/upload.md) #### Useful links {#see-also} * [Getting started with the AWS S3 API in Yandex Object Storage](../../s3-api-quickstart.md) * [Debugging requests using the AWS CLI](../../signing-requests.md#debugging) * [Example of sending a signed request using curl](../../../api-ref/authentication.md#s3-api-example) * [Code example for generating a signature](../../../concepts/pre-signed-urls.md#code-examples)