Skip to main content

Start Here

Quickstart

Use this page when you need the shortest reliable path from access token to a created ZennoHosting virtual machine. The flow stays at workflow level and links to the generated reference when you need exact schema details.

Prerequisites

  • A working API token already issued from the ZennoHosting account experience.

  • A client that can send HTTPS requests with the Authorization header.

  • Permission to query live image and tariff catalogs before building the VM payload.

Connection check

Once you have a token, start with a safe read request. This confirms that the base URL and bearer header are accepted before you prepare project or VM state.

curl --request GET \
  --url 'https://api.zennohosting.com/projects' \
  --header 'Authorization: Bearer <token>' \
  --header 'Accept: application/json'
  1. 1

    Obtain a working access token

    Issue the token in the ZennoHosting account flow, then store it securely in your client runtime or secret store.

  2. 2

    Verify access with a safe read request

    Call GET /projects to confirm that the API accepts the base URL and bearer header before you build provisioning inputs.

  3. 3

    List available provisioning options

    Read configurations, images, and VM tariffs first. If you plan to request a new public IP during VM creation, also resolve the separate public IP tariff inputs instead of reusing the VM tariff.

  4. 4

    Create a project

    Projects scope the VMs, SSH keys, networks, and public IP resources you work with later. Create the project before any child resource and reuse its identifier across the remaining calls.

  5. 5

    Prepare access inputs

    Decide whether the VM should receive raw sshPublicKeys in the creation request or attach existing project-level sshKeyIds. If you want backup-related automation at provisioning time, also decide whether to pass optional plugins.

  6. 6

    Create the VM

    Submit a VM request with image, VM tariff, name, and access data. Optionally declare public IP behavior, public IP tariff inputs, private network attachments, and provisioning-time plugins in the same request.

  7. 7

    Store the password immediately if one is returned

    VM creation can return a password that is shown only once. If the response includes it, persist it immediately because the API should not be treated as a place to retrieve it later.

  8. 8

    Fetch the VM until state is usable

    VM creation is asynchronous. Treat 202 Accepted and commandId as acknowledgement only, then fetch the VM resource and confirm the required operationStatus and bootStatus.

Expected result

After the sequence completes, you should have a working token, a project identifier, a VM identifier, the final access inputs you attached, and a confirmed VM state rather than just an accepted command.

Common issues

Use identifiers from the live API responses, not copied values from examples. Most provisioning failures on first integration come from stale projectId, imageId, or tariffId values, or from assuming the VM is ready immediately after 202 Accepted.

GET/configurations

List available VM configuration profiles.

GET/images

List available base images for provisioning.

GET/tariffs

List the tariff identifiers you can apply to a VM.

POST/projects

Create the project that will own the VM.

POST/projects/{projectId}/vms

Create the virtual machine itself.

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

Fetch the resulting VM resource and inspect operation and boot state.