Skip to contentcloudvix

Version 1.0.0

Cloudvix API

Order, check and manage your servers from your own scripts and tools. Everything here also works in the dashboard.

Overview

Authentication

Send your API key in the Authorization header of every request. Create keys in the dashboard under API: a key is shown only once, so store it safely. A revoked key stops working at once.

Authentication

Authorization: Bearer cvx_…
Create an API key

Base URL

All paths below start at this address. Requests and responses are JSON (UTF-8); times are UTC in ISO 8601.

Base URL

https://cloudvix.com/api/v1

Rate limit

Each key may make 60 requests per minute. Above that, the answer is 429 with a Retry-After header in seconds. Orders and server actions have their own limits, listed with each endpoint.

Safe retries

Send an Idempotency-Key header (for example a UUID) with orders and server actions. If the connection drops, repeat the request with the same key: it is never done twice.

Errors

Every error has the same JSON shape: a stable code and a message in English. Check the code, not the message. New codes may be added.

Errors

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is unknown or has been revoked."
  }
}

Error codes

  • missing_api_key
  • invalid_api_key
  • rate_limited
  • internal_error
  • invalid_request
  • invalid_idempotency_key
  • invalid_name
  • invalid_location
  • invalid_image
  • invalid_plan
  • invalid_billing
  • invalid_access
  • invalid_ssh_key
  • password_required
  • image_disk_too_small
  • insufficient_balance
  • subscription_inactive
  • not_found
  • out_of_stock
  • server_limit_reached
  • idempotency_conflict
  • catalog_unavailable
  • invalid_state
  • action_in_progress
  • confirm_mismatch
  • actions_unavailable
  • action_failed
  • action_unconfirmed
  • permission_denied
  • password_unconfirmed
  • invalid_key_name
  • invalid_public_key
  • private_key_sent
  • weak_key
  • unsupported_key_type
  • ssh_key_limit_reached
  • ssh_key_in_use
  • request_too_large
  • abuse_stopped
  • payment_unavailable

Endpoints

GET/account

The account that owns the API key#

Responses

  • 200

    The account.

    Returns Account

  • 401

    The API key is missing, malformed, unknown or revoked (missing_api_key, invalid_api_key).

    Headers: WWW-Authenticate

  • 429

    More than 60 requests in the current minute for this key (rate_limited).

    Headers: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Example request

curl https://cloudvix.com/api/v1/account \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Example response (200)

{
  "id": "0b6c1d2e-3f40-4a5b-9c6d-7e8f9a0b1c2d",
  "email": "you@example.com",
  "locale": "en",
  "created_at": "2026-11-01T08:30:00Z"
}
Back to contents

GET/servers

List your servers#

Responses

  • 200

    Your servers, newest first.

    Returns ServerList

  • 401

    The API key is missing, malformed, unknown or revoked (missing_api_key, invalid_api_key).

    Headers: WWW-Authenticate

  • 429

    More than 60 requests in the current minute for this key (rate_limited).

    Headers: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Example request

curl https://cloudvix.com/api/v1/servers \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Example response (200)

{
  "servers": [
    {
      "id": "3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70",
      "name": "web-1",
      "status": "running",
      "location": "DE",
      "image": "ubuntu-24.04",
      "plan": "R-START",
      "plan_name": "Start",
      "plan_line": "Regular · Intel",
      "billing": "hourly",
      "access": "ssh_key",
      "ssh_key_id": "8d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "ipv4": "203.0.113.10",
      "failure_reason": null,
      "price": {
        "currency": "EUR",
        "hourly": "0.0118",
        "daily": "0.29"
      },
      "created_at": "2026-11-12T10:00:00Z",
      "updated_at": "2026-11-12T10:03:12Z",
      "subscription": null
    },
    {
      "id": "5d2c8e41-7a9b-4c3d-8e1f-2a3b4c5d6e7f",
      "name": "db-1",
      "status": "stopped",
      "location": "DE",
      "image": "ubuntu-24.04",
      "plan": "R-START",
      "plan_name": "Start",
      "plan_line": "Regular · Intel",
      "billing": "monthly",
      "access": "ssh_key",
      "ssh_key_id": "8d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "ipv4": "203.0.113.11",
      "failure_reason": null,
      "price": {
        "currency": "EUR",
        "hourly": "0.0118",
        "daily": "0.29"
      },
      "created_at": "2026-10-12T09:00:00Z",
      "updated_at": "2026-11-12T09:00:00Z",
      "subscription": {
        "status": "unpaid",
        "current_period_end": "2026-11-12T09:00:00Z",
        "deletion_at": "2026-11-15T09:05:00Z"
      }
    }
  ]
}
Back to contents

POST/servers

Order a server (hourly or daily from the balance, or monthly or yearly by card subscription)#

**Hourly or daily:** creates the server record in status pending; it is then set up automatically. Nothing is charged at order time: charges start when the server is running and go on until it is deleted, also while it is stopped. Your balance must cover the first hour (or day) of the new server plus the next hour of your other servers. At most 10 servers per account and 5 orders per 10 minutes. **Monthly or yearly** (only while the catalog's api_billing lists them, and only with a key created with “Allow monthly and yearly orders”): answers 202 with a checkout. The account owner opens its url and pays by card; the server is created after the payment and then appears in GET /api/v1/servers, and the owner gets an email that the order was started with this key. An open checkout holds one place of the server limit until it is paid or expires (after 1 hour). The subscription renews until it is cancelled (dashboard: Balance & billing → Manage subscriptions) or the server is deleted. An Idempotency-Key names one order: a key used for an hourly or daily order cannot be used for a monthly one, and the other way round (409).

Parameters

  • Idempotency-Keystringheaderoptional

    Any unique string (1–200 printable ASCII characters), e.g. a UUID. Repeating a request with the same key returns the same server.

Request body · required

What to order: location, operating system, plan, how you pay and how you log in.

  • namestring or nulloptional

    Hostname (1–63 lower-case letters, digits, dashes). Omit for a generated name like cvx-7f3a.

  • locationstringrequired

    Location code from the catalog, e.g. DE.

  • imagestringrequired

    Operating system slug, e.g. ubuntu-24.04.

  • planstringrequired

    Plan code, e.g. R-START.

  • billing"hourly" | "daily" | "monthly" | "yearly"required

    hourly or daily, paid from the prepaid balance: the server is ordered at once. monthly or yearly: a card subscription; the answer is a checkout (202) whose url the account owner opens to pay, and the server is created after the payment. Refused with invalid_billing while subscriptions are not offered (the catalog's api_billing lists what you can order).

  • access"ssh_key" | "password"required

    ssh_key (needs ssh_key_id) or password (a root password is shown once when the server is ready). Windows Server images: password only.

  • ssh_key_idstring (uuid) or nulloptional

    Id of one of your SSH keys; required when access is ssh_key.

Responses

  • 200

    Same Idempotency-Key as an earlier request: the server ordered then.

    Returns Server

  • 201

    The server was ordered.

    Returns Server

  • 202

    Monthly or yearly: the checkout to pay (the same open checkout again for a repeated Idempotency-Key). Nothing is charged until the account owner pays on its url.

    Returns SubscriptionCheckout

  • 400

    The request is not valid: invalid_request, invalid_idempotency_key, invalid_name, invalid_location, invalid_image, invalid_plan, invalid_billing, invalid_access, invalid_ssh_key, password_required (Windows Server images take password access only), image_disk_too_small (the system needs a bigger disk than the plan has: Windows Server 20 GB).

  • 401

    The API key is missing, malformed, unknown or revoked (missing_api_key, invalid_api_key).

    Headers: WWW-Authenticate

  • 402

    Your balance does not cover the first billing period (insufficient_balance). Top up in the dashboard.

  • 403

    Monthly or yearly with a key created without “Allow monthly and yearly orders” (permission_denied). Nothing was ordered.

  • 409

    out_of_stock, server_limit_reached, or idempotency_conflict (the key was used for a different order).

  • 413

    The request body is larger than 16 KB (request_too_large).

  • 429

    Too many requests for this key, or more than 5 orders in 10 minutes (rate_limited).

    Headers: Retry-After

  • 500

    Unexpected error on our side (internal_error).

  • 503

    Ordering is paused for a moment while the catalog updates (catalog_unavailable), or card subscriptions cannot be paid right now (payment_unavailable; nothing was charged).

Example request

curl -X POST https://cloudvix.com/api/v1/servers \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-1",
    "location": "DE",
    "image": "ubuntu-24.04",
    "plan": "R-START",
    "billing": "hourly",
    "access": "ssh_key",
    "ssh_key_id": "8d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
  }'
Example response (201)

{
  "id": "3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70",
  "name": "web-1",
  "status": "pending",
  "location": "DE",
  "image": "ubuntu-24.04",
  "plan": "R-START",
  "plan_name": "Start",
  "plan_line": "Regular · Intel",
  "billing": "hourly",
  "access": "ssh_key",
  "ssh_key_id": "8d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "ipv4": null,
  "failure_reason": null,
  "price": {
    "currency": "EUR",
    "hourly": "0.0118",
    "daily": "0.29"
  },
  "created_at": "2026-11-12T10:00:00Z",
  "updated_at": "2026-11-12T10:00:00Z",
  "subscription": null
}
Example request · monthly

curl -X POST https://cloudvix.com/api/v1/servers \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "db-1",
    "location": "DE",
    "image": "ubuntu-24.04",
    "plan": "R-START-AMD",
    "billing": "monthly",
    "access": "ssh_key",
    "ssh_key_id": "8d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
  }'
Example response (202) · monthly

{
  "object": "subscription_checkout",
  "id": "7c3b2a19-0d8e-4f6a-9b5c-1e2d3f4a5b6c",
  "url": "https://checkout.example.com/pay/cs_example",
  "billing": "monthly",
  "plan": "R-START-AMD",
  "location": "DE",
  "price": {
    "currency": "EUR",
    "amount": "6.95"
  },
  "expires_at": "2026-11-12T11:00:00Z"
}
Back to contents

GET/servers/{id}

One of your servers#

Parameters

  • idstring (uuid)in pathrequired

Responses

  • 200

    The server.

    Returns Server

  • 401

    The API key is missing, malformed, unknown or revoked (missing_api_key, invalid_api_key).

    Headers: WWW-Authenticate

  • 404

    No server of yours with this id (not_found).

  • 429

    More than 60 requests in the current minute for this key (rate_limited).

    Headers: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Example request

curl https://cloudvix.com/api/v1/servers/3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70 \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Example response (200)

{
  "id": "3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70",
  "name": "web-1",
  "status": "running",
  "location": "DE",
  "image": "ubuntu-24.04",
  "plan": "R-START",
  "plan_name": "Start",
  "plan_line": "Regular · Intel",
  "billing": "hourly",
  "access": "ssh_key",
  "ssh_key_id": "8d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "ipv4": "203.0.113.10",
  "failure_reason": null,
  "price": {
    "currency": "EUR",
    "hourly": "0.0118",
    "daily": "0.29"
  },
  "created_at": "2026-11-12T10:00:00Z",
  "updated_at": "2026-11-12T10:03:12Z",
  "subscription": null
}
Back to contents

DELETE/servers/{id}

Delete a server (all data is destroyed)#

A failed server was never created: deleting it only removes it from your list. Allowed for servers that are pending, running, stopped or failed (not while provisioning). A running or stopped server's usage up to now is charged first; then billing ends. Confirm with the server's name: JSON body {"confirm": "<name>"} or the query parameter confirm. The response shows the server as deleted, or deleting while the data centre still has to confirm.

Parameters

  • idstring (uuid)in pathrequired
  • Idempotency-Keystringheaderoptional

    Any unique string (1–200 printable ASCII characters), e.g. a UUID. Repeating a request with the same key does not do the action twice.

  • confirmstringin queryoptional

    The server's name (instead of the body).

Request body · optional

Confirmation of a deletion: the server's name. It may also be sent as the query parameter confirm.

  • confirmstringrequired

    The server's name, typed again to confirm: all data on the server is destroyed.

Responses

  • 200

    The server was deleted (or is being deleted).

    Returns ServerActionResult

  • 400

    invalid_request, invalid_idempotency_key, or confirm_mismatch (send the server's name in confirm).

  • 401

    The API key is missing, malformed, unknown or revoked (missing_api_key, invalid_api_key).

    Headers: WWW-Authenticate

  • 403

    The server was stopped by our abuse team (abuse_stopped): it cannot be deleted until it is released — see your tickets.

  • 404

    No server of yours with this id (not_found).

  • 409

    invalid_state (the server is still being created), action_in_progress (another action on this server is still running), or idempotency_conflict (the key was used for a different action).

  • 413

    The request body is larger than 16 KB (request_too_large).

  • 429

    Too many requests for this key, or more than 10 actions on this server or 30 on your account in 10 minutes (rate_limited).

    Headers: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Example request

curl -X DELETE https://cloudvix.com/api/v1/servers/3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70 \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "confirm": "web-1"
  }'
Example response (200)

{
  "type": "delete",
  "queued": false,
  "server": {
    "id": "3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70",
    "name": "web-1",
    "status": "deleted",
    "location": "DE",
    "image": "ubuntu-24.04",
    "plan": "R-START",
    "plan_name": "Start",
    "plan_line": "Regular · Intel",
    "billing": "hourly",
    "access": "ssh_key",
    "ssh_key_id": "8d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "ipv4": "203.0.113.10",
    "failure_reason": null,
    "price": {
      "currency": "EUR",
      "hourly": "0.0118",
      "daily": "0.29"
    },
    "created_at": "2026-11-12T10:00:00Z",
    "updated_at": "2026-11-12T12:00:00Z",
    "subscription": null
  }
}
Back to contents

POST/servers/{id}/actions

Start, stop, reboot, reinstall, delete or reset the root password#

start: stopped servers; your balance must cover the server's first hour (or day) plus the next hour of your running servers. stop: running servers; a stopped server keeps its data and is billed like a running one until you delete it. reboot: running servers. reinstall: running or stopped servers — all data is destroyed; confirm with the server's name. delete: as DELETE /servers/{id}. reset_password: running servers, only with an API key created with the permission “Allow root password resets”; the new password is in root_password of the response and nowhere else, and the account owner gets an email (without the password). At most 10 actions per server and 30 per account in 10 minutes, 3 reinstalls per server per hour, 3 starts at a time (action_in_progress). Stop, start, reboot, reinstall and reset_password return actions_unavailable while server actions are paused on our side.

Parameters

  • idstring (uuid)in pathrequired
  • Idempotency-Keystringheaderoptional

    Any unique string (1–200 printable ASCII characters), e.g. a UUID. Repeating a request with the same key does not do the action twice.

Request body · required

An action on one of your servers. Send an Idempotency-Key header: a repeated request with the same key is not done twice.

type: "start"

  • type"start"required

    Start a stopped server. Your balance must cover its first hour (or day) plus the next hour of your running servers.

type: "stop"

  • type"stop"required

    Stop a running server. It keeps its data and is billed like a running one until you delete it.

type: "reboot"

  • type"reboot"required

    Restart a running server (soft reboot).

type: "reinstall"

  • type"reinstall"required

    Reinstall the operating system of a running or stopped server. ALL DATA ON THE SERVER IS DESTROYED.

  • imagestringrequired

    Operating system slug, available in the server's location, e.g. debian-12.

  • access"ssh_key" | "password"required

    ssh_key (needs ssh_key_id) or password (a new root password, shown once in the dashboard). Windows Server images: password only.

  • ssh_key_idstring (uuid) or nulloptional

    Id of one of your SSH keys; required when access is ssh_key.

  • confirmstringrequired

    The server's name, typed again to confirm: all data on the server is destroyed.

type: "delete"

  • type"delete"required

    Delete the server (same as DELETE /servers/{id}). ALL DATA IS DESTROYED.

  • confirmstringrequired

    The server's name, typed again to confirm: all data on the server is destroyed.

type: "reset_password"

  • type"reset_password"required

    Set a new root password on a running server; the old one stops working, SSH keys keep working. Only with an API key that was created with the permission “Allow root password resets” (otherwise 403 permission_denied). The new password is in root_password of this response only: it is not stored for the API and not shown again.

Responses

  • 200

    The action was done. Same Idempotency-Key as an earlier request: the response of that request, nothing done twice.

    Returns ServerActionResult

  • 400

    invalid_request, invalid_idempotency_key, confirm_mismatch (send the server's name in confirm), and for reinstall: invalid_image, invalid_access, invalid_ssh_key, password_required (Windows Server images take password access only), image_disk_too_small (the system needs a bigger disk than the server's plan has: Windows Server 20 GB).

  • 401

    The API key is missing, malformed, unknown or revoked (missing_api_key, invalid_api_key).

    Headers: WWW-Authenticate

  • 402

    start: your balance does not cover the first hour (or day) of the server (insufficient_balance; top up in the dashboard), or a monthly or yearly server's subscription is not active (subscription_inactive; subscriptions are not available yet).

  • 403

    reset_password, or reinstall with access: password, with a key that was created without the permission “Allow root password resets” (permission_denied), or the server was stopped by our abuse team (abuse_stopped): no action is possible until it is released — see your tickets.

  • 404

    No server of yours with this id (not_found).

  • 409

    invalid_state (not possible in the server's current status), action_in_progress (another action on this server is still running), or idempotency_conflict (the key was used for a different action).

  • 413

    The request body is larger than 16 KB (request_too_large).

  • 429

    Too many requests for this key, more than 10 actions on this server or 30 on your account in 10 minutes, more than 3 reinstalls or 5 root password resets of this server in an hour (rate_limited).

    Headers: Retry-After

  • 500

    Unexpected error on our side (internal_error).

  • 502

    The data centre could not do the action (action_failed): nothing was changed, try again in a few minutes. action_unconfirmed (start): no clear response from the data centre — the server stays stopped; we check it and switch it off if it did start. password_unconfirmed (reset_password, or reinstall with access: password): no clear response from the data centre — the old password may no longer work; reset again.

  • 503

    The action is not available right now (actions_unavailable).

Example request

curl -X POST https://cloudvix.com/api/v1/servers/3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70/actions \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "reboot"
  }'
Example response (200)

{
  "type": "reboot",
  "queued": false,
  "server": {
    "id": "3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70",
    "name": "web-1",
    "status": "running",
    "location": "DE",
    "image": "ubuntu-24.04",
    "plan": "R-START",
    "plan_name": "Start",
    "plan_line": "Regular · Intel",
    "billing": "hourly",
    "access": "ssh_key",
    "ssh_key_id": "8d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "ipv4": "203.0.113.10",
    "failure_reason": null,
    "price": {
      "currency": "EUR",
      "hourly": "0.0118",
      "daily": "0.29"
    },
    "created_at": "2026-11-12T10:00:00Z",
    "updated_at": "2026-11-12T11:00:00Z",
    "subscription": null
  }
}
Example request · reset_password

curl -X POST https://cloudvix.com/api/v1/servers/3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70/actions \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "reset_password"
  }'
Example response (200) · reset_password

{
  "type": "reset_password",
  "root_password": "…",
  "queued": false,
  "server": {
    "id": "3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70",
    "name": "web-1",
    "status": "running",
    "location": "DE",
    "image": "ubuntu-24.04",
    "plan": "R-START",
    "plan_name": "Start",
    "plan_line": "Regular · Intel",
    "billing": "hourly",
    "access": "ssh_key",
    "ssh_key_id": "8d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "ipv4": "203.0.113.10",
    "failure_reason": null,
    "price": {
      "currency": "EUR",
      "hourly": "0.0118",
      "daily": "0.29"
    },
    "created_at": "2026-11-12T10:00:00Z",
    "updated_at": "2026-11-12T11:05:00Z",
    "subscription": null
  }
}
Back to contents

GET/catalog

Locations, operating systems and plans with prices#

Everything you can order, with stock per location. Use code and slug values in POST /servers.

Responses

  • 200

    The catalog.

    Returns Catalog

  • 401

    The API key is missing, malformed, unknown or revoked (missing_api_key, invalid_api_key).

    Headers: WWW-Authenticate

  • 429

    More than 60 requests in the current minute for this key (rate_limited).

    Headers: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Example request

curl https://cloudvix.com/api/v1/catalog \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Example response (200)

{
  "locations": [
    {
      "code": "DE",
      "country": "Germany",
      "city": "Frankfurt"
    }
  ],
  "images": [
    {
      "slug": "ubuntu-24.04",
      "family": "ubuntu",
      "version": "24.04",
      "locations": [
        "DE",
        "NL",
        "PL",
        "US"
      ]
    }
  ],
  "plans": [
    {
      "code": "R-START",
      "plan_name": "Start",
      "plan_line": "Regular · Intel",
      "family": "regular",
      "cpu": "intel",
      "vcpu": 1,
      "ram_gb": 2.5,
      "disk_gb": 15,
      "disk_type": "nvme",
      "traffic_tb": 1,
      "port_mbps": 1000,
      "prices": {
        "currency": "EUR",
        "hourly": "0.0118",
        "hourly_estimated": false,
        "daily": "0.29",
        "monthly_cap": "7.93",
        "monthly": "7.95",
        "yearly": "93.02"
      },
      "availability": {
        "DE": "available",
        "NL": "available",
        "PL": "out_of_stock",
        "US": "available"
      }
    },
    {
      "code": "R-START-AMD",
      "plan_name": "Start",
      "plan_line": "Regular · AMD",
      "family": "regular",
      "cpu": "amd",
      "vcpu": 1,
      "ram_gb": 2.5,
      "disk_gb": 15,
      "disk_type": "nvme",
      "traffic_tb": 1,
      "port_mbps": 1000,
      "prices": {
        "currency": "EUR",
        "hourly": "0.0103",
        "hourly_estimated": true,
        "daily": "0.25",
        "monthly_cap": "6.93",
        "monthly": "6.95",
        "yearly": "81.32"
      },
      "availability": {
        "DE": "available",
        "NL": "available",
        "PL": "available",
        "US": "available"
      }
    }
  ],
  "api_billing": [
    "hourly",
    "daily"
  ]
}
Back to contents

GET/balance

Your prepaid balance#

Responses

  • 200

    The balance and the current spending.

    Returns Balance

  • 401

    The API key is missing, malformed, unknown or revoked (missing_api_key, invalid_api_key).

    Headers: WWW-Authenticate

  • 429

    More than 60 requests in the current minute for this key (rate_limited).

    Headers: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Example request

curl https://cloudvix.com/api/v1/balance \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Example response (200)

{
  "currency": "EUR",
  "balance": "24.71",
  "usage": {
    "per_day": "0.29",
    "per_month": "7.93",
    "days_left": 85
  },
  "auto_top_up": {
    "enabled": true,
    "threshold": "5.00",
    "amount": "25.00",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "expires": "2030-05"
    },
    "disabled_reason": null
  }
}
Back to contents

GET/balance/ledger

Balance history (top-ups, charges, refunds), newest first#

Parameters

  • limitintegerin queryoptional

    Entries per page, 1–100 (default 50).

  • beforestring (uuid)in queryoptional

    next_cursor of the previous page.

Responses

  • 200

    A page of entries.

    Returns LedgerPage

  • 400

    limit or before is not valid (invalid_request).

  • 401

    The API key is missing, malformed, unknown or revoked (missing_api_key, invalid_api_key).

    Headers: WWW-Authenticate

  • 429

    More than 60 requests in the current minute for this key (rate_limited).

    Headers: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Example request

curl https://cloudvix.com/api/v1/balance/ledger?limit=2 \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Example response (200)

{
  "entries": [
    {
      "id": "5e0f1a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
      "kind": "usage",
      "amount": "-0.02",
      "balance_after": "24.71",
      "description": null,
      "server_id": "3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70",
      "created_at": "2026-11-12T11:00:00Z"
    },
    {
      "id": "4d9e0f1a-2b3c-4d4e-9f5a-6b7c8d9e0f1a",
      "kind": "topup",
      "amount": "25.00",
      "balance_after": "24.73",
      "description": null,
      "server_id": null,
      "created_at": "2026-11-12T09:55:00Z"
    }
  ],
  "next_cursor": "4d9e0f1a-2b3c-4d4e-9f5a-6b7c8d9e0f1a"
}
Back to contents

GET/ssh-keys

List your SSH keys#

Responses

  • 200

    Your SSH keys.

    Returns SshKeyList

  • 401

    The API key is missing, malformed, unknown or revoked (missing_api_key, invalid_api_key).

    Headers: WWW-Authenticate

  • 429

    More than 60 requests in the current minute for this key (rate_limited).

    Headers: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Example request

curl https://cloudvix.com/api/v1/ssh-keys \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Example response (200)

{
  "ssh_keys": [
    {
      "id": "8d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "name": "laptop",
      "type": "ssh-ed25519",
      "fingerprint": "SHA256:sE67U6MgwwtZEvQrdveUcRNgNWhaWrUHsJkB2j9wDKw",
      "created_at": "2026-11-12T09:58:00Z"
    }
  ]
}
Back to contents

POST/ssh-keys

Add a public SSH key#

The key can then be used as ssh_key_id when ordering or reinstalling a server. Adding a key that is already in your account returns 200 with the stored key: repeating the request adds nothing. The account owner gets an email for every key added through the API (name, fingerprint, the API key used and the time).

Request body · required

A public SSH key to add.

  • namestringrequired

    A name for the key, 1–64 characters, e.g. laptop.

  • public_keystringrequired

    The PUBLIC key in OpenSSH format (one line of ~/.ssh/id_ed25519.pub). Ed25519, ECDSA or RSA of at least 2048 bits. Never send a private key.

Responses

  • 200

    The key was already in your account: the stored key.

    Returns SshKey

  • 201

    The key was added.

    Returns SshKey

  • 400

    invalid_request, invalid_key_name, invalid_public_key, private_key_sent, weak_key, unsupported_key_type.

  • 401

    The API key is missing, malformed, unknown or revoked (missing_api_key, invalid_api_key).

    Headers: WWW-Authenticate

  • 409

    Your account has its maximum number of SSH keys (ssh_key_limit_reached).

  • 413

    The body is larger than 16 KB (request_too_large).

  • 429

    More than 60 requests in the current minute for this key (rate_limited).

    Headers: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Example request

curl -X POST https://cloudvix.com/api/v1/ssh-keys \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "laptop",
    "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIM5ziDItQKdpJTra65ZH9Tnw9JJrpKKisqc5ggaZOAft you@laptop"
  }'
Example response (201)

{
  "id": "8d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "name": "laptop",
  "type": "ssh-ed25519",
  "fingerprint": "SHA256:sE67U6MgwwtZEvQrdveUcRNgNWhaWrUHsJkB2j9wDKw",
  "created_at": "2026-11-12T09:58:00Z"
}
Back to contents

DELETE/ssh-keys/{id}

Remove an SSH key#

Servers that already have the key keep it. Refused while a server that is still being created waits for the key.

Parameters

  • idstring (uuid)in pathrequired

    SSH key id.

Responses

  • 204

    The key was removed.

  • 401

    The API key is missing, malformed, unknown or revoked (missing_api_key, invalid_api_key).

    Headers: WWW-Authenticate

  • 404

    No SSH key of yours with this id (not_found).

  • 409

    A server that is still being created uses this key (ssh_key_in_use).

  • 413

    The request body is larger than 16 KB (request_too_large).

  • 429

    More than 60 requests in the current minute for this key (rate_limited).

    Headers: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Example request

curl -X DELETE https://cloudvix.com/api/v1/ssh-keys/8d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Example response (204)

HTTP/1.1 204 No Content
Back to contents

Objects

Server#

A server of your account.

  • idstring (uuid)required

    Server id.

  • namestringrequired

    Hostname: lower-case letters, digits and dashes.

  • status"pending" | "provisioning" | "running" | "stopped" | "failed" | "deleting" | "deleted"required

    pending = ordered, waiting to be created; provisioning = being created (usually a few minutes); running = ready, ipv4 is set; failed = could not be created, nothing was charged (see failure_reason); later stopped, deleting (being deleted) and deleted (only in the response to a delete: deleted servers are not listed). Poll this endpoint until the status is running or failed.

  • locationstringrequired

    Location code, e.g. DE, NL, PL, US.

  • imagestringrequired

    Operating system, e.g. ubuntu-24.04.

  • planstringrequired

    Plan code, e.g. R-START.

  • plan_namestringrequired

    Size name to show people, e.g. Start for R-START-AMD. The same in every language. The plan code when we have no name for it. Use plan (the code) as the identifier.

  • plan_linestringnullrequired

    Product line to show next to plan_name: Regular · AMD, Regular · Intel, Storage or Budget (more may be added). null when we have no name for the plan.

  • billing"hourly" | "daily" | "monthly" | "yearly"required

    hourly or daily: paid from the prepaid balance. monthly or yearly: paid by a card subscription (see subscription).

  • access"ssh_key" | "password"required

    SSH key, or a root password shown once when the server is ready.

  • ssh_key_idstring (uuid) or nullrequired

    The SSH key installed on the server (null for password access or a removed key).

  • ipv4string (ipv4) or nullrequired

    Public IPv4 address once the server is running (or stopped); otherwise null.

  • failure_reason"insufficient_balance" | "unavailable" | "rejected" | "provider_error" | "timeout" | "subscription_inactive" | "ssh_key_rejected" or nullrequired

    Why a failed server could not be created, otherwise null: insufficient_balance (the balance no longer covered the first period), unavailable (plan, image or location no longer offered), rejected, provider_error or timeout (a problem on our side; support is told), subscription_inactive (a monthly or yearly server whose subscription was not active when it was to be created; it is refunded), ssh_key_rejected (the SSH key was not accepted by our infrastructure: order again with another key or a root password).

  • priceobjectrequired

    Excluding VAT. Nothing is charged until the server is running.

  • price.currency"EUR"required
  • price.hourlystringrequired

    Price per hour in euro, fixed at order time, e.g. 0.0118.

  • price.dailystringrequired

    Price per day in euro (24 hours, rounded up to a cent), fixed at order time.

  • created_atstring (date-time)required

    When the server was ordered (UTC, ISO 8601).

  • updated_atstring (date-time)required

    Last status change (UTC, ISO 8601).

  • subscriptionobject or nullrequired

    monthly and yearly servers: their card subscription. Null for hourly and daily servers.

Back to contents

ServerActionResult#

The server after the action.

  • type"start" | "stop" | "reboot" | "reinstall" | "delete" | "reset_password"required

    The action that was done.

  • queuedbooleanrequired

    Stop and delete only: true when the server is stopped or deleted on our side but the data centre has not confirmed it yet (it is retried automatically).

  • serverServerrequired
  • root_passwordstringnulloptional

    reset_password only: the new root password, shown in this response once — store it now. Null when the request repeats an earlier Idempotency-Key (nothing was reset again) or the password was already shown in the dashboard. Absent for other actions.

Back to contents

Catalog#

What you can order: locations, operating systems and plans with prices.

  • locationsarray of objectrequired

    Locations you can order in.

  • imagesarray of objectrequired

    Operating systems.

  • plansarray of objectrequired

    Plans with prices and where they can be ordered.

  • api_billingarray of "hourly" | "daily" | "monthly" | "yearly"required

    Billing you can order right now (in the API and in the dashboard): hourly and daily, plus monthly and yearly while subscriptions are offered.

Back to contents

Balance#

The prepaid balance that pays hourly and daily servers. Top up with a card in the dashboard.

  • currency"EUR"required
  • balancestringrequired

    Prepaid balance (negative when usage went past zero) in euro, two decimals, e.g. 7.95.

  • usageobject or nullrequired

    Current spending; null when no hourly or daily server is billed (running, or stopped by you).

  • auto_top_upobject or nullrequired

    Your auto top-up rule, read only (set it up in the dashboard); null when it is not set up or not available.

Back to contents

LedgerPage#

A page of the balance history.

  • entriesarray of LedgerEntryrequired

    Newest first.

  • next_cursorstring (uuid) or nullrequired

    Pass as before for the next (older) page; null on the last page.

Back to contents

LedgerEntry#

One movement of the balance.

  • idstring (uuid)required

    Entry id; also the cursor for the next page.

  • kind"topup" | "refund" | "usage" | "adjustment"required

    topup (card payment), refund (money returned to the card), usage (an hour or a day of a server), adjustment (by support).

  • amountstringrequired

    Change of the balance (negative for charges and refunds) in euro, two decimals, e.g. 7.95.

  • balance_afterstringrequired

    Balance right after this entry in euro, two decimals, e.g. 7.95.

  • descriptionstringnullrequired

    Reason given by support for an adjustment; otherwise null.

  • server_idstring (uuid) or nullrequired

    The server a usage entry charges; otherwise null.

  • created_atstring (date-time)required

    When it was booked (UTC, ISO 8601). For usage: the start of the charged hour or day.

Back to contents

SshKey#

A public SSH key of your account.

  • idstring (uuid)required

    SSH key id, used as ssh_key_id in orders and reinstalls.

  • namestringrequired

    Your name for the key.

  • type"ssh-ed25519" | "ssh-rsa" | "ecdsa-sha2-nistp256" | "ecdsa-sha2-nistp384" | "ecdsa-sha2-nistp521"required

    Key type.

  • fingerprintstringrequired

    SHA-256 fingerprint, as ssh-keygen -lf shows it, e.g. SHA256:….

  • created_atstring (date-time)required

    When the key was added (UTC, ISO 8601).

Back to contents

Account#

The account that owns the API key.

  • idstring (uuid)required

    Your account id.

  • emailstring (email)required

    Email address of the account.

  • locale"en" | "de" | "nl" | "fr"required

    Language of emails and messages.

  • created_atstring (date-time)required

    When the account was created (UTC, ISO 8601).

Back to contents

Error#

Every error response has this shape.

  • errorobjectrequired
  • error.code"missing_api_key" | "invalid_api_key" | "rate_limited" | "internal_error" | "invalid_request" | "invalid_idempotency_key" | "invalid_name" | "invalid_location" | "invalid_image" | "invalid_plan" | "invalid_billing" | "invalid_access" | "invalid_ssh_key" | "password_required" | "image_disk_too_small" | "insufficient_balance" | "subscription_inactive" | "not_found" | "out_of_stock" | "server_limit_reached" | "idempotency_conflict" | "catalog_unavailable" | "invalid_state" | "action_in_progress" | "confirm_mismatch" | "actions_unavailable" | "action_failed" | "action_unconfirmed" | "permission_denied" | "password_unconfirmed" | "invalid_key_name" | "invalid_public_key" | "private_key_sent" | "weak_key" | "unsupported_key_type" | "ssh_key_limit_reached" | "ssh_key_in_use" | "request_too_large" | "abuse_stopped" | "payment_unavailable"required

    Stable machine-readable code. New codes may be added.

  • error.messagestringrequired

    Explanation for a human, in English. Do not parse it.

Back to contents

Download OpenAPI JSON

Ready to try it?

Create a key in the dashboard and paste it into the examples above.

Create an API key