Storage

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

POST
/scopes/{scopeId}/storage/buckets

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

Authorization

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

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

Header Parameters

Idempotency-Key*string

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

Formatuuid

Request Body

application/json
  1. body

Payload for creating a bucket.

name*string

Globally unique, DNS-compatible bucket name (3–63 chars).

Match^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$
region*RegionId

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

Match^[a-z][a-z0-9-]{1,39}$
visibility*CreateBucketVisibility

Visibility selected when creating a bucket.

Value in"private""public"
versioning?boolean
Defaultfalse
objectLock?boolean

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

Defaultfalse
storageClass*CreateBucketStorageClass

Storage class selected when creating a bucket. Saved with the bucket; it doesn't change how objects are stored or billed.

Value in"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<>
Itemsitems <= 50

Response Body

Bucket creation accepted; returns the bucket in its transitional creating state.

application/json
  1. response

Object storage bucket, as listed and shown in the bucket detail header and properties.

origin?string

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

Value in"portal""api""system""imported"
status*BucketStatus

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

Value in"creating""active""deleting""error"
id*string
name*string

Globally unique, DNS-compatible bucket name used as the S3 endpoint host.

region*RegionId

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

Match^[a-z][a-z0-9-]{1,39}$
objectCount*integer
sizeBytes*integer
visibility*BucketVisibility

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

Value in"Private""Public""Authenticated"
versioning*boolean
encryption*BucketEncryption

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

Value in"NONE""AT_REST"
kmsKeyId*|

Always null -- customer-managed (KMS) keys are not offered.

storageClass*ObjectStorageClass

Storage class of a bucket, echoed on its objects. Saved with the bucket; it doesn't change how objects are stored or billed.

Value in"Standard""Infrequent Access""Archive"
blockPublicAcls*boolean

Ignore ACLs that grant public access.

blockPublicPolicy*boolean

While true, visibility cannot be set to Public (409). Bucket policy statements are not supported at all.

objectLock*boolean

Legacy 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*boolean
logTarget*string

Server access log target bucket.

owner*string
createdAt*string
Formatdate-time
updatedAt*string
Formatdate-time
curl -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"}