Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Create an object storage bucket
Provisions a new object storage bucket in the active scope: a globally unique
DNS-compatible name, target region, visibility (private or public), object versioning, a
default storage class (standard, ia or archive; saved with the bucket, it doesn't change how
objects are stored or billed) and key/value tags. Lifecycle rules are NOT supported: the object
store (OpenStack Swift) has no lifecycle engine, so a non-empty lifecycleRules is refused
(see Validation) rather than stored and never applied. encryption is reported truthfully: AT_REST only where the region's object store encrypts at rest, else NONE;
customer-managed keys are not offered. On acceptance the bucket becomes
discoverable in the scoped bucket list in its transitional state.
Validation: name must match ^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$ (3–63 chars,
lowercase letters, numbers, dots, hyphens; alphanumeric at both ends) and be globally
unique (taken → 409 CONFLICT); region must be an offered, generally-available region
(unknown or coming-soon → 422 VALIDATION_FAILED); objectLock: true → 422
VALIDATION_FAILED with field: objectLock and details.reason: object_lock_not_supported
(: the object store cannot enforce object lock against the project's own
credentials, so no new bucket can enable it); a non-empty lifecycleRules → 422
VALIDATION_FAILED with field: lifecycleRules and details.reason: lifecycle_not_supported
(an empty array is accepted); the subscription
bucket quota must not be exhausted (→ 409 QUOTA_EXCEEDED); caller must hold
owner|admin|contributor on the scope, otherwise 403 FORBIDDEN.
Async & state: Asynchronous — returns 202 with the Bucket resource in its transitional
creating state, transitioning creating → active (or → failed on provisioning error).
Progress is emitted as resource.updated SSE frames (kind storage.bucket, patch
{status, objectCount, sizeBytes}) until the bucket is serving requests.
Errors: 401 unauthenticated; 403 caller lacks create permission on the scope; 404
unknown scopeId; 409 CONFLICT bucket name already taken globally; 409 QUOTA_EXCEEDED
bucket quota for the subscription exhausted; 409 CAPACITY_UNAVAILABLE selected region
cannot accept new buckets; 422 invalid name, region, unsupported lifecycle rules or object-lock
combination; 500 unexpected backend failure.
Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns
the original 202 response without creating a duplicate bucket (duplicate creation under a
globally unique namespace would be harmful).
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
Idempotency-Key*stringRequired: this operation creates a new resource asynchronously, so a retry without the key would create a second one. Same key+body within 24h replays the original result; the same key with a different body is 409 CONFLICT. Keys are unique per tenant (the same key in two tenants is two different requests). An API token or service-account (bearer) caller MUST send it -- a request without it is refused with 400 IDEMPOTENCY_KEY_REQUIRED (ErrIdempotencyKeyRequired); reuse the same key on every retry of one logical request. A console session gets one from the edge.
uuidapplication/json- body
Payload for creating a bucket.
name*stringGlobally unique, DNS-compatible bucket name (3–63 chars).
^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$region*RegionIdPlatform region code (a DNS-label-shaped slug, e.g. ist-1). No longer a closed enum: the set of valid region codes is operator-managed in the platform-region registry, so this carries only a shape guard. The authoritative set of activated regions is read from GET /regions; invalid-shape codes are VALIDATION_FAILED and codes absent from the registry are rejected at the resolving endpoint.
^[a-z][a-z0-9-]{1,39}$visibility*CreateBucketVisibilityVisibility selected when creating a bucket.
"private""public"versioning?booleanfalseobjectLock?booleanLegacy platform delete protection. Enforced only on this API and the console; the
object store itself does not enforce it. Direct OpenStack Swift access with the
project's own credentials can delete objects. No new bucket can enable it: true →
422 VALIDATION_FAILED details.reason=object_lock_not_supported.
falsestorageClass*CreateBucketStorageClassStorage class selected when creating a bucket. Saved with the bucket; it doesn't change how objects are stored or billed.
"standard""ia""archive"lifecycleRules?array<>Not supported — must be omitted or empty; a non-empty array is refused with 422 details.reason: lifecycle_not_supported.
tags?array<>items <= 50Bucket creation accepted; returns the bucket in its transitional creating state.
application/json- response
Object storage bucket, as listed and shown in the bucket detail header and properties.
origin?stringWhere the resource was made -- portal for a create on the console, api for an object made straight against the OpenStack API (CLI, Terraform, the Kubernetes cloud provider) that discovery adopted. Informational; nothing behaves differently. Absent from a backend that predates it, which means portal.
"portal""api""system""imported"status*BucketStatusLifecycle status of a bucket. creating until its Swift container exists; active; deleting while the delete Operation drains and removes it (object operations, rule changes and a second delete are refused with 409); error when a create or delete failed (the bucket can be deleted again).
"creating""active""deleting""error"id*stringname*stringGlobally unique, DNS-compatible bucket name used as the S3 endpoint host.
region*RegionIdPlatform region code (a DNS-label-shaped slug, e.g. ist-1). No longer a closed enum: the set of valid region codes is operator-managed in the platform-region registry, so this carries only a shape guard. The authoritative set of activated regions is read from GET /regions; invalid-shape codes are VALIDATION_FAILED and codes absent from the registry are rejected at the resolving endpoint.
^[a-z][a-z0-9-]{1,39}$objectCount*integersizeBytes*integervisibility*BucketVisibilityAccess visibility of a bucket. Authenticated can no longer be set (no container ACL is written for it); a bucket that carries it from before is reported as stored, but the only read ACL ever written for it is the private one.
"Private""Public""Authenticated"versioning*booleanencryption*BucketEncryptionWhether the bucket's data is encrypted at rest. NONE = not encrypted;
AT_REST = encrypted at rest by the object store with platform-managed keys. Set at
bucket creation from the region's operator-asserted capability and never changed
afterwards (the object store encrypts at write time). There are no S3 modes and no
customer-managed keys.
"NONE""AT_REST"kmsKeyId*|Always null -- customer-managed (KMS) keys are not offered.
storageClass*ObjectStorageClassStorage class of a bucket, echoed on its objects. Saved with the bucket; it doesn't change how objects are stored or billed.
"Standard""Infrequent Access""Archive"blockPublicAcls*booleanIgnore ACLs that grant public access.
blockPublicPolicy*booleanWhile true, visibility cannot be set to Public (409). Bucket policy statements are not supported at all.
objectLock*booleanLegacy platform delete protection. Enforced only on this API and the console; the object store itself does not enforce it. Direct OpenStack Swift access with the project's own credentials can delete objects. No new bucket can enable it.
accessLogging*booleanlogTarget*stringServer access log target bucket.
owner*stringcreatedAt*stringdate-timeupdatedAt*stringdate-timecurl -X POST "https://example.com/scopes/string/storage/buckets" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "region": "string", "visibility": "private", "storageClass": "standard" }'{ "origin": "portal", "status": "creating", "id": "string", "name": "string", "region": "string", "objectCount": 0, "sizeBytes": 0, "visibility": "Private", "versioning": true, "encryption": "NONE", "kmsKeyId": "string", "storageClass": "Standard", "blockPublicAcls": true, "blockPublicPolicy": true, "objectLock": true, "accessLogging": true, "logTarget": "string", "owner": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z"}