POST Object

Last updated: 2019-10-23 16:45:06


This API (POST Object) is used to upload a file (object) to the specified bucket through the use of a form. This operation requires that you have write permission to the bucket. All API parameters carried by the HTTP header are requested through form fields.


If versioning is enabled for the bucket, the POST operation will automatically generate a unique version ID for the object to be uploaded. COS returns this ID in the response using the x-cos-version-id response header.
If you suspend versioning for the bucket, COS will always use "null" as the version ID of the object stored in the bucket.

Detail Analysis

  1. You need to have write permission to the bucket.
  2. If a file with the same name as the file to be uploaded already exists in the bucket, it will be overwritten and a success will be returned as if the upload succeeded.


Sample Request

Host: <BucketName-APPID>.cos.<Region>
Content-Length: length

Request Header

Common Headers

The implementation of this request operation uses a common request header. For more information on common request headers, see Common Request Headers.

Non-common Headers

The following request headers are required for the implementation of this request operation:

Name Description Type Required
Content-Length HTTP request length in bytes as defined in RFC 2616 String Yes

Form Fields

Name Description Type Required
acl It defines the ACL attribute of the object. Value range: private, public-read, and default. Default value: default (i.e., inheriting the bucket's permission). Note: Currently, there can be up to 1,000 entries in one ACL. If you do not need access control for the object, use "default" for this parameter or simply leave it blank, so that the object will inherit the permission of the bucket String No
Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires       Header as defined in RFC 2616. For more information, see PUT Object String No
file File content as the last field in the form String Yes
key The filename after the file is uploaded, which will be changed if ${filename} is used; for example, with a/b/${filename}, if the uploaded file is photo.jpg, then the final path after upload will be a/b/photo.jpg String Yes
success_action_redirect If this is set, it will take precedence to return 303, provide the Location header, and add the bucket={bucket}&key={key}&etag={%22etag%22} parameter at the end of the URL String No
success_action_status Value range: 200, 201, and 204. 204 is returned by default. If success_action_redirect is set, this parameter will be ignored String No
x-cos-meta-* This includes the suffix and information of the user-defined header, which will be returned as the object metadata of up to 2 KB.
Note: User-defined header information can contain underscores, but user-defined header suffixes cannot
String No
x-cos-storage-class This sets the storage class of the object. Enumerated values: STANDARD, STANDARD_IA, and ARCHIVE. Default value: STANDARD String No
policy This should be Base64-encoded and is used for request verification. If the content of the request does not match the conditions specified by the policy, 403 Access Denied will be returned String No
x-cos-server-side-encryption This specifies how the server-side encryption is enabled for the object. For encryption with the COS master key, enter AES256 String Yes if encryption is needed

Signature Protection

If signature protection is needed for an HTTP POST request as a form, the form should contain the content of the following form-data:

Form Field Description
policy Base64-encrypted policy content, which is used to verify the content of the request. If the request content does not match the conditions specified by the policy, the request will be rejected.
q-sign-algorithm Algorithm for calculating the signature. COS currently supports SHA1. Enter "sha1" (in lowercase) here.
q-ak Your account ID in Tencent Cloud, i.e., SecretId
q-key-time The validity start and end time of the key used to request the signature, which should be described by a Unix timestamp in seconds in the format of [start-seconds];[end-seconds],
such as 1480932292;1481012298
q-signature Request signature calculated using the elements above. COS will verify the form elements against the signing information and reject the request if the signature does not match the signed content

Signature Calculation

The signature "q-signature" can be calculated in three steps:

  1. Use the key content to encrypt the time value of q-key-time and calculate the value of SignKey.
  2. Create a POST request policy and encrypt its content with sha1 to get the StringToSign.
  3. Encrypt the StringToSign with the SignKey to generate the signature.


Below is a sample of a complete policy:

{ "expiration": "2007-12-01T12:00:00.000Z",
  "conditions": [
    {"acl": "public-read" },
    {"bucket": "examplebucket-1250000000" },
    ["starts-with", "$key", "user/eric/"],
    {"q-sign-algorithm": "sha1" },
    {"q-ak": "AKIDQjz3ltompVjBni5LitkWHFlFpwkn9U5q" },
    {"q-sign-time": "1480932292;1481012298" }

This sets the expiration time for the POST policy in ISO8601 GMT time, such as 2017-12-01T12:00:00.000Z

Conditions Rules

Type Description
Full match Expressed with {"key": "value"} or ["eq", "$key", "value"]
Prefix match Expressed with ["starts-with", "$key", "value"], where the value can be left blank
Range match Only for ["content-length-range", int1, int2]. The number of file bytes must be between int1 and int2

Conditions Parameters
All parameters are optional. If they are not entered, the verification can be skipped.

Name Description Matching Method
acl Permitted scope for the file's ACL attribute. This is optional Full, prefix
bucket This specifies the bucket to upload to Full
content-length-range This specifies the upload size range of the file Range
key Object storage path Full, prefix
success_action_redirect URL returned after a successful upload Full, prefix
success_action_status Status returned after successful upload Full
x-cos-meta-* This includes the suffix and information of the user-defined header, which will be returned as the object metadata of up to 2 KB.
Note: User-defined header information can contain underscores, but user-defined header suffixes cannot
Full, prefix
x-cos-* Other COS headers that need to be signed Full


Response Header

Common Response Headers

This response uses a common response header. For more information on common response headers, see Common Response Headers.

Special Response Headers

The request may return the following response headers:

Name Description Type
x-cos-version-id A version of the copied object in the destination bucket. This header will be returned only if versioning is enabled or enabled and then suspended for the bucket String
x-cos-server-side-encryption If the object is stored with COS-managed server-side encryption, the response will contain the values of this header and the encryption algorithm used (AES256) string

Response Parameters

Name Description Type
ETag This returns the MD5 checksum of the file. The value of ETag can be used to check whether the object gets corrupted during upload String
Location If success_action_redirect for upload is specified, the corresponding value will be returned; otherwise, the full path of the object will be returned String

Response Body

application/xml data is returned in the response body, which contains the complete node data as shown below:


The detailed data are described as follows:

Node Name (Keyword) Parent Node Description Type
PostResponse None Container for storing the POST Object result Container

Content of the Container node PostResponse:

Node Name (Keyword) Parent Node Description Type
Location PostResponse Full path of the object String
Bucket PostResponse The bucket where the object is stored String
Key PostResponse Key name of the object String
ETag PostResponse Etag content String

Error Codes

Some frequent special errors that may occur with the request are listed below. For more common error codes in COS, see Error Codes.

Error Code HTTP Status Code Description
InvalidDigest 400 Bad Request If the Content-MD5 header is carried in the request when the file is uploaded, COS will check whether the MD5 of the body is the same as that carried, and if not, InvalidDigest will be returned
KeyTooLong 400 Bad Request If a custom header beginning with x-cos-meta is carried in the request when the file is uploaded, the combined size of the key and value of the custom header cannot exceed 4 KB; otherwise, the KeyTooLong error will be returned
MissingContentLength 411 Length Required If the Content-Length header is not carried in the request when the file is uploaded, this error code will be returned
NoSuchBucket 404 Not Found If the bucket to which you want to upload the object does not exist, the 404 Not Found error will be returned with the error code NoSuchBucket
EntityTooLarge 400 Bad Request If the file to be uploaded is larger than 5 GB, the EntityTooLarge error will be returned with the error message Your proposed upload exceeds the maximum allowed object size
InvalidURI 400 Bad Request The object key length cannot exceed 850 bytes; otherwise, the InvalidURI error will be returned



Connection: keep-alive
Accept-Encoding: gzip, deflate
Accept: */*
User-Agent: python-requests/2.12.4
Content-Length: 1352
Content-Type: multipart/form-data; boundary=e07f2a7876ae4755ae18d300807ad879

Content-Disposition: form-data; name="key"

Content-Disposition: form-data; name="success_action_status"

Content-Disposition: form-data; name="Acl"

Content-Disposition: form-data; name="x-cos-storage-class"

Content-Disposition: form-data; name="Signature"

Content-Disposition: form-data; name="policy"

Content-Disposition: form-data; name="x-Cos-meta-bb"

Content-Disposition: form-data; name="key1"

Content-Disposition: form-data; name="file"; filename="empty:a"



HTTP/1.1 204
Content-Type: application/xml
Content-Length: 232
Connection: keep-alive
Date: Mon, 11 Dec 2017 09:16:56 GMT
ETag: "d41d8cd98f00b204e9800998ecf8427e"
Server: tencent-cos
x-cos-request-id: NWEyZTRkMDZfMjQ4OGY3MGFfNTE4Yl81