- Method:
POST
- Path:
/v1/orgs/{org}/s3/buckets
- Operation ID:
createBucket
- Tag: Object storage
Send Authorization: Bearer <credential>. The credential is either an API key (vsk_…) created for an organization, or an OIDC access token obtained by signing in to VirtScale.
| Name |
Type |
Required |
Description |
org |
string (uuid) |
Yes |
The organization’s id. |
| Name |
Type |
Required |
Description |
Idempotency-Key |
string, nullable |
No |
|
Content type application/json, schema BucketCreateRequest, required.
| Field |
Type |
Required |
Enum |
Description |
name |
string |
Yes |
|
The bucket name, unique within your organization. Lowercase letters, digits and hyphens; must start and end alphanumeric. Dots are not permitted – they break virtual-hosted addressing. |
versioning |
boolean |
No |
|
Keep previous versions of overwritten and deleted objects. Applied to the bucket by the operation this request returns; read the bucket back and check observed_versioning before relying on it. Note that a versioned bucket is not emptied by deleting its objects – previous versions and delete markers remain, and count towards storage and towards the not-empty check on delete. |
| Field |
Type |
Required |
Enum |
Description |
bucket |
BucketOut |
Yes |
|
|
bucket.created_at |
string (date-time) |
Yes |
|
|
bucket.id |
string (uuid) |
Yes |
|
|
bucket.name |
string |
Yes |
|
|
bucket.observed_at |
string (date-time), nullable |
No |
|
|
bucket.observed_exists |
boolean, nullable |
No |
|
|
bucket.observed_quota |
BucketQuotaOut, nullable |
No |
|
|
bucket.observed_quota.max_objects |
integer, nullable |
No |
|
Objects this bucket may hold. null = no per-bucket cap. |
bucket.observed_quota.max_size_bytes |
integer, nullable |
No |
|
Bytes this bucket may hold. null = no per-bucket cap. |
bucket.observed_versioning |
boolean, nullable |
No |
|
Versioning as the object store last reported it. null means no observation has been recorded – not that versioning is off. |
bucket.operation_id |
string (uuid), nullable |
No |
|
|
bucket.purge_after |
string (date-time), nullable |
No |
|
|
bucket.quota |
BucketQuotaOut |
Yes |
|
|
bucket.quota.max_objects |
integer, nullable |
No |
|
Objects this bucket may hold. null = no per-bucket cap. |
bucket.quota.max_size_bytes |
integer, nullable |
No |
|
Bytes this bucket may hold. null = no per-bucket cap. |
bucket.soft_deleted_at |
string (date-time), nullable |
No |
|
|
bucket.state |
string |
Yes |
|
|
bucket.updated_at |
string (date-time) |
Yes |
|
|
bucket.versioning |
boolean |
Yes |
|
Whether previous versions of overwritten objects are kept, as requested when the bucket was created. This is desired state; observed_versioning is what the object store last reported. |
operation |
OperationRef |
Yes |
|
|
operation.attempt |
integer |
Yes |
|
|
operation.created_at |
string (date-time) |
Yes |
|
|
operation.error_class |
string, nullable |
No |
|
|
operation.error_detail |
string, nullable |
No |
|
|
operation.finished_at |
string (date-time), nullable |
No |
|
When the operation reached a terminal state. Guaranteed non-null whenever state is succeeded, failed or cancelled – including operations that complete synchronously and are returned already succeeded. null means the operation is still in flight. |
operation.id |
string (uuid) |
Yes |
|
|
operation.max_attempts |
integer |
Yes |
|
|
operation.resource_id |
string |
Yes |
|
|
operation.resource_type |
string |
Yes |
|
|
operation.state |
string |
Yes |
|
|
operation.type |
string |
Yes |
|
|
Every error response is application/problem+json (schema Problem).
| Status |
Meaning |
| 400 |
The request is malformed or failed validation. |
| 401 |
The credential is missing or invalid. |
| 403 |
The credential does not have permission to perform this operation. |
| 404 |
The resource does not exist. |
| default |
Any other status is possible; the code field identifies the error. |
curl -X POST "https://api.virtscale.nl/v1/orgs/$ORG_ID/s3/buckets" \
-H "Authorization: Bearer $VIRTSCALE_API_KEY" \
-H "Content-Type: application/json" \
--data @body.json