Object Storage API¶

Discoverability¶

If configured, lists the activated capabilities for this version of the OpenStack Object Storage API.

GET

/info

List activated capabilities

Lists the activated capabilities for this version of the OpenStack Object Storage API.

Most of the information is “public” i.e. visible to all callers. However, some configuration and capability items are reserved for the administrators of the system. To access this data, the swiftinfo_sig and swiftinfo_expires query parameters must be added to the request.

Normal response codes: 200 Error response codes:

Request¶

Name	In	Type	Description
swiftinfo_sig (Optional)	query	string	A hash-based message authentication code (HMAC) that enables access to administrator-only information. To use this parameter, the `swiftinfo_expires` parameter is also required.
swiftinfo_expires (Optional)	query	integer	The time at which `swiftinfo_sig` expires. The time is in UNIX Epoch time stamp format.

Response Example¶

{
    "swift": {
        "version": "1.11.0"
    },
    "slo": {
        "max_manifest_segments": 1000,
        "max_manifest_size": 2097152,
        "min_segment_size": 1
    },
    "staticweb": {},
    "tempurl": {}
}

Accounts¶

Lists containers for an account. Creates, updates, shows, and deletes account metadata. For more information and concepts about accounts see Object Storage API overview.

GET

/v1/{account}

Show account details and list containers

Shows details for an account and lists containers, sorted by name, in the account.

The sort order for the name is based on a binary comparison, a single built-in collating sequence that compares string data by using the SQLite memcmp() function, regardless of text encoding. See Collating Sequences.

The response body returns a list of containers. The default response (text/plain) returns one container per line.

If you use query parameters to page through a long list of containers, you have reached the end of the list if the number of items in the returned list is less than the request limit value. The list contains more items if the number of items in the returned list equals the limit value.

When asking for a list of containers and there are none, the response behavior changes depending on whether the request format is text, JSON, or XML. For a text response, you get a 204 , because there is no content. However, for a JSON or XML response, you get a 200 with content indicating an empty array.

Example requests and responses:

Show account details and list containers and ask for a JSON response:

curl -i $publicURL?format=json -X GET -H "X-Auth-Token: $token"

HTTP/1.1 200 OK
Content-Length: 96
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
X-Openstack-Request-Id: tx274a77a8975c4a66aeb24-0052d95365
Date: Fri, 17 Jan 2014 15:59:33 GMT

[
    {
        "count": 0,
        "bytes": 0,
        "name": "janeausten",
        "last_modified": "2013-11-19T20:08:13.283452"
    },
    {
        "count": 1,
        "bytes": 14,
        "name": "marktwain",
        "last_modified": "2016-04-29T16:23:50.460230"
    }
]

Show account details and list containers and ask for an XML response:

curl -i $publicURL?format=xml -X GET -H "X-Auth-Token: $token"

HTTP/1.1 200 OK
Content-Length: 262
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/xml; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b
X-Openstack-Request-Id: tx69f60bc9f7634a01988e6-0052d9544b
Date: Fri, 17 Jan 2014 16:03:23 GMT

<?xml version="1.0" encoding="UTF-8"?>
<account name="my_account">
    <container>
        <name>janeausten</name>
        <count>0</count>
        <bytes>0</bytes>
        <last_modified>2013-11-19T20:08:13.283452</last_modified>
    </container>
    <container>
        <name>marktwain</name>
        <count>1</count>
        <bytes>14</bytes>
        <last_modified>2016-04-29T16:23:50.460230</last_modified>
    </container>
</account>

If the request succeeds, the operation returns one of these status codes:

OK (200). Success. The response body lists the containers.
No Content (204). Success. The response body shows no containers. Either the account has no containers or you are paging through a long list of names by using the marker, limit, or end_marker query parameter and you have reached the end of the list.

Normal response codes: 200 Error response codes:204,

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
limit (Optional)	query	integer	For an integer value n , limits the number of results to n .
marker (Optional)	query	string	For a string value, x , constrains the list to items whose names are greater than x.
end_marker (Optional)	query	string	For a string value, x , constrains the list to items whose names are less than x.
format (Optional)	query	string	The response format. Valid values are `json`, `xml`, or `plain`. The default is `plain`. If you append the `format=xml` or `format=json` query parameter to the storage account URL, the response shows extended container information serialized in that format. If you append the `format=plain` query parameter, the response lists the container names separated by newlines.
prefix (Optional)	query	string	Only objects with this prefix will be returned. When combined with a `delimiter` query, this enables API users to simulate and traverse the objects in a container as if they were in a directory tree.
delimiter (Optional)	query	string	The delimiter is a single character used to split object names to present a pseudo-directory hierarchy of objects. When combined with a `prefix` query, this enables API users to simulate and traverse the objects in a container as if they were in a directory tree.
reverse (Optional)	query	boolean	By default, listings are returned sorted by name, ascending. If you include the `reverse=true` query parameter, the listing will be returned sorted by name, descending.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
X-Newest (Optional)	header	boolean	If set to true , Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.
Accept (Optional)	header	string	Instead of using the `format` query parameter, set this header to `application/json`, `application/xml`, or `text/xml`.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters¶

Name	In	Type	Description
Content-Length	header	string	If the operation succeeds, the length of the response body in bytes. On error, this is the length of the error text.
X-Account-Meta-name (Optional)	header	string	The custom account metadata item, where `name` is the name of the metadata item. One `X-Account-Meta-name` response header appears for each metadata item (for each `name`).
X-Account-Meta-Temp-URL-Key (Optional)	header	string	The secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Account-Meta-Temp-URL-Key-2 (Optional)	header	string	The second secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
X-Account-Bytes-Used	header	integer	The total number of bytes that are stored in Object Storage for the account.
X-Account-Container-Count	header	integer	The number of containers.
X-Account-Object-Count	header	integer	The number of objects in the account.
X-Account-Storage-Policy-name-Bytes-Used	header	integer	The total number of bytes that are stored in in a given storage policy, where `name` is the name of the storage policy.
X-Account-Storage-Policy-name-Container-Count	header	integer	The number of containers in the account that use the given storage policy where `name` is the name of the storage policy.
X-Account-Storage-Policy-name-Object-Count	header	integer	The number of objects in given storage policy where `name` is the name of the storage policy.
X-Account-Meta-Quota-Bytes (Optional)	header	string	If present, this is the limit on the total size in bytes of objects stored in the account. Typically this value is set by an administrator.
X-Account-Access-Control (Optional)	header	string	Note: X-Account-Access-Control is not supported by Keystone auth. The account access control list (ACL) that grants access to containers and objects in the account. If there is no ACL, this header is not returned by this operation. See Account ACLs for more information.
Content-Type	header	string	If the operation succeeds, this value is the MIME type of the list response. The MIME type is determined by the listing format specified by the request and will be one of `text/plain`, `application/json`, `application/xml`, or `text/xml`. If the operation fails, this value is the MIME type of the error text in the response body.
count	body	integer	The number of objects in the container.
bytes	body	integer	The total number of bytes that are stored in Object Storage for the account.
name	body	string	The name of the container.

POST

/v1/{account}

Create, update, or delete account metadata

Creates, updates, or deletes account metadata.

To create, update, or delete custom metadata, use the X-Account-Meta-{name} request header, where {name} is the name of the metadata item.

Account metadata operations work differently than how object metadata operations work. Depending on the contents of your POST account metadata request, the Object Storage API updates the metadata as shown in the following table:

Account metadata operations

POST request header contains	Result
A metadata key without a value. The metadata key already exists for the account.	The API removes the metadata item from the account.
A metadata key without a value. The metadata key does not already exist for the account.	The API ignores the metadata key.
A metadata key value. The metadata key already exists for the account.	The API updates the metadata key value for the account.
A metadata key value. The metadata key does not already exist for the account.	The API adds the metadata key and value pair, or item, to the account.
One or more account metadata items are omitted. The metadata items already exist for the account.	The API does not change the existing metadata items.

To delete a metadata header, send an empty value for that header, such as for the X-Account-Meta-Book header. If the tool you use to communicate with Object Storage, such as an older version of cURL, does not support empty headers, send the X-Remove-Account- Meta-{name} header with an arbitrary value. For example, X-Remove-Account-Meta-Book: x. The operation ignores the arbitrary value.

Note

Metadata keys (the name of the metadata) must be treated as case-insensitive at all times. These keys can contain ASCII 7-bit characters that are not control (0-31) characters, DEL, or a separator character, according to HTTP/1.1 . The underscore character is silently converted to a hyphen.

Note

The metadata value must be UTF-8-encoded and then URL-encoded before you include it in the header. This is a direct violation of the HTTP/1.1 basic rules.

Subsequent requests for the same key and value pair overwrite the existing value.

If the container already has other custom metadata items, a request to create, update, or delete metadata does not affect those items.

This operation does not accept a request body.

Example requests and responses:

Create account metadata:

curl -i $publicURL -X POST -H "X-Auth-Token: $token" -H "X-Account-Meta-Book: MobyDick" -H "X-Account-Meta-Subject: Literature"

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx8c2dd6aee35442a4a5646-0052d954fb
X-Openstack-Request-Id: tx8c2dd6aee35442a4a5646-0052d954fb
Date: Fri, 17 Jan 2014 16:06:19 GMT

Update account metadata:

curl -i $publicURL -X POST -H "X-Auth-Token: $token" -H "X-Account-Meta-Subject: AmericanLiterature"

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx1439b96137364ab581156-0052d95532
X-Openstack-Request-Id: tx1439b96137364ab581156-0052d95532
Date: Fri, 17 Jan 2014 16:07:14 GMT

Delete account metadata:

curl -i $publicURL -X POST -H "X-Auth-Token: $token" -H "X-Remove-Account-Meta-Subject: x"

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx411cf57701424da99948a-0052d9556f
X-Openstack-Request-Id: tx411cf57701424da99948a-0052d9556f
Date: Fri, 17 Jan 2014 16:08:15 GMT

If the request succeeds, the operation returns the No Content (204) response code.

To confirm your changes, issue a show account metadata request.

Error response codes:204,

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
X-Account-Meta-Temp-URL-Key (Optional)	header	string	The secret key value for temporary URLs.
X-Account-Meta-Temp-URL-Key-2 (Optional)	header	string	A second secret key value for temporary URLs. The second key enables you to rotate keys by having two active keys at the same time.
X-Account-Meta-name (Optional)	header	string	The account metadata. The `name` is the name of metadata item that you want to add, update, or delete. To delete this item, send an empty value in this header. You must specify an `X-Account-Meta-name` header for each metadata item (for each `name`) that you want to add, update, or delete.
X-Remove-Account-name (Optional)	header	string	Removes the metadata item named `name`. For example, `X-Remove-Account-Meta-Blue` removes custom metadata.
X-Account-Access-Control (Optional)	header	string	Note: X-Account-Access-Control is not supported by Keystone auth. Sets an account access control list (ACL) that grants access to containers and objects in the account. See Account ACLs for more information.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters¶

Name	In	Type	Description
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
Content-Length	header	string	If the operation succeeds, this value is zero (0) or the length of informational or error text in the response body.
Content-Type (Optional)	header	string	If present, this value is the MIME type of the informational or error text in the response body.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)

HEAD

/v1/{account}

Show account metadata

Shows metadata for an account.

Metadata for the account includes:

Number of containers
Number of objects
Total number of bytes that are stored in Object Storage for the account

Because the storage system can store large amounts of data, take care when you represent the total bytes response as an integer; when possible, convert it to a 64-bit unsigned integer if your platform supports that primitive type.

Do not include metadata headers in this request.

Show account metadata request:

curl -i $publicURL -X HEAD -H "X-Auth-Token: $token"

HTTP/1.1 204 No Content
Content-Length: 0
X-Account-Object-Count: 1
X-Account-Meta-Book: MobyDick
X-Timestamp: 1389453423.35964
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: text/plain; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: txafb3504870144b8ca40f7-0052d955d4
X-Openstack-Request-Id: txafb3504870144b8ca40f7-0052d955d4
Date: Fri, 17 Jan 2014 16:09:56 GMT

If the account or authentication token is not valid, the operation returns the Unauthorized (401) response code.

Error response codes:204,401,

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
X-Newest (Optional)	header	boolean	If set to true , Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters¶

Name	In	Type	Description
Content-Length	header	string	If the operation succeeds, this value is zero (0) or the length of informational or error text in the response body.
X-Account-Meta-name (Optional)	header	string	The custom account metadata item, where `name` is the name of the metadata item. One `X-Account-Meta-name` response header appears for each metadata item (for each `name`).
X-Account-Meta-Temp-URL-Key (Optional)	header	string	The secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Account-Meta-Temp-URL-Key-2 (Optional)	header	string	The second secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
X-Account-Bytes-Used	header	integer	The total number of bytes that are stored in Object Storage for the account.
X-Account-Object-Count	header	integer	The number of objects in the account.
X-Account-Container-Count	header	integer	The number of containers.
X-Account-Storage-Policy-name-Bytes-Used	header	integer	The total number of bytes that are stored in in a given storage policy, where `name` is the name of the storage policy.
X-Account-Storage-Policy-name-Container-Count	header	integer	The number of containers in the account that use the given storage policy where `name` is the name of the storage policy.
X-Account-Storage-Policy-name-Object-Count	header	integer	The number of objects in given storage policy where `name` is the name of the storage policy.
X-Account-Meta-Quota-Bytes (Optional)	header	string	If present, this is the limit on the total size in bytes of objects stored in the account. Typically this value is set by an administrator.
X-Account-Access-Control (Optional)	header	string	Note: X-Account-Access-Control is not supported by Keystone auth. The account access control list (ACL) that grants access to containers and objects in the account. If there is no ACL, this header is not returned by this operation. See Account ACLs for more information.
Content-Type (Optional)	header	string	If present, this value is the MIME type of the informational or error text in the response body.

DELETE

/v1/{account}

Delete the specified account

Deletes the specified account when a reseller admin issues this request. Accounts are only deleted by (1) having a reseller admin level auth token (2) sending a DELETE to a proxy server for the account to be deleted and (3) that proxy server having the allow_account_management” config option set to true.

Note that an issuing a DELETE request simply marks the account for deletion later as outlined in the link: https://docs.openstack.org/swift/latest/overview_reaper.html.

Take care when performing this operation because deleting an account is a one-way operation that is not trivially recoverable. It’s crucial to note that in an OpenStack context, you should delete an account after the project/tenant has been deleted from Keystone.

curl -i $publicURL -X DELETE -H 'X-Auth-Token: $<reseller admin token>'

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Account-Status: Deleted
X-Trans-Id: tx91ce60a640cc42eca198a-006128c180
X-Openstack-Request-Id: tx91ce60a640cc42eca198a-006128c180
Date: Fri, 27 Aug 2021 11:42:08 GMT

If the account or authentication token is not valid, the operation returns the Unauthorized (401). If you try to delete an account with a non-admin token, a 403 Forbidden response code is returned. If you give a non-existent account or an invalid URL, a 404 Not Found response code is returned.

Error response codes:204,401,403,404.

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).

Response Parameters¶

Name	In	Type	Description
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
Content-Length	header	string	If the operation succeeds, this value is zero (0) or the length of informational or error text in the response body.
Content-Type (Optional)	header	string	If present, this value is the MIME type of the informational or error text in the response body.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)

Containers¶

Lists objects in a container. Creates, shows details for, and deletes containers. Creates, updates, shows, and deletes container metadata. For more information and concepts about containers see Object Storage API overview.

GET

/v1/{account}/{container}

Show container details and list objects

Shows details for a container and lists objects, sorted by name, in the container.

Specify query parameters in the request to filter the list and return a subset of objects. Omit query parameters to return a list of objects that are stored in the container, up to 10,000 names. The 10,000 maximum value is configurable. To view the value for the cluster, issue a GET /info request.

Example requests and responses:

OK (200). Success. The response body lists the objects.
No Content (204). Success. The response body shows no objects. Either the container has no objects or you are paging through a long list of objects by using the marker, limit, or end_marker query parameter and you have reached the end of the list.

If the container does not exist, the call returns the Not Found (404) response code.

Normal response codes: 200, 204

Error response codes: 404

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
container (Optional)	path	string	The unique (within an account) name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (`/`) character because this character delimits the container and object name. For example, the path `/v1/account/www/pages` specifies the `www` container, not the `www/pages` container.
limit (Optional)	query	integer	For an integer value n , limits the number of results to n .
marker (Optional)	query	string	For a string value, x , constrains the list to items whose names are greater than x.
end_marker (Optional)	query	string	For a string value, x , constrains the list to items whose names are less than x.
prefix (Optional)	query	string	Only objects with this prefix will be returned. When combined with a `delimiter` query, this enables API users to simulate and traverse the objects in a container as if they were in a directory tree.
format (Optional)	query	string	The response format. Valid values are `json`, `xml`, or `plain`. The default is `plain`. If you append the `format=xml` or `format=json` query parameter to the storage account URL, the response shows extended container information serialized in that format. If you append the `format=plain` query parameter, the response lists the container names separated by newlines.
delimiter (Optional)	query	string	The delimiter is a single character used to split object names to present a pseudo-directory hierarchy of objects. When combined with a `prefix` query, this enables API users to simulate and traverse the objects in a container as if they were in a directory tree.
path (Optional)	query	string	For a string value, returns the object names that are nested in the pseudo path. Please use `prefix`/`delimiter` queries instead of using this `path` query.
reverse (Optional)	query	boolean	By default, listings are returned sorted by name, ascending. If you include the `reverse=true` query parameter, the listing will be returned sorted by name, descending.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
X-Newest (Optional)	header	boolean	If set to true , Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.
Accept (Optional)	header	string	Instead of using the `format` query parameter, set this header to `application/json`, `application/xml`, or `text/xml`.
X-Container-Meta-Temp-URL-Key (Optional)	header	string	The secret key value for temporary URLs.
X-Container-Meta-Temp-URL-Key-2 (Optional)	header	string	A second secret key value for temporary URLs. The second key enables you to rotate keys by having two active keys at the same time.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.
X-Storage-Policy (Optional)	header	string	In requests, specifies the name of the storage policy to use for the container. In responses, is the storage policy name. The storage policy of the container cannot be changed.

Response Parameters¶

Name	In	Type	Description
X-Container-Meta-name	header	string	The custom container metadata item, where `name` is the name of the metadata item. One `X-Container-Meta-name` response header appears for each metadata item (for each `name`).
Content-Length	header	string	If the operation succeeds, the length of the response body in bytes. On error, this is the length of the error text.
X-Container-Object-Count	header	integer	The number of objects.
X-Container-Bytes-Used	header	integer	The total number of bytes used.
Accept-Ranges	header	string	The type of ranges that the object accepts.
X-Container-Meta-Temp-URL-Key (Optional)	header	string	The secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Container-Meta-Temp-URL-Key-2 (Optional)	header	string	The second secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Container-Meta-Quota-Count (Optional)	header	string	The maximum object count of the container. If not set, this header is not returned by this operation.
X-Container-Meta-Quota-Bytes (Optional)	header	string	The maximum size of the container, in bytes. If not set, this header is not returned by this operation.
X-Storage-Policy (Optional)	header	string	In requests, specifies the name of the storage policy to use for the container. In responses, is the storage policy name. The storage policy of the container cannot be changed.
X-Container-Read (Optional)	header	string	The ACL that grants read access. If there is no ACL, this header is not returned by this operation. See Container ACLs for more information.
X-Container-Write (Optional)	header	string	The ACL that grants write access. If there is no ACL, this header is not returned by this operation. See Container ACLs for more information.
X-Container-Sync-Key (Optional)	header	string	The secret key for container synchronization. If not set, this header is not returned by this operation.
X-Container-Sync-To (Optional)	header	string	The destination for container synchronization. If not set, this header is not returned by this operation.
X-Versions-Location (Optional)	header	string	If present, this container has versioning enabled and the value is the UTF-8 encoded name of another container. For more information about object versioning, see Object versioning.
X-History-Location (Optional)	header	string	If present, this container has versioning enabled and the value is the UTF-8 encoded name of another container. For more information about object versioning, see Object versioning.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)
Content-Type	header	string	If the operation succeeds, this value is the MIME type of the list response. The MIME type is determined by the listing format specified by the request and will be one of `text/plain`, `application/json`, `application/xml`, or `text/xml`. If the operation fails, this value is the MIME type of the error text in the response body.
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
hash	body	string	The MD5 checksum value of the object content.
last_modified	body	string	The date and time when the object was last modified. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm For example, `2015-08-27T09:49:58-05:00`. The `±hh:mm` value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is `-05:00`.
content_type	body	string	The content type of the object.
bytes	body	integer	The total number of bytes that are stored in Object Storage for the container.
name	body	string	The name of the object.
symlink_path	body	string	This field exists only when the object is symlink. This is the target path of the symlink object.

Response Example format=json¶

HTTP/1.1 200 OK
Content-Length: 341
X-Container-Object-Count: 2
Accept-Ranges: bytes
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Bytes-Used: 26
Content-Type: application/json; charset=utf-8
X-Trans-Id: tx26377fe5fab74869825d1-0052d6bdff
X-Openstack-Request-Id: tx26377fe5fab74869825d1-0052d6bdff
Date: Wed, 15 Jan 2014 16:57:35 GMT

[
    {
        "hash": "451e372e48e0f6b1114fa0724aa79fa1",
        "last_modified": "2014-01-15T16:41:49.390270",
        "bytes": 14,
        "name": "goodbye",
        "content_type": "application/octet-stream"
    },
    {
        "hash": "ed076287532e86365e841e92bfc50d8c",
        "last_modified": "2014-01-15T16:37:43.427570",
        "bytes": 12,
        "name": "helloworld",
        "content_type": "application/octet-stream"
    }
]

Response Example format=xml¶

HTTP/1.1 200 OK
Content-Length: 500
X-Container-Object-Count: 2
Accept-Ranges: bytes
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Bytes-Used: 26
Content-Type: application/xml; charset=utf-8
X-Trans-Id: txc75ea9a6e66f47d79e0c5-0052d6be76
X-Openstack-Request-Id: txc75ea9a6e66f47d79e0c5-0052d6be76
Date: Wed, 15 Jan 2014 16:59:35 GMT

<?xml version="1.0" encoding="UTF-8"?>
<container name="marktwain">
    <object>
        <name>goodbye</name>
        <hash>451e372e48e0f6b1114fa0724aa79fa1</hash>
        <bytes>14</bytes>
        <content_type>application/octet-stream</content_type>
        <last_modified>2014-01-15T16:41:49.390270</last_modified>
    </object>
    <object>
        <name>helloworld</name>
        <hash>ed076287532e86365e841e92bfc50d8c</hash>
        <bytes>12</bytes>
        <content_type>application/octet-stream</content_type>
        <last_modified>2014-01-15T16:37:43.427570</last_modified>
    </object>
</container>

PUT

/v1/{account}/{container}

Create container

Creates a container.

You do not need to check whether a container already exists before issuing a PUT operation because the operation is idempotent: It creates a container or updates an existing container, as appropriate.

To create, update, or delete a custom metadata item, use the X -Container-Meta-{name} header, where {name} is the name of the metadata item.

Note

The metadata value must be UTF-8-encoded and then URL-encoded before you include it in the header. This is a direct violation of the HTTP/1.1 basic rules.

Example requests and responses:

Create a container with no metadata:

curl -i $publicURL/steven -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"

HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx7f6b7fa09bc2443a94df0-0052d58b56
X-Openstack-Request-Id: tx7f6b7fa09bc2443a94df0-0052d58b56
Date: Tue, 14 Jan 2014 19:09:10 GMT

Create a container with metadata:

curl -i $publicURL/marktwain -X PUT -H "X-Auth-Token: $token" -H "X-Container-Meta-Book: TomSawyer"

HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37
X-Openstack-Request-Id: tx06021f10fc8642b2901e7-0052d58f37
Date: Tue, 14 Jan 2014 19:25:43 GMT

Create a container with an ACL to allow anybody to get an object in the marktwain container:

curl -i $publicURL/marktwain -X PUT -H "X-Auth-Token: $token" -H "X-Container-Read: .r:*"

HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37
X-Openstack-Request-Id: tx06021f10fc8642b2901e7-0052d58f37
Date: Tue, 14 Jan 2014 19:25:43 GMT

Normal response codes: 201, 202

Error response codes: 400, 404, 507

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
container (Optional)	path	string	The unique (within an account) name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (`/`) character because this character delimits the container and object name. For example, the path `/v1/account/www/pages` specifies the `www` container, not the `www/pages` container.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
X-Container-Read (Optional)	header	string	Sets a container access control list (ACL) that grants read access. The scope of the access is specific to the container. The ACL grants the ability to perform GET or HEAD operations on objects in the container or to perform a GET or HEAD operation on the container itself. The format and scope of the ACL is dependent on the authorization system used by the Object Storage service. See Container ACLs for more information.
X-Container-Write (Optional)	header	string	Sets a container access control list (ACL) that grants write access. The scope of the access is specific to the container. The ACL grants the ability to perform PUT, POST and DELETE operations on objects in the container. It does not grant write access to the container metadata. The format of the ACL is dependent on the authorization system used by the Object Storage service. See Container ACLs for more information.
X-Container-Sync-To (Optional)	header	string	Sets the destination for container synchronization. Used with the secret key indicated in the `X -Container-Sync-Key` header. If you want to stop a container from synchronizing, send a blank value for the `X-Container-Sync-Key` header.
X-Container-Sync-Key (Optional)	header	string	Sets the secret key for container synchronization. If you remove the secret key, synchronization is halted. For more information, see Container to Container Synchronization
X-Versions-Location (Optional)	header	string	The URL-encoded UTF-8 representation of the container that stores previous versions of objects. If neither this nor `X-History-Location` is set, versioning is disabled for this container. `X-Versions-Location` and `X-History-Location` cannot both be set at the same time. For more information about object versioning, see Object versioning.
X-History-Location (Optional)	header	string	The URL-encoded UTF-8 representation of the container that stores previous versions of objects. If neither this nor `X-Versions-Location` is set, versioning is disabled for this container. `X-History-Location` and `X-Versions-Location` cannot both be set at the same time. For more information about object versioning, see Object versioning.
X-Container-Meta-name (Optional)	header	string	The container metadata, where `name` is the name of metadata item. You must specify an `X-Container-Meta-name` header for each metadata item (for each `name`) that you want to add or update.
X-Container-Meta-Access-Control-Allow-Origin (Optional)	header	string	Originating URLs allowed to make cross-origin requests (CORS), separated by spaces. This heading applies to the container only, and all objects within the container with this header applied are CORS-enabled for the allowed origin URLs. A browser (user-agent) typically issues a preflighted request , which is an OPTIONS call that verifies the origin is allowed to make the request. The Object Storage service returns 200 if the originating URL is listed in this header parameter, and issues a 401 if the originating URL is not allowed to make a cross-origin request. Once a 200 is returned, the browser makes a second request to the Object Storage service to retrieve the CORS-enabled object.
X-Container-Meta-Access-Control-Max-Age (Optional)	header	string	Maximum time for the origin to hold the preflight results. A browser may make an OPTIONS call to verify the origin is allowed to make the request. Set the value to an integer number of seconds after the time that the request was received.
X-Container-Meta-Access-Control-Expose-Headers (Optional)	header	string	Headers the Object Storage service exposes to the browser (technically, through the `user-agent` setting), in the request response, separated by spaces. By default the Object Storage service returns the following headers: All “simple response headers” as listed on http://www.w3.org/TR/cors/#simple-response-header. The headers `etag`, `x-timestamp`, `x-trans-id`, `x-openstack-request-id`. All metadata headers (`X-Container-Meta-` for containers and `X-Object-Meta-` for objects). headers listed in `X-Container-Meta-Access-Control-Expose-Headers`.
X-Container-Meta-Quota-Bytes (Optional)	header	string	Sets maximum size of the container, in bytes. Typically these values are set by an administrator. Returns a 413 response (request entity too large) when an object PUT operation exceeds this quota value. This value does not take effect immediately. see Container Quotas for more information.
X-Container-Meta-Quota-Count (Optional)	header	string	Sets maximum object count of the container. Typically these values are set by an administrator. Returns a 413 response (request entity too large) when an object PUT operation exceeds this quota value. This value does not take effect immediately. see Container Quotas for more information.
X-Container-Meta-Temp-URL-Key (Optional)	header	string	The secret key value for temporary URLs.
X-Container-Meta-Temp-URL-Key-2 (Optional)	header	string	A second secret key value for temporary URLs. The second key enables you to rotate keys by having two active keys at the same time.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.
X-Storage-Policy (Optional)	header	string	In requests, specifies the name of the storage policy to use for the container. In responses, is the storage policy name. The storage policy of the container cannot be changed.

Response Parameters¶

Name	In	Type	Description
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
Content-Length	header	string	If the operation succeeds, this value is zero (0) or the length of informational or error text in the response body.
Content-Type (Optional)	header	string	If present, this value is the MIME type of the informational or error text in the response body.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)

POST

/v1/{account}/{container}

Create, update, or delete container metadata

Creates, updates, or deletes custom metadata for a container.

To create, update, or delete a custom metadata item, use the X -Container-Meta-{name} header, where {name} is the name of the metadata item.

Note

The metadata value must be UTF-8-encoded and then URL-encoded before you include it in the header. This is a direct violation of the HTTP/1.1 basic rules.

Subsequent requests for the same key and value pair overwrite the previous value.

To delete container metadata, send an empty value for that header, such as for the X-Container-Meta-Book header. If the tool you use to communicate with Object Storage, such as an older version of cURL, does not support empty headers, send the X-Remove- Container-Meta-{name} header with an arbitrary value. For example, X-Remove-Container-Meta-Book: x. The operation ignores the arbitrary value.

If the container already has other custom metadata items, a request to create, update, or delete metadata does not affect those items.

Example requests and responses:

Create container metadata:

curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Container-Meta-Author: MarkTwain" -H "X-Container-Meta-Web-Directory-Type: text/directory" -H "X-Container-Meta-Century: Nineteenth"

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx05dbd434c651429193139-0052d82635
X-Openstack-Request-Id: tx05dbd434c651429193139-0052d82635
Date: Thu, 16 Jan 2014 18:34:29 GMT

Update container metadata:

curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Container-Meta-Author: SamuelClemens"

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txe60c7314bf614bb39dfe4-0052d82653
X-Openstack-Request-Id: txe60c7314bf614bb39dfe4-0052d82653
Date: Thu, 16 Jan 2014 18:34:59 GMT

Delete container metadata:

curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Remove-Container-Meta-Century: x"

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx7997e18da2a34a9e84ceb-0052d826d0
X-Openstack-Request-Id: tx7997e18da2a34a9e84ceb-0052d826d0
Date: Thu, 16 Jan 2014 18:37:04 GMT

If the request succeeds, the operation returns the No Content (204) response code.

To confirm your changes, issue a show container metadata request.

Normal response codes: 204

Error response codes: 404

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
container (Optional)	path	string	The unique (within an account) name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (`/`) character because this character delimits the container and object name. For example, the path `/v1/account/www/pages` specifies the `www` container, not the `www/pages` container.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
X-Container-Read (Optional)	header	string	Sets a container access control list (ACL) that grants read access. The scope of the access is specific to the container. The ACL grants the ability to perform GET or HEAD operations on objects in the container or to perform a GET or HEAD operation on the container itself. The format and scope of the ACL is dependent on the authorization system used by the Object Storage service. See Container ACLs for more information.
X-Remove-Container-name (Optional)	header	string	Removes the metadata item named `name`. For example, `X-Remove-Container-Read` removes the `X-Container-Read` metadata item and `X-Remove-Container-Meta-Blue` removes custom metadata.
X-Container-Write (Optional)	header	string	Sets a container access control list (ACL) that grants write access. The scope of the access is specific to the container. The ACL grants the ability to perform PUT, POST and DELETE operations on objects in the container. It does not grant write access to the container metadata. The format of the ACL is dependent on the authorization system used by the Object Storage service. See Container ACLs for more information.
X-Container-Sync-To (Optional)	header	string	Sets the destination for container synchronization. Used with the secret key indicated in the `X -Container-Sync-Key` header. If you want to stop a container from synchronizing, send a blank value for the `X-Container-Sync-Key` header.
X-Container-Sync-Key (Optional)	header	string	Sets the secret key for container synchronization. If you remove the secret key, synchronization is halted. For more information, see Container to Container Synchronization
X-Versions-Location (Optional)	header	string	The URL-encoded UTF-8 representation of the container that stores previous versions of objects. If neither this nor `X-History-Location` is set, versioning is disabled for this container. `X-Versions-Location` and `X-History-Location` cannot both be set at the same time. For more information about object versioning, see Object versioning.
X-History-Location (Optional)	header	string	The URL-encoded UTF-8 representation of the container that stores previous versions of objects. If neither this nor `X-Versions-Location` is set, versioning is disabled for this container. `X-History-Location` and `X-Versions-Location` cannot both be set at the same time. For more information about object versioning, see Object versioning.
X-Remove-Versions-Location (Optional)	header	string	Set to any value to disable versioning. Note that this disables version that was set via `X-History-Location` as well.
X-Remove-History-Location (Optional)	header	string	Set to any value to disable versioning. Note that this disables version that was set via `X-Versions-Location` as well.
X-Container-Meta-name (Optional)	header	string	The container metadata, where `name` is the name of metadata item. You must specify an `X-Container-Meta-name` header for each metadata item (for each `name`) that you want to add or update.
X-Container-Meta-Access-Control-Allow-Origin (Optional)	header	string	Originating URLs allowed to make cross-origin requests (CORS), separated by spaces. This heading applies to the container only, and all objects within the container with this header applied are CORS-enabled for the allowed origin URLs. A browser (user-agent) typically issues a preflighted request , which is an OPTIONS call that verifies the origin is allowed to make the request. The Object Storage service returns 200 if the originating URL is listed in this header parameter, and issues a 401 if the originating URL is not allowed to make a cross-origin request. Once a 200 is returned, the browser makes a second request to the Object Storage service to retrieve the CORS-enabled object.
X-Container-Meta-Access-Control-Max-Age (Optional)	header	string	Maximum time for the origin to hold the preflight results. A browser may make an OPTIONS call to verify the origin is allowed to make the request. Set the value to an integer number of seconds after the time that the request was received.
X-Container-Meta-Access-Control-Expose-Headers (Optional)	header	string	Headers the Object Storage service exposes to the browser (technically, through the `user-agent` setting), in the request response, separated by spaces. By default the Object Storage service returns the following headers: All “simple response headers” as listed on http://www.w3.org/TR/cors/#simple-response-header. The headers `etag`, `x-timestamp`, `x-trans-id`, `x-openstack-request-id`. All metadata headers (`X-Container-Meta-` for containers and `X-Object-Meta-` for objects). headers listed in `X-Container-Meta-Access-Control-Expose-Headers`.
X-Container-Meta-Quota-Bytes (Optional)	header	string	Sets maximum size of the container, in bytes. Typically these values are set by an administrator. Returns a 413 response (request entity too large) when an object PUT operation exceeds this quota value. This value does not take effect immediately. see Container Quotas for more information.
X-Container-Meta-Quota-Count (Optional)	header	string	Sets maximum object count of the container. Typically these values are set by an administrator. Returns a 413 response (request entity too large) when an object PUT operation exceeds this quota value. This value does not take effect immediately. see Container Quotas for more information.
X-Container-Meta-Web-Directory-Type (Optional)	header	string	Sets the content-type of directory marker objects. If the header is not set, default is `application/directory`. Directory marker objects are 0-byte objects that represent directories to create a simulated hierarchical structure. For example, if you set `"X-Container- Meta-Web-Directory-Type: text/directory"`, Object Storage treats 0-byte objects with a content-type of `text/directory` as directories rather than objects.
X-Container-Meta-Temp-URL-Key (Optional)	header	string	The secret key value for temporary URLs.
X-Container-Meta-Temp-URL-Key-2 (Optional)	header	string	A second secret key value for temporary URLs. The second key enables you to rotate keys by having two active keys at the same time.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters¶

Name	In	Type	Description
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
Content-Length	header	string	If the operation succeeds, this value is zero (0) or the length of informational or error text in the response body.
Content-Type (Optional)	header	string	If present, this value is the MIME type of the informational or error text in the response body.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)

HEAD

/v1/{account}/{container}

Show container metadata

Shows container metadata, including the number of objects and the total bytes of all objects stored in the container.

Show container metadata request:

curl -i $publicURL/marktwain -X HEAD -H "X-Auth-Token: $token"

HTTP/1.1 204 No Content
Content-Length: 0
X-Container-Object-Count: 1
Accept-Ranges: bytes
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Meta-Author: SamuelClemens
X-Container-Bytes-Used: 14
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx0287b982a268461b9ec14-0052d826e2
X-Openstack-Request-Id: tx0287b982a268461b9ec14-0052d826e2
Date: Thu, 16 Jan 2014 18:37:22 GMT

If the request succeeds, the operation returns the No Content (204) response code.

Normal response codes: 204

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
container (Optional)	path	string	The unique (within an account) name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (`/`) character because this character delimits the container and object name. For example, the path `/v1/account/www/pages` specifies the `www` container, not the `www/pages` container.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
X-Newest (Optional)	header	boolean	If set to true , Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters¶

Name	In	Type	Description
X-Container-Meta-name	header	string	The custom container metadata item, where `name` is the name of the metadata item. One `X-Container-Meta-name` response header appears for each metadata item (for each `name`).
Content-Length	header	string	If the operation succeeds, this value is zero (0) or the length of informational or error text in the response body.
X-Container-Object-Count	header	integer	The number of objects.
X-Container-Bytes-Used	header	integer	The total number of bytes used.
X-Container-Write (Optional)	header	string	The ACL that grants write access. If there is no ACL, this header is not returned by this operation. See Container ACLs for more information.
X-Container-Meta-Quota-Bytes (Optional)	header	string	The maximum size of the container, in bytes. If not set, this header is not returned by this operation.
X-Container-Meta-Quota-Count (Optional)	header	string	The maximum object count of the container. If not set, this header is not returned by this operation.
Accept-Ranges	header	string	The type of ranges that the object accepts.
X-Container-Read (Optional)	header	string	The ACL that grants read access. If there is no ACL, this header is not returned by this operation. See Container ACLs for more information.
X-Container-Meta-Access-Control-Expose-Headers (Optional)	header	string	Headers the Object Storage service exposes to the browser (technically, through the `user-agent` setting), in the request response, separated by spaces. By default the Object Storage service returns the following headers: All “simple response headers” as listed on http://www.w3.org/TR/cors/#simple-response-header. The headers `etag`, `x-timestamp`, `x-trans-id`, `x-openstack-request-id`. All metadata headers (`X-Container-Meta-` for containers and `X-Object-Meta-` for objects). headers listed in `X-Container-Meta-Access-Control-Expose-Headers`.
X-Container-Meta-Temp-URL-Key (Optional)	header	string	The secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Container-Meta-Temp-URL-Key-2 (Optional)	header	string	The second secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
X-Container-Meta-Access-Control-Allow-Origin (Optional)	header	string	Originating URLs allowed to make cross-origin requests (CORS), separated by spaces. This heading applies to the container only, and all objects within the container with this header applied are CORS-enabled for the allowed origin URLs. A browser (user-agent) typically issues a preflighted request , which is an OPTIONS call that verifies the origin is allowed to make the request. The Object Storage service returns 200 if the originating URL is listed in this header parameter, and issues a 401 if the originating URL is not allowed to make a cross-origin request. Once a 200 is returned, the browser makes a second request to the Object Storage service to retrieve the CORS-enabled object.
X-Container-Meta-Access-Control-Max-Age (Optional)	header	string	Maximum time for the origin to hold the preflight results. A browser may make an OPTIONS call to verify the origin is allowed to make the request. Set the value to an integer number of seconds after the time that the request was received.
X-Container-Sync-Key (Optional)	header	string	The secret key for container synchronization. If not set, this header is not returned by this operation.
X-Container-Sync-To (Optional)	header	string	The destination for container synchronization. If not set, this header is not returned by this operation.
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)
Content-Type (Optional)	header	string	If present, this value is the MIME type of the informational or error text in the response body.
X-Versions-Location (Optional)	header	string	If present, this container has versioning enabled and the value is the UTF-8 encoded name of another container. For more information about object versioning, see Object versioning.
X-History-Location (Optional)	header	string	If present, this container has versioning enabled and the value is the UTF-8 encoded name of another container. For more information about object versioning, see Object versioning.
X-Storage-Policy (Optional)	header	string	In requests, specifies the name of the storage policy to use for the container. In responses, is the storage policy name. The storage policy of the container cannot be changed.

DELETE

/v1/{account}/{container}

Delete container

Deletes an empty container.

This operation fails unless the container is empty. An empty container has no objects.

Delete the steven container:

curl -i $publicURL/steven -X DELETE -H "X-Auth-Token: $token"

If the container does not exist, the response is:

HTTP/1.1 404 Not Found
Content-Length: 70
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx4d728126b17b43b598bf7-0052d81e34
X-Openstack-Request-Id: tx4d728126b17b43b598bf7-0052d81e34
Date: Thu, 16 Jan 2014 18:00:20 GMT

If the container exists and the deletion succeeds, the response is:

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txf76c375ebece4df19c84c-0052d81f14
X-Openstack-Request-Id: txf76c375ebece4df19c84c-0052d81f14
Date: Thu, 16 Jan 2014 18:04:04 GMT

If the container exists but is not empty, the response is:

HTTP/1.1 409 Conflict
Content-Length: 95
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx7782dc6a97b94a46956b5-0052d81f6b
X-Openstack-Request-Id: tx7782dc6a97b94a46956b5-0052d81f6b
Date: Thu, 16 Jan 2014 18:05:31 GMT
<html>
<h1>Conflict
</h1>
<p>There was a conflict when trying to complete your request.
</p>
</html>

Normal response codes: 204

Error response codes: 404, 409

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
container (Optional)	path	string	The unique (within an account) name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (`/`) character because this character delimits the container and object name. For example, the path `/v1/account/www/pages` specifies the `www` container, not the `www/pages` container.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters¶

Name	In	Type	Description
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
Content-Length	header	string	If the operation succeeds, this value is zero (0) or the length of informational or error text in the response body.
Content-Type (Optional)	header	string	If present, this value is the MIME type of the informational or error text in the response body.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)

Objects¶

Creates, replaces, shows details for, and deletes objects. Copies objects from another object with a new or different name. Updates object metadata. For more information and concepts about objects see Object Storage API overview and Large Objects.

GET

/v1/{account}/{container}/{object}

Get object content and metadata

Downloads the object content and gets the object metadata.

This operation returns the object metadata in the response headers and the object content in the response body.

If this is a large object, the response body contains the concatenated content of the segment objects. To get the manifest instead of concatenated segment objects for a static large object, use the multipart-manifest query parameter.

Example requests and responses:

Show object details for the goodbye object in the marktwain container:

curl -i $publicURL/marktwain/goodbye -X GET -H "X-Auth-Token: $token"

HTTP/1.1 200 OK
Content-Length: 14
Accept-Ranges: bytes
Last-Modified: Wed, 15 Jan 2014 16:41:49 GMT
Etag: 451e372e48e0f6b1114fa0724aa79fa1
X-Timestamp: 1389804109.39027
X-Object-Meta-Orig-Filename: goodbyeworld.txt
Content-Type: application/octet-stream
X-Trans-Id: tx8145a190241f4cf6b05f5-0052d82a34
X-Openstack-Request-Id: tx8145a190241f4cf6b05f5-0052d82a34
Date: Thu, 16 Jan 2014 18:51:32 GMT
Goodbye World!

Show object details for the goodbye object, which does not exist, in the janeausten container:

curl -i $publicURL/janeausten/goodbye -X GET -H "X-Auth-Token: $token"

HTTP/1.1 404 Not Found
Content-Length: 70
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx073f7cbb850c4c99934b9-0052d82b04
X-Openstack-Request-Id: tx073f7cbb850c4c99934b9-0052d82b04
Date: Thu, 16 Jan 2014 18:55:00 GMT
<html>
<h1>Not Found
</h1>
<p>The resource could not be found.
</p>
</html>

The operation returns the Range Not Satisfiable (416) response code for any ranged GET requests that specify more than:

Fifty ranges.
Three overlapping ranges.
Eight non-increasing ranges.

Normal response codes: 200

Error response codes: 416, 404

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
container (Optional)	path	string	The unique (within an account) name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (`/`) character because this character delimits the container and object name. For example, the path `/v1/account/www/pages` specifies the `www` container, not the `www/pages` container.
object (Optional)	path	string	The unique name for the object.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
X-Newest (Optional)	header	boolean	If set to true , Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.
temp_url_sig	query	string	Used with temporary URLs to sign the request with an HMAC-SHA1 cryptographic signature that defines the allowed HTTP method, expiration date, full path to the object, and the secret key for the temporary URL. For more information about temporary URLs, see Temporary URL middleware.
temp_url_expires	query	integer	The date and time in UNIX Epoch time stamp format or ISO 8601 UTC timestamp when the signature for temporary URLs expires. For example, `1440619048` or `2015-08-26T19:57:28Z` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`. For more information about temporary URLs, see Temporary URL middleware.
filename (Optional)	query	string	Overrides the default file name. Object Storage generates a default file name for GET temporary URLs that is based on the object name. Object Storage returns this value in the `Content-Disposition` response header. Browsers can interpret this file name value as a file attachment to save. For more information about temporary URLs, see Temporary URL middleware.
multipart-manifest (Optional)	query	string	If you include the `multipart-manifest=get` query parameter and the object is a large object, the object contents are not returned. Instead, the manifest is returned in the `X-Object-Manifest` response header for dynamic large objects or in the response body for static large objects.
symlink (Optional)	query	string	If you include the `symlink=get` query parameter and the object is a symlink, then the response will include data and metadata from the symlink itself rather than from the target.
Range (Optional)	header	string	The ranges of content to get. You can use the `Range` header to get portions of data by using one or more range specifications. To specify many ranges, separate the range specifications with a comma. The types of range specifications are: - Byte range specification. Use FIRST_BYTE_OFFSET to specify the start of the data range, and LAST_BYTE_OFFSET to specify the end. You can omit the LAST_BYTE_OFFSET and if you do, the value defaults to the offset of the last byte of data. - Suffix byte range specification. Use LENGTH bytes to specify the length of the data range. The following forms of the header specify the following ranges of data: `Range: bytes=-5`. The last five bytes. `Range: bytes=10-15`. The six bytes of data after a 10-byte offset. `Range: bytes=10-15,-5`. A multi-part response that contains the last five bytes and the six bytes of data after a 10-byte offset. The `Content-Type` response header contains `multipart/byteranges`. `Range: bytes=4-6`. Bytes 4 to 6 inclusive. `Range: bytes=2-2`. Byte 2, the third byte of the data. `Range: bytes=6-`. Byte 6 and after. `Range: bytes=1-3,2-5`. A multi-part response that contains bytes 1 to 3 inclusive, and bytes 2 to 5 inclusive. The `Content-Type` response header contains `multipart/byteranges`.
If-Match (Optional)	header	string	See Request for Comments: 2616.
If-None-Match (Optional)	header	string	A client that has one or more entities previously obtained from the resource can verify that none of those entities is current by including a list of their associated entity tags in the `If-None-Match header` field. See Request for Comments: 2616 for details.
If-Modified-Since (Optional)	header	string	See Request for Comments: 2616.
If-Unmodified-Since (Optional)	header	string	See Request for Comments: 2616.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters¶

Name	In	Type	Description
Content-Length	header	string	The length of the object content in the response body, in bytes.
Content-Type	header	string	If the operation succeeds, this value is the MIME type of the object. If the operation fails, this value is the MIME type of the error text in the response body.
X-Object-Meta-name (Optional)	header	string	If present, the custom object metadata item, where `name` is the name of the metadata item. One``X-Object-Meta-name`` response header appears for each metadata `name` item.
Content-Disposition (Optional)	header	string	If present, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default. If not set, this header is not returned by this operation.
Content-Encoding (Optional)	header	string	If present, the value of the `Content-Encoding` metadata. If not set, the operation does not return this header.
X-Delete-At (Optional)	header	integer	If present, specifies date and time in UNIX Epoch time stamp format when the system removes the object. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
Accept-Ranges	header	string	The type of ranges that the object accepts.
X-Object-Manifest (Optional)	header	string	If present, this is a dynamic large object manifest object. The value is the container and object name prefix of the segment objects in the form `container/prefix`.
Last-Modified	header	string	The date and time when the object was created or its metadata was changed. The date and time is formatted as shown in this example: `Fri, 12 Aug 2016 14:24:16 GMT` The time is always in UTC.
ETag	header	string	For objects smaller than 5 GB, this value is the MD5 checksum of the object content. The value is not quoted. For manifest objects, this value is the MD5 checksum of the concatenated string of ETag values for each of the segments in the manifest, and not the MD5 checksum of the content that was downloaded. Also the value is enclosed in double-quote characters. You are strongly recommended to compute the MD5 checksum of the response body as it is received and compare this value with the one in the ETag header. If they differ, the content was corrupted, so retry the operation.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
X-Static-Large-Object	header	boolean	Set to `true` if this object is a static large object manifest object.
X-Symlink-Target (Optional)	header	string	If present, this is a symlink object. The value is the relative path of the target object in the format <container>/<object>.
X-Symlink-Target-Account (Optional)	header	string	If present, and `X-Symlink-Target` is present, then this is a cross-account symlink to an object in the account specified in the value.

Response Example¶

See examples above.

PUT

/v1/{account}/{container}/{object}

Create or replace object

Creates an object with data content and metadata, or replaces an existing object with data content and metadata.

The PUT operation always creates an object. If you use this operation on an existing object, you replace the existing object and metadata rather than modifying the object. Consequently, this operation returns the Created (201) response code.

If you use this operation to copy a manifest object, the new object is a normal object and not a copy of the manifest. Instead it is a concatenation of all the segment objects. This means that you cannot copy objects larger than 5 GB.

Note that the provider may have limited the characters which are allowed in an object name. Any name limits are exposed under the name_check key in the /info discoverability response. Regardless of name_check limitations, names must be URL quoted UTF-8.

To create custom metadata, use the X-Object-Meta-name header, where name is the name of the metadata item.

Note

Example requests and responses:

Create object:

curl -i $publicURL/janeausten/helloworld.txt -X PUT -d "Hello" -H "Content-Type: text/html; charset=UTF-8" -H "X-Auth-Token: $token"

HTTP/1.1 201 Created
Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT
Content-Length: 0
Etag: 8b1a9953c4611296a827abf8c47804d7
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
X-Openstack-Request-Id: tx4d5e4f06d357462bb732f-0052d96843
Date: Fri, 17 Jan 2014 17:28:35 GMT

Replace object:

curl -i $publicURL/janeausten/helloworld.txt -X PUT -d "Hola" -H "X-Auth-Token: $token"

HTTP/1.1 201 Created
Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT
Content-Length: 0
Etag: f688ae26e9cfa3ba6235477831d5122e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
X-Openstack-Request-Id: tx4d5e4f06d357462bb732f-0052d96843
Date: Fri, 17 Jan 2014 17:28:35 GMT

The Created (201) response code indicates a successful write.

If the container for the object does not already exist, the operation returns the 404 Not Found response code.

If the request times out, the operation returns the Request Timeout (408) response code.

The Length Required (411) response code indicates a missing Transfer-Encoding or Content-Length request header.

If the MD5 checksum of the data that is written to the object store does not match the optional ETag value, the operation returns the Unprocessable Entity (422) response code.

Normal response codes: 201

Error response codes: 404, 408, 411, 422

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
container (Optional)	path	string	The unique (within an account) name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (`/`) character because this character delimits the container and object name. For example, the path `/v1/account/www/pages` specifies the `www` container, not the `www/pages` container.
object (Optional)	path	string	The unique name for the object.
multipart-manifest (Optional)	query	string	If you include the `multipart-manifest=put` query parameter, the object is a static large object manifest and the body contains the manifest. See Static large objects for more information.
temp_url_sig	query	string	Used with temporary URLs to sign the request with an HMAC-SHA1 cryptographic signature that defines the allowed HTTP method, expiration date, full path to the object, and the secret key for the temporary URL. For more information about temporary URLs, see Temporary URL middleware.
temp_url_expires	query	integer	The date and time in UNIX Epoch time stamp format or ISO 8601 UTC timestamp when the signature for temporary URLs expires. For example, `1440619048` or `2015-08-26T19:57:28Z` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`. For more information about temporary URLs, see Temporary URL middleware.
X-Object-Manifest (Optional)	header	string	Set to specify that this is a dynamic large object manifest object. The value is the container and object name prefix of the segment objects in the form `container/prefix`. You must UTF-8-encode and then URL-encode the names of the container and prefix before you include them in this header.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
Content-Length (Optional)	header	integer	Set to the length of the object content (i.e. the length in bytes of the request body). Do not set if chunked transfer encoding is being used.
Transfer-Encoding (Optional)	header	string	Set to `chunked` to enable chunked transfer encoding. If used, do not set the `Content-Length` header to a non-zero value.
Content-Type (Optional)	header	string	Sets the MIME type for the object.
X-Detect-Content-Type (Optional)	header	boolean	If set to `true`, Object Storage guesses the content type based on the file extension and ignores the value sent in the `Content-Type` header, if present.
X-Copy-From (Optional)	header	string	If set, this is the name of an object used to create the new object by copying the `X-Copy-From` object. The value is in form `{container}/{object}`. You must UTF-8-encode and then URL-encode the names of the container and object before you include them in the header. Using PUT with `X-Copy-From` has the same effect as using the COPY operation to copy an object. Using `Range` header with `X-Copy-From` will create a new partial copied object with bytes set by `Range`.
X-Copy-From-Account (Optional)	header	string	Specifies the account name where the object is copied from. If not specified, the object is copied from the account which owns the new object (i.e., the account in the path).
ETag (Optional)	header	string	The MD5 checksum value of the request body. For example, the MD5 checksum value of the object content. For manifest objects, this value is the MD5 checksum of the concatenated string of ETag values for each of the segments in the manifest. You are strongly recommended to compute the MD5 checksum value and include it in the request. This enables the Object Storage API to check the integrity of the upload. The value is not quoted.
Content-Disposition (Optional)	header	string	If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default.
Content-Encoding (Optional)	header	string	If set, the value of the `Content-Encoding` metadata.
X-Delete-At (Optional)	header	integer	The date and time in UNIX Epoch time stamp format when the system removes the object. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`. The value should be a positive integer corresponding to a time in the future. If both `X-Delete-After` and `X-Delete-At` are set then `X-Delete-After` takes precedence.
X-Delete-After (Optional)	header	integer	The number of seconds after which the system removes the object. The value should be a positive integer. Internally, the Object Storage system uses this value to generate an `X-Delete-At` metadata item. If both `X-Delete-After` and `X-Delete-At` are set then `X-Delete-After` takes precedence.
X-Object-Meta-name (Optional)	header	string	The object metadata, where `name` is the name of the metadata item. You must specify an `X-Object-Meta-name` header for each metadata `name` item that you want to add or update.
If-None-Match (Optional)	header	string	In combination with `Expect: 100-Continue`, specify an `"If-None-Match: *"` header to query whether the server already has a copy of the object before any data is sent.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.
X-Symlink-Target (Optional)	header	string	Set to specify that this is a symlink object. The value is the relative path of the target object in the format <container>/<object>. The target object does not need to exist at the time of symlink creation. You must UTF-8-encode and then URL-encode the names of the container and object before you include them in this header.
X-Symlink-Target-Account (Optional)	header	string	Set to specify that this is a cross-account symlink to an object in the account specified in the value. The `X-Symlink-Target` must also be set for this to be effective. You must UTF-8-encode and then URL-encode the account name before you include it in this header.

Response Parameters¶

Name	In	Type	Description
Content-Length	header	string	If the operation succeeds, this value is zero (0) or the length of informational or error text in the response body.
ETag	header	string	The MD5 checksum of the uploaded object content. The value is not quoted. If it is an SLO, it would be MD5 checksum of the segments’ etags.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
Content-Type	header	string	If the operation succeeds, this value is the MIME type of the object. If the operation fails, this value is the MIME type of the error text in the response body.
last_modified	body	string	The date and time when the object was last modified. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm For example, `2015-08-27T09:49:58-05:00`. The `±hh:mm` value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is `-05:00`.

COPY

/v1/{account}/{container}/{object}

Copy object

Copies an object to another object in the object store.

You can copy an object to a new object with the same name. Copying to the same name is an alternative to using POST to add metadata to an object. With POST, you must specify all the metadata. With COPY, you can add additional metadata to the object.

With COPY, you can set the X-Fresh-Metadata header to true to copy the object without any existing metadata.

Alternatively, you can use PUT with the X-Copy-From request header to accomplish the same operation as the COPY object operation.

The COPY operation always creates an object. If you use this operation on an existing object, you replace the existing object and metadata rather than modifying the object. Consequently, this operation returns the Created (201) response code.

Normally, if you use this operation to copy a manifest object, the new object is a normal object and not a copy of the manifest. Instead it is a concatenation of all the segment objects. This means that you cannot copy objects larger than 5 GB in size.

To copy the manifest object, you include the multipart-manifest=get query string in the COPY request. The new object contains the same manifest as the original. The segment objects are not copied. Instead, both the original and new manifest objects share the same set of segment objects.

To copy a symlink either with a COPY or a PUT with the X-Copy-From request, include the symlink=get query string. The new symlink will have the same target as the original. The target object is not copied. Instead, both the original and new symlinks point to the same target object.

All metadata is preserved during the object copy. If you specify metadata on the request to copy the object, either PUT or COPY , the metadata overwrites any conflicting keys on the target (new) object.

Example requests and responses:

Copy the goodbye object from the marktwain container to the janeausten container:

curl -i $publicURL/marktwain/goodbye -X COPY -H "X-Auth-Token: $token" -H "Destination: janeausten/goodbye"

HTTP/1.1 201 Created
Content-Length: 0
X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT
X-Copied-From: marktwain/goodbye
Last-Modified: Fri, 17 Jan 2014 18:22:57 GMT
Etag: 451e372e48e0f6b1114fa0724aa79fa1
Content-Type: text/html; charset=UTF-8
X-Object-Meta-Movie: AmericanPie
X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501
X-Openstack-Request-Id: txdcb481ad49d24e9a81107-0052d97501
Date: Fri, 17 Jan 2014 18:22:57 GMT

Alternatively, you can use PUT to copy the goodbye object from the marktwain container to the janeausten container. This request requires a Content-Length header, even if it is set to zero (0).

curl -i $publicURL/janeausten/goodbye -X PUT -H "X-Auth-Token: $token" -H "X-Copy-From: /marktwain/goodbye" -H "Content-Length: 0"

HTTP/1.1 201 Created
Content-Length: 0
X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT
X-Copied-From: marktwain/goodbye
Last-Modified: Fri, 17 Jan 2014 18:22:57 GMT
Etag: 451e372e48e0f6b1114fa0724aa79fa1
Content-Type: text/html; charset=UTF-8
X-Object-Meta-Movie: AmericanPie
X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501
X-Openstack-Request-Id: txdcb481ad49d24e9a81107-0052d97501
Date: Fri, 17 Jan 2014 18:22:57 GMT

When several replicas exist, the system copies from the most recent replica. That is, the COPY operation behaves as though the X-Newest header is in the request.

Normal response codes: 201

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
container (Optional)	path	string	The unique (within an account) name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (`/`) character because this character delimits the container and object name. For example, the path `/v1/account/www/pages` specifies the `www` container, not the `www/pages` container.
object (Optional)	path	string	The unique name for the object.
multipart-manifest (Optional)	query	string	If you include the `multipart-manifest=get` query parameter and the object is a large object, the object contents are not copied. Instead, the manifest is copied to the new object.
symlink (Optional)	query	string	If you include the `symlink=get` query parameter and the object is a symlink, the target object contents are not copied. Instead, the symlink is copied to create a new symlink to the same target.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
Destination	header	string	The container and object name of the destination object in the form of `/container/object`. You must UTF-8-encode and then URL-encode the names of the destination container and object before you include them in this header.
Destination-Account (Optional)	header	string	Specifies the account name where the object is copied to. If not specified, the object is copied to the account which owns the object (i.e., the account in the path).
Content-Type (Optional)	header	string	Sets the MIME type for the object.
Content-Encoding (Optional)	header	string	If set, the value of the `Content-Encoding` metadata.
Content-Disposition (Optional)	header	string	If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default.
X-Object-Meta-name (Optional)	header	string	The object metadata, where `name` is the name of the metadata item. You must specify an `X-Object-Meta-name` header for each metadata `name` item that you want to add or update.
X-Fresh-Metadata (Optional)	header	boolean	Enables object creation that omits existing user metadata. If set to `true`, the COPY request creates an object without existing user metadata. Default value is `false`.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters¶

Name	In	Type	Description
Content-Length	header	string	If the operation succeeds, this value is zero (0) or the length of informational or error text in the response body.
X-Copied-From-Last-Modified (Optional)	header	integer	For a copied object, the date and time in UNIX Epoch time stamp format when the container and object name from which the new object was copied was last modified. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
X-Copied-From (Optional)	header	string	For a copied object, shows the container and object name from which the new object was copied. The value is in the `{container}/{object}` format.
X-Copied-From-Account (Optional)	header	string	For a copied object, shows the account from which the new object was copied.
Last-Modified	header	string	The date and time when the object was created or its metadata was changed. The date and time is formatted as shown in this example: `Fri, 12 Aug 2016 14:24:16 GMT` The time is always in UTC.
ETag	header	string	The MD5 checksum of the copied object content. The value is not quoted.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
Content-Type	header	string	If the operation succeeds, this value is the MIME type of the object. If the operation fails, this value is the MIME type of the error text in the response body.

DELETE

/v1/{account}/{container}/{object}

Delete object

Permanently deletes an object from the object store.

Object deletion occurs immediately at request time. Any subsequent GET, HEAD, POST, or DELETE operations will return a 404 Not Found error code.

For static large object manifests, you can add the ?multipart- manifest=delete query parameter. This operation deletes the segment objects and, if all deletions succeed, this operation deletes the manifest object.

A DELETE request made to a symlink path will delete the symlink rather than the target object.

An alternative to using the DELETE operation is to use the POST operation with the bulk-delete query parameter.

Example request and response:

Delete the helloworld object from the marktwain container:

curl -i $publicURL/marktwain/helloworld -X DELETE -H "X-Auth-Token: $token"

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx36c7606fcd1843f59167c-0052d6fdac
X-Openstack-Request-Id: tx36c7606fcd1843f59167c-0052d6fdac
Date: Wed, 15 Jan 2014 21:29:16 GMT

Typically, the DELETE operation does not return a response body. However, with the multipart-manifest=delete query parameter, the response body contains a list of manifest and segment objects and the status of their DELETE operations.

Normal response codes: 204

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
container (Optional)	path	string	The unique (within an account) name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (`/`) character because this character delimits the container and object name. For example, the path `/v1/account/www/pages` specifies the `www` container, not the `www/pages` container.
object (Optional)	path	string	The unique name for the object.
multipart-manifest (Optional)	query	string	If you include the `multipart-manifest=delete` query parameter and the object is a static large object, the segment objects and manifest object are deleted. If you omit the `multipart-manifest=delete` query parameter and the object is a static large object, the manifest object is deleted but the segment objects are not deleted. The response body will contain the status of the deletion of every processed segment object.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters¶

Name	In	Type	Description
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
Content-Length	header	string	If the operation succeeds, this value is zero (0) or the length of informational or error text in the response body.
Content-Type (Optional)	header	string	If present, this value is the MIME type of the informational or error text in the response body.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)

HEAD

/v1/{account}/{container}/{object}

Show object metadata

Shows object metadata.

Example requests and responses:

Show object metadata:

curl $publicURL/marktwain/goodbye --head -H "X-Auth-Token: $token"

HTTP/1.1 200 OK
Content-Length: 14
Accept-Ranges: bytes
Last-Modified: Thu, 16 Jan 2014 21:12:31 GMT
Etag: 451e372e48e0f6b1114fa0724aa79fa1
X-Timestamp: 1389906751.73463
X-Object-Meta-Book: GoodbyeColumbus
Content-Type: application/octet-stream
X-Trans-Id: tx37ea34dcd1ed48ca9bc7d-0052d84b6f
X-Openstack-Request-Id: tx37ea34dcd1ed48ca9bc7d-0052d84b6f
Date: Thu, 16 Jan 2014 21:13:19 GMT

Note: The --head option was used in the above example. If we had used -i -X HEAD and the Content-Length response header is non-zero, the cURL command stalls after it prints the response headers because it is waiting for a response body. However, the Object Storage system does not return a response body for the HEAD operation.

If the request succeeds, the operation returns the 200 response code.

Normal response codes: 200

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
container (Optional)	path	string	The unique (within an account) name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (`/`) character because this character delimits the container and object name. For example, the path `/v1/account/www/pages` specifies the `www` container, not the `www/pages` container.
object (Optional)	path	string	The unique name for the object.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
temp_url_sig	query	string	Used with temporary URLs to sign the request with an HMAC-SHA1 cryptographic signature that defines the allowed HTTP method, expiration date, full path to the object, and the secret key for the temporary URL. For more information about temporary URLs, see Temporary URL middleware.
temp_url_expires	query	integer	The date and time in UNIX Epoch time stamp format or ISO 8601 UTC timestamp when the signature for temporary URLs expires. For example, `1440619048` or `2015-08-26T19:57:28Z` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`. For more information about temporary URLs, see Temporary URL middleware.
filename (Optional)	query	string	Overrides the default file name. Object Storage generates a default file name for GET temporary URLs that is based on the object name. Object Storage returns this value in the `Content-Disposition` response header. Browsers can interpret this file name value as a file attachment to save. For more information about temporary URLs, see Temporary URL middleware.
multipart-manifest (Optional)	query	string	If you include the `multipart-manifest=get` query parameter and the object is a large object, the object metadata is not returned. Instead, the response headers will include the manifest metadata and for dynamic large objects the `X-Object-Manifest` response header.
symlink (Optional)	query	string	If you include the `symlink=get` query parameter and the object is a symlink, then the response will include data and metadata from the symlink itself rather than from the target.
X-Newest (Optional)	header	boolean	If set to true , Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.
If-Match (Optional)	header	string	See Request for Comments: 2616.
If-None-Match (Optional)	header	string	A client that has one or more entities previously obtained from the resource can verify that none of those entities is current by including a list of their associated entity tags in the `If-None-Match header` field. See Request for Comments: 2616 for details.
If-Modified-Since (Optional)	header	string	See Request for Comments: 2616.
If-Unmodified-Since (Optional)	header	string	See Request for Comments: 2616.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters¶

Name	In	Type	Description
Content-Length	header	string	HEAD operations do not return content. The `Content-Length` header value is not the size of the response body but is the size of the object, in bytes.
X-Object-Meta-name (Optional)	header	string	The object metadata, where `name` is the name of the metadata item. You must specify an `X-Object-Meta-name` header for each metadata `name` item that you want to add or update.
Content-Disposition (Optional)	header	string	If present, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default. If not set, this header is not returned by this operation.
Content-Encoding (Optional)	header	string	If present, the value of the `Content-Encoding` metadata. If not set, the operation does not return this header.
X-Delete-At (Optional)	header	integer	If present, specifies date and time in UNIX Epoch time stamp format when the system removes the object. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
X-Object-Manifest (Optional)	header	string	If present, this is a dynamic large object manifest object. The value is the container and object name prefix of the segment objects in the form `container/prefix`.
Last-Modified	header	string	The date and time when the object was created or its metadata was changed. The date and time is formatted as shown in this example: `Fri, 12 Aug 2016 14:24:16 GMT` The time is always in UTC.
ETag	header	string	For objects smaller than 5 GB, this value is the MD5 checksum of the object content. The value is not quoted. For manifest objects, this value is the MD5 checksum of the concatenated string of ETag values for each of the segments in the manifest, and not the MD5 checksum of the content that was downloaded. Also the value is enclosed in double-quote characters. You are strongly recommended to compute the MD5 checksum of the response body as it is received and compare this value with the one in the ETag header. If they differ, the content was corrupted, so retry the operation.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
X-Static-Large-Object	header	boolean	Set to `true` if this object is a static large object manifest object.
Content-Type	header	string	If the operation succeeds, this value is the MIME type of the object. If the operation fails, this value is the MIME type of the error text in the response body.
X-Symlink-Target (Optional)	header	string	If present, this is a symlink object. The value is the relative path of the target object in the format <container>/<object>.
X-Symlink-Target-Account (Optional)	header	string	If present, and `X-Symlink-Target` is present, then this is a cross-account symlink to an object in the account specified in the value.

Response Example¶

See examples above.

POST

/v1/{account}/{container}/{object}

Create or update object metadata

Creates or updates object metadata.

To create or update custom metadata, use the X-Object-Meta-name header, where name is the name of the metadata item.

Note

In addition to the custom metadata, you can update the Content-Type, Content-Encoding, Content-Disposition, and X-Delete-At system metadata items. However you cannot update other system metadata, such as Content-Length or Last-Modified.

You can use COPY as an alternate to the POST operation by copying to the same object. With the POST operation you must specify all metadata items, whereas with the COPY operation, you need to specify only changed or additional items. All metadata is preserved during the object copy. If you specify metadata on the request to copy the object, either PUT or COPY , the metadata overwrites any conflicting keys on the target (new) object.

Note

While using COPY instead of POST allows sending only a subset of the metadata, it carries the cost of reading and rewriting the entire contents of the object.

A POST request deletes any existing custom metadata that you added with a previous PUT or POST request. Consequently, you must specify all custom metadata in the request. However, system metadata is unchanged by the POST request unless you explicitly supply it in a request header.

You can also set the X-Delete-At or X-Delete-After header to define when to expire the object.

When used as described in this section, the POST operation creates or replaces metadata. This form of the operation has no request body. There are alternate uses of the POST operation as follows:

You can also use the form POST feature to upload objects.
The POST operation when used with the bulk-delete query parameter can be used to delete multiple objects and containers in a single operation.
The POST operation when used with the extract-archive query parameter can be used to upload an archive (tar file). The archive is then extracted to create objects.

A POST request must not include X-Symlink-Target header. If it does then a 400 status code is returned and the object metadata is not modified.

When a POST request is sent to a symlink, the metadata will be applied to the symlink, but the request will result in a 307 Temporary Redirect response to the client. The POST is never redirected to the target object, thus a GET/HEAD request to the symlink without symlink=get will not return the metadata that was sent as part of the POST request.

Example requests and responses:

Create object metadata:

curl -i $publicURL/marktwain/goodbye -X POST -H "X-Auth-Token: $token" -H "X-Object-Meta-Book: GoodbyeColumbus"

HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txb5fb5c91ba1f4f37bb648-0052d84b3f
X-Openstack-Request-Id: txb5fb5c91ba1f4f37bb648-0052d84b3f
Date: Thu, 16 Jan 2014 21:12:31 GMT
<html>
<h1>Accepted
</h1>
<p>The request is accepted for processing.
</p>
</html>

Update object metadata:

curl -i $publicURL/marktwain/goodbye -X POST -H "X-Auth-Token: $token" -H "X-Object-Meta-Book: GoodbyeOldFriend"

HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx5ec7ab81cdb34ced887c8-0052d84ca4
X-Openstack-Request-Id: tx5ec7ab81cdb34ced887c8-0052d84ca4
Date: Thu, 16 Jan 2014 21:18:28 GMT
<html>
<h1>Accepted
</h1>
<p>The request is accepted for processing.
</p>
</html>

Normal response codes: 202

Request¶

Name	In	Type	Description
account (Optional)	path	string	The unique name for the account. An account is also known as the project or tenant.
container (Optional)	path	string	The unique (within an account) name for the container. The container name must be from 1 to 256 characters long and can start with any character and contain any pattern. Character set must be UTF-8. The container name cannot contain a slash (`/`) character because this character delimits the container and object name. For example, the path `/v1/account/www/pages` specifies the `www` container, not the `www/pages` container.
object (Optional)	path	string	The unique name for the object.
bulk-delete (Optional)	query	string	When the `bulk-delete` query parameter is present in the POST request, multiple objects or containers can be deleted with a single request. See Bulk Delete for how this feature is used.
extract-archive (Optional)	query	string	When the `extract-archive` query parameter is present in the POST request, an archive (tar file) is uploaded and extracted to create multiple objects. See Extract Archive for how this feature is used.
X-Auth-Token (Optional)	header	string	Authentication token. If you omit this header, your request fails unless the account owner has granted you access through an access control list (ACL).
X-Service-Token (Optional)	header	string	A service token. See OpenStack Service Using Composite Tokens for more information.
X-Object-Meta-name (Optional)	header	string	The object metadata, where `name` is the name of the metadata item. You must specify an `X-Object-Meta-name` header for each metadata `name` item that you want to add or update.
X-Delete-At (Optional)	header	integer	The date and time in UNIX Epoch time stamp format when the system removes the object. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`. The value should be a positive integer corresponding to a time in the future. If both `X-Delete-After` and `X-Delete-At` are set then `X-Delete-After` takes precedence.
X-Delete-After (Optional)	header	integer	The number of seconds after which the system removes the object. The value should be a positive integer. Internally, the Object Storage system uses this value to generate an `X-Delete-At` metadata item. If both `X-Delete-After` and `X-Delete-At` are set then `X-Delete-After` takes precedence.
Content-Disposition (Optional)	header	string	If set, specifies the override behavior for the browser. For example, this header might specify that the browser use a download program to save this file rather than show the file, which is the default.
Content-Encoding (Optional)	header	string	If set, the value of the `Content-Encoding` metadata.
Content-Type (Optional)	header	string	Sets the MIME type for the object.
X-Trans-Id-Extra (Optional)	header	string	Extra transaction information. Use the `X-Trans-Id-Extra` request header to include extra information to help you debug any errors that might occur with large object upload and other Object Storage transactions. The server appends the first 32 characters of the `X-Trans-Id-Extra` request header value to the transaction ID value in the generated `X-Trans-Id` response header. You must UTF-8-encode and then URL-encode the extra transaction information before you include it in the `X-Trans-Id-Extra` request header. For example, you can include extra transaction information when you upload large objects such as images. When you upload each segment and the manifest, include the same value in the `X-Trans-Id-Extra` request header. If an error occurs, you can find all requests that are related to the large object upload in the Object Storage logs. You can also use `X-Trans-Id-Extra` strings to help operators debug requests that fail to receive responses. The operator can search for the extra information in the logs.

Response Parameters¶

Name	In	Type	Description
Date	header	string	The date and time the system responded to the request, using the preferred format of RFC 7231 as shown in this example `Thu, 16 Jun 2016 15:10:38 GMT`. The time is always in UTC.
X-Timestamp	header	integer	The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version. For example, `1440619048` is equivalent to `Mon, Wed, 26 Aug 2015 19:57:28 GMT`.
Content-Length	header	string	If the operation succeeds, this value is zero (0) or the length of informational or error text in the response body.
Content-Type (Optional)	header	string	If present, this value is the MIME type of the informational or error text in the response body.
X-Trans-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem.
X-Openstack-Request-Id	header	string	A unique transaction ID for this request. Your service provider might need this value if you report a problem. (same as `X-Trans-Id`)

Endpoints¶

If configured, lists endpoints for an account.

GET

/v1/endpoints

List endpoints

Lists endpoints for an object, account, or container.

When the cloud provider enables middleware to list the /endpoints/ path, software that needs data location information can use this call to avoid network overhead. The cloud provider can map the /endpoints/ path to another resource, so this exact resource might vary from provider to provider. Because it goes straight to the middleware, the call is not authenticated, so be sure you have tightly secured the environment and network when using this call.

Error response codes:201,

Request¶

This operation does not accept a request body.