PostObject

Updated at：2025-11-03

API description

This API allows file uploads to a specified bucket using an HTML form, facilitating browser-based uploads. During the PutObject operation, parameters are passed through the HTTP request header; during the PostObject operation, parameters are included in the form fields within the message body, which is encoded in multipart/form-data format.

Request

Request syntax

Plain Text

1POST / HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Content-Length：<ContentLength>
4Storage-class: <StorageClass>
5Date：<date>
6Content-Type: multipart/form-data; boundary=<boundary>
7--<boundary>
8Content-Disposition: form-data; name="accessKey"
9499d0610679c4da2a69b64086a4cc3bc
10--<boundary>
11Content-Disposition: form-data; name="policy"
12eyJleHBpcmF0aW9uIjoiMjAxNy0wMS0yOFQxMDo1NjoxOVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDMwMDAwMDAwLCA0MDAwMDAwMF0sIHsia2V5IjogImFiKiJ9LCB7ImJ1Y2tldCI6ICJib3MxMDAtZGVidWcifV19
13--<boundary>
14Content-Disposition: form-data; name="signature"
15d1a617a725122c203195fe22ed9c4d20406ee259df8552e3f5344c3e1db84afe
16--<boundary>
17Content-Disposition: form-data; name="key"
18test_object_name
19--<boundary>
20Content-Disposition: form-data; name="Content-Disposition"
21attachment;filename="download/object"
22--<boundary>
23Content-Disposition: form-data; name="x-bce-meta-object-tag"
24test1
25--<boundary>
26Content-Disposition: form-data; name="success-redirect-url"
27http://demo.test.com/upload_success?object=test_object&bucket=test_bucket&time=xxx&userid=xxx
28--<boundary>
29Content-Disposition: form-data; name="file"; filename="upload_file"
30Content-Type: text/plain
31i'm test file content.
32--<boundary>--

Request parameters

Term	Types	Description	Required or not
accessKey	String	User's AccessKey	Optional
Cache-Control、Content-Type、Content-Disposition、Expires	String	Headers applicable for object uploads are configured during upload and returned during download.	Optional
file	-	The uploaded text content must be in the last field of the form. Any form fields after the file field will be ignored.	Yes
key	String	The name of the uploaded object. Leaving this field empty will result in an error.	Yes
policy	String	The policy defines the constraints for the form. Anonymous requests without a policy can access only public-read-write buckets. The policy must be base64-encoded and cannot exceed 4,096 characters. More details about the policy format can be found below the table.	Optional
signature	String	The signature is generated using the secret key and policy, and BOS validates the signature to confirm the legitimacy of the Post request.	Optional
success-action-redirect	String	The URL to redirect to after a successful upload.	-
success-action-status	Int	Supports status codes 200, 201, and 204, with 200 as the default. If set to 201, the Location field will indicate the position of the object.	-
x-bce-meta-*	String	Custom user metadata.	Optional
x-bce-storage-class	String	It specifies the storage class of the object: `STANDARD_IA` indicates infrequent access storage, `COLD` indicates cold storage, `ARCHIVE` indicates archive storage. If the storage class is not specified, the default class is standard storage. For multi-AZ buckets, `MAZ_STANDARD_IA` indicates multi-AZ infrequent access storage. If the storage class is not specified, the default class is `MAZ_STANDARD` multi-AZ standard storage, rather than other options.	Optional
x-bce-acl	String	Headers supported by CannedACL enable users to set object permissions, allowing either private or public-read access.	No
x-bce-grant-read	String	Headers supported by CannedACL allow users to set read permissions for an object. Multiple IDs can be set and should be separated by commas.	No
x-bce-grant-full-control	String	Header supported by CannedACL. Users assign FULL_CONTROL permissions to the object. It supports multiple IDs, separated by commas.	No
x-bce-security-token	String	Required fields for temporary AccessKey/secretAccessKey and sessionToken authentication.	No
x-bce-server-side-encryption	String	Server-Side Encryption (SSE) supports AES256 and SM4 encryption algorithms.	No
x-bce-content-crc32	String	The CRC value (Cyclic Redundancy Check) of the uploaded object.	No

Policy must be UTF-8 character, supporting expiration time settings and restrictions on bucket, key and file length. buckets only support exact match, while objects support exact and prefix matches. The format is as follows:

Plain Text

1 { "expiration": "2015-03-01T12:00:00Z",
2   "conditions": [
3        {
4            "bucket": "testbucket"
5        },
6        {
7            "key": "testkey"
8 }, // exact match
9        {
10            "key": "testkey*"
11 }, // prefix match, with exactly one * and only at the end
12        ["content-length-range", 0, 4096]
13   ]
14 }

Note

PostObject must have write permissions for the bucket. There’s no need to upload signature information for public-read-write buckets; otherwise, the signature must be verified. Unlike PutObject, PostObject uses the sk corresponding to the ak to sign the policy field after base64 encoding it as the signature. BOS verifies the signature to ensure the user's legitimacy.

Key and file fields are required throughout the entire form domain. Any parameters beyond the listed ones will result in an InvalidArgument error.

If PostObject contains an authorization field, BOS will skip its validation.

The form code submitted during the PostObject operation must be "multipart/form-data"; other formats aren’t supported. The Content-Type header should be multipart/form-data; boundary=xxxxxx, where boundary is the delimiter string.

PostObject now supports STS authentication.

If your request size exceeds the content-length-range specified in the policy, a MaxMessageLengthExceeded error will be returned. You can either adjust the maximum content-length-range value to match your request size or remove the limitation.

For the signature method, refer to Python code:

Plain Text

1import base64
2import hashlib
3import hmac
4sk = bytes('<your secret key>','utf-8')
5policy = bytes('your policy','utf-8')
6signature = hmac.new(sk, base64.b64encode(policy), hashlib.sha256).hexdigest()
7print(signature)

Response

Response headers

Name	Types	Description
Content-MD5	String	The MD5 digest of the HTTP request content, as defined in RFC 2616, verifies data consistency between the file stored in BOS and the one expected by the user.
ETag	String	The HTTP protocol entity tag of object

Response parameters

None

Example

Example of standard storage request

Plain Text

1POST / HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Content-Length：11434
4Date：Tue, 29 Mar 2016 12:00:00 GMT
5Content-Type: multipart/form-data; boundary=341261481596
6--341261481596
7Content-Disposition: form-data; name="accessKey"
8499d0610679c4da2a69b64086a4cc3bc
9--341261481596
10Content-Disposition: form-data; name="policy"
11eyJleHBpcmF0aW9uIjoiMjAxNy0wMS0yOFQxMDo1NjoxOVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDMwMDAwMDAwLCA0MDAwMDAwMF0sIHsia2V5IjogImFiKiJ9LCB7ImJ1Y2tldCI6ICJib3MxMDAtZGVidWcifV19
12--341261481596
13Content-Disposition: form-data; name="signature"
14d1a617a725122c203195fe22ed9c4d20406ee259df8552e3f5344c3e1db84afe
15--341261481596
16Content-Disposition: form-data; name="key"
17test_object_name
18--341261481596
19Content-Disposition: form-data; name="Content-Disposition"
20attachment;filename="download/object"
21--341261481596
22Content-Disposition: form-data; name="x-bce-meta-object-tag"
23test1
24--341261481596
25Content-Disposition: form-data; name="success-redirect-url"
26http://demo.test.com/upload_success?object=test_object&bucket=test_bucket&time=xxx&userid=xxx
27--341261481596
28Content-Disposition: form-data; name="file"; filename="upload_file"
29Content-Type: text/plain
30i'm test file content.
31--341261481596--

Example of infrequent access/cold storage request

Plain Text

1POST / HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Content-Length：11434
4Storage-class: STANDARD_IA
5Date：Tue, 29 Mar 2016 12:00:00 GMT
6Content-Type: multipart/form-data; boundary=341261481596
7--341261481596
8Content-Disposition: form-data; name="accessKey"
9499d0610679c4da2a69b64086a4cc3bc
10--341261481596
11Content-Disposition: form-data; name="policy"
12eyJleHBpcmF0aW9uIjoiMjAxNy0wMS0yOFQxMDo1NjoxOVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDMwMDAwMDAwLCA0MDAwMDAwMF0sIHsia2V5IjogImFiKiJ9LCB7ImJ1Y2tldCI6ICJib3MxMDAtZGVidWcifV19
13--341261481596
14Content-Disposition: form-data; name="signature"
15d1a617a725122c203195fe22ed9c4d20406ee259df8552e3f5344c3e1db84afe
16--341261481596
17Content-Disposition: form-data; name="key"
18test_object_name
19--341261481596
20Content-Disposition: form-data; name="Content-Disposition"
21attachment;filename="download/object"
22--341261481596
23Content-Disposition: form-data; name="x-bce-meta-object-tag"
24test1
25--341261481596
26Content-Disposition: form-data; name="success-redirect-url"
27http://demo.test.com/upload_success?object=test_object&bucket=test_bucket&time=xxx&userid=xxx
28--341261481596
29Content-Disposition: form-data; name="file"; filename="upload_file"
30Content-Type: text/plain
31i'm test file content.
32--341261481596--

STS authentication method request example

Plain Text

1POST / HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Content-Length：11434
4Date：Tue, 29 Mar 2016 12:00:00 GMT
5Content-Type: multipart/form-data; boundary=341261481596
6--341261481596
7Content-Disposition: form-data; name="accessKey"
8499d0610679c4da2a69b64086a4cc3bc
9--341261481596
10Content-Disposition: form-data; name="policy"
11eyJleHBpcmF0aW9uIjoiMjAxNy0wMS0yOFQxMDo1NjoxOVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDMwMDAwMDAwLCA0MDAwMDAwMF0sIHsia2V5IjogImFiKiJ9LCB7ImJ1Y2tldCI6ICJib3MxMDAtZGVidWcifV19
12--341261481596
13Content-Disposition: form-data; name="signature"
14d1a617a725122c203195fe22ed9c4d20406ee259df8552e3f5344c3e1db84afe
15--341261481596
16Content-Disposition: form-data; name="x-bce-security-token"
17ds3wHsWRSAJFeafjkAji2OFjJIOLijRk32IRRAJfMISTRhIAJfSJHkdsa
18--341261481596
19Content-Disposition: form-data; name="key"
20test_object_name
21--341261481596
22Content-Disposition: form-data; name="Content-Disposition"
23attachment;filename="download/object"
24--341261481596
25Content-Disposition: form-data; name="x-bce-meta-object-tag"
26test1
27--341261481596
28Content-Disposition: form-data; name="success-redirect-url"
29http://demo.test.com/upload_success?object=test_object&bucket=test_bucket&time=xxx&userid=xxx
30--341261481596
31Content-Disposition: form-data; name="file"; filename="upload_file"
32Content-Type: text/plain
33i'm test file content.
34--341261481596--

Response example

Plain Text

1HTTP/1.1 200 OK
2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
3Date：Tue, 29 Mar 2016 12:00:00 GMT
4ETag: "1b2cf535f27731c974343645a3985328"
5Content-MD5: H2koac2M0YsMxDNte2XJ8A==
6Content-Length: 0
7Connection: close
8Server: BceBOS

GetObjectMeta

listObjectVersions

BOS

BOS

PostObject

API description

Request

Request syntax

Request parameters

Response

Response headers

Response parameters

Example

Example of standard storage request

Example of infrequent access/cold storage request

STS authentication method request example

Response example