OpenStack API Documentation

Object Storage API v1 (SUPPORTED)

Manages the accounts, containers, and objects in the Object Storage system.

To run the cURL command examples for these requests, set these environment variables:

publicURL. The public URL that is the HTTP endpoint from where you can access Object Storage. It includes the Object Storage API version number and your account name. For example, https://23.253.72.207/v1/my_account.
token. The authentication token for Object Storage.

To obtain these values, run the swift stat -v command.

As shown in this example, the public URL appears in the StorageURL field, and the token appears in the Auth Token field:

StorageURL: https://23.253.72.207/v1/my_account
Auth Token: {token}
Account: my_account
Containers: 2
Objects: 3
Bytes: 47
Meta Book: MobyDick
X-Timestamp: 1389453423.35964
X-Trans-Id: txee55498935404a2caad89-0052dd3b77
Content-Type: text/plain; charset=utf-8
Accept-Ranges: bytes

For a complete description of HTTP 1.1 header definitions, see Header Field Definitions.

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.

Normal response codes

200

Request parameters

Parameter	Style	Type	Description
swiftinfo_sig (Optional)	query	xsd:char	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	xsd:int	Sets the expiration time in UNIX Epoch timestamp format.

{
    "swift": {
        "version": "1.11.0"
    },
    "staticweb": {},
    "tempurl": {}
}

Endpoints

If configured, lists endpoints for a specified account.

GET

/v1/endpoints

List endpoints

Lists endpoints for an object, account, or container.

When the cloud provider has enabled middleware to list the endpoints path, software that needs data location information can use this call to avoid network overhead. The cloud provider can customize the /endpoints/ path to another resource, so this exact resource may 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.

Normal response codes

201

{
    "endpoints": [
        "http://storage02.swiftdrive:6002/d2/617/AUTH_dev",
        "http://storage01.swiftdrive:6002/d8/617/AUTH_dev",
        "http://storage01.swiftdrive:6002/d11/617/AUTH_dev"
    ],
    "headers": {}
}

{
    "endpoints": [
        "http://storage01.swiftdrive.com:6008/d8/583/AUTH_dev/EC_cont1/obj",
        "http://storage02.swiftdrive.com:6008/d2/583/AUTH_dev/EC_cont1/obj",
        "http://storage02.swiftdrive.com:6006/d3/583/AUTH_dev/EC_cont1/obj",
        "http://storage02.swiftdrive.com:6008/d5/583/AUTH_dev/EC_cont1/obj",
        "http://storage01.swiftdrive.com:6007/d7/583/AUTH_dev/EC_cont1/obj",
        "http://storage02.swiftdrive.com:6007/d4/583/AUTH_dev/EC_cont1/obj",
        "http://storage01.swiftdrive.com:6006/d6/583/AUTH_dev/EC_cont1/obj"
    ],
    "headers": {
        "X-Backend-Storage-Policy-Index": "2"
    }
}

This operation does not accept a request body.

Accounts

Lists containers for a specified account. Creates, updates, shows, and deletes account metadata.

GET

/v1/{account}

Show account details and list containers

Shows details for a specified 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.

This operation does not accept a request body.

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"

See the example response below.
List containers and ask for an XML response: curl -i $publicURL?format=xml -X GET -H "X-Auth-Token: $token"

See the example response below.

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.

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

200. Success. The response body lists the containers.
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 parameters, and you have reached the end of the list.

Normal response codes

200, 204

Request parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
limit (Optional)	query	xsd:int	For an integer value n, limits the number of results to n.
marker (Optional)	query	xsd:string	For a string value x, returns container names that are greater in value than the specified marker.
end_marker (Optional)	query	xsd:string	For a string value x, returns container names that are less in value than the specified marker.
format (Optional)	query	xsd: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 the specified format. If you append the `format=plain` query parameter, the response lists the container names separated by newlines.
prefix (Optional)	query	xsd:string	Prefix value. Named items in the response begin with this value.
delimiter (Optional)	query	xsd:char	Delimiter value, which returns the object names that are nested in the container.
X-Auth-Token	header	xsd:string	Authentication token.
X-Newest (Optional)	header	xsd: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	xsd:string	Instead of using the `format` query parameter, set this header to `application/json`, `application/xml`, or `text/xml`.

Response parameters

Parameter	Style	Type	Description
Content-Length	header	xsd:string	The length of the response body that contains the list of names. If the operation fails, this value is the length of the error text in the response body.
Content-Type	header	xsd:string	The MIME type of the list of names. If the operation fails, this value is the MIME type of the error text in the response body.
X-Account-Object-Count	header	xsd:int	The number of objects in the account.
X-Account-Bytes-Used	header	xsd:int	The total number of bytes that are stored in Object Storage for the account.
X-Account-Container-Count	header	xsd:int	The number of containers.
X-Account-Meta-name (Optional)	header	xsd: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-Timestamp	header	xsd:int	The time and date, in UNIX Epoch timestamp format, when the account was initially created as a current version.
X-Account-Meta-Temp-URL-Key (Optional)	header	xsd:string	The secret key value for temporary URLs. If not set, this header is not returned by this operation.
X-Account-Meta-Temp-URL-Key-2 (Optional)	header	xsd:string	A second secret key value for temporary URLs. If not set, this header is not returned by this operation.
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.
name	plain	xsd:string	The name of the container.
count	plain	xsd:int	The number of objects in the container.
bytes	plain	xsd:int	The total number of bytes that are stored in Object Storage for the account.

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
Date: Fri, 17 Jan 2014 15:59:33 GMT

[
    {
        "count": 0,
        "bytes": 0,
        "name": "janeausten"
    },
    {
        "count": 1,
        "bytes": 14,
        "name": "marktwain"
    }
]

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
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>
    </container>
    <container>
        <name>marktwain</name>
        <count>1</count>
        <bytes>14</bytes>
    </container>
</account>

POST

/v1/{account}

Create, update, or delete account metadata

Creates, updates, or deletes account metadata.

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

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

To delete a metadata header, send an empty value for that particular 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}: arbitrary value header. For example, X-Remove-Account-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.

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
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
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
Date: Fri, 17 Jan 2014 16:08:15 GMT
```

If the request succeeds, the operation returns the 204 status code.

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

Normal response codes

204

Request parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
X-Auth-Token	header	xsd:string	Authentication token.
X-Account-Meta-Temp-URL-Key (Optional)	header	xsd:string	The secret key value for temporary URLs.
X-Account-Meta-Temp-URL-Key-2 (Optional)	header	xsd:string	A second secret key value for temporary URLs. The second key enables you to rotate keys by having an old and new key active at the same time.
X-Account-Meta-name (Optional)	header	xsd: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.
Content-Type (Optional)	header	xsd:string	Changes the MIME type for the object.
X-Detect-Content-Type (Optional)	header	xsd: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.

Response parameters

Parameter	Style	Type	Description
Content-Length	header	xsd:string	If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Content-Type	header	xsd:string	If the operation fails, this value is the MIME type of the error text in the response body.
X-Timestamp	header	xsd:int	The time and date, in UNIX Epoch timestamp format, when the account was initially created as a current version.
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.

This operation does not return a response body.

HEAD

/v1/{account}

Show account metadata

Shows metadata for a specified 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.

This operation does not accept a request body.

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
Date: Fri, 17 Jan 2014 16:09:56 GMT

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

Normal response codes

204

Error response codes

unauthorized (401)

Request parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
X-Auth-Token	header	xsd:string	Authentication token.
X-Newest (Optional)	header	xsd: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.

Response parameters

Parameter	Style	Type	Description
X-Account-Object-Count	header	xsd:int	The number of objects in the account.
X-Account-Container-Count	header	xsd:int	The number of containers.
X-Account-Bytes-Used	header	xsd:int	The total number of bytes that are stored in Object Storage for the account.
X-Account-Meta-name (Optional)	header	xsd: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-Timestamp	header	xsd:int	The time and date, in UNIX Epoch timestamp format, when the account was initially created as a current version.
X-Account-Meta-Temp-URL-Key (Optional)	header	xsd:string	The secret key value for temporary URLs. If not set, this header is not returned by this operation.
X-Account-Meta-Temp-URL-Key-2 (Optional)	header	xsd:string	A second secret key value for temporary URLs. If not set, this header is not returned by this operation.
Content-Length	header	xsd:string	If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Content-Type	header	xsd:string	If the operation fails, this value is the MIME type of the error text in the response body.
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.

This operation does not return a response body.

Containers

Lists objects in a specified container. Creates, shows details for, and deletes containers. Creates, updates, shows, and deletes container metadata.

GET

/v1/{account}/{container}

Show container details and list objects

Shows details for a specified 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 object names. Omit query parameters to return the complete list of object names 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:

Show container details for and list objects in the marktwain container, and ask for a JSON response:

curl -i $publicURL/marktwain?format=json -X GET -H "X-Auth-Token: $token"
Show container details for and list objects in the marktwain container, and ask for an XML response:

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

If you use query parameters to page through a long list of objects, 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.

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

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

If the container does not exist, the 404 Not Found error code is returned.

Normal response codes

200, 204

Error response codes

NotFound (404)

Request parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
container	URI	xsd:string	The unique 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, `/account/container/object`.
limit (Optional)	query	xsd:int	For an integer value n, limits the number of results to n.
marker (Optional)	query	xsd:string	For a string value x, returns container names that are greater in value than the specified marker.
end_marker (Optional)	query	xsd:string	For a string value x, returns container names that are less in value than the specified marker.
prefix (Optional)	query	xsd:string	Prefix value. Named items in the response begin with this value.
format (Optional)	query	xsd: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 the specified format. If you append the `format=plain` query parameter, the response lists the container names separated by newlines.
delimiter (Optional)	query	xsd:char	Delimiter value, which returns the object names that are nested in the container.
path (Optional)	query	xsd:string	For a string value, returns the object names that are nested in the pseudo path. Equivalent to setting delimiter to `/` and `prefix` to the path with a `/` at the end.
X-Auth-Token	header	xsd:string	Authentication token.
X-Newest (Optional)	header	xsd: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	xsd:string	Instead of using the `format` query parameter, set this header to `application/json`, `application/xml`, or `text/xml`.

Response parameters

Parameter	Style	Type	Description
Content-Length	header	xsd:string	The length of the response body that contains the list of names. If the operation fails, this value is the length of the error text in the response body.
X-Container-Object-Count	header	xsd:int	The number of objects.
Accept-Ranges	header	xsd:string	The type of ranges that the object accepts.
X-Container-Meta-name	header	xsd: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}`).
X-Timestamp	header	xsd:int	The time and date, in UNIX Epoch timestamp format, when the container was initially created as a current version.
X-Container-Bytes-Used	header	xsd:int	The count of bytes used in total.
Content-Type	header	xsd:string	The MIME type of the list of names. If the operation fails, this value is the MIME type of the error text in the response body.
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.
name	plain	xsd:string	The name of the container.
hash	plain	xsd:string	The MD5 checksum value of the object content.
bytes	plain	xsd:int	The total number of bytes that are stored in Object Storage for the account.
content_type	plain	xsd:string	The content type of the object.
last_modified	plain	xsd:datetime	The date and time when the object was last modified.

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
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"
    }
]

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
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.

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
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
Date: Tue, 14 Jan 2014 19:25:43 GMT
```

Normal response codes

201, 204

Request parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
container	URI	xsd:string	The unique 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, `/account/container/object`.
X-Auth-Token	header	xsd:string	Authentication token.
X-Container-Read (Optional)	header	xsd:string	Sets a container access control list (ACL) that grants read access. Container ACLs are available on any Object Storage cluster, and are enabled by container rather than by cluster. To set the container read ACL: $ curl -X {PUT\|POST} -i -H "X-Auth-Token: TOKEN" -H \ "X-Container-Read: ACL" STORAGE_URL/CONTAINER For example: $ curl -X PUT -i \ -H "X-Auth-Token: 0101010101" \ -H "X-Container-Read: .r:" \ http://swift.example.com/v1/AUTH_bob/read_container In the command, specify the ACL in the `X-Container-Read` header, as follows: `.r:`—All referrers. `.r:example.com,swift.example.com`—Comma-separated list of referrers. `.rlistings`—Container listing access. `AUTH_username`—Access to a specified user who authenticates through a legacy or non-OpenStack-Identity-based authentication system. `LDAP_`—Access to all users who authenticate through an LDAP-based legacy or non-OpenStack-Identity-based authentication system.
X-Container-Write (Optional)	header	xsd:string	Sets an ACL that grants write access.
X-Container-Sync-To (Optional)	header	xsd: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	xsd:string	Sets the secret key for container synchronization. If you remove the secret key, synchronization is halted.
X-Versions-Location (Optional)	header	xsd:string	Enables versioning on this container. The value is the name of another container. You must UTF-8-encode and then URL-encode the name before you include it in the header. To disable versioning, set the header to an empty string.
X-Container-Meta-name (Optional)	header	xsd: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.
Content-Type (Optional)	header	xsd:string	Changes the MIME type for the object.
X-Detect-Content-Type (Optional)	header	xsd: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.
If-None-Match (Optional)	header	xsd: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.

Response parameters

Parameter	Style	Type	Description
Content-Length	header	xsd:string	If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Content-Type	header	xsd:string	If the operation fails, this value is the MIME type of the error text in the response body.
X-Timestamp	header	xsd:int	The time and date, in UNIX Epoch timestamp format, when the container was initially created as a current version.
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.

This operation does not return a response body.

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
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
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
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

NotFound (404), Conflict (409)

Request parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
container	URI	xsd:string	The unique 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, `/account/container/object`.
X-Auth-Token	header	xsd:string	Authentication token.

Response parameters

Parameter	Style	Type	Description
Content-Length	header	xsd:string	If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Content-Type	header	xsd:string	If the operation fails, this value is the MIME type of the error text in the response body.
X-Timestamp	header	xsd:int	The time and date, in UNIX Epoch timestamp format, when the container was initially created as a current version.
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.

This operation does not return a response body.

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.

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}: arbitrary value header. 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.

This operation does not accept a request body.

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
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
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
Date: Thu, 16 Jan 2014 18:37:04 GMT
```

If the request succeeds, the operation returns the 204 status code.

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

Normal response codes

204

Request parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
container	URI	xsd:string	The unique 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, `/account/container/object`.
X-Auth-Token	header	xsd:string	Authentication token.
X-Container-Read (Optional)	header	xsd:string	Sets a container access control list (ACL) that grants read access. Container ACLs are available on any Object Storage cluster, and are enabled by container rather than by cluster. To set the container read ACL: $ curl -X {PUT\|POST} -i -H "X-Auth-Token: TOKEN" -H \ "X-Container-Read: ACL" STORAGE_URL/CONTAINER For example: $ curl -X PUT -i \ -H "X-Auth-Token: 0101010101" \ -H "X-Container-Read: .r:" \ http://swift.example.com/v1/AUTH_bob/read_container In the command, specify the ACL in the `X-Container-Read` header, as follows: `.r:`—All referrers. `.r:example.com,swift.example.com`—Comma-separated list of referrers. `.rlistings`—Container listing access. `AUTH_username`—Access to a specified user who authenticates through a legacy or non-OpenStack-Identity-based authentication system. `LDAP_`—Access to all users who authenticate through an LDAP-based legacy or non-OpenStack-Identity-based authentication system.
X-Remove-Container-name (Optional)	header	xsd:string	Removes the metadata item named `{name}`. For example, `X-Remove-Container-Read` removes the `X-Container-Read` metadata item.
X-Container-Write (Optional)	header	xsd:string	Sets an ACL that grants write access.
X-Container-Sync-To (Optional)	header	xsd: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	xsd:string	Sets the secret key for container synchronization. If you remove the secret key, synchronization is halted.
X-Versions-Location (Optional)	header	xsd:string	Enables versioning on this container. The value is the name of another container. You must UTF-8-encode and then URL-encode the name before you include it in the header. To disable versioning, set the header to an empty string.
X-Remove-Versions-Location (Optional)	header	xsd:string	Set to any value to disable versioning.
X-Container-Meta-name (Optional)	header	xsd: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-Quota-Bytes (Optional)	header	xsd: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.
X-Container-Meta-Quota-Count (Optional)	header	xsd: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.
X-Container-Meta-Web-Directory-Type (Optional)	header	xsd: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.
Content-Type (Optional)	header	xsd:string	Changes the MIME type for the object.
X-Detect-Content-Type (Optional)	header	xsd: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.

Response parameters

Parameter	Style	Type	Description
Content-Length	header	xsd:string	If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Content-Type	header	xsd:string	If the operation fails, this value is the MIME type of the error text in the response body.
X-Timestamp	header	xsd:int	The time and date, in UNIX Epoch timestamp format, when the container was initially created as a current version.
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.

This operation does not return a response body.

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
Date: Thu, 16 Jan 2014 18:37:22 GMT

If the request succeeds, the operation returns the 204 status code.

Normal response codes

204

Request parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
container	URI	xsd:string	The unique 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, `/account/container/object`.
X-Auth-Token (Optional)	header	xsd: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-Newest (Optional)	header	xsd: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.

Response parameters

Parameter	Style	Type	Description
Content-Length	header	xsd:string	If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
X-Container-Object-Count	header	xsd:int	The number of objects.
Accept-Ranges	header	xsd:string	The type of ranges that the object accepts.
X-Container-Meta-name	header	xsd: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}`).
X-Timestamp	header	xsd:int	The time and date, in UNIX Epoch timestamp format, when the container was initially created as a current version.
X-Container-Meta-Quota-Bytes (Optional)	header	xsd: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.
X-Container-Meta-Quota-Count (Optional)	header	xsd: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.
X-Container-Bytes-Used	header	xsd:int	The count of bytes used in total.
X-Container-Read (Optional)	header	xsd:string	The ACL that grants read access. If not set, this header is not returned by this operation.
X-Container-Write (Optional)	header	xsd:string	The ACL that grants write access. If not set, this header is not returned by this operation.
X-Container-Sync-To (Optional)	header	xsd:string	The destination for container synchronization. If not set, this header is not returned by this operation.
X-Container-Sync-Key (Optional)	header	xsd:string	The secret key for container synchronization. If not set, this header is not returned by this operation.
X-Versions-Location	header	xsd:string	Enables versioning on this container. The value is the name of another container. You must UTF-8-encode and then URL-encode the name before you include it in the header. To disable versioning, set the header to an empty string.
Content-Type	header	xsd:string	If the operation fails, this value is the MIME type of the error text in the response body.
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.

This operation does not return a response body.

Objects

Creates, replaces, shows details for, and deletes objects. Copies objects from another object with a new or different name. Updates object metadata.

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
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
Date: Thu, 16 Jan 2014 18:55:00 GMT

<html><h1>Not Found</h1><p>The resource could not be found.</p></html>
```

Normal response codes

200

Error response codes

NotFound (404)

Request parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
container	URI	xsd:string	The unique 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, `/account/container/object`.
object	URI	xsd:string	The unique name for the object.
X-Auth-Token (Optional)	header	xsd: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-Newest (Optional)	header	xsd: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	xsd: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 OpenStack Object Storage API v1 Reference .
temp_url_expires	query	xsd:string	Used with temporary URLs to specify the expiry time of the signature as a UNIX Epoch timestamp, which is an integer value. For example, 1390852007 represents Mon, 27 Jan 2014 19:46:47 GMT. For more information about temporary URLs, see OpenStack Object Storage API v1 Reference .
filename (Optional)	query	xsd:string	Used with temporary URLs to override 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 be saved. For more information about temporary URLs, see OpenStack Object Storage API v1 Reference .
multipart-manifest (Optional)	query	xsd: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.
Range (Optional)	header	xsd: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 five 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 five bytes of data after a 10-byte offset. The `Content-Type` of the response is then `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` of the response is then `multipart/byteranges`.
If-Match (Optional)	header	xsd:string	See http://www.ietf.org/rfc/rfc2616.txt.
If-None-Match (Optional)	header	xsd: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.
If-Modified-Since (Optional)	header	xsd:date	See http://www.ietf.org/rfc/rfc2616.txt.
If-Unmodified-Since (Optional)	header	xsd:date	See http://www.ietf.org/rfc/rfc2616.txt.

Response parameters

Parameter	Style	Type	Description
Content-Length	header	xsd:string	The length of the object content in the response body, in bytes.
Accept-Ranges	header	xsd:string	The type of ranges that the object accepts.
Last-Modified	header	xsd:string	The date and time that the object was created or the last time that the metadata was changed.
X-Timestamp	header	xsd:string	The date and time, in UNIX Epoch timestamp format, when the object was initially created as a current version.
ETag	header	xsd: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 MD5 checksums and ETags 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.
Content-Type	header	xsd:string	The MIME type of the object.
Content-Encoding (Optional)	header	xsd:string	If set, the value of the `Content-Encoding` metadata. If not set, this header is not returned by this operation.
Content-Disposition (Optional)	header	xsd: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. If not set, this header is not returned by this operation.
X-Delete-At (Optional)	header	xsd:string	If set, the time, in UNIX Epoch timestamp format, when the object will be deleted by the system. If not set, this header is not returned by this operation.
X-Object-Meta-name	header	xsd:string	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 item (for each `{name}`).
X-Object-Manifest (Optional)	header	xsd:string	If set, to 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`.
X-Static-Large-Object	header	xsd:boolean	Set to `True` if this object is a static large object manifest object.
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.

This operation does not return a response body.

PUT

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

Create or replace object

Creates an object with specified data content and metadata, or replaces an existing object with specified 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 a 201 Created status code.

Example requests and responses:

Create object:

curl -i $publicURL/janeausten/helloworld.txt -X PUT -H "Content-Length: 1" -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: 116
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
Date: Fri, 17 Jan 2014 17:28:35 GMT
```

Replace object:

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

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

The 201 Created status code indicates a successful write.

If the request times out, the operation returns the 408 Request Timeout error code.

The 411 Length Required error 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 422 Unprocessable Entity error code.

Normal response codes

201

Error response codes

timeout (408), lengthRequired (411), unprocessableEntity (422)

Request parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
container	URI	xsd:string	The unique 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, `/account/container/object`.
object	URI	xsd:string	The unique name for the object.
multipart-manifest (Optional)	query	xsd:string	If `?multipart-manifest=put`, the object is a static large object manifest and the body contains the manifest.
temp_url_sig	query	xsd: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 OpenStack Object Storage API v1 Reference .
temp_url_expires	query	xsd:string	Used with temporary URLs to specify the expiry time of the signature as a UNIX Epoch timestamp, which is an integer value. For example, 1390852007 represents Mon, 27 Jan 2014 19:46:47 GMT. For more information about temporary URLs, see OpenStack Object Storage API v1 Reference .
filename (Optional)	query	xsd:string	Used with temporary URLs to override 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 be saved. For more information about temporary URLs, see OpenStack Object Storage API v1 Reference .
X-Object-Manifest (Optional)	header	xsd: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	xsd: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).
Content-Length (Optional)	header	xsd:int	Set to the length of the object content. Do not set if chunked transfer encoding is being used.
Transfer-Encoding (Optional)	header	xsd: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	xsd:string	Changes the MIME type for the object.
X-Detect-Content-Type (Optional)	header	xsd: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	xsd: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.
ETag (Optional)	header	xsd:string	The MD5 checksum value of the request body. For example, the MD5 checksum value of the object content. You are strongly recommended to compute the MD5 checksum value of object content 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	xsd: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	xsd:string	If set, the value of the `Content-Encoding` metadata.
X-Delete-At (Optional)	header	xsd:int	The certain date, in UNIX Epoch timestamp format, when the object will be removed.
X-Delete-After (Optional)	header	xsd:int	Specifies the number of seconds after which the object is removed. Internally, the Object Storage system stores this value in the `X-Delete-At` metadata item.
X-Object-Meta-name (Optional)	header	xsd: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 item (for each `{name}`) that you want to add or update.
If-None-Match (Optional)	header	xsd: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.

Response parameters

Parameter	Style	Type	Description
last_modified	plain	xsd:datetime	The date and time when the object was last modified.
Content-Length	header	xsd:string	If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
ETag	header	xsd:string	For objects smaller than 5 GB, this value is the MD5 checksum of the uploaded object content. The value is not quoted. If you supplied an `ETag` request header and the operation was successful, the values are the same. If you did not supply an `ETag` request header, check the `ETag` response header value against the object content you have just uploaded. For static large objects, this value is the MD5 checksum of the concatenated string of MD5 checksums and ETags for each of the segments in the manifest, and not the MD5 checksum of the content that was uploaded. Also the value is enclosed in double-quotes. For dynamic large objects, the value is the MD5 checksum of the empty string.
Content-Type	header	xsd:string	The MIME type of the object.
X-Timestamp	header	xsd:string	The date and time, in UNIX Epoch timestamp format, when the object was initially created as a current version.
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.

This operation does not return a response body.

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.

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. 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
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
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 parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
container	URI	xsd:string	The unique 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, `/account/container/object`.
object	URI	xsd:string	The unique name for the object.
X-Auth-Token (Optional)	header	xsd: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).
Destination	header	xsd: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.
Content-Type (Optional)	header	xsd:string	Changes the MIME type for the object.
Content-Encoding (Optional)	header	xsd:string	If set, the value of the `Content-Encoding` metadata.
Content-Disposition (Optional)	header	xsd: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	xsd: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 item (for each `{name}`) that you want to add or update.
X-Fresh-Metadata (Optional)	header	xsd: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`.

Response parameters

Parameter	Style	Type	Description
Content-Length	header	xsd:string	If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
X-Copied-From-Last-Modified (Optional)	header	xsd:string	For a copied object, shows the last modified date and time for the container and object name from which the new object was copied.
X-Copied-From (Optional)	header	xsd:string	For a copied object, shows the container and object name from which the new object was copied. The value is in form `{container}/{object}`.
Last-Modified	header	xsd:string	The date and time that the object was created or the last time that the metadata was changed.
ETag	header	xsd:string	The MD5 checksum of the copied object content. The value is not quoted.
Content-Type	header	xsd:string	The MIME type of the object.
X-Timestamp	header	xsd:string	The date and time, in UNIX Epoch timestamp format, when the object was initially created as a current version.
X-Object-Meta-name	header	xsd:string	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 item (for each `{name}`).
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.

This operation does not return a response body.

DELETE

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

Delete object

Permanently deletes an object from the object store.

You can use the COPY method to copy the object to a new location. Then, use the DELETE method to delete the original object.

Object deletion occurs immediately at request time. Any subsequent GET, HEAD, POST, or DELETE operations 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.

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
Date: Wed, 15 Jan 2014 21:29:16 GMT
```

Normally 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.

Error response codes

400, 500, …

Request parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
container	URI	xsd:string	The unique 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, `/account/container/object`.
object	URI	xsd:string	The unique name for the object.
multipart-manifest (Optional)	query	xsd:string	If you include the `multipart-manifest=delete` query parameter and the object is a static large object, the segment objects and the manifest object are deleted. If you omit the `multipart-manifest=delete` query parameter and this is a static large object, the manifest object is deleted and the segment objects are not deleted. For a bulk delete, the response body looks the same as it does for a normal bulk delete. In contrast, a plain object DELETE response has an empty body.
X-Auth-Token (Optional)	header	xsd: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

Parameter	Style	Type	Description
Content-Length	header	xsd:string	If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Content-Type	header	xsd:string	The MIME type of the object.
X-Timestamp	header	xsd:string	The date and time, in UNIX Epoch timestamp format, when the object was initially created as a current version.
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.

This operation does not return a response body.

HEAD

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

Show object metadata

Shows object metadata.

If the Content-Length response header is non-zero, the example 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.

Example requests and responses:

Show object metadata:

curl -i $publicURL/marktwain/goodbye -X 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
Date: Thu, 16 Jan 2014 21:13:19 GMT

If the request succeeds, the operation returns the 204 status code.

Normal response codes

204

Request parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
container	URI	xsd:string	The unique 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, `/account/container/object`.
object	URI	xsd:string	The unique name for the object.
X-Auth-Token	header	xsd:string	Authentication token.
temp_url_sig	query	xsd: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 OpenStack Object Storage API v1 Reference .
temp_url_expires	query	xsd:string	Used with temporary URLs to specify the expiry time of the signature as a UNIX Epoch timestamp, which is an integer value. For example, 1390852007 represents Mon, 27 Jan 2014 19:46:47 GMT. For more information about temporary URLs, see OpenStack Object Storage API v1 Reference .
filename (Optional)	query	xsd:string	Used with temporary URLs to override 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 be saved. For more information about temporary URLs, see OpenStack Object Storage API v1 Reference .
X-Newest (Optional)	header	xsd: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.

Response parameters

Parameter	Style	Type	Description
Last-Modified	header	xsd:string	The date and time that the object was created or the last time that the metadata was changed.
Content-Length	header	xsd:string	The length of the object content in the response body, in bytes.
Content-Length	header	xsd:string	HEAD operations do not return content. However, in this operation the value in the `Content-Length` header is not the size of the response body. Instead it contains the size of the object, in bytes.
Content-Type	header	xsd:string	The MIME type of the object.
X-Timestamp	header	xsd:string	The date and time, in UNIX Epoch timestamp format, when the object was initially created as a current version.
ETag	header	xsd: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 MD5 checksums and ETags 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.
Content-Encoding (Optional)	header	xsd:string	If set, the value of the `Content-Encoding` metadata. If not set, this header is not returned by this operation.
Content-Disposition (Optional)	header	xsd: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. If not set, this header is not returned by this operation.
X-Delete-At (Optional)	header	xsd:string	If set, the time, in UNIX Epoch timestamp format, when the object will be deleted by the system. If not set, this header is not returned by this operation.
X-Object-Manifest (Optional)	header	xsd:string	If set, to 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`.
X-Object-Meta-name	header	xsd:string	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 item (for each `{name}`).
X-Static-Large-Object	header	xsd:boolean	Set to `True` if this object is a static large object manifest object.
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.

This operation does not return a response body.

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.

In addition to the custom metadata, you can also update these system metadata items: Content-Type Content-Encoding Content-Disposition X-Delete-At. 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.

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.

You can also use the form POST feature to upload objects.

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
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
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 parameters

Parameter	Style	Type	Description
account	URI	xsd:string	The unique name for the account. An account is also known as the project or tenant.
container	URI	xsd:string	The unique 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, `/account/container/object`.
object	URI	xsd:string	The unique name for the object.
X-Auth-Token (Optional)	header	xsd: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-Object-Meta-name (Optional)	header	xsd: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 item (for each `{name}`) that you want to add or update.
X-Delete-At (Optional)	header	xsd:int	The certain date, in UNIX Epoch timestamp format, when the object will be removed.
Content-Disposition (Optional)	header	xsd: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	xsd:string	If set, the value of the `Content-Encoding` metadata.
X-Delete-After (Optional)	header	xsd:int	Specifies the number of seconds after which the object is removed. Internally, the Object Storage system stores this value in the `X-Delete-At` metadata item.
Content-Type (Optional)	header	xsd:string	Changes the MIME type for the object.
X-Detect-Content-Type (Optional)	header	xsd: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.

Response parameters

Parameter	Style	Type	Description
Content-Length	header	xsd:string	If the operation succeeds, this value is zero (0). If the operation fails, this value is the length of the error text in the response body.
Content-Type	header	xsd:string	The MIME type of the object.
X-Timestamp	header	xsd:string	The date and time, in UNIX Epoch timestamp format, when the object was initially created as a current version.
X-Trans-Id	header	csapi:uuid	A unique transaction identifier for this request. Your service provider might need this value if you report a problem.
Date	header	xsd:datetime	The transaction date and time.

This operation does not return a response body.