[Yandex Cloud documentation](../../../index.md) > [Yandex Object Storage](../../index.md) > [Step-by-step guides](../index.md) > Objects > Uploading an object

# Uploading an object

You can create folders within a bucket and upload objects to them. Keep in mind that in the SDK and HTTP API, an object key is the entire path to the object from the bucket root. For more information, see [Object](../../concepts/object.md).

{% note info %}

You can upload objects of up to 5 GB via the management console (see [Object Storage quotas and limits](../../concepts/limits.md)). When uploading via the console, you cannot specify `content-type` or other headers. To upload larger objects or specify object headers, use other [tools](../../tools/index.md).

{% endnote %}

You can use [tools](../../tools/index.md) that support Object Storage and [signed URLs](../../concepts/pre-signed-urls.md) to upload objects into a bucket.

## Regular uploads {#simple}


To work with objects in an [encrypted](../../concepts/encryption.md) bucket, a user or [service account](../../../iam/concepts/users/service-accounts.md) must have the following [roles for the encryption key](../../../kms/operations/key-access.md) in addition to the `storage.configurer` [role](../../security/index.md#storage-configurer):

* `kms.keys.encrypter`: To read the key, [encrypt](../../../kms/security/index.md#kms-keys-encrypter) and upload objects.
* `kms.keys.decrypter`: To read the key, [decrypt](../../../kms/security/index.md#kms-keys-decrypter) and download objects.
* `kms.keys.encrypterDecrypter`: This role includes the `kms.keys.encrypter` and `kms.keys.decrypter` [permissions](../../../kms/security/index.md#kms-keys-encrypterDecrypter).

For more information, see [Key Management Service service roles](../../../kms/security/index.md#service-roles).


{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select a folder.
  1. Navigate to **Object Storage**.
  1. Select the bucket to upload the object into.
  1. In the left-hand panel, select ![image](../../../_assets/console-icons/folder-tree.svg) **Objects**.
  1. If you want to upload an object to the bucket for the first time, click **Upload objects**.
  1. If you want to upload the object to a specific folder, navigate to that folder by clicking its name. If you need to create a new folder, click **Create folder**.
  1. Within the folder you need, click ![image](../../../_assets/console-icons/arrow-up-from-line.svg) **Upload** on the top panel.
  1. In the window that opens, select the files and click **Open**.
  1. The management console will display all the objects you selected for uploading and prompt you to select a [storage class](../../concepts/storage-class.md). The [bucket configuration](../../concepts/bucket.md#bucket-settings) determines the default storage class.
  1. Click **Upload**.
  1. Refresh the page.

  In the management console, the information about the number of objects and storage space used in the bucket is updated with a few minutes' delay.

- Yandex Cloud CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. See the description of the CLI command for uploading a file to a bucket:
  
      ```bash
      yc storage s3api put-object --help
      ```
  
  1. Get a list of buckets in the default folder:
     
     ```bash
     yc storage bucket list
     ```
     
     Result:
     
     ```text
     +------------------+----------------------+-------------+-----------------------+---------------------+
     |       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     | first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     ```
  1. Run this command:
  
      ```bash
      yc storage s3api put-object \
        --body <local_file_path> \
        --bucket <bucket_name> \
        --key <object_path>
      ```
  
      Where:
  
      * `--body`: Path to the file you need to upload to the bucket.
      * `--bucket`: Name of your bucket.
      * `--key`: [Key](../../concepts/object.md#key) by which to store the object in the bucket.
  
      Result:
  
      ```text
      etag: '"d41d8cd98f00b204e980099********"'
      request_id: 3f2705f********
      ```
  
      Alternative command:
  
      ```bash
      yc storage s3 cp \
        <local_file_path> \
        s3://<bucket_name>/<object_path>
      ```
  
      Result:
  
      ```text
      upload: object.txt to s3://my-bucket/object.txt
      ```
  
      {% cut "Configuring parameters for the `yc storage s3 cp` command" %}
  
      You can set the following parameters for the `yc storage s3 cp` command:
      
      * `s3.max-queue-size`: Maximum number of issues per queue. The default value is `1,000`.
      * `s3.max-concurrent-requests`: Maximum number of simultaneous requests. The default value is `10`.
      * `s3.multipart-threshold`: Object threshold size to trigger a multipart upload if exceeded. The default value is `8MB`.
      * `s3.multipart-chunksize`: Size of parts the object will be split into in a multipart upload. The default value is `8MB`.
      
      To set these parameters, use the `yc config set <parameter> <value>` command.
  
      {% endcut %}

- AWS CLI {#aws-cli}

  1. If you do not have the AWS CLI yet, [install and configure it](../../tools/aws-cli.md).
  1. To upload a single object, run this command:

     ```bash
     aws --endpoint-url=https://storage.yandexcloud.net/ \
       s3 cp <local_file_path> s3://<bucket_name>/<object_key>
     ```

     Where:

     * `--endpoint-url`: Object Storage endpoint.
     * `s3 cp`: Command to upload an object. To upload an object, in the first part of the command, provide the path to the local file you want to upload, and in the second part, the name of your bucket and the object storage [key](../../concepts/object.md#key).

     To load all objects from the local directory, use the following command:
   
     ```bash
     aws --endpoint-url=https://storage.yandexcloud.net/ \
       s3 cp --recursive <path_to_local_directory>/ s3://<bucket_name>/<prefix>/
     ```
   
     Where:
   
     * `--endpoint-url`: Object Storage endpoint.
     * `s3 cp --recursive`: Command to upload all objects stored in a local directory, including the nested ones. To upload objects, in the first part of the command, provide the path to the folder from which you want to copy the files to the bucket, and in the second part, the name of your bucket and storage [folder ID](../../concepts/object.md#folder).

  `aws s3 cp` is a high-level command providing limited features. For more information, see the [AWS CLI reference](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/cp.html). To access all upload features supported by Object Storage, use the [aws s3api put-object](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object.html) command instead (see examples of using [object locks](../../concepts/object-lock.md) [below](#w-object-lock)).

- Terraform {#tf}

  {% note info %}
  
  If you access Object Storage via Terraform under a [service account](../../../iam/concepts/users/service-accounts.md), [assign](../../../iam/operations/sa/assign-role-for-sa.md) to the service account the relevant [role](../../security/index.md#roles-list), e.g., `storage.admin`, for the folder you are going to create the resources in.
  
  {% endnote %}

  With [Terraform](https://www.terraform.io/), you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.
  
  Terraform is distributed under the [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE). The [Yandex Cloud provider for Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) is distributed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/) license.
  
  For more information about the provider resources, see the guides on the [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) website or [its mirror](../../../terraform/index.md).

  If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../../terraform/authentication.md) using the appropriate method.

  Before you start, retrieve the [static access keys](../../../iam/operations/authentication/manage-access-keys.md#create-access-key): a secret key and key ID used for Object Storage authentication.

  {% note info %}
  
  In addition to static access keys, you can use an IAM token for authentication in Object Storage. For more details, see [Creating a bucket](../buckets/create.md) and the [relevant provider documentation](../../../terraform/resources/storage_object.md). 
  
  {% endnote %}


  To create an object in an existing bucket:

  1. In the configuration file, describe the resources you want to create:

     ```hcl
     # Creating a service account

     resource "yandex_iam_service_account" "sa" {
       name = "<service_account_name>"
     }

     # Assigning roles to a service account

     resource "yandex_resourcemanager_folder_iam_member" "sa-admin" {
       folder_id = "<folder_ID>"
       role      = "storage.admin"
       member    = "serviceAccount:${yandex_iam_service_account.sa.id}"
     }

     # Creating a static access key
     
     resource "yandex_iam_service_account_static_access_key" "sa-static-key" {
       service_account_id = yandex_iam_service_account.sa.id
       description        = "static access key for object storage"
     }

     # Create object

     resource "yandex_storage_object" "test-object" {
       access_key = yandex_iam_service_account_static_access_key.sa-static-key.access_key
       secret_key = yandex_iam_service_account_static_access_key.sa-static-key.secret_key
       bucket     = "<bucket_name>"
       key        = "<object_name>"
       source     = "<path_to_file>"
     }
     ```

     Where:
     * `access_key`: Static access key ID.
     * `secret_key`: Secret access key value.
     * `bucket`: Name of the bucket to add the object to. This is a required setting.
     * `key`: Name of the object in the bucket. This is a required setting. Follow these naming requirements:

        * Length: between 3 and 63 characters.
        * It can only contain lowercase Latin letters, numbers, and hyphens.
        * It must start with a letter and cannot end with a hyphen.

     * `source`: Relative or absolute path to the file you need to upload to the bucket.

      For more information on the properties of the `yandex_storage_object` resource in Terraform, see [this provider guide](../../../terraform/resources/storage_object.md).

  1. Create the resources:

     1. In the terminal, navigate to the configuration file directory.
     1. Make sure the configuration is correct using this command:
     
        ```bash
        terraform validate
        ```
     
        If the configuration is valid, you will get this message:
     
        ```bash
        Success! The configuration is valid.
        ```
     
     1. Run this command:
     
        ```bash
        terraform plan
        ```
     
        You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
     1. Apply the configuration changes:
     
        ```bash
        terraform apply
        ```
     
     1. Type `yes` and press **Enter** to confirm the changes.

     This will create all the resources you need in the specified folder. You can check the new resources and their settings using the [management console](https://console.yandex.cloud).

- API {#api}

  To upload an object, use the [upload](../../s3/api-ref/object/upload.md) S3 API method.

  For more information, see [Getting started with the AWS S3 API in Yandex Object Storage](../../s3/s3-api-quickstart.md).

{% endlist %}

## Uploading an object version with an object lock {#w-object-lock}

For a bucket with enabled [versioning](../buckets/versioning.md) and [object lock](../buckets/configure-object-lock.md), you can define object lock settings (disable deleting or overwriting) when uploading an object version.

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select a folder.
  1. Navigate to **Object Storage**.
  1. Select the bucket to upload the object into.
  1. In the left-hand panel, select ![image](../../../_assets/console-icons/folder-tree.svg) **Objects**.
  1. If you want to upload an object to the bucket for the first time, click **Upload objects**.
  1. If you want to upload the object to a specific folder, navigate to that folder by clicking its name. If you want to create a new folder, click **Create folder** on the top panel.
  1. Within the folder you need, click ![image](../../../_assets/console-icons/arrow-up-from-line.svg) **Upload** on the top panel.
  1. In the window that opens, select the files and click **Open**.
  1. The management console will display all the objects you selected for uploading and prompt you to select a [storage class](../../concepts/storage-class.md) (`STANDARD`, `COLD`, `INTELLIGENT_TIERING`, or `ICE`). The [bucket configuration](../../concepts/bucket.md#bucket-settings) determines the default storage class.
  1. To configure locks for the objects you are uploading, select the lock type from the **Object version lock** drop-down list:
     * **Legal hold**: Indefinitely prohibits deleting or overwriting the object version, while you still can upload new versions of the object. A user with the `storage.uploader` role can set and remove legal hold. There is no way to bypass this type of lock. When combined with retention, legal hold takes priority.
     * **Retention**: Prohibits deleting or overwriting the object version for a specified period of time, while you still can upload new versions of the object. A user with the `storage.uploader` role can set a retention period. When combined with legal hold, retention takes no priority.
  1. If you selected **Retention**, specify **Default lock type**:
     * **Governance**: User with the `storage.admin` role can bypass the lock, change its expiration date, or remove it.
     * **Compliance**: User with the `storage.admin` role can only extend the retention period. You cannot override, shorten, or remove such locks until they expire.
  1. Specify **Default lock period** in days or years. It starts from the moment you upload the object version to the bucket.
  1. Click **Upload** and refresh the page.

  In the management console, the information about the number of objects and storage space used in the bucket is updated with a few minutes' delay.

- Yandex Cloud CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. See the description of the CLI command for uploading a file to a bucket:

      ```bash
      yc storage s3api put-object --help
      ```

  1. Get a list of buckets in the default folder:
     
     ```bash
     yc storage bucket list
     ```
     
     Result:
     
     ```text
     +------------------+----------------------+-------------+-----------------------+---------------------+
     |       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     | first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     ```
  1. Run this command:

      ```bash
      yc storage s3api put-object \
       --body <local_file_path> \
       --bucket <bucket_name> \
       --key <object_key> \
       --object-lock-mode <retention_type> \
       --object-lock-retain-until-date <retention_end_date_and_time> \
       --object-lock-legal-hold-status <legal_hold_status>
      ```

     Where:

     * `--body`: Path to the file you need to upload to the bucket.
     * `--bucket`: Name of your bucket.
     * `--key`: [Key](../../concepts/object.md#key) by which to store the object in the bucket.
     * `--object-lock-mode`: [Type](../../concepts/object-lock.md#types) of retention:

       * `GOVERNANCE`: Governance-mode retention.
       * `COMPLIANCE`: Compliance-mode retention.
  
     * `--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., `2025-01-02T15:04:05Z`. You can only specify it together with the `--object-lock-mode` parameter.
  
     * `--object-lock-legal-hold-status`: [Legal hold](../../concepts/object-lock.md#types) status:
  
       * `ON`: Enabled.
       * `OFF`: Disabled.

     For an object version, you can use either retention (the `object-lock-mode` and `object-lock-retain-until-date` parameters), legal hold (`object-lock-legal-hold-status`), or both. For more information about their combined use, see [Object lock types](../../concepts/object-lock.md#types).

     Result:

     ```bash
     etag: '"d41d8cd98f00b204e9800998********"'
     request_id: e19afe50********
     version_id: 0006241E********
     ```

- AWS CLI {#aws-cli}

  1. If you do not have the AWS CLI yet, [install and configure it](../../tools/aws-cli.md).
  1. Run this command:

     ```bash
     aws --endpoint-url=https://storage.yandexcloud.net/ \
       s3api put-object \
       --body <local_file_path> \
       --bucket <bucket_name> \
       --key <object_key> \
       --object-lock-mode <retention_type> \
       --object-lock-retain-until-date <retention_end_date_and_time> \
       --object-lock-legal-hold-status <legal_hold_status>
     ```
     
     Where:
   
     * `--endpoint-url`: Object Storage endpoint.
     * `s3api put-object`: Command to upload an object version. To upload object versions with an object lock, specify the following parameters:
       * `--body`: Path to the file you need to upload to the bucket.
       * `--bucket`: Name of your bucket.
       * `--key`: [Key](../../concepts/object.md#key) by which to store the object in the bucket.
       * `--object-lock-mode`: [Type](../../concepts/object-lock.md#types) of retention:
   
         * `GOVERNANCE`: Governance-mode retention.
         * `COMPLIANCE`: Compliance-mode retention.
    
       * `--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`. You can only specify it together with the `--object-lock-mode` parameter.
    
       * `--object-lock-legal-hold-status`: [Legal hold](../../concepts/object-lock.md#types) status:
    
         * `ON`: Enabled.
         * `OFF`: Disabled.
    
     For an object version, you can use either retention (the `object-lock-mode` and `object-lock-retain-until-date` parameters), legal hold (`object-lock-legal-hold-status`), or both. For more information about their combined use, see [Object lock types](../../concepts/object-lock.md#types).

- API {#api}

  To upload an object version with a lock, use the [upload](../../s3/api-ref/object/upload.md) S3 API method with the `X-Amz-Object-Lock-Mode` and `X-Amz-Object-Lock-Retain-Until-Date` headers to apply a retention period and `X-Amz-Object-Lock-Legal-Hold` to put a legal hold.

{% endlist %}

If your bucket already has [default retention periods](../../concepts/object-lock.md#default) configured, specify the relevant [MD5 hash](https://en.wikipedia.org/wiki/MD5) for any object you upload to the bucket:

{% list tabs group=instructions %}

- Yandex Cloud CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. Determine the file’s MD5 hash and encode it with [Base64](https://en.wikipedia.org/wiki/Base64):

     ```bash
     md5=($(md5sum <local_file_path>))
     md5_base64=$(echo $md5 | base64)
     ```

  1. See the description of the CLI command for uploading a file to a bucket:

     ```bash
     yc storage s3api put-object --help
     ```

  1. Get a list of buckets in the default folder:
     
     ```bash
     yc storage bucket list
     ```
     
     Result:
     
     ```text
     +------------------+----------------------+-------------+-----------------------+---------------------+
     |       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     | first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
     +------------------+----------------------+-------------+-----------------------+---------------------+
     ```
  1. Upload an object to the bucket:

     ```bash
      yc storage s3api put-object \
       --body <local_file_path> \
       --bucket <bucket_name> \
       --key <object_key> \
       --content-md5 $md5_base64
     ```

     Where:

     * `--body`: Path to the file you need to upload to the bucket.
     * `--bucket`: Name of your bucket.
     * `--key`: [Key](../../concepts/object.md#key) by which to store the object in the bucket.
     * `--content-md5`: Object's encoded MD5 hash.

     You can also add the following parameters to the command:

     * `--object-lock-mode` and `--object-lock-retain-until-date` to set a retention period for an object version that overrides the bucket's default retention settings.
     * `--object-lock-legal-hold-status` to set a legal hold on an object version.

     For more information about these parameters, see above.

- AWS CLI {#aws-cli}

  1. Determine the file’s MD5 hash and encode it with [Base64](https://en.wikipedia.org/wiki/Base64):

     ```bash
     md5=($(md5sum <local_file_path>))
     md5_base64=$(echo $md5 | base64)
     ```

  1. If you do not have the AWS CLI yet, [install and configure it](../../tools/aws-cli.md).
  1. Upload an object to the bucket:

     ```bash
     aws --endpoint-url=https://storage.yandexcloud.net/ \
       s3api put-object \
       --body <local_file_path> \
       --bucket <bucket_name> \
       --key <object_key> \
       --content-md5 $md5_base64
     ```
   
     Where:
   
     * `--endpoint-url`: Object Storage endpoint.
     * `s3api put-object`: Command to upload an object version. To upload object versions, specify the following parameters:
       * `--body`: Path to the file you need to upload to the bucket.
       * `--bucket`: Name of your bucket.
       * `--key`: [Key](../../concepts/object.md#key) by which to store the object in the bucket.
       * `--content-md5`: Object's encoded MD5 hash.
     
     You can also add the following parameters to the command:
     
     * `--object-lock-mode` and `--object-lock-retain-until-date` to set a retention period for an object version that overrides the bucket's default retention settings.
     * `--object-lock-legal-hold-status` to set a legal hold on an object version.
 
     For more information about these parameters, see above.

- API {#api}

  To upload an object version with a default retention period, use the [upload](../../s3/api-ref/object/upload.md) S3 API method with the `Content-MD5` header.

{% endlist %}


## Conditional writes {#conditional-writes}

You can use [conditions](../../concepts/object.md#conditional-writes) when uploading an object, as well as when [completing a multipart upload](multipart-upload.md#conditional-writes).

{% note tip %}

To make the conditions check mandatory, use an [access policy](../../concepts/policy.md#conditional-writes-policy). See [these rule examples](../../concepts/policy.md#conditional-writes-rules).

{% endnote %}


### Uploading an object with an ETag condition {#if-match}

{% list tabs group=instructions %}


- AWS CLI {#aws-cli}

  1. If you do not have the AWS CLI yet, [install and configure it](../../tools/aws-cli.md).
  1. To upload an object only if an object with a certain `ETag` exists, run this command:

      ```bash
      aws s3api put-object \
          --endpoint-url https://storage.yandexcloud.net \
          --body <local_file_path> \
          --bucket <bucket_name> \
          --key <object_path> \
          --if-match "<object_ETag>"
      ```

      Where:

      * `--endpoint-url`: Object Storage endpoint.
      * `--body`: Path to the file you need to upload to the bucket, e.g., `./my-folder/my-file.txt`.
      * `--bucket`: Name of your bucket.
      * `--key`: [Key](../../concepts/object.md#key) by which to store the object in the bucket, e.g., `my-folder/my-file.txt`.
      * `--if-match`: Current object `ETag`, e.g., `\"d41d8cd98f00b204e9800998********\"`. The write will only be performed if an object already exists for the specified key and its current `ETag` matches.

- API {#api}

  To upload an object only if an object with a certain `ETag` exists, use the [upload](../../s3/api-ref/object/upload.md) S3 API method with the `--if-match` header.

{% endlist %}


### Uploading an object with an absence condition {#if-none-match}

{% list tabs group=instructions %}


- AWS CLI {#aws-cli}

  1. If you do not have the AWS CLI yet, [install and configure it](../../tools/aws-cli.md).
  1. To upload an object only if there is no object with a specific key in the bucket, run this command:

      ```bash
      aws s3api put-object \
          --endpoint-url https://storage.yandexcloud.net \
          --body <local_file_path> \
          --bucket <bucket_name> \
          --key <object_path> \
          --if-none-match "*"
      ```

      Where:

      * `--endpoint-url`: Object Storage endpoint.
      * `--body`: Path to the file you need to upload to the bucket, e.g., `./my-folder/my-file.txt`.
      * `--bucket`: Name of your bucket.
      * `--key`: [Key](../../concepts/object.md#key) by which to store the object in the bucket, e.g., `my-folder/my-file.txt`.
      * `--if-none-match`: Type `"*"` to perform the write only if there is no object with the specified key yet.

- API {#api}

  To upload an object only if the bucket does not contain an object with a specific key, use the [upload](../../s3/api-ref/object/upload.md) S3 API method with the `--if-none-match` header.

{% endlist %}



#### Useful links {#see-also}

* [Connecting to Object Storage from Virtual Private Cloud](../../tutorials/storage-vpc-access.md)