Block Storage

API for block storage operations

Version: 0.1.0

Server

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

Paths

/resource/blockstorage/{providerUid}

GET

List block storage volumes

List block storage volumes 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 resource belongs to
nextToken query string ❌ Token for the next page of volumes, if there are more items to fetch
maxResults query integer ❌ Maximum number of volumes 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 block storage volume

Initiate creation of a new block storage volume 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 resource 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: BlockStorageCreate

Responses:

  • 200: Block storage volume create operation completed

  • 202: Block storage volume create operation initiated

  • 400: Argument validation error

/resource/blockstorage/{providerUid}/{resourceUid}

GET

Get block storage volume

Get block storage volume details

Parameters:

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

Responses:

  • 200: Block storage volume data

  • 400: Argument validation error

  • 404: Block storage volume not found

DELETE

Delete block storage volume

Initiate deletion of a block storage volume, 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.

Parameters:

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

Responses:

  • 200: Block storage volume deletion completed

  • 202: Block storage volume deletion initiated

  • 400: Argument validation error

  • 404: Block storage volume not found

/resource/blockstorage/{providerUid}/{resourceUid}/attachment

GET

List block storage attachments

List attachments for the specified block storage volume (volume-to-machine associations).

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider
regionUid query string ✅ Unique identifier of the region the resource belongs to
resourceUid path string ✅ Unique identifier of the block storage volume
nextToken query string ❌ Token for the next page of attachments, if there are more items to fetch
maxResults query integer ❌ Maximum number of attachments to fetch

Responses:

  • 200: Block storage attachments for the volume

  • 400: Argument validation error

  • 404: Provider or block storage volume not found

POST

Create block storage attachment (attach volume to machine)

Initiate attaching the block storage volume to a machine, and return an Action representing the attach operation.

The operation may take a while. The request starts the action immediately, and optionally waits a configurable amount of time for the action to complete. If the action completes within the wait time, the operation returns 200 OK with the Action object in completed state. If the action does not complete within the wait time, 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 returns successful HTTP response (200 or 202) even if the underlying attach operation fails. Error response is returned if the Action cannot be initiated.

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider
regionUid query string ✅ Unique identifier of the region the resource belongs to
resourceUid path string ✅ Unique identifier of the block storage volume
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: BlockStorageAttachmentCreate

Responses:

  • 200: Attach operation completed

  • 202: Attach operation initiated

  • 400: Argument validation error

  • 404: Provider or block storage volume not found

/resource/blockstorage/{providerUid}/{resourceUid}/attachment/{attachmentUid}

GET

Get block storage attachment

Get attachment details for the specified volume and attachment.

Parameters:

Name In Type Required Description
providerUid path ProviderId ✅ Unique identifier of the provider
regionUid query string ✅ Unique identifier of the region the resource belongs to
resourceUid path string ✅ Unique identifier of the block storage volume
attachmentUid path string ✅ Unique identifier of the attachment (e.g. machine UID or composite volume:machine)

Responses:

  • 200: Block storage attachment data

  • 400: Argument validation error

  • 404: Provider, block storage volume, or attachment not found

DELETE

Delete block storage attachment (detach volume from machine)

Initiate detaching the block storage volume from the machine, and return an Action representing the detach operation.

The operation may take a while. The request starts the action immediately, and optionally waits a configurable amount of time for the action to complete. If the action completes within the wait time, the operation returns 200 OK with the Action object in completed state. If the action does not complete within the wait time, 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 returns successful HTTP response (200 or 202) even if the underlying detach operation fails. Error response is returned if the Action cannot be initiated.

Parameters:

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

Responses:

  • 200: Detach operation completed

  • 202: Detach operation initiated

  • 400: Argument validation error

  • 404: Provider, block storage volume, or attachment not found

Schemas

BlockStorage

Block storage volume

Composition: allOf

Type: object

Properties:

Name Type Required Description
availabilityZone string Availability zone of the block storage volume, if applicable
name string Name of the block storage volume
sizeGb number ✅ Size of the block storage volume, in gigabytes
status string Status of the block storage volume
tags array Tags of the volume. kopernik.us stores tags itself for every provider, so they are not visible in the provider’s own console, and they are deleted along with the volume.
description string Description of the block storage volume
attachments array<BlockStorageAttachment> Attachments of the block storage volume to machines. Currently, only one attachment is supported per volume, but this may change in the future.

BlockStorageResourceResponse

Response with block storage volume

Composition: allOf

Type: object

Properties:

Name Type Required Description
resource BlockStorage ✅

BlockStoragePagedResourceResponse

Response with paged block storage volumes

Composition: allOf

Type: object

Properties:

Name Type Required Description
resources array<BlockStorage> ✅

BlockStorageCreate

Request to create a new block storage volume

Type: object

Properties:

Name Type Required Description
regionUid string ✅ Region identifier where the volume will be created
availabilityZone string Availability zone where the volume will be created, if applicable
sizeGb number ✅ Size of the block storage volume, in gigabytes
name string Name of the block storage volume
description string Description of the block storage volume
tags array Tags for the volume. kopernik.us stores tags itself rather than sending any to the provider, so they are not visible in the provider’s own console, and they are deleted along with the volume. A tag is either key or key=value, holds no control characters and at most 256 characters, and one volume carries at most 100; one tag is kept per key, so a repeated key keeps the value given last. Tags are set when the volume is created, and replaced afterwards through /resource/tags.
mountPoint string When creating a volume attached to a machine (via Machine API), optional mount point on the machine. If there is more than one volume attached to the machine, then this property must be unique for each volume. This property cannot be set when creating a standalone volume.

BlockStorageAttachment

Represents the association of a volume with a machine.

Type: object

Properties:

Name Type Required Description
uid string ✅ Unique identifier of the attachment.
accountKey AccountKey ✅
blockStorageUid string ✅ UID of the block storage volume.
regionUid string ✅ Region where the attachment is located.
machineUid string ✅ UID of the machine the volume is attached to.
deviceName string Device name of the attached volume, e.g. “/dev/disk/by-id/scsi-0_volume_012345”.
mountPoint string Mount point on the machine. When set, the volume is mounted to this path. This property is only available when the machine and the volume are managed via this API.
status string enum Attachment lifecycle state. Semantics are provider-specific.
mount BlockStorageMount

BlockStorageMount

Whether the volume is mounted at its mount point, as the agent on the machine last reported. Only present when the attachment has a mount point and the machine is managed via this API.

Type: object

Properties:

Name Type Required Description
state string enum ✅ mounted when the volume is mounted at its mount point, failed when the agent could not mount it, and pending while the agent has yet to report either.
status string ✅ Human-readable detail of the state, carrying the reason a volume is not mounted.

BlockStorageAttachmentCreate

Request to attach a block storage volume to a machine.

Type: object

Properties:

Name Type Required Description
machineUid string ✅ UID of the machine to attach the volume to
mountPoint string Optional mount point on the machine. When set, the volume is mounted to this path.

BlockStorageAttachmentResponse

Response with a single block storage attachment.

Composition: allOf

Type: object

Properties:

Name Type Required Description
attachment BlockStorageAttachment ✅

BlockStorageAttachmentListResponse

Response with a list of block storage attachments for a volume.

Composition: allOf

Type: object

Properties:

Name Type Required Description
attachments array<BlockStorageAttachment> ✅ List of attachments.
Last updated October 30, 2026Send feedback