Object storage service API reference

Endpoint documentation lives on the Object Storage API reference (Swift) and the S3-compatible API reference.

See https://docs.openstack.org/api-ref/object-store/. For error handling guidance, see the API error reference.

In these methods, \{account\} is the account or project identifier, \{container\} is the name of the container, and \{object\} is the name of the object. These methods manage containers and objects in the OpenStack Object Storage (Swift) service: creating, listing, uploading, downloading, and deleting containers and objects, and managing their metadata.

Base URL and account#

The Swift API is served under the /swift/ path prefix on the regional object storage host:

https://object.{region}.rumble.cloud/swift/v1/{account}

\{account\} resolves to AUTH_\{project_id\}, where \{project_id\} is the Keystone project (tenant) UUID. For a project in us-east-1, the base URL has this form:

https://object.us-east-1.rumble.cloud/swift/v1/AUTH_{project_id}

Discover the base URL for the current project from the service catalog:

openstack catalog show object-store -c endpoints -f value

The paths below are relative to the host. Prepend https://object.{region}.rumble.cloud to each one. Every path includes the /swift/ prefix.

Authentication#

Every Swift request carries an X-Auth-Token header. Issue a token with the OpenStack CLI and pass it on each call:

TOKEN=$(openstack token issue -f value -c id)
curl -H "X-Auth-Token: $TOKEN" \
  https://object.us-east-1.rumble.cloud/swift/v1/AUTH_{project_id}

Methods#

List containers#

GET /swift/v1/{account}

Create a container#

PUT /swift/v1/{account}/{container}

Delete a container#

DELETE /swift/v1/{account}/{container}

A container must be empty before deletion. Deleting a container that still holds objects returns 409 Conflict.

List objects in a container#

GET /swift/v1/{account}/{container}

Upload an object#

PUT /swift/v1/{account}/{container}/{object}

The request body carries the object data.

Download an object#

GET /swift/v1/{account}/{container}/{object}

Delete an object#

DELETE /swift/v1/{account}/{container}/{object}

Copy an object#

COPY /swift/v1/{account}/{container}/{object}

The Destination header names the target as \{container\}/\{object\}, with no leading slash and no host. The response confirms the source with X-Copied-From and X-Copied-From-Account headers. A COPY without a valid Destination returns 412 Precondition Failed.

Get container metadata#

HEAD /swift/v1/{account}/{container}

Set container metadata#

POST /swift/v1/{account}/{container}

Set a custom key with an X-Container-Meta-\{name\} request header. A successful update returns 204 No Content. To remove a key, send an empty X-Remove-Container-Meta-\{name\} header.

Get object metadata#

HEAD /swift/v1/{account}/{container}/{object}

Set object metadata#

POST /swift/v1/{account}/{container}/{object}

Set a custom key with an X-Object-Meta-\{name\} request header. A successful update returns 202 Accepted. To remove a key, send an empty X-Remove-Object-Meta-\{name\} header.

Listing options#

Account and container listings return plain-text, newline-delimited names by default. The query parameters below control the response format and pagination. They apply to GET /swift/v1/\{account\} and GET /swift/v1/\{account\}/\{container\}.

curl -H "X-Auth-Token: $TOKEN" \
  "https://object.us-east-1.rumble.cloud/swift/v1/AUTH_{project_id}?format=json"

[{"name":"app-assets","count":537,"bytes":93412560,"last_modified":"2026-05-24T15:37:32.353Z"},
 {"name":"db-backups","count":689,"bytes":141128122,"last_modified":"2026-05-22T12:03:38.060Z"}]

Response status codes#

Quake AI-specific behavior#

Default quotas#

Each container reports its quota in metadata headers, returned on a container HEAD or GET. The platform defaults:

Account-level quotas appear on an account HEAD or GET:

Gateway fall-through and error bodies#

The object storage host serves both the Swift proxy (under /swift/) and the S3-compatible gateway. Two consequences follow:

• An unauthenticated Swift request falls through to the gateway and returns 404 with a plain-text NoSuchKey body instead of a Swift 401. Pass X-Auth-Token to reach the Swift proxy.
• Authenticated 404 responses on Swift paths return gateway-rewritten plain-text bodies: NoSuchBucket for a missing container, NoSuchKey for a missing object. They do not return the Swift-standard JSON or HTML error body.

Extended features#

The proxy supports the standard Swift capabilities below. This page does not detail them. Each entry links to the upstream reference:

• Bulk delete (?bulk-delete=true): Swift bulk middleware.
• Large objects, static and dynamic (X-Object-Manifest, ?multipart-manifest=put): Large object support.
• Temporary URLs (an account Temp-URL-Key plus a signed GET): TempURL middleware.
• Container access control (X-Container-Read, X-Container-Write): Container ACLs.
• Account metadata (X-Account-Meta-\{name\}): Accounts.
• Object versioning (X-Versions-Location): Object versioning.