Bucket

API for object storage bucket operations

Version: 0.1.0

Server

  • URL: https://api.kopernik.us/v0
    • Kopernik.us API server

Paths

/resource/bucket/{providerUid}

GET

List buckets

List object storage buckets for the specified provider

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider
regionUid query string ✅ Unique identifier of the region the buckets belong to
nextToken query string ❌ Token for the next page of buckets, if there are more items to fetch
maxResults query integer ❌ Maximum number of buckets to fetch
jq query string ❌ JQ filter expression to filter the results. Only resources where the expression evaluates to a truthy value are included. The expression is applied to each resource’s JSON representation. Uses jq 1.7 syntax.

Responses:

POST

Create bucket

Initiate creation of a new object storage bucket for the specified provider, and return an Action representing the create operation.

The operation starts the action immediately, and then waits a configurable amount of time for the action to complete. If the action completes within the wait time, then the operation returns 200 OK with the Action object in completed state. If the action does not complete within the wait time, then the operation returns 202 Accepted with the Action object in initiated state. Action status and result can be checked later using the Action API.

Note that this operation’s result represents Action, not the created resource, i.e. returns successful HTTP response (200 or 202) even if the underlying Create resource operation fails. If the action cannot be initiated, then an error response is returned.

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider
regionUid query string ❌ Unique identifier of the region to create the bucket in. Must be provided either as this query parameter or in the request body; when both are given, they must be equal.
waitTime query number ❌ Maximum time to wait for the action to complete with 200 OK before returning 202 Accepted; in seconds

Request Body:

Content Type: application/json

Schema: BucketCreate

Responses:

  • 200: Bucket create operation completed

  • 202: Bucket create operation initiated

  • 400: Argument validation error

/resource/bucket/{providerUid}/{resourceUid}

GET

Get bucket

Get bucket details

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider
resourceUid path string ✅ Unique identifier of the bucket
regionUid query string ✅ Unique identifier of the region the bucket belongs to

Responses:

  • 200: Bucket data

  • 400: Argument validation error

  • 404: Bucket not found

DELETE

Delete bucket

Initiate deletion of a bucket, and return an Action representing the delete operation. Note that this operation returns successful HTTP response (200 or 202) even if the Delete action fails. Error response is returned if the Action cannot be initiated. Resource deletion status and result are available in the returned Action object, or via the Action API later.

The bucket must be empty; deleting a bucket which still holds objects fails.

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider
resourceUid path string ✅ Unique identifier of the bucket to delete
regionUid query string ✅ Unique identifier of the region the bucket belongs to
waitTime query number ❌ Maximum time to wait for the action to complete with 200 OK before returning 202 Accepted; in seconds

Responses:

  • 200: Bucket deletion completed

  • 202: Bucket deletion initiated

  • 400: Argument validation error

  • 404: Bucket not found

Schemas

Bucket

Object storage bucket

Composition: allOf

Type: object

Properties:

Name Type Required Description
name string ✅ Name of the bucket. For S3-compatible providers the name is also the bucket’s unique identifier, and is unique within the provider’s namespace for the region.
endpoint string S3-compatible service endpoint serving this bucket, e.g. “https://s3.us-east-1.amazonaws.com”. Clients use it to address the bucket directly.
createdAt string Creation time of the bucket, in ISO 8601 format.

BucketResourceResponse

Response with bucket

Composition: allOf

Type: object

Properties:

Name Type Required Description
resource Bucket ✅

BucketPagedResourceResponse

Response with paged buckets

Composition: allOf

Type: object

Properties:

Name Type Required Description
resources array<Bucket> ✅

BucketCreate

Request to create a new object storage bucket

Type: object

Properties:

Name Type Required Description
regionUid string ✅ Region identifier where the bucket will be created
name string ✅ Name of the bucket. Must satisfy the provider’s bucket naming rules; for S3-compatible providers this generally means 3-63 characters, lowercase letters, digits, hyphens and dots, starting and ending with a letter or digit.
Last updated October 30, 2026Send feedback