Yandex Cloud
Search
Contact UsGet started
  • Blog
  • Pricing
  • Documentation
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • ML & AI
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Customer Stories
    • Cloud credits to scale your IT product
    • Gateway to Russia
    • Cloud for Startups
    • Education and Science
    • Yandex Cloud Partner program
  • Blog
  • Pricing
  • Documentation
© 2025 Direct Cursus Technology L.L.C.
Yandex Object Storage
  • Terraform reference
    • Authentication with the API
      • How to use the API
      • Signing requests
        • All services and methods
          • All methods
          • upload
          • get
          • patch
          • copy
          • getObjectMeta
          • delete
          • deleteMultipleObjects
          • options
          • selectObjectContent
          • putObjectRetention
          • putObjectLegalHold
          • getObjectRetention
          • getObjectLegalHold
          • putObjectTagging
          • getObjectTagging
          • deleteObjectTagging
        • Common request headers
        • Common response headers
        • Responses
  • Monitoring metrics
  • Audit Trails events
  • Bucket logs
  • Release notes
  • FAQ

In this article:

  • Request
  • Path parameters
  • Headers
  • Response
  • Headers
  • Response codes
  1. API reference
  2. REST (Amazon S3-compatible)
  3. REST
  4. Object
  5. upload

upload method

Written by
Yandex Cloud
Updated at April 10, 2025
  • Request
    • Path parameters
    • Headers
  • Response
    • Headers
    • Response codes

Uploads an object and its metadata to Yandex Object Storage.

Note

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 to ensure that the history is saved when objects are overwritten or deleted.

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.

Warning

If default object locks are configured in the bucket, the Content-MD5 header is required.

For more information on getting started with the API and the general request format, see How to use the S3 API.

RequestRequest

PUT /{bucket}/{key} HTTP/2

Path parametersPath parameters

Parameter Description
bucket Bucket name.
key Object key, which is the ID the object is saved with in Object Storage.

HeadersHeaders

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 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.

Possible values:
  • STANDARD: Standard storage
  • COLD, STANDARD_IA, or NEARLINE: Cold storage
  • ICE or GLACIER: Ice storage
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 for encrypting an uploaded object.
X-Amz-Object-Lock-Mode

Type of retention put on the object (if the bucket is versioned and object lock is enabled in it):

  • GOVERNANCE: Governance-mode retention.
  • COMPLIANCE: Compliance-mode retention.

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.

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):

  • ON: Enabled.
  • OFF: Disabled.

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.

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"

ResponseResponse

HeadersHeaders

Responses can only contain common headers.

Response codesResponse codes

For a list of possible responses, see Responses.

See alsoSee also

  • Debugging requests using the AWS CLI
  • Example of sending a signed request using curl
  • Code example for generating a signature

Was the article helpful?

Previous
All methods
Next
get
© 2025 Direct Cursus Technology L.L.C.