Introduction

This interface is used to add objects to a bucket. To add objects to a bucket, you must have write permission for the bucket.

TOS is a distributed system. If it receives multiple write requests for the same object simultaneously, it will overwrite all write requests except for the last one. You can use the Content-MD5 header to provide the expected MD5 value, which will be compared with the MD5 value of the uploaded object. If they do not match, an error will be returned.

Server-side encryption

If you use server-side encryption, TOS encrypts your uploaded data at the object level upon receipt and then persistently stores the encrypted data. When you download an object, TOS automatically decrypts the encrypted data and returns it to you. For more detailed information about server-side encryption, see the Server-side encryption overview.

ACL

You can set the object's ACL through headers. All objects are private by default. You can grant the corresponding permissions to a specific account or predefined group. For more detailed information about ACL, see ACL Policy Overview.

Storage type

TOS uses the standard storage type to store objects by default. The standard storage type is a storage type characterized by high availability, high reliability, and high performance. You may also select different storage types according to specific usage scenarios. For more detailed information about storage types, see Storage Types.

Versioning

If versioning is enabled for the bucket, a unique version ID is automatically generated for each newly uploaded object, and the version ID is returned in the response message through the x-tos-version-id header field.

If multi-versioning is suspended for a bucket, the version number of newly uploaded objects will be null, and after suspension, only the most recently uploaded object will be retained in the case of repeated uploads.

Request syntax

Request parameters and headers

For the public request message headers used by this request, see Public parameters.

Name	Location	Type	Required	Sample value	Description
Content-Length	Header	Integer	Yes	100	The size of the message body.
Content-MD5	Header	String	No	XrY7u+Ae7tCTyyK7j1rNww==	Base64MD5 digest of the message body.
Content-Type	Header	String	No	text/plain	Object type.
Cache-Control	Header	String	No	no-cache, no-store, must-revalidate	Specifies the caching behavior of the web page when this object is downloaded.
Expires	Header	String	No	Mon, 04 Jul 2022 02:57:31 GMT	Cache expiration time as defined in RFC2616.
Content-Disposition	Header	String	No	attachment; filename=123.txt	The name of the object when downloaded.
Content-Encoding	Header	String	No	gzip	Content encoding type when the object is downloaded.
Content-Language	Header	String	No	en-US	Content language format when the object is downloaded.
x-tos-acl	Header	String	No	private	Access permissions for objects. Effective permission settings include: private: Private. public-read: Public Read. public-read-write: Public read-write. authenticated-read: Read access for authenticated users. bucket-owner-read: Bucket Owner Read. bucket-owner-full-control: The bucket owner has full control. bucket-owner-entrusted: Controlled by bucket policies; the bucket owner has full permissions. default: Inherits the bucket ACL, ensuring that the object's ACL policy is consistent with the bucket's ACL policy.
x-tos-grant-full-control	Header	String	No	id=123,id=456	When creating an object, use this header field to grant users permissions for object read (READ), read ACP (READ ACP), and write ACP (WRITE ACP). Format: id=account1,id=account2.
x-tos-grant-read	Header	String	No	id=123,id=456	Permission that allows authorized users to read objects and object metadata. Format: id=account1, id=account2.
x-tos-grant-read-acp	Header	String	No	id=123,id=456	Allow authorized users to read the object's ACL. Format: id=account1,id=account2.
x-tos-grant-write-acp	Header	String	No	id=123,id=456	Authorized users are permitted to modify the object ACL. Format: id=account1,id=account2.
x-tos-meta-*	Header	String	No	x-tos-meta-key: value	When creating an object, you can include headers in the HTTP request that begin with x-tos-meta- to add custom metadata, enabling customized management of the object. When a user retrieves this object or queries its metadata, the added custom metadata will appear in the response header.
x-tos-server-side-encryption	Header	String	No	AES256	Configure the encryption method for the target object. If not specified, the object is unencrypted by default. The possible values are explained as follows: AES256: Uses SSE-TOS encryption and the AES256 encryption algorithm. SM4: Uses the SSE-TOS encryption mode and applies the SM4 encryption algorithm. kms: Use SSE-KMS encryption. For detailed information on SSE-TOS and SSE-KMS encryption methods, please refer to the Server-side encryption overview. tip Using SSE-KMS for server-side encryption incurs API call fees, and creating KMS keys incurs key custody fees, both of which are charged by KMS. For more information, please refer to KMS billing details.
x-tos-server-side-data-encryption	Header	String	No	AES256	The possible values for the encryption algorithm used with SSE-KMS encryption are explained as follows: AES256: AES256 encryption algorithm. SM4: SM4 encryption algorithm. The default is the AES256 algorithm.
x-tos-server-side-encryption-kms-key-id	Header	String	No, this option is required when using SSE-KMS encryption.	trn:kms:cn-beijing:20000111:keyrings/ring-test/keys/key-test	Specify the master key used for SSE-KMS encryption of the target object in the following format: trn:kms:<region>:<accountID>:keyrings/<keyring>/keys/<key>: The TRN of the KMS master key, where region refers to the Region ID to which the key belongs, accountID is the ID of the account that owns the key, keyring is the keyring alias, and key is the master key alias. tip The default master key is currently not supported. If SSE-KMS encryption is specified without providing the required header, the server will return a 400 InvalidRequest error.
x-tos-server-side-encryption-customer-algorithm	Header	String	No. This option is required when using SSE-C encryption.	AES256	Specifies the algorithm to be used for encrypting objects with SSE-C. The possible values are explained as follows: AES256: Encrypt objects using the AES256 algorithm.
x-tos-server-side-encryption-customer-key	Header	String	No. Required when using SSE-C encryption.	YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE=	Used in conjunction with x-tos-server-side-encryption-customer-algorithm, specifies the key for SSE-C encryption of the target object. The key is a 256-bit encryption key encoded in base64.
x-tos-server-side-encryption-customer-key-MD5	Header	String	No. Required when using SSE-C encryption.	0gYVWExOAz67jX5A6qY4+A==	Used in conjunction with x-tos-server-side-encryption-customer-key, this header field indicates the MD5 value of the key used to encrypt the object. This header field is generated by applying base64 encoding to the 128-bit MD5 value of the key. This value is used for message integrity verification to ensure that the encryption key has not been corrupted during transmission.
x-tos-website-redirect-location	Header	String	No	/anotherObjectName	When a bucket is configured with Website settings, requests to retrieve this object can be redirected to another object within the bucket or to an external URL. TOS extracts this value from the header and stores it in the object's metadata.
x-tos-storage-class	Header	String	No	STANDARD	Set the storage type of the target object. If not specified, the storage class of the target object will be consistent with the default storage class of the bucket in which it resides. The possible values are as follows: STANDARD: Standard Storage. IA: Infrequent Access Storage. INTELLIGENT_TIERING: Intelligent Tiering. ARCHIVE_FR: Flashback Archive. ARCHIVE: Archive. COLD_ARCHIVE: Cold Archive. DEEP_COLD_ARCHIVE: Deep Cold Archive. tip Currently, only China (Beijing), China (Shanghai), and China (Guangzhou) support Cold Archive. Currently, only China (Beijing), China (Shanghai), and China (Guangzhou) support Deep Cold Archive. All are currently in an invite-only beta testing phase. If you need to use this storage type, please contact your account manager.
x-tos-tagging	Header	String	No	Key1=Value1&Key2=Value2	Set object tag information in the format {Key}={Value}. Multiple tags can be set simultaneously, separated by &. tip The tag keys and values need to be URL-encoded. If a tag is set without using = to specify a tag value, TOS treats the tag value as an empty string. For more information on restrictions related to object tags, see Object tags.
x-tos-traffic-limit	Header	String	No	819200	TOS provides per-link speed limiting, enabling flow control during object upload, download, and similar operations to ensure network bandwidth for other applications. The explanation of values is as follows: Value range: 245760–838860800, unit: bit/s. This parameter cannot exist simultaneously in both the Header and the Query.
x-tos-forbid-overwrite	Header	String	No	false	Whether overwriting an Object with the same name is permitted. The value descriptions are as follows: If not specified or specified as false: It means that overwriting objects with the same name is allowed. When set to true: Overwriting objects with the same name is prohibited. warning When the target bucket is in an enabled or suspended versioning state, the x-tos-forbid-overwrite parameter setting is ineffective; that is, overwriting Objects with the same name is permitted.
x-tos-traffic-limit	Query	String	No	819200	TOS provides single-link rate limiting functionality, enabling traffic control during operations such as object upload, download, and other similar activities to ensure network bandwidth for other applications. Explanation of Values is as follows: Value range: 245760–838860800, unit: bit/s. This parameter cannot exist simultaneously in both the Header and Query.
x-tos-object-expires	Header	String	No	3	Set the expiration time for the object. After expiration, TOS will automatically delete the object. The unit is days and can be set as a positive integer, indicating that the object will expire at the specified time. The expiration period is calculated from the object's Last-Modified time, and the deletion task is executed at midnight after the expiration time is reached. For example, if you set the x-tos-object-expires parameter to 3, and the object's last modified time is 2024-09-26 12:00, the object will expire at 2024-09-30 00:00. tip The object expiration time takes precedence over the lifecycle deletion rules. For example, if the object expiration time is set to 5 days and the lifecycle rule specifies deletion after 3 days, the deletion will be executed according to the expiration time rule, meaning the object will be deleted after 5 days. TOS supports querying the expiration time of objects via GetObject or HeadObject.
x-tos-object-lock-mode	Header	String	No	COMPLIANCE	The mode of the retention policy can only be COMPLIANCE, which indicates compliance mode. tip To configure a retention policy for an object, you must first enable the retention policy feature. For detailed information, see PutBucketObjectLockConfiguration.
x-tos-object-lock-retain-until-date	Header	String	No	2025-01-01T00:00:00Z	The object's locked deadline is the date during which the object cannot be deleted or overwritten. Follow the ISO 8601 time format. tip x-tos-object-lock-retain-until-date parameter must be used together with the x-tos-object-lock-mode parameter.
if-match	Header	String	No	d41d8cd98f00b204e9800998ecf8427e	The ETag condition controlling upload behavior ensures that an object is uploaded only when the specified ETag matches the ETag of an existing object in the bucket. If the specified ETag does not exist or does not match, the object upload will fail and a 412 status code will be returned.
if-none-match	Header	String	No	d41d8cd98f00b204e9800998ecf8427e	The ETag condition controlling upload behavior ensures that an object is uploaded only when the specified ETag does not match the ETag of an existing object in the bucket. If an existing object's ETag in the bucket matches the specified ETag, the upload will fail and a 412 status code will be returned. tip if-none-match supports being set to *. This indicates that as long as an object with the same name exists in the target storage bucket, regardless of its ETag, the upload will fail and a 412 status code will be returned.

Request body elements

This request does not contain any request message elements; the request body carries the data content of the uploaded object.

Response headers

The public response headers returned by this request. Please refer to Common parameters.

Name	Type	Sample value	Description
x-tos-server-side-encryption	String	kms	This header field is returned when the object is encrypted using SSE-TOS or SSE-KMS. It indicates the server-side encryption method applied to the object, with possible values as follows: AES256: Uses the SSE-TOS encryption method and the AES256 encryption algorithm. SM4: Uses the SSE-TOS encryption mode and adopts the SM4 encryption algorithm. kms: Use SSE-KMS encryption method. For a detailed explanation of SSE-TOS and SSE-KMS encryption methods, please refer to Server-side encryption overview.
x-tos-server-side-encryption-kms-key-id	String	trn:kms:cn-beijing:****:keyrings/ring-test/keys/key-test	This header field is returned when an object uses SSE-KMS encryption. It indicates the KMS master key ID used for SSE-KMS encryption.
x-tos-server-side-encryption-customer-algorithm	String	AES256	This header field is returned when an object is encrypted using SSE-C, confirming the encryption algorithm employed.
x-tos-server-side-encryption-customer-key-MD5	String	0gYVWExOAz67jX5A6qY4+A==	This header field is returned when an object is encrypted using SSE-C, and it indicates the MD5 value of the encryption key used.
x-tos-version-id	String	57AF1A32CECB56721267	The version number of the object. If no version number exists, this message header will not appear in the response message.
x-tos-hash-crc64ecma	Integer	6186290338114851376	Represents the 64-bit CRC value of the object. The 64-bit CRC is calculated in accordance with the ECMA-182 standard. tip When server-side encryption is used for object uploads, this value is the CRC64 checksum of the object's plaintext content.
x-tos-qos-delay-time	Integer	10	This header field indicates the duration for which the request is subject to flow control, measured in milliseconds (ms). Upload requests return the precise duration affected by rate limiting; copy requests or download requests return an estimated duration affected by rate limiting, based on the degree of rate limiting and the object size.

Response body elements

There is no message element in the response to this request.

Sample request

Sample response

Torch Object Storage