startUpload method
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.
Request
POST /{bucket}/{key}?uploads HTTP/2
Path parameters
| Parameter | Description |
|---|---|
bucket |
Bucket name. |
key |
Object key. The object will be saved in Object Storage with the specified name. |
Request parameters
| Parameter | Description |
|---|---|
uploads |
Flag indicating a multipart upload operation. |
Headers
Use the appropriate common headers 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 converts all headers starting with X-Amz-Meta- as follows: X-Amz-Meta-foo-bar_baz → X-Amz-Meta-Foo-Bar_baz.The total size of user-defined headers 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 |
Storage class of the object. It may have any of the following values:
|
X-Amz-Object-Lock-Mode |
Type of retention put on the object (if the bucket is versioned and object lock is enabled in it):
For an object version, you can use only retention (the |
X-Amz-Object-Lock-Retain-Until-Date |
Retention end date and time in any format described in the HTTP standard, 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 put on the object (if the bucket is versioned and object lock is enabled in it):
For an object version, you can use only retention (the |
The headers below enable you to set the ACL for the object being uploaded.
| Header | Description |
|---|---|
X-Amz-Acl |
Sets a predefined ACL 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 <access_grantee_type>:<access_grantee_ID>. Object Storage supports the following types of access grantees:
id: Access grantee is a cloud user.uri: Access grantee is a public group.
Example:
X-Amz-Grant-Read: uri="http://acs.amazonaws.com/groups/s3/AuthenticatedUsers"
Response
Headers
Responses can only contain common headers.
Response codes
For a list of possible responses, see Responses.
A successful response contains additional data in XML format with the schema described below.
Data schema
<ListBucketResult
xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<KeyCount>1</KeyCount>
<Name>my-sample-bucket</Name>
<Prefix></Prefix>
<MaxKeys>1000</MaxKeys>
<IsTruncated>false</IsTruncated>
<Contents>
<Key>text.txt</Key>
<LastModified>2025-05-15T07:23:08.030Z</LastModified>
<Owner>
<ID>ajegtlf2q28a********</ID>
<DisplayName>ajegtlf2q28a********</DisplayName>
</Owner>
<ETag>"f75a361db63aa4722fb8e083********"</ETag>
<Size>103</Size>
<StorageClass>STANDARD</StorageClass>
<TagSet></TagSet>
</Contents>
</ListBucketResult>
| 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. |