Skip to main content

Create and access a VM

The usual path is: create a project, gather the inputs, choose how access works, send the create request, and wait until the VM is ready. Each step below says what to look at.

Create a project

A project owns VMs, networks, public IPs and SSH keys. The same projectId takes part in every call that follows.

curl --request POST \
  --url 'https://api.zennohosting.com/v1/projects' \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
"name": "automation-project"
}'

Pick an image and a configuration

Before creating a VM, fetch live imageId and tariffId values from the catalogues — do not copy them from examples. If the VM needs a new public IP, choose a separate tariff for it as well.

The configurations list carries two fields worth checking before you send the request.

  • availability — whether at least one VM of this configuration can be created right now.

  • maxCount — roughly how many VMs of this configuration can be created right now. It is 0 when the configuration is unavailable or capacity is unknown.

Availability is advisory, not a guarantee

Both fields are advisory and may lag real cluster capacity by a short interval. Use them so you do not offer a configuration that clearly cannot be created, but still handle 409 Conflict with code insufficientCapacity: capacity can run out between the check and the request.

Decide how access works

  • sshPublicKeys — when the client already holds OpenSSH public keys and passes them in the request.

  • sshKeyIds — when you want to reuse keys registered in the project.

  • publicIpMode — whether the VM gets a public IP at creation and whether that IP is new.

  • plugins — whether to attach optional plugins during provisioning.

Create the VM

The example below reuses project keys, requests a new public IP with its own tariff and attaches a plugin. Adjust the field set to your case.

curl --request POST \
  --url 'https://api.zennohosting.com/v1/projects/{projectId}/vms' \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
"tariffId": "00000000-0000-0000-0000-000000000000",
"imageId": "00000000-0000-0000-0000-000000000000",
"vmName": "worker-01",
"plugins": [
  "00000000-0000-0000-0000-000000000000"
],
"sshKeyIds": [
  "00000000-0000-0000-0000-000000000000"
],
"publicIpMode": "New",
"publicIpTariffId": "00000000-0000-0000-0000-000000000000",
"privateNetworkIds": [
  "00000000-0000-0000-0000-000000000000"
]
}'
  1. 1

    Check your quotas

    GET /limits shows how many VMs and how much CPU, memory and disk you have left. If the remainder is zero, the create request will be refused.

  2. 2

    Fetch the image and tariff

    Pull the image and tariff catalogues, and while you are there check availability and maxCount for the configuration you picked.

  3. 3

    Create the project and keep its identifier

    The same projectId is needed for VMs, SSH keys, networks and backups.

  4. 4

    Settle the access method

    Either register SSH keys in the project up front, or pass public keys directly in the create request.

  5. 5

    Send the request and save the password immediately

    If the response contains a password, store it right away: it is shown once and cannot be retrieved later.

  6. 6

    Wait until the VM is ready

    Poll the VM and watch status: creating while it is being provisioned, active once it is ready. bootStatus shows power. Check the identifiers, sizing and network interfaces at the same time.

What you should end up with

At the end you have a VM in active, its identifier, a clear access method and a recorded decision about the public IP and plugins. If status came out as failed, the VM will not recover on its own — the operation record and its failureCode carry the reason.

The password is shown once

The create response may contain a password that no endpoint will return again. If your workflow needs it, store it before the response leaves the client boundary.

GET/limits

Check remaining quota before creating.

POST/projects

Create the parent project.

GET/configurations

Pick a configuration and check its availability.

GET/images

Get an image identifier for the create request.

GET/tariffs

Get a VM tariff identifier.

POST/projects/{projectId}/ssh-keys

Register reusable SSH keys in the project.

POST/projects/{projectId}/vms

Create the virtual machine.

GET/projects/{projectId}/vms/{vmId}

Read the VM and check its status.