tencent cloud

PUT Object
Download PDF
Last updated: 2025-06-24 17:37:47
PUT Object
Last updated: 2025-06-24 17:37:47
Download PDF

Feature Overview

The PUT Object API request allows uploading a local object (Object) to a specified bucket. The requester must have write permissions for the bucket. If permission is denied, please refer to set access permissions. To upload to a specified bucket in the form of a web page (HTML Form), please use POST Object.


Precautions

The PUT Object Interface supports uploading files with a maximum size of 5GB. To upload files larger than 5GB, please use the Upload Part API interface.
If the Content-Length value in the request header is less than the length of the transmitted data in the actual request body, COS will still complete the file creation, but the object size will only equal the size defined in Content-Length, and other data will be discarded.
In Cloud Object Storage, there is no concept of folders and directories itself. Upload objects to a specified folder or path by using /.
Set the object key to doc/picture.png, which means uploading the picture.png object to the doc folder.
Set the object key to doc/, which means creating a folder named doc. For more details, please see folders and directories.
If you attempt to add an existing object with the same name, the newly uploaded object will override the original one, returning 200 OK upon success. To prevent overwriting previous versions, toggle on version control. For details, see version control.
Enable bucket versioning: When uploading an object, COS automatically generates a unique version ID for the added object and returns the x-cos-version-id in the response header.
Suspend bucket versioning: When uploading an object, COS always uses null as the version ID for objects in a bucket, and the response header does not return the x-cos-version-id in response.

Authorization Description

When performing authorization policy, set action to cos:PutObject, as shown in the example below.
{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-beijing:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}
For more actions in COS, see Business APIs Supported by CAM.

Request

Request Syntax

PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Type: Content Type
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String

[Object Content]
Note:
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com. <BucketName-APPID> indicates the bucket name with APPID suffix, for example, examplebucket-1250000000. See Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Conventions documentation. <Region> indicates the available region for COS. See Regions and Access Endpoints documentation.
Authorization: Auth String (For details, refer to Request Signature).

Request parameters.

This API has no request parameter.

Request header.

In addition to common request headers, this API also supports the following request headers. For details on common request headers, refer to the Common Request Headers documentation.

Regular Request Header

Name
Description
Type
Required or Optional
Cache-Control
Cache directives defined in RFC 2616 will be saved as object metadata.
string
No
Content-Disposition
The file name defined in RFC 2616 will be saved as object metadata.
For example:
inline: Preview file content directly.
attachment: Download to the browser-specified path in the form of the original file name.
attachment; filename="FileName": Download to the browser-specified path in the form of a custom file name. FileName is used for customizing the downloaded file name, for example example.jpg.
string
No
Content-Encoding
The encoding format defined in RFC 2616 will be saved as object metadata.
string
No
Content-Type
The HTTP request content type (MIME) defined in RFC 2616. This header is for description of the content type of the uploaded object and will be saved as object metadata.
For example, application/xml or image/jpeg.
string
Yes
Expires
Cache expiration time defined in RFC 2616 is an absolute date and time, saved as object metadata.
string
No
Transfer-Encoding
The transfer encoding format defined in RFC 2616. If you want to use chunked transfer during upload, specify the Transfer-Encoding: chunked request header. You cannot specify the Content-Length request header.
string
No

Dedicated Request Header

When uploading an object, you can specify the following request headers to set the object's metadata, storage type, traffic control, and Tag:
Name
Description
Type
Required or Optional
x-cos-meta-[custom suffix]
Custom metadata headers. For example x-cos-meta-test: test metadata.
Note:
Custom metadata headers follow the fixed format x-cos-meta-[custom suffix]. Among them, the custom suffix supports minus signs (-), digits, and English letters (a–z). Uppercase letters in English characters will be converted to lowercase letters. Other characters, including underscores (_), are not supported.
- There is no limit on the number of custom metadata headers. Each header has a size limit of 2KB, and the total size of all x-cos-meta-[custom suffix] headers must be no more than 4KB.
string
No
x-cos-storage-class
Storage type. Default value: STANDARD. For enumeration values, see the storage type overview document.
Reference values:
STANDARD: standard storage
STANDARD_IA: infrequent storage
ARCHIVE: archive storage
DEEP_ARCHIVE: deep archive storage
MAZ_STANDARD: standard storage (multi-AZ)
MAZ_STANDARD_IA: infrequent storage (multi-AZ)
INTELLIGENT_TIERING: intelligent tiering storage
MAZ_INTELLIGENT_TIERING: intelligent tiering storage (multi-AZ)
enum
No
x-cos-traffic-limit
The rate-limiting value for traffic control targeting this upload must be a number, with a default unit of bit/s. The speed limit setting range is 819200 - 838860800 (800Kb/s - 800Mb/s). If outside of this range, it will return a 400 error.
integer
No
x-cos-tagging
The tag set of an object supports up to 10 tags (for example, Key1=Value1&Key2=Value2). Keys and values in the tag set must first perform URL encoding.
string
No
x-cos-forbid-overwrite
For buckets with versioning not enabled, when uploading files, used to specify whether to forbid overwriting objects with the same name during upload operation:
When the x-cos-forbid-overwrite header is not included or set to false, default overwrite applies if an Object with the same name already exists.
Set x-cos-forbid-overwrite to true to forbid overwriting an Object with the same name.
Note:
When the bucket is in enabled or paused versioning status, the x-cos-forbid-overwrite request header setting is invalid, allowing overwriting objects with the same name.
string
No

ACL Relevant Headings

When uploading an object, you can specify the following request headers to set the object's access permissions:
Name
Description
Type
Required or Optional
x-cos-acl
Define the access control list (ACL) property of the object. Default is default. For enumeration values, see the preset ACL part of the object in the ACL overview document.
Reference values:
default: inherit permissions
private: private read/write
public-read: public read/private write
Note:
If you do not need to control object ACL, set it to default or leave this item unset. Permissions are inherited from the bucket by default.
enum
No
x-cos-grant-read
Grant the read permission of the object to the authorized person. Format: id="[OwnerUin]", for example id="100000000001". Use a comma (half-width) to separate multiple authorized entities, such as id="100000000001",id="100000000002".
string
No
x-cos-grant-read-acp
Grant the authorized entities permission to read the object's access control list (ACL). Format: id="[OwnerUin]", for example id="100000000001". Use a comma (half-width) to separate multiple authorized entities, such as id="100000000001",id="100000000002".
string
No
x-cos-grant-write-acp
Grant the authorized entities permission to write to the object's access control list (ACL). Format: id="[OwnerUin]", for example id="100000000001". Use a comma (half-width) to separate multiple authorized entities, such as id="100000000001",id="100000000002".
string
No
x-cos-grant-full-control
Grant all privileges on the operation object to the authorized entities. Format: id="[OwnerUin]", for example id="100000000001". Use a comma (half-width) to separate multiple authorized entities, such as id="100000000001",id="100000000002".
string
No

SSE-related headers

SSE can be set during object upload by specifying the server-side encryption dedicated header. Leave unset for default no encryption.

Request Body

The request body of this API request is the content of an object (file).

Response

Response Headers

In addition to common response headers, this API returns the following response headers. For details about common response headers, see Common Response Headers.

Versioning-related headers

When uploading objects to a versioning-enabled bucket, the following response headers will be returned. To set version control permissions, for details, see Version Control.
Name
Description
Type
x-cos-version-id
Version ID of an object.
string

SSE-related headers

If SSE is used during object upload, this API returns headers used specifically for SSE. For details, see Server-Side Encryption Custom Header.

Response Body

The response body for this API is empty.

Case

Note:
API explorer will use frequently used and functional request headers as input parameters during use. Please check.

Error Code

This API adheres to standardized error responses and codes. For details, refer to the Error Codes document.

Appendix: PUT Object Interface SDKs for Languages

SDK
Documentation Link
Android SDK
C SDK
C++ SDK
.NET(C#) SDK
Flutter SDK
Go SDK
iOS SDK
Java SDK
JavaScript SDK
Node.js SDK
PHP SDK
Python SDK
React Native SDK
Mini Program SDK

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback