Working with buckets

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to create a bucket has either of these formats:

•With the bucket name included in the hostname:

PUT / HTTP/1.1

•With the bucket name following the hostname:

PUT /bucket-name HTTP/1.1

The table below describes the headers you can use in a request to create a bucket.

Request header	Description	Required
Authorization	See Authentication. You cannot create a bucket as an anonymous user.	Yes
Content-Length	Specifies the size, in bytes, of the request body. For a request to create a bucket, the value of this header must be 0 (zero).	Yes
Date	See Common request headers.	Date or x-amz-date
Host	See Common request headers.	Yes
x-amz-acl	Adds a canned ACL to the bucket. This header is used only to add a canned ACL to a bucket. If you’re using individual x-amz-grant- headers to add the ACL, the x-amz-acl header is invalid. For valid values for this header, see Canned ACLs.	No
x-amz-date	See Common request headers.	x-amz-date or Date
x-amz-grant-full-   control	Grants full control over the bucket to one or more specified grantees. If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-full-control header is invalid. For valid values for this and the following x-amz-grant- headers, see Specifying an ACL with headers.	No
x-amz-grant-read	Grants the browse and read data access permissions for the bucket to one or more specified grantees. If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read header is invalid.	No
x-amz-grant-read-acp	Grants the read ACL data access permission for the bucket to one or more specified grantees. If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read-acp header is invalid.	No
x-amz-grant-write	Grants the write and delete data access permissions for the bucket to one or more specified grantees. If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write header is invalid.	No
x-amz-grant-write-acp	Grants the write ACL data access permission for the bucket to one or more specified grantees. If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write-acp header is invalid.	No

The table below describes the headers returned in response to a successful request to create a bucket.

Response header	Description
Content-length	Specifies the size, in bytes, of the response body. In response to a successful request to create a bucket, the value of this header is always 0 (zero).
Date	See Common response headers.
Location	Specifies the name of the bucket created by the request.

The table below describes HTTP status codes that can be returned in response to a request to create a bucket. For more information on HTTP status codes and the error codes that can accompany them, see Error codes.

Code	Meaning	Description
200	OK	One of these: •The bucket was successfully created. •A bucket with the specified name already exists and is owned by you.
400	Bad Request	Possible reasons include: •The specified bucket name is invalid. •An ACL grant header specifies an invalid grantee. •You already own the maximum number buckets allowed per user. •The tenant does not have enough space for another bucket. •The tenant already has the maximum number of buckets it’s allowed to have.
403	Forbidden	Possible reasons include: •The credentials provided with the request are invalid. •You do not have permission to create buckets. •The tenant does not currently support use of the S3 compatible API for creating buckets.
409	Conflict	A bucket with the specified name already exists and either is owned by a user other than you or has no owner.
500	Internal Server Error	An internal error occurred. If this error persists, contact your tenant administrator.
501	Not Implemented	The request includes the x-amz-acl header with an invalid value.
503	Service Unavailable	HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator.

This section of the Help contains sample PUT requests for creating buckets.

An S3 compatible request to list the buckets you own has this format:

GET / HTTP/1.1

The table below describes the headers you can use in a request to list the buckets you own.

Request header	Description	Required
Authorization	See Authentication.	Yes
Date	See Common request headers.	Date or x-amz-date
Host	See Common request headers.	Yes
x-amz-date	See Common request headers.	x-amz-date or Date
x-hcp-pretty-print	Optionally, requests that the XML response body be formatted for readability. Valid values are: •true — Format the XML response body for readability. •false — Do not apply any special formatting to the XML response body. The default is false. The values true and false are not case sensitive.	No

The table below describes the headers returned in response to a successful request to create a bucket.

Response header	Description
Content-Type	Specifies the Internet media type of the response body. For a request to list the buckets you own, the value of this header is always application/xml;charset=UTF-8.
Date	See Common request headers.
Transfer-Encoding	Indicates that HCP could not determine the size of the response body before formulating the response. For a request to list the buckets you own, the value of this header is always chunked.

HCP returns the list of buckets you own in an XML response body, in this format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Owner>
          <ID>bucket-owner-user-id</ID>
          <DisplayName>bucket-owner-username</DisplayName>
     </Owner>
     <Buckets>
Format for a bucket:
          <Bucket>
               <Name>bucket-name</Name>
               <CreationDate>bucket-creation-date-and-time</CreationDate>
          </Bucket>
            .
            .
            .
     </Buckets>
</ListAllMyBucketsResult>

The table below describes XML elements in the response body returned in response to a request for a bucket listing. The elements are listed in alphabetical order.

Element	Description
Bucket	Child of the ListAllMyBucketsResult element and container for the Name and CreationDate elements. The response body contains one Bucket element for each bucket you own.
CreationDate	Child of the Bucket element. The CreationDate element specifies the date and time when the applicable bucket was created, in Greenwich Mean Time (GMT). The date and time are expressed in this format: yyyy-MM-ddTHH:mm:ss.SSSZ For example: 2019-02-18T19:46:03.856Z
DisplayName	Child of the Owner element. If the bucket owner is identified by an HCP user account, the value of the DisplayName element is the username for that account. If the bucket owner is identified by an AD user account, the value of the DisplayName element is the username of that account followed by an at sign (@) and the AD domain name.
ID	Child of the Owner element. If the bucket owner is identified by an HCP user account, the value of the ID element is the user ID for that account. If the bucket owner is identified by an AD user account, the value of the ID element is the SID for that account.
ListAllMyBuckets   Result	Root element.
Name	Child of the Bucket element. The Name element specifies the name of a bucket.
Owner	Child of the ListAllMyBucketsResult element and container for the DisplayName and ID elements. The Owner element identifies the owner of the applicable bucket.

The table below describes HTTP status codes that can be returned in response to a request to list the buckets you own. For more information on HTTP status codes and the error codes that can accompany them, see Error codes.

Code	Meaning	Description
200	OK	HCP successfully retrieved the list of buckets you own.
403	Forbidden	Possible reasons include: •The credentials provided with the request are invalid. •The tenant does not currently support use of the S3 compatible API for listing the buckets you own. •The specified tenant does not exist.
500	Internal Server Error	An internal error occurred. If this error persists, contact your tenant administrator.
503	Service Unavailable	HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator.

Here’s a sample GET request that returns a list of the buckets owned by user lgreen in the context of the europe tenant.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://europe.hcp.example.com"
     -H "x-hcp-pretty-print: true"

Request headers

GET / HTTP/1.1
Host: europe.hcp.example.com
Date: Thu, 10 Jan 2019 17:19:26 +0000
Authorization: AWS bGdyZWVu:Gek+OrFpyg06Bufgg+TW6kH5ISA=
x-hcp-pretty-print: true

Response headers

HTTP/1.1 200 OK
Date: Thu, 10 Jan 2019 17:19:26 GMT
Content-Type: application/xml;charset=UTF-8
Transfer-Encoding: chunked

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Owner>
          <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
          <DisplayName>lgreen</DisplayName>
     </Owner>
     <Buckets>
          <Bucket>
               <Name>finance</Name>
               <CreationDate>2018-03-18T12:59:11.898Z</CreationDate>
          </Bucket>
          <Bucket>
               <Name>human-resources</Name>
               <CreationDate>2018-03-18T19:46:03.856Z</CreationDate>
          </Bucket>
     </Buckets>
</ListAllMyBucketsResult>

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to check the existence of a bucket has either of these formats:

•With the bucket name included in the hostname:

HEAD / HTTP/1.1

•With the bucket name following the hostname:

HEAD /bucket-name HTTP/1.1

The table below describes the headers you can use in a request to check the existence of a bucket.

Request header	Description	Required
Authorization	See Authentication.	Yes
Date	See Common request headers.	Date or x-amz-date
Host	See Common request headers.	Yes
x-amz-date	See Common request headers.	x-amz-date or Date

The table below describes the headers returned in response to a successful request to check the existence of a bucket.

Response header	Description
Content-Length	Specifies the size, in bytes, of the response body. In response to a successful request to check the existence of a bucket, the value of this header is always 0 (zero).
Date	See Common response headers.

The table below describes HTTP status codes that can be returned in response to a request to check the existence of a bucket. For more information on HTTP status codes and the error codes that can accompany them, see Error codes.

Code	Meaning	Description
200	OK	The specified bucket exists.
403	Forbidden	Possible reasons include: •The credentials provided with the request are invalid. •The specified bucket exists, but you do not have read permission for it. •The specified bucket does not currently support the requested operation. •The S3 compatible API is currently disabled for the specified bucket. •The tenant does not currently support use of the S3 compatible API for checking bucket existence.
404	Not Found	The specified bucket does not exist.
500	Internal Server Error	An internal error occurred. If this error persists, contact your tenant administrator.
503	Service Unavailable	HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator.

Here’s a sample HEAD request that checks the existence of a bucket named finance.

Request with s3curl command line

./s3curl.pl --id=lgreen --head -- -k "https://finance.europe.hcp.example.com"

Request headers

HEAD / HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Thu, 10 Jan 2019 17:19:26 +0000
Authorization: AWS bGdyZWVu:N2UfjwTaydEqS45O5vgcoGerZKw=

Response headers

HTTP/1.1 200 OK
Date: Thu, 10 Jan 2019 17:19:26 GMT
Content-Length: 0

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to add an ACL to a bucket has either of these formats:

•With the bucket name included in the hostname:

PUT /?acl HTTP/1.1

•With the bucket name following the hostname:

PUT /bucket-name?acl HTTP/1.1

The acl query parameter is not case sensitive.

The table below describes the headers you can use in a request to add an ACL to a bucket.

Request header	Description	Required
Authorization	See Authentication.	Yes
Content-Length	Specifies the size, in bytes, of the request body. This header is required when you’re using an ACL request body to add an ACL to the bucket. If you’re using ACL headers to add the ACL, the Content-Length header is invalid.	Conditional
Content-Type	Specifies the Internet media type of the request body. This header is valid only when the ACL is specified in the request body. The only valid values are application/xml and text/xml.	No
Date	See Common request headers.	Date or x-amz-date
Host	See Common request headers.	Yes
x-amz-acl	Adds a canned ACL to the bucket. This header is used only to add a canned ACL to a bucket. If you’re using an ACL request body or individual x-amz-grant- headers to add the ACL, the x-amz-acl header is invalid. For valid values for this header, see Canned ACLs.	No
x-amz-date	See Common request headers.	x-amz-date or Date
x-amz-grant-full-   control	Grants full control over the bucket to one or more specified grantees. If you’re using an ACL request body or a canned ACL to add an ACL to the bucket, the x-amz-grant-full-control header is invalid. For valid values for this and the following x-amz-grant- headers, see Specifying an ACL with headers.	No
x-amz-grant-read	Grants the browse and read data access permissions for the bucket to one or more specified grantees. If you’re using an ACL request body or a canned ACL to add an ACL to the bucket, the x-amz-grant-read header is invalid.	No
x-amz-grant-read-acp	Grants the read ACL data access permission for the bucket to one or more specified grantees. If you’re using an ACL request body or a canned ACL to add an ACL to the bucket, the x-amz-grant-read-acp header is invalid.	No
x-amz-grant-write	Grants the write and delete data access permissions for the bucket to one or more specified grantees. If you’re using an ACL request body or a canned ACL to add an ACL to the bucket, the x-amz-grant-write header is invalid.	No
x-amz-grant-write-acp	Grants the write ACL data access permission for the bucket to one or more specified grantees. If you’re using an ACL request body or a canned ACL to add an ACL to the bucket, the x-amz-grant-write-acp header is invalid.	No

The table below describes the headers returned in response to a successful request to add an ACL to a bucket.

Response header	Description
Content-Length	Specifies the size, in bytes, of the response body. In response to a successful request to add an ACL to a bucket, the value of this header is always 0 (zero).
Date	See Common response headers.

The table below describes HTTP status codes that can be returned in response to a request to add an ACL to a bucket. For more information on HTTP status codes and the error codes that can accompany them, see Error codes.

Code	Meaning	Description
200	OK	HCP successfully added the ACL to the bucket.
400	Bad Request	Possible reasons include: •You are trying to add an ACL that contains more than one hundred permission grants. •A specified grantee does not exist. •The specified owner does not exist. •Two grants of the same permission specify the same grantee. •The x-amz-acl header specifies an invalid value. •An x-amz-grant- header specifies an invalid identifier type. •The XML in the ACL request body is malformed or contains an invalid value.
403	Forbidden	Possible reasons include: •The credentials provided with the request are invalid. •You do not have permission to add an ACL to the bucket. •The specified bucket does not currently support the requested operation. •The S3 compatible API is currently disabled for the specified bucket. •The tenant does not currently support use of the S3 compatible API for adding ACLs to a buckets.
404	Not Found	The specified bucket does not exist.
500	Internal Server Error	An internal error occurred. If this error persists, contact your tenant administrator.
503	Service Unavailable	HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator.

This section of the Help contains sample PUT requests for adding ACLs to buckets.

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to retrieve a bucket ACL has either of these formats:

•With the bucket name included in the hostname:

GET /?acl HTTP/1.1

•With the bucket name following the hostname:

GET /bucket-name?acl HTTP/1.1

The acl query parameter is not case sensitive.

The table below describes the headers you can use in a request to retrieve a bucket ACL.

Request header	Description	Required
Authorization	See Authentication.	Yes
Date	See Common request headers.	Date or x-amz-date
Host	See Common request headers.	Yes
x-amz-date	See Common request headers.	x-amz-date or Date
x-hcp-pretty-print	Optionally, requests that the XML response body be formatted for readability. Valid values are: •true — Format the XML response body for readability. •false — Do not apply any special formatting to the XML response body. The default is false. The values true and false are not case sensitive.	No

The table below describes the headers returned in response to a successful request to retrieve a bucket ACL.

Response header	Description
Content-Type	Specifies the Internet media type of the response body. For a request to retrieve a bucket ACL, the value of this header is always application/xml;charset=UTF-8.
Date	See Common response headers.
Transfer-Encoding	Indicates that HCP could not determine the size of the response body before formulating the response. For a request to retrieve a bucket ACL, the value of this header is always chunked.

The table below describes HTTP status codes that can be returned in response to a request to retrieve a bucket ACL. For more information on HTTP status codes and the error codes that can accompany them, see Error codes.

Code	Meaning	Description
200	OK	HCP successfully retrieved the bucket ACL.
403	Forbidden	Possible reasons include: •The credentials provided with the request are invalid. •You do not have permission to read the bucket ACL. •The specified bucket does not currently support the requested operation. •The S3 compatible API is currently disabled for the specified bucket. •The tenant does not currently support use of the S3 compatible API for retrieving bucket ACLs.
404	Not Found	The specified bucket does not exist.
500	Internal Server Error	An internal error occurred. If this error persists, contact your tenant administrator.
503	Service Unavailable	HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator.

Here’s a sample GET request that retrieves the ACL for the bucket named finance.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.com?acl"
     -H "x-hcp-pretty-print: true"

Request headers

GET /?acl HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Thu, 10 Jan 2019 17:19:26 +0000
Authorization: AWS bGdyZWVu:Msry4PBtztkM6FMvzdDblC5RoPE=
x-hcp-pretty-print: true

Response headers

HTTP/1.1 200 OK
Date: Thu, 10 Jan 2019 17:19:26 GMT
Content-Type: application/xml;charset=UTF-8
Transfer-Encoding: chunked

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Owner>
          <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
          <DisplayName>lgreen</DisplayName>
     </Owner>
     <AccessControlList>
          <Grant>
               <Grantee xsi:type="Group"
                 mlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <URI>http://acs.amazonaws.com/groups/glob...enticatedUsers
                    </URI>
               </Grantee>
               <Permission>READ</Permission>
          </Grant>
          <Grant>
               <Grantee xsi:type="Group"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <URI>http://acs.amazonaws.com/groups/global/AllUsers</URI>
               </Grantee>
               <Permission>READ</Permission>
          </Grant>
          <Grant>
               <Grantee xsi:type="CanonicalUser"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <ID>b9d39144-a081-4760-b0e8-b8fb51e10192</ID>
               <DisplayName>mwhite</DisplayName>
          </Grantee>
          <Permission>READ_ACP</Permission>
          </Grant>
          <Grant>
               <Grantee xsi:type="CanonicalUser"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <ID>b9d39144-a081-4760-b0e8-b8fb51e10192</ID>
               <DisplayName>mwhite</DisplayName>
               </Grantee>
               <Permission>WRITE_ACP</Permission>
          </Grant>
          <Grant>
               <Grantee xsi:type="CanonicalUser"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <ID>b9d39144-a081-4760-b0e8-b8fb51e10192</ID>
                    <DisplayName>mwhite</DisplayName>
               </Grantee>
               <Permission>WRITE</Permission>
          </Grant>
          <Grant>
               <Grantee xsi:type="CanonicalUser"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                          <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
                    <DisplayName>lgreen</DisplayName>
               </Grantee>
               <Permission>FULL_CONTROL</Permission>
          </Grant>
          <Grant>
               <Grantee xsi:type="CanonicalUser"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <ID>b9d39144-a081-4763-b0e8-b8fb51e10192</ID>
                    <DisplayName>pdgrey</DisplayName>
               </Grantee>
               <Permission>WRITE</Permission>
          </Grant>
      </AccessControlList>
</AccessControlPolicy>

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to enable or disable versioning for a bucket has either of these formats:

•With the bucket name included in the hostname:

PUT /?versioning HTTP/1.1

•With the bucket name following the hostname:

PUT /bucket-name?versioning HTTP/1.1

The versioning query parameter is not case sensitive.

For the content of a versioning request body, you use XML in this format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VersioningConfiguration
     xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Status>versioning-status</Status>
</VersioningConfiguration>

The table below describes the XML elements in a versioning request body. The elements are listed in alphabetical order.

Element	Description
Status	Child of the VersioningConfiguration element. Valid values for the Status element are: •Enabled — Enables versioning for the bucket •Suspended — Disables versioning for the bucket
VersioningConfiguration	Root element. This must be the first element in the versioning request body. The VersioningConfiguration element can optionally include this XML namespace specification: xmlns="http://s3.amazonaws.com/doc/2006-03-01/">

The table below describes the headers you can use in a request to enable or disable versioning for a bucket.

Request header	Description	Required
Authorization	See Authentication.	Yes
Content-Length	Specifies the size, in bytes, of the request body.	Yes
Content-Type	Specifies the Internet media type of the request body. The only valid values are application/xml and text/xml.	No
Date	See Common request headers.	Date or x-amz-date
Host	See Common request headers.	Yes
x-amz-date	See Common request headers.	x-amz-date or Date

The table below describes the headers returned in response to a successful request to enable or disable versioning for a bucket.

Response header	Description
Content-Length	Specifies the size, in bytes, of the response body. In response to a successful request to enable or disable versioning for a bucket, the value of this header is always 0 (zero).
Date	See Common response headers.
Location	Specifies the name of the target bucket.

The table below describes HTTP status codes that can be returned in response to a request to enable or disable versioning for a bucket. For more information on HTTP status codes and the error codes that can accompany them, see Error codes.

Code	Meaning	Description
200	OK	HCP successfully enabled or disabled versioning for the bucket.
400	Bad Request	Possible reasons include that the XML in the versioning request body is malformed or contains an invalid value.
403	Forbidden	Possible reasons include: •The credentials provided with the request are invalid. •You are not the bucket owner. •The S3 compatible API is currently disabled for the specified bucket. •The tenant does not currently support use of the S3 compatible API for enabling or disabling bucket versioning.
404	Not Found	The specified bucket does not exist.
500	Internal Server Error	An internal error occurred. If this error persists, contact your tenant administrator.
503	Service Unavailable	HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator.

Here’s a sample PUT request that enables versioning for the finance bucket. The versioning request body is in a file named versioning.xml.

Request body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Status>Enabled</Status>
</VersioningConfiguration>

Request with s3curl command line

./s3curl.pl --id=lgreen --put versioning.xml -- -k
     "https://europe.hcp.example.com/finance?versioning"

Request headers

PUT /finance?versioning HTTP/1.1
Host: europe.hcp.example.com
Date: Thu, 10 Jan 2019 17:19:26 +0000
Authorization: AWS bGdyZWVu:ETdibK607bVlNdxb0aKCttJU33U=
Content-Length: 182

Response headers

HTTP/1.1 200 OK
Date: Thu, 10 Jan 2019 17:19:26 GMT
Location: /finance
Content-Length: 0

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to check the versioning status of a bucket has either of these formats:

•With the bucket name included in the hostname:

GET /?versioning HTTP/1.1

•With the bucket name following the hostname:

GET /bucket-name?versioning HTTP/1.1

The versioning query parameter is not case sensitive.

The table below describes the headers you can use in a request to check the versioning status of a bucket.

Request header	Description	Required
Authorization	See Authentication.	Yes
Date	See Common request headers.	Date or x-amz-date
Host	See Common request headers.	Yes
x-amz-date	See Common request headers.	x-amz-date or Date
x-hcp-pretty-print	Optionally, requests that the XML response body be formatted for readability. Valid values are: •true — Format the XML response body for readability. •false — Do not apply any special formatting to the XML response body. The default is false. The values true and false are not case sensitive.	No

The table below describes the headers returned in response to a successful request to check the versioning status of a bucket.

Response header	Description
Content-Type	Specifies the Internet media type of the response body. For a request to check the versioning status of a bucket, the value of this header is always application/xml;charset=UTF-8.
Date	See Common response headers.
Transfer-Encoding	Indicates that HCP could not determine the size of the response body before formulating the response. For a request to check the versioning status of a bucket, the value of this header is always chunked.

The table below describes HTTP status codes that can be returned in response to a request to check the versioning status of a bucket. For more information on HTTP status codes and the error codes that can accompany them, see Error codes.

Code	Meaning	Description
200	OK	HCP successfully retrieved the versioning status.
403	Forbidden	Possible reasons include: •The credentials provided with the request are invalid. •You are not the bucket owner. •The S3 compatible API is currently disabled for the specified bucket. •The tenant does not currently support use of the S3 compatible API for retrieving the versioning status of a bucket.
404	Not Found	The specified bucket does not exist.
500	Internal Server Error	An internal error occurred. If this error persists, contact your tenant administrator.
503	Service Unavailable	HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator.

Here’s a sample GET request that retrieves the versioning status of the bucket named finance.

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.com?versioning"
     -H "x-hcp-pretty-print: true"

Request headers

GET /?versioning HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Thu, 10 Jan 2019 17:19:26 +0000
Authorization: AWS bGdyZWVu:2rmMzjz+08PWDb/4Kd1nD43Wf1s=
x-hcp-pretty-print: true

Response headers

HTTP/1.1 200 OK
Date: Thu, 10 Jan 2019 17:19:26 GMT
Content-Type: application/xml;charset=UTF-8
Transfer-Encoding: chunked

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Status>Enabled</Status>
</VersioningConfiguration>

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to list the contents of a bucket of a bucket has either of these formats:

•With the bucket name included in the hostname:

GET /[?[versions][query-parameters]] HTTP/1.1

•With the bucket name following the hostname:

GET /bucket-name[?[versions][query-parameters]] HTTP/1.1

The versions query parameter is not case sensitive.

query-parameters can be none, one, or more of:

•delimiter

•key-marker (used only with versions)

•marker (used only without versions)

•max-keys

•prefix

•encoding-type

•version-id-marker (used only with versions)

For information on these query parameters other than key-marker and version-id-marker, see Limiting a listing of current items. For information on the key-marker and version-id-marker query parameters, see Limiting a version listing.

You use query parameters to limit the items included in a bucket listing. The query parameters you can use depend on whether you’re requesting a list of the current (or only) versions of objects or a list of object versions.

The table below describes the headers you can use in a request to list the contents of a bucket.

Request header	Description	Required
Authorization	See Authentication.	Yes
Date	See Common request headers.	Date or x-amz-date
Host	See Common request headers.	Yes
x-amz-date	See Common request headers.	x-amz-date or Date
x-hcp-pretty-print	Optionally, requests that the XML response body be formatted for readability. Valid values are: •true — Format the XML response body for readability. •false — Do not apply any special formatting to the XML response body. The default is false. The values true and false are not case sensitive.	No

The table below describes the headers returned in response to a successful request to list the contents of a bucket.

Response header	Description
Content-Type	Specifies the Internet media type of the response body. For a request to list the contents of a bucket, the value of this header is always application/xml;charset=UTF-8.
Date	The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format: DDDddMMMyyyyHH:mm:ss GMT For example: Thu, 23 Mar 2017 14:27:05 GMT
Transfer-Encoding	Indicates that HCP could not determine the size of the response body before formulating the response. For a request to list the contents of a bucket, the value of this header is always chunked.

The response body returned in response to a request to list the contents of a bucket differs depending on whether request is for the current (or only) versions of objects or for object versions.

The table below describes HTTP status codes that can be returned in response to a request to list the contents of a bucket. For more information on HTTP status codes and the error codes that can accompany them, see Error codes.

Code	Meaning	Description
200	OK	HCP successfully retrieved the requested bucket listing.
400	Bad Request	Possible reasons include that a query parameter has an invalid value.
403	Forbidden	Possible reasons include: •The credentials provided with the request are invalid. •You do not have permission to list the contents of the specified bucket. •The S3 compatible API is currently disabled for the specified bucket.
404	Not Found	The specified bucket does not exist.
500	Internal Server Error	An internal error occurred. If this error persists, contact your tenant administrator.
503	Service Unavailable	HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator.

This section of the Help contains sample GET requests for listing bucket contents.

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to list the contents of a bucket of a bucket has either of these formats:

•With the bucket name included in the hostname:

GET /[?[query-parameters]] HTTP/1.1

•With the bucket name following the hostname:

GET /bucket-name[?[query-parameters]] HTTP/1.1

query-parameters can be one or more of:

•delimiter

•max-keys

•prefix

•encoding-type

•list-type

•continuation-token

•fetch-owner

•start-after

For more information on these query parameters, see Limiting the bucket listing (v2).

You use query parameters to limit the items included in a bucket listing. You can use prefix, max-keys, delimiter, encoding-type, list-type, continuation-token, fetch-owner, and start-after query parameters, alone or in combination with each other, to limit the list of the current items in a bucket.

prefix query parameter

You use the prefix query parameter to request a bucket listing that contains only items with names that begin with a specified character string (the prefix) and, if applicable, common prefixes that begin that prefix.

The list of items does not include in-progress multipart uploads or common prefixes that are exclusively for multipart uploads. For more information on multipart uploads, see Working with multipart uploads.

prefix parameter rules

The character string you specify for the prefix query parameter can contain any valid UTF-8 characters, including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

The prefix parameter name and the character string you specify are both case sensitive.

max-keys query parameter

By default, a bucket listing can include at most one thousand items. However, you can use the max-keys query parameter in a bucket listing request to specify a smaller maximum number of items. If more than the maximum number of items satisfy the criteria for a request, you can use query parameters to retrieve the parts in groups.

max-keys parameter rules

Valid values for the max-keys query parameter are integers in the range 0 (zero) through 2,147,483,647. If you specify an integer greater than one thousand, the returned bucket listing includes only the first one thousand items that satisfy the request criteria (or fewer if fewer than one thousand items satisfy the criteria).

The max-keys parameter name is case sensitive.

delimiter query parameter

You use the delimiter query parameter to request a bucket listing that includes a list of common prefixes, where a prefix is the name of an item up through the first occurrence of the character string specified by the delimiter parameter. Each common prefix is listed only once regardless of the number of items with matching names. The items with matching names are not included elsewhere in the listing.

The returned listing also contains items with names that do not include the character string specified by the delimiter parameter. In the listing, all the named items are listed first, followed by all the common prefixes.

The items and common prefixes included in a listing are subject to any other criteria specified in the request.

Both the items and the common prefixes count toward the maximum number of items that can be included in the bucket listing.

The list of items does not include in-progress multipart uploads. The list of common prefixes does not include common prefixes that are exclusively for multipart uploads. For more information on multipart uploads, see Working with multipart uploads.

delimiter parameter rules

The character string you specify for the delimiter query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

The delimiter parameter name and the character string you specify are both case sensitive.

encoding-type parameter

You use the encoding-type query parameter to request the S3 compatible API to encode the response. You can also use this query parameter to specify the encoding method to use.

encoding-type parameter rules

The key for an object can contain any Unicode character. Some characters, such as those with an ASCII value from 0 to 10, cannot be parsed by XML 1.0 parsers. For these characters, you can add the encoding-type query parameter to request the S3 compatible API to encode the keys in the response.

The encoding-type parameter name is case sensitive.

list-type parameter

You use the list-type query parameter in order to use version 2 of the S3 compatible API. The value for this query parameter must always be set to 2 if you want to use version 2 of S3 compatible API requests.

list-type parameter rules

If any value other than 2 is specified for this query parameter, version 1 of the S3 compatible API is used by default.

The list-type parameter name is case sensitive.

continuation-token parameter

By default, a bucket listing can include at most one thousand items. If your request exceeds this or exceeds the value set for the max-keys query parameter, the response is truncated and you can use the continuation-token query parameter to list the next set of objects. Also, when the IsTruncated response element value is set to true, the response includes the NextContinuationToken element. The value of this element can be used in your next request as the continuation token to list the next set of objects.

continuation-token parameter rules

The continuation-token is a value that only the S3 compatible API understands, and objects are listed in UTF-8 character encoding in lexicographical order. If you specify an invalid continuation-token query parameter in a request, a 400 (Bad Request) error is returned, including a message that specifies the invalid continuation-token query parameter.

The continuation-token parameter name is case sensitive.

fetch-owner parameter

You use the fetch-owner query parameter to retrieve owner information. When you specify the fetch-owner query parameter to true, the S3 compatible API returns the owner information in the response.

fetch-owner parameter rules

The S3 compatible API no longer returns owner information by default in the response. To include owner information in the response, you need to set the fetch-owner query parameter to true.

The fetch-owner parameter name is case sensitive.

start-after parameter

You use the start-after query parameter to specify that you want the S3 compatible API to return key names after a specific object key. The start-after query parameter that you specify is always returned in the response, regardless of whether the specified value is valid.

start-after parameter rules

The start-after query parameter is valid only in the first request. If the response is truncated, you can use the continuation-token query parameter to list the next set of objects. The S3 compatible API lists objects in UTF-8 character encoding in lexicographical order.

The start-after parameter name and the character string you specify are both case sensitive.

The table below describes the headers you can use in a request to list the contents of a bucket.

Request header	Description	Required
Authorization	See Authentication.	Yes
Date	See Common request headers.	Date or x-amz-date
Host	See Common request headers.	Yes
x-amz-date	See Common request headers.	x-amz-date or Date
x-hcp-pretty-print	Optionally, requests that the XML response body be formatted for readability. Valid values are: •true — Format the XML response body for readability. •false — Do not apply any special formatting to the XML response body. The default is false. The values true and false are not case sensitive.	No

The table below describes the headers returned in response to a successful request to list the contents of a bucket.

Response header	Description
Connection	Specifies if the connection to the server is open or closed.
Content-Length	The size, in bytes, of the response body if HCP can determine the size before formulating the response. If the response does not include a response body, the value of the Content-Length header is 0 (zero).
Content-Type	Specifies the Internet media type of the response body. For a request to list the contents of a bucket, the value of this header is always application/xml;charset=UTF-8.
Date	The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format: DDDddMMMyyyyHH:mm:ss GMT For example: Thu, 23 Mar 2017 14:27:05 GMT
Server	The version of the HCP system that responded to the request. The value of this header is always HCP followed by the HCP version number (for example, HCP V8.1.2.2).
Transfer-Encoding	Indicates that HCP could not determine the size of the response body before formulating the response. For a request to list the contents of a bucket, the value of this header is always chunked.

The table below describes the XML elements in the response body that is returned in response to a request to list the contents of a bucket. The elements are listed in alphabetical order.

Element	Description
CommonPrefixes	Child of the ListBucketResult element and container for the Prefix element. The response body contains one CommonPrefixes element for each common prefix in the bucket listing.
Contents	Child of the ListBucketResult element and container for the elements that describe a current item in the bucket. The response body contains one Contents element for each item that satisfies the request criteria.
ContinuationToken	Child of the ListBucketResult element. If sent with the request, the ContinuationToken element specifies the continuation token for listing the next set of objects.
Delimiter	Child of the ListBucketResult element. The Delimiter element specifies the value of the delimiter query parameter included in the request. If the request did not include the delimiter query parameter, the response body does not include the Delimiter element.
DisplayName	Child of the Owner element. If the item owner is identified by an HCP user account, the value of the DisplayName element is the username for that account. If the item owner is identified by an AD user account, the value of the DisplayName element is the username of that account followed by an at sign (@) and the AD domain name. If the item has no owner, the value of the DisplayName element is nobody. For folders, the value of the DisplayName element is always nobody.
Encoding-Type	Child of the ListBucketResult element. The Encoding-Type element specifies the type of encoding used by the S3 compatible API to encode the key names of objects.
ETag	Child of the Contents element. The ETag element specifies the ETag of the applicable item. The response body includes ETag elements for the listed folders. However, because they have no content, all folders have the same value for this element. For information on ETags, see Storing an object.
ID	Child of the Owner element. If the item owner is identified by an HCP user account, the value of the ID element is the user ID for that account. If the item owner is identified by an AD user account, the value of the ID element is the SID for that account. If the item has no owner, the value of the ID element is nobody. For folders, the value of the ID element is always nobody.
IsTruncated	Child of the ListBucketResult element. The IsTruncated element indicates whether the returned bucket listing includes the last item that satisfies the request criteria. Possible values are: •true — The returned listing includes the last item that satisfies the request criteria. •false — The returned listing does not include the last item that satisfies the request criteria.
Key	Child of the Contents element. The Key element specifies the name of an item in the bucket listing.
KeyCount	Child of the ListBucketResult element. The KeyCount element specifies the number of keys in the response. The value of the KeyCount element is always less than or equal to the value of the MaxKeys element.
LastModified	Child of the Contents element. The LastModified element specifies the date and time when the applicable item was last modified, in Greenwich Mean Time (GMT). The date and time are expressed in this format: yyyy-MM-ddTHH:mm:ss.SSSZ For example: 2019-02-18T19:46:03.856Z Modifying an object means modifying its metadata. You cannot modify the content of an object.
ListBucketResult	Root element for a listing of current items.
MaxKeys	Child of the ListBucketResult element. The MaxKeys element specifies the value of the max-keys query parameter included in the request. If the request did not include the max-keys query parameter, the value of the MaxKeys element is 1000.
Name	Child of the ListBucketResult element. The Name element specifies the name of the applicable bucket.
NextContinuationToken	Child of the ListBucketResult element. If the response is truncated, the NextContinuationToken element is included in the response. The value of this element can be used in your next request as the continuation token to list the next set of objects.
Owner	Child of the Contents element and container for the DisplayName and ID elements. The Owner element identifies the owner of the applicable item.
Prefix	One of these: •Child of the ListBucketResult element. In this case, the Prefix element specifies the value of the prefix query parameter included in the request. If the request did not include the prefix query parameter, the response body includes Prefix as an empty element. •Child of the CommonPrefixes element. In this case, the Prefix element specifies a common prefix.
Size	Child of the Contents element. The Size element specifies the size, in bytes, of the content of the item. The response body includes Size elements for the listed folders. However, because folders have no content, the value of this element for a folder is always 0 (zero).
StartAfter	Child of the ListBucketResult element. If sent with the request, the StartAfter element includes the specific object key after which the S3 compatible API returns key names.
StorageClass	Child of the Contents element. The value of the StorageClass element is always STANDARD.

In response to a request to list the objects in a bucket, HCP returns an XML response body in this format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Name>bucket-name</Name>
     <Prefix>prefix</Prefix>
     <StartAfter>item-name</StartAfter>
     <NextContinuationToken>continuation-token</NextContinuationToken>
     <KeyCount>number-of-items-listed</KeyCount>
     <MaxKeys>maximum-items-to-list</MaxKeys>
     <Delimiter>delimiter</Delimiter>
     <IsTruncated>true|false</IsTruncated>
Format for an item:
     <Contents>
          <Key>item-name</Key>
          <LastModified>date-and-time-last-modified</LastModified>
          <ETag>"etag"</ETag>
          <Size>size-in-bytes</Size>
          <Owner>
               <ID>owner-user-id</ID>
               <DisplayName>owner-username</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Contents>
       .
       .
       .
Format for a common prefix:
     <CommonPrefixes>
          <Prefix>common-prefix</Prefix>
            .
            .
            .
     </CommonPrefixes>
</ListBucketResult>

The table below describes HTTP status codes that can be returned in response to a request to list the contents of a bucket. For more information on HTTP status codes and the error codes that can accompany them, see Error codes.

Code	Meaning	Description
200	OK	HCP successfully retrieved the requested bucket listing.
400	Bad Request	Possible reasons include that a query parameter has an invalid value.
403	Forbidden	Possible reasons include: •The credentials provided with the request are invalid. •You do not have permission to list the contents of the specified bucket. •The S3 compatible API is currently disabled for the specified bucket.
404	Not Found	The specified bucket does not exist.
500	Internal Server Error	An internal error occurred. If this error persists, contact your tenant administrator.
503	Service Unavailable	HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator.

Here’s a sample GET request for a bucket listing that lists the objects that are in the mktg folder and, separately, the subfolders that are in the mktg folder. The request uses these query parameters:

•list-type=2 — Uses version 2 of the S3 compatible API

•max-keys=1000 — Lists no more than 1000 items in the response

•prefix=mktg/ — Lists only items that start with mktg/

•start-after=mktg/ — Starts the listing with the item that follows mktg/ by itself

•delimiter=/ — Treats items that have a forward slash (/) after mktg/ as having a common prefix

Request with s3curl command line

./s3curl.pl --id=lgreen -- -k "https://finance.europe.hcp.example.c...&max-keys=1000
     &prefix=mktg/&start-after=mktg/&delimiter=/" -H "x-hcp-pretty-print: true"

Request headers

GET /?list-type=2&max-keys=1000&prefix=mktg/&delimiter=/&start-after=mktg/ HTTP/1.1
Host: finance.europe.hcp.example.com
Date: Thu, 10 Jan 2019 17:19:26 +0000
Authorization: AWS bGdyZWVu:ysiVYJ/cOr78z69BuDy6fy07ryo=
x-hcp-pretty-print: true

Response headers

HTTP/1.1 200 OK
Date: Thu, 10 Jan 2019 17:19:26 GMT
Content-Type: application/xml;charset=UTF-8
Content-Length: 157
Connection: close
Server: HCP V8.1.2.2
Transfer-Encoding: chunked

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Name>finance</Name>
     <Prefix>mktg/</Prefix>
     <StartAfter>mktg/</StartAfter>
     <NextContinuationToken>1eGcxW1r/XYCxHnhbY24cK3/Jd36Hy4vZkbM=</NextContinuationToken>
     <KeyCount>1000</KeyCount>
     <MaxKeys>1000</MaxKeys>
     <Delimiter>/</Delimiter>
     <IsTruncated>true</IsTruncated>
     <Contents>
          <Key>mktg/campaign_GoGetEm_expenses.xls</Key>
          <LastModified>2019-02-13T17:44:53.000Z</LastModified>
          <ETag>"6ed7faad1e0661c03ad65a4317d4a94c"</ETag>
          <Size>94328</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Contents>
     <Contents>
          <Key>mktg/campaign_LiveIt_expenses.xls</Key>
          <LastModified>2018-12-05T14:32:29.110Z</LastModified>
          <ETag>"7ad452af1e2f61b33a865c4362be5921"</ETag>
          <Size>81578</Size>
          <Owner>
               <ID>b9d39144-a081-4762-b0e8-b8fb51e10192</ID>
               <DisplayName>lgreen</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
     </Contents>
       .
       .
       .
     <CommonPrefixes>
          <Prefix>mktg/budget_proposals/</Prefix>
            .
            .
            .
     </CommonPrefixes>
</ListBucketResult>

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to list in-progress multipart uploads has either of these formats:

•With the bucket name included in the hostname:

GET/?uploads[&query-parameters] HTTP/1.1

•With the bucket name following the hostname:

GET/bucket-name?uploads[&query-parameters] HTTP/1.1

The uploads query parameter is case sensitive.

query-parameters can be none, one, or more of:

•delimiter

•key-marker

•max-uploads

•prefix

•encoding-type

•upload-id-marker

For more information on these query parameters, see Limiting the part listing.

You can use the prefix, max-uploads, key-marker, upload-id-marker, encoding-type, and delimiter query parameters to limit the multipart uploads included in a listing of in-progress multipart uploads.

prefix query parameter

You use the prefix query parameter to request a multipart upload listing that contains only multipart uploads with object names that begin with a specified character string (the prefix).

For example, the multipart upload listing returned in response to a GET bucket list multipart uploads request with the prefix=acctg query parameter contains only these items:

acctg/AcctgAtExampleCorp-Advanced.mov
acctg/AcctgAtExampleCorp-Introduction.mov
acctg/RulesAndRegulations.pdf

prefix parameter rules

The character string you specify for the prefix query parameter can contain any valid UTF-8 characters, including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

The prefix parameter name and the character string you specify are both case sensitive.

max-uploads query parameter

By default, a multipart upload listing can include at most one thousand multipart uploads. However, you can use the max-uploads query parameter in a multipart upload listing request to specify a smaller maximum number of multipart uploads.

For example, the bucket listing returned in response to a GET bucket list multipart uploads request with the max-uploads=2 query parameter contains these multipart uploads:

acctg/AcctgAtExampleCorp-Advanced.mov
acctg/AcctgAtExampleCorp-Introduction.mov

If more than the maximum number of multipart uploads satisfy the criteria for a request, you can use the the key-marker and, optionally, upload-id-marker query parameters in conjunction with max-uploads to retrieve the parts in groups.

max-uploads parameter rules

Valid values for the max-uploads query parameter are integers in the range 0 (zero) through 1,000. If you specify an integer greater than one thousand, HCP returns a 400 (Invalid Argument) status code and does not return a multipart upload listing.

The max-uploads parameter name is case sensitive.

key-marker query parameter

You use the key-marker query parameter without the upload-id-marker query parameter to specify a starting point for the returned multipart upload listing. That point is the first multipart upload with an object name that's alphanumerically greater than the character string specified by the key-marker parameter.

For example, the multipart upload listing returned in response to a GET multipart upload listing request with the key-marker=sales/ query parameter contains this multipart upload:

sales/RulesAndRegulations.pdf

For information on using the key-marker query parameter with the upload-id-marker query parameter, see upload-id-marker query parameter.

When more than the requested number of multipart uploads satisfy the criteria in a request for a multipart upload listing, HCP returns a partial listing. In this case, the response body includes:

•The IsTruncated element with a value of true.

•The NextKeyMarker element. The value of this element is either the object name for the last multipart upload included in the returned listing or the last common prefix in the returned listing, whichever is alphanumerically greater.

•Conditionally, the NextUploadIdMarker element. For information on this element, see upload-id-marker query parameter.

To return the next part of the multipart upload listing, you include the key-marker query parameter in another request for the listing. As the parameter value, you specify the value of the NextKeyMarker element returned with the previous partial listing.

When the returned listing includes the last multipart upload that satisfies the request criteria, the response body includes the IsTruncated element with a value of false and does not include the NextKeyMarker and NextUploadIdMarker elements.

key-marker parameter rules

The character string you specify for the key-marker query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

The key-marker parameter name and the character string you specify are both case sensitive.

upload-id-marker query parameter

By default, if a bucket contains multiple multipart uploads for a given object, a multipart upload listing for the bucket includes all the multipart uploads for that object, where those multipart uploads satisfy the request criteria.

You use the upload-id-marker query parameter in conjunction with the key-marker parameter to start a multipart upload listing with a multipart upload for which:

•The object name is the same as the character string specified by the key-marker parameter.

•The upload ID is the first upload ID for the named object that's alphanumerically greater than the character string specified by the upload-id-marker parameter.

If no multipart upload satisfies the above criteria, the returned listing starts with the first multipart upload with an object name that's alphanumerically greater than the character string specified by the key-marker parameter.

If the multipart upload listing request includes the upload-id-marker parameter without the key-marker parameter, the upload-id-marker parameter is ignored.

When the response body for a multipart upload listing request includes the IsTruncated element with a value of true, the response body also includes the NextUploadIdMarker element, except when both of these are true:

•The response body lists one or more common prefixes.

•The last multipart upload that satisfies the request criteria does not appear in the response body because the object name for that multipart upload starts with the last listed common prefix.

The value of the NextUploadIdMarker element, when present, is the upload ID of the last multipart upload included in the returned listing. This is the value to use for the upload-id-marker query parameter in a request to retrieve the next group of multipart uploads that satisfy the request criteria.

For example, suppose the finance bucket contains three in-progress multipart uploads for acctg/RulesAndRegulations.pdf with upload IDs 1, 2, and 3. To page through all the multipart uploads in the finance bucket four at a time, you would use a sequence of requests like this:

1.Request line:

GET  /?uploads&max-uploads=4  HTTP/1.1

The response body lists these multipart uploads:

acctg/AcctgAtExampleCorp-Advanced.mov
acctg/AcctgAtExampleCorp-Introduction.mov
acctg/RulesAndRegulations.pdf (upload ID 1)
acctg/RulesAndRegulations.pdf (upload ID 2)

The response body also includes these elements:

<IsTruncated>true</IsTruncated>
<NextKeyMarker>acctg/RulesAndRegulations.pdf</NextKeyMarker>
<NextUploadIdMarker>2</NextUploadIdMarker>

2.Request line:

GET  /?uploads&max-uploads=4&key-marker=acctg/RulesAndRegulations.pdf
    &upload-id-marker=2  HTTP/1.1

The response body lists these multipart uploads:

acctg/RulesAndRegulations.pdf (upload ID 3)
sales/RulesAndRegulations.pdf

The response body also includes this element:

<IsTruncated>false</IsTruncated>

upload-id-marker parameter rules

The character string you specify for the upload-id-marker query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

The upload-id-marker parameter name and the character string you specify are both case sensitive.

encoding-type parameter

You use the encoding-type query parameter to request the S3 compatible API to encode the response. You can also use this query parameter to specify the encoding method to use.

encoding-type parameter rules

The key for an object can contain any Unicode character. Some characters, such as those with an ASCII value from 0 to 10, cannot be parsed by XML 1.0 parsers. For these characters, you can add the encoding-type query parameter to request the S3 compatible API to encode the keys in the response.

The encoding-type parameter name is case sensitive.

delimiter query parameter

You use the delimiter query parameter to request a multipart upload listing that includes a list of common prefixes for multipart upload object names. A common prefix is the name of an object up through the first occurrence of the character string specified by the delimiter parameter.

Each common prefix is listed only once regardless of the number of multipart uploads with matching object names. The multipart uploads with object names that begin with the common prefix are not included elsewhere in the listing.

The returned listing also contains multipart uploads with object names that do not include the character string specified by the delimiter parameter. In the listing, all these multipart uploads are listed first, followed by all the common prefixes.

For example, the multipart upload listing returned in response to a GET bucket list multipart uploads request with the delimiter=RulesAndRegulations query parameter contains these multipart uploads and common prefixes:

Multipart uploads:

acctg/AcctgAtExampleCorp-Advanced.mov
acctg/AcctgAtExampleCorp-Introduction.mov

Common prefixes:

acctg/RulesAndRegulations
sales/RulesAndRegulations

The listed multipart uploads do not have the string RulesAndRegulations in their object names. The acctg/RulesAndRegulations common prefix represents the multipart uploads with object names that start with the string acctgRulesAndRegulations. The salesRulesAndRegulations common prefix represents the multipart uploads with object names that start with the string salesRulesAndRegulations.

The multipart uploads and common prefixes included in a listing are subject to any other criteria specified in the request.

Both the multipart uploads and the common prefixes count toward the maximum number of multipart uploads that can be included in the listing.

delimiter parameter rules

The character string you specify for the delimiter query parameter can contain any valid UTF-8 characters. including white space. Percent-encode non-ASCII characters and reserved special characters such as ampersands (&), commas (,) and equal signs (=). If the character string contains spaces, enclose the entire string in quotation marks.

The delimiter parameter name and the character string you specify are both case sensitive.

The table below describes the headers you can use in a request to list in-progress multipart uploads.

Request header	Description	Required
Authorization	See Authentication.	Yes
Date	See Common request headers.	Date or x-amz-date
Host	See Common request headers.	Yes
x-amz-date	See Common request headers.	x-amz-date or Date
x-hcp-pretty-print	Optionally, requests that the XML response body be formatted for readability. Valid values are: •true — Format the XML response body for readability. •false — Do not apply any special formatting to the XML response body. The default is false. The values true and false are not case sensitive.	No

The table below describes the headers returned in response to a successful request to list in-progress multipart uploads.

Response header	Description
Content-Type	Specifies the Internet media type of the response body. For a request to list the parts of a multipart upload, the value of this header is always application/xml;charset=UTF-8.
Date	See Common response headers.
Transfer-Encoding	Indicates that HCP could not determine the size of the response body before formulating the response. For a request to list the parts of a multipart upload, the value of this header is always chunked.

HCP returns the list of in-progress multipart uploads in an XML response body, in this format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
     <Bucket>bucket-name</Bucket>
     <KeyMarker>key-marker</KeyMarker>
     <UploadIdMarker>upload-id-marker</UploadIdMarker>
     <NextKeyMarker>object-name-for-last-multipart-upload-in-listing
             </NextKeyMarker>
     <NextUploadIdMarker>upload-id-of-last-multipart-upload-in-listing
             </NextUploadIdMarker>
     <Delimiter>delimiter</Delimiter>
     <Prefix>prefix</Prefix>
     <MaxUploads>maximum-multipart-uploads-to-list</MaxUploads>
     <IsTruncated>false</IsTruncated>
Format for a multipart upload:
     <Upload>
          <Key>object-name</Key>
          <UploadId>upload-id</UploadId>
          <Initiator>
               <ID>initiator-user-id</ID>
               <DisplayName>initiator-username</DisplayName>
          </Initiator>
          <Owner>
               <ID>owner-user-id</ID>
               <DisplayName>owner-username</DisplayName>
          </Owner>
          <StorageClass>STANDARD</StorageClass>
          <Initiated>date-and-time-initiated</Initiated>
     </Upload>
       .
       .
       .
Format for a common prefix:
     <CommonPrefixes>
          <Prefix>prefix</Prefix>
     </CommonPrefixes>
       .
       .
       .
</ListMultipartUploadsResult>

The table below describes the XML elements in the response body returned in response to a request to list the multipart uploads that are in progress in a bucket. The elements are listed in alphabetical order.

Element	Description
Bucket	Child of the ListMultipartUploadsResult element. The Bucket element specifies the name of the bucket targeted by the request.
CommonPrefixes	Child of the ListMultipartUploadsResult and container for the Prefix element. The response body contains one CommonPrefixes element for each common prefix in the multipart upload listing.
Delimiter	Child of the ListMultipartUploadsResult element. The Delimiter element specifies the value of the delimiter query parameter included in the request. If the request did not include the delimiter query parameter, the response body does not include the Delimiter element.
DisplayName	Child of the Initiator or Owner element. If the initiator or owner is identified by an HCP user account, the value of the DisplayName element is the username for that account. If the initiator or owner is identified by an AD user account, the value of the DisplayName element is the username of that account followed by an at sign (@) and the AD domain name.
ID	Child of the Initiator or Owner element. If the initiator or owner is identified by an HCP user account, the value of the ID element is the user ID for that account. If the initiator or owner is identified by an AD user account, the value of the ID element is the SID for that account.
Initiated	Child of the Upload element. The Initiated element specifies the date and time when the applicable multipart upload was initiated, in Greenwich Mean Time (GMT). The date and time are expressed in this format: yyyy-MM-ddTHH:mm:ss.SSSZ For example: 2019-02-18T19:46:03.856Z
Initiator	Child of the Upload element and container for the DisplayName and ID elements. The Initiator element identifies the user who initiated the applicable multipart upload.
IsTruncated	Child of the ListMultipartUploadsResult element. The IsTruncated element indicates whether the returned listing includes the last multipart upload that satisfies the request criteria. Possible values are: •true — The returned listing includes the last multipart upload that satisfies the request criteria. •false — The returned listing does not include the last multipart upload that satisfies the request criteria.
Key	Child of the Upload element. The Key element specifies the name of the object to be created by the applicable multipart upload.
KeyMarker	Child of the ListMultipartUploadsResult element. The KeyMarker element specifies the value of the key-marker query parameter included in the request. If the request did not include the key-marker query parameter, the response body includes KeyMarker as an empty element.
ListMultipartUploads   Result	Root element.
MaxUploads	Child of the ListMultipartUploadsResult element. The MaxUploads element specifies the value of the max-uploads query parameter included in the request. If the request did not include the max-uploads query parameter, the value of the MaxUploads element is 1000.
NextKeyMarker	Child of the ListMultipartUploadsResult element. The NextKeyMarker element specifies the object name for the last multipart upload included in the returned listing. This element is included in the response body only when the value of the IsTruncated element is true. If the returned listing is truncated, you can use the value of the NextKeyMarker element as the value of the key-marker query parameter in a new request to retrieve the next set of multipart uploads that satisfy the request criteria.
NextUploadIdMarker	Child of the ListMultipartUploadsResult element. The NextUploadIdMarker element specifies the upload ID of the last multipart upload included in the returned listing. This element is included in the response body only when the value of the IsTruncated element is true. If the returned listing is truncated, you can use the value of the NextUploadIdMarker element as the value of the upload-id-marker query parameter in a new request to retrieve the next set of multipart uploads that satisfy the request criteria.
Owner	Child of the Upload element and container for the DisplayName and ID elements. The Owner element identifies the user who will own the object created by the applicable multipart upload.
Prefix	One of these: •Child of the ListMultipartUploadsResult. In this case, the Prefix element specifies the value of the prefix query parameter included in the request. If the request did not include the prefix query parameter, the response body includes Prefix as an empty element. •Child of the CommonPrefixes element. In this case, the Prefix element specifies a common prefix.
StorageClass	Child of the Upload element. The value of the StorageClass element is always STANDARD.
Upload	Child of the ListMultipartUploadsResult and container for the elements that describe a multipart upload. The response body contains one Upload element for each multipart upload in the returned listing.
UploadId	Child of the Upload element. The UploadId element specifies the upload ID of the applicable multipart upload.
UploadIdMarker	Child of the ListMultipartUploadsResult element. The UploadIdMarker element specifies the value of the upload-id-marker query parameter included in the request. If the request did not include the upload-id-marker query parameter, the response body does not include the KeyMarker element.

The table below describes HTTP status codes that can be returned in response to a request to list the in-progress multipart uploads in a bucket. For more information on HTTP status codes and the error codes that can accompany them, see Error codes.

Code	Meaning	Description
200	OK	HCP successfully retrieved the requested multipart upload listing.
400	Bad Request	Possible reasons include that a query parameter has an invalid value.
403	Forbidden	Possible reasons include: •The credentials provided with the request are invalid. •You do not have permission to list the in-progress multipart uploads in the specified bucket. •The S3 compatible API is currently disabled for the specified bucket.
404	Not Found	The specified bucket does not exist.
500	Internal Server Error	An internal error occurred. If this error persists, contact your tenant administrator.
503	Service Unavailable	HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator.

This section of the Help contains sample GET requests for listing the in-progress multipart uploads in a bucket.

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to delete a bucket has either of these formats:

•With the bucket name included in the hostname:

DELETE / HTTP/1.1

•With the bucket name following the hostname:

DELETE /bucket-name HTTP/1.1

The table below describes the headers you can use in a request to delete a bucket.

Request header	Description	Required
Authorization	See Authentication.	Yes
Date	See Common request headers.	Date or x-amz-date
Host	See Common request headers.	Yes
x-amz-date	See Common request headers.	x-amz-date or Date

The table below describes the header returned in response to a successful request to delete a bucket.

Response header	Description
Date	See Common response headers.

The table below describes HTTP status codes that can be returned in response to a request to delete a bucket. For more information on HTTP status codes and the error codes that can accompany them, see Error codes.

Code	Meaning	Description
204	No Content	HCP successfully deleted the bucket.
403	Forbidden	Possible reasons include: •The credentials provided with the request are invalid. •You are not the bucket owner. •The S3 compatible API is currently disabled for the specified bucket. •The tenant does not currently support use of the S3 compatible API for deleting buckets.
404	Not Found	The specified bucket does not exist.
409	Conflict	The specified bucket is not empty.
500	Internal Server Error	An internal error occurred. If this error persists, contact your tenant administrator.
503	Service Unavailable	HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator.

Here’s a sample DELETE request that deletes the bucket named sales-mktg.

Request with s3curl command line

./s3curl.pl --id=lgreen --delete -- -k "https://sales-mktg.europe.hcp.example.com"

Request headers

DELETE / HTTP/1.1
Host: sales-mktg.europe.hcp.example.com
Date: Thu, 10 Jan 2019 17:19:26 +0000
Authorization: AWS bGdyZWVu:2nVpI9dSOakB9JZtEyx81RCZTKw=

Response headers

HTTP/1.1 204 No Content
Date: Thu, 10 Jan 2019 17:19:26 GMT