[Yandex Cloud documentation](../../../../index.md) > [Yandex Object Storage](../../../index.md) > API reference > [AWS S3 REST](../../index.md) > [REST](../index.md) > Multipart upload > CreateMultipartUpload # Object Storage API, Amazon S3-compatible REST: CreateMultipartUpload Returns the ID to use in all subsequent operations for uploading objects. If you need to store objects with user-defined metadata, provide it in this request. 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 POST /{bucket}/{key}?uploads HTTP/2 ``` ### Path parameters {#path-parameters} Parameter | Description ----- | ----- `bucket` | Bucket name. `key` | Object key. The object will be saved in Object Storage with the specified name. ### Query parameters {#request-parameters} Parameter | Description ----- | ----- `uploads` | Flag indicating a multipart upload operation. ### 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 ----- | ----- `X-Amz-Meta-*` | User-defined object 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 storage is defined in the bucket settings. `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). A successful response contains additional data in XML format with the schema described below. ### Data schema {#response-scheme} ```xml bucket-name object-key upload-id ``` Tag | Description ----- | ----- `InitiateMultipartUploadResult` | Response root tag.

Path: `/InitiateMultipartUploadResult`. `Bucket` | Name of the bucket the object is uploaded to.

Path: `/InitiateMultipartUploadResult/Bucket`. `Key` | Key associated with the object after the upload is complete.

Path: `/InitiateMultipartUploadResult/Key`. `UploadId` | Upload ID.

All subsequent upload operations must provide this ID to Object Storage.

Path: `/InitiateMultipartUploadResult/UploadId`. #### Related articles {#related-articles} * [Multipart upload](../../../concepts/multipart.md) * [Creating a multipart upload in a bucket](../../../operations/objects/multipart-upload.md#create-multipart-upload) #### 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)