Machine

API for machine operations

Version: 0.1.0

Server

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

Paths

/resource/machine/{providerUid}

GET

List machines

List machines 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 machines, if there are more items to fetch
maxResults query integer ❌ Maximum number of machines 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 machine

Initiate creation of a new machine 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: MachineCreate

Responses:

  • 200: Machine created

  • 202: Machine create initiated

  • 400: Argument validation error

/resource/machine/{providerUid}/{resourceUid}

GET

Get machine

Get machine 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 machine

Responses:

  • 200: Machine details

  • 400: Argument validation error

  • 404: Machine not found

DELETE

Delete machine

Initiate deletion of a machine, 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 machine to delete
attachedVolumesDeletePolicy query AttachedVolumesDeletePolicy ❌
waitTime query number ❌ Maximum time to wait for the action to complete with 200 OK before returning 202 Accepted; in seconds

Responses:

  • 200: Machine deletion completed

  • 202: Machine deletion initiated

  • 400: Argument validation error

  • 404: Machine not found

Schemas

Machine

Machine

Composition: allOf

Type: object

Properties:

Name Type Required Description
machineTypeUid string ✅ ID of the hardware configuration
name string ✅ Name of the machine
status string enum Status of the machine
ipv4 array<NetworkAddress> IPv4 addresses of the machine
ipv6 array<NetworkAddress> IPv6 addresses of the machine
tags array Tags of the machine. 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 machine.
attachments array<BlockStorageAttachment> Block storage attachments to the machine.

NetworkAddress

Network address

Type: object

Properties:

Name Type Required Description
address string ✅ Host address
netmask string Netmask address
gateway string Gateway address
scope string enum Scope of the address

MachineCreate

Request to create a new machine

Type: object

Properties:

Name Type Required Description
regionUid string ✅ Region identifier where the machine will be created
imageUid string ✅ Image identifier for the machine operating system
machineTypeUid string ✅ Machine type identifier specifying hardware configuration
name string Name of the machine
firewallUid string Firewall identifier to associate with the machine
vpcUid string VPC identifier to place the machine in
vpcSubnetUid string VPC subnet identifier for the machine
networkAccess string enum Whether the machine gets a public address of its own. public is rejected when the machine’s subnet does not permit it, so a subnet whose access is enforced by the provider’s network stays the stronger of the two. When omitted, the subnet decides where it can, and the provider’s default applies otherwise. A value the provider cannot honor is rejected rather than ignored; the accepted values are reported in limits.service.machine.supportedNetworkAccess.
userData string User data script to run on machine initialization
authorizedKeyUids array SSH key identifiers to authorize for the machine
tags array Tags for the machine. 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 machine. A tag is either key or key=value, holds no control characters and at most 256 characters, and one machine carries at most 100; one tag is kept per key, so a repeated key keeps the value given last. Tags are set when the machine is created, and replaced afterwards through /resource/tags.
volumes object Configuration of block storage volumes to attach to the machine
enableAdvancedFeatures boolean Set this flag to enable kopernik.us agent installation. This unblocks certain functions, e.g. volume mount managements, use of container app, etc. Default is true; set it to false to create a machine without the agent. Mount points, DNS allocation and container apps require it, and cannot be used when it is false.
dnsRecord MachineDnsRecordCreate When set, an A record is created in one of your DNS zones at the same provider, pointing to the machine’s public IPv4 address, once the machine is provisioned and has obtained a public IP. Requires enableAdvancedFeatures (implied when set). If the machine cannot obtain a public IPv4 address, the create action fails. Omit to skip DNS allocation.

Properties of volumes:

Name Type Required Description
rootVolume BlockStorageCreate Root block storage volume to attach to the machine. Must be empty if machine type provides a root volume, otherwise it must be set. Root volume ignores “mountPoint” property.
additionalVolumes array<BlockStorageCreate> Additional (non-root) block storage volumes to attach to the machine.

MachineDnsRecordCreate

Request to create a DNS A record for the machine’s public IPv4 address.

Type: object

Properties:

Name Type Required Description
zoneUid string ✅ Identifier of your DNS hosted zone (at the same provider) in which to create the record.
hostname string Record name within the zone, e.g. “www” or “@” for the zone apex. Optional; when omitted, a random hostname is generated within the zone.
ttl integer Optional TTL for the record, in seconds.

MachineResourceResponse

Response with machine

Composition: allOf

Type: object

Properties:

Name Type Required Description
resource Machine ✅

MachinePagedResourceResponse

Response with paged machines

Composition: allOf

Type: object

Properties:

Name Type Required Description
resources array<Machine> ✅

AttachedVolumesDeletePolicy

Action to take with attached non-root block storage volumes:

  • “error”: Return an error if there are any attached non-root volumes.
  • “detach”: Detach all non-root volumes before deleting the machine; the volumes (except root volume) remain available after the machine is deleted.
  • “delete”: Delete all attached volumes (including root volume) along with the machine. Default is “error”. Note that root volume is always deleted along with the machine.

Type: enum

Values:

  • error
  • detach
  • delete
Last updated October 30, 2026Send feedback