Zum Inhalt springencloudvix

Version 1.0.0

Cloudvix-API

Bestellen, prüfen und verwalten Sie Ihre Server aus eigenen Skripten und Tools. Alles hier funktioniert auch im Dashboard.

Überblick

Die Referenz der Endpunkte unten ist auf Englisch.

Anmeldung

Senden Sie Ihren API-Schlüssel bei jeder Anfrage im Authorization-Header. Schlüssel erstellen Sie im Dashboard unter API: Ein Schlüssel wird nur einmal angezeigt, bewahren Sie ihn sicher auf. Ein widerrufener Schlüssel funktioniert sofort nicht mehr.

Anmeldung

Authorization: Bearer cvx_…
API-Schlüssel erstellen

Basis-URL

Alle Pfade unten beginnen bei dieser Adresse. Anfragen und Antworten sind JSON (UTF-8); Zeiten sind UTC im Format ISO 8601.

Basis-URL

https://cloudvix.com/api/v1

Anfragelimit

Jeder Schlüssel darf 60 Anfragen pro Minute stellen. Darüber hinaus lautet die Antwort 429 mit einem Retry-After-Header in Sekunden. Bestellungen und Serveraktionen haben eigene Limits, die beim jeweiligen Endpunkt stehen.

Sichere Wiederholungen

Senden Sie bei Bestellungen und Serveraktionen einen Idempotency-Key-Header (zum Beispiel eine UUID). Bricht die Verbindung ab, wiederholen Sie die Anfrage mit demselben Schlüssel: Sie wird nie doppelt ausgeführt.

Fehler

Jeder Fehler hat dieselbe JSON-Form: einen festen Code und eine Meldung auf Englisch. Prüfen Sie den Code, nicht die Meldung. Neue Codes können hinzukommen.

Fehler

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

Fehlercodes

  • 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

Endpunkte

GET/account

The account that owns the API key#

Antworten

  • 200

    The account.

    Liefert Account

  • 401

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

    Header: WWW-Authenticate

  • 429

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

    Header: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Beispielanfrage

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

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

GET/servers

List your servers#

Antworten

  • 200

    Your servers, newest first.

    Liefert ServerList

  • 401

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

    Header: WWW-Authenticate

  • 429

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

    Header: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Beispielanfrage

curl https://cloudvix.com/api/v1/servers \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Beispielantwort (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"
      }
    }
  ]
}
Zurück zum Inhalt

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).

Parameter

  • 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.

Anfrage-Body · Pflicht

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.

  • locationstringPflicht

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

  • imagestringPflicht

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

  • planstringPflicht

    Plan code, e.g. R-START.

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

    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"Pflicht

    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.

Antworten

  • 200

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

    Liefert Server

  • 201

    The server was ordered.

    Liefert 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.

    Liefert 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).

    Header: 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).

    Header: 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).

Beispielanfrage

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"
  }'
Beispielantwort (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
}
Beispielanfrage · 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"
  }'
Beispielantwort (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"
}
Zurück zum Inhalt

GET/servers/{id}

One of your servers#

Parameter

  • idstring (uuid)im PfadPflicht

Antworten

  • 200

    The server.

    Liefert Server

  • 401

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

    Header: 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).

    Header: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Beispielanfrage

curl https://cloudvix.com/api/v1/servers/3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70 \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Beispielantwort (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
}
Zurück zum Inhalt

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.

Parameter

  • idstring (uuid)im PfadPflicht
  • 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 der QueryOptional

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

Anfrage-Body · Optional

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

  • confirmstringPflicht

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

Antworten

  • 200

    The server was deleted (or is being deleted).

    Liefert 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).

    Header: 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).

    Header: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Beispielanfrage

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"
  }'
Beispielantwort (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
  }
}
Zurück zum Inhalt

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.

Parameter

  • idstring (uuid)im PfadPflicht
  • 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.

Anfrage-Body · Pflicht

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"Pflicht

    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"Pflicht

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

type: "reboot"

  • type"reboot"Pflicht

    Restart a running server (soft reboot).

type: "reinstall"

  • type"reinstall"Pflicht

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

  • imagestringPflicht

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

  • access"ssh_key" | "password"Pflicht

    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.

  • confirmstringPflicht

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

type: "delete"

  • type"delete"Pflicht

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

  • confirmstringPflicht

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

type: "reset_password"

  • type"reset_password"Pflicht

    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.

Antworten

  • 200

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

    Liefert 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).

    Header: 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).

    Header: 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).

Beispielanfrage

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"
  }'
Beispielantwort (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
  }
}
Beispielanfrage · 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"
  }'
Beispielantwort (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
  }
}
Zurück zum Inhalt

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.

Antworten

  • 200

    The catalog.

    Liefert Catalog

  • 401

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

    Header: WWW-Authenticate

  • 429

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

    Header: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Beispielanfrage

curl https://cloudvix.com/api/v1/catalog \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Beispielantwort (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"
  ]
}
Zurück zum Inhalt

GET/balance

Your prepaid balance#

Antworten

  • 200

    The balance and the current spending.

    Liefert Balance

  • 401

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

    Header: WWW-Authenticate

  • 429

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

    Header: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Beispielanfrage

curl https://cloudvix.com/api/v1/balance \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Beispielantwort (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
  }
}
Zurück zum Inhalt

GET/balance/ledger

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

Parameter

  • limitintegerin der QueryOptional

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

  • beforestring (uuid)in der QueryOptional

    next_cursor of the previous page.

Antworten

  • 200

    A page of entries.

    Liefert 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).

    Header: WWW-Authenticate

  • 429

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

    Header: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Beispielanfrage

curl https://cloudvix.com/api/v1/balance/ledger?limit=2 \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Beispielantwort (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"
}
Zurück zum Inhalt

GET/ssh-keys

List your SSH keys#

Antworten

  • 200

    Your SSH keys.

    Liefert SshKeyList

  • 401

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

    Header: WWW-Authenticate

  • 429

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

    Header: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Beispielanfrage

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

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

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).

Anfrage-Body · Pflicht

A public SSH key to add.

  • namestringPflicht

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

  • public_keystringPflicht

    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.

Antworten

  • 200

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

    Liefert SshKey

  • 201

    The key was added.

    Liefert 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).

    Header: 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).

    Header: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Beispielanfrage

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"
  }'
Beispielantwort (201)

{
  "id": "8d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "name": "laptop",
  "type": "ssh-ed25519",
  "fingerprint": "SHA256:sE67U6MgwwtZEvQrdveUcRNgNWhaWrUHsJkB2j9wDKw",
  "created_at": "2026-11-12T09:58:00Z"
}
Zurück zum Inhalt

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.

Parameter

  • idstring (uuid)im PfadPflicht

    SSH key id.

Antworten

  • 204

    The key was removed.

  • 401

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

    Header: 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).

    Header: Retry-After

  • 500

    Unexpected error on our side (internal_error).

Beispielanfrage

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

HTTP/1.1 204 No Content
Zurück zum Inhalt

Objekte

Server#

A server of your account.

  • idstring (uuid)Pflicht

    Server id.

  • namestringPflicht

    Hostname: lower-case letters, digits and dashes.

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

    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.

  • locationstringPflicht

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

  • imagestringPflicht

    Operating system, e.g. ubuntu-24.04.

  • planstringPflicht

    Plan code, e.g. R-START.

  • plan_namestringPflicht

    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_linestringnullPflicht

    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"Pflicht

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

  • access"ssh_key" | "password"Pflicht

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

  • ssh_key_idstring (uuid) or nullPflicht

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

  • ipv4string (ipv4) or nullPflicht

    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 nullPflicht

    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).

  • priceobjectPflicht

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

  • price.currency"EUR"Pflicht
  • price.hourlystringPflicht

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

  • price.dailystringPflicht

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

  • created_atstring (date-time)Pflicht

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

  • updated_atstring (date-time)Pflicht

    Last status change (UTC, ISO 8601).

  • subscriptionobject or nullPflicht

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

Zurück zum Inhalt

ServerActionResult#

The server after the action.

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

    The action that was done.

  • queuedbooleanPflicht

    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).

  • serverServerPflicht
  • 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.

Zurück zum Inhalt

Catalog#

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

  • locationsarray of objectPflicht

    Locations you can order in.

  • imagesarray of objectPflicht

    Operating systems.

  • plansarray of objectPflicht

    Plans with prices and where they can be ordered.

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

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

Zurück zum Inhalt

Balance#

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

  • currency"EUR"Pflicht
  • balancestringPflicht

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

  • usageobject or nullPflicht

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

  • auto_top_upobject or nullPflicht

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

Zurück zum Inhalt

LedgerPage#

A page of the balance history.

  • entriesarray of LedgerEntryPflicht

    Newest first.

  • next_cursorstring (uuid) or nullPflicht

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

Zurück zum Inhalt

LedgerEntry#

One movement of the balance.

  • idstring (uuid)Pflicht

    Entry id; also the cursor for the next page.

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

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

  • amountstringPflicht

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

  • balance_afterstringPflicht

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

  • descriptionstringnullPflicht

    Reason given by support for an adjustment; otherwise null.

  • server_idstring (uuid) or nullPflicht

    The server a usage entry charges; otherwise null.

  • created_atstring (date-time)Pflicht

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

Zurück zum Inhalt

SshKey#

A public SSH key of your account.

  • idstring (uuid)Pflicht

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

  • namestringPflicht

    Your name for the key.

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

    Key type.

  • fingerprintstringPflicht

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

  • created_atstring (date-time)Pflicht

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

Zurück zum Inhalt

Account#

The account that owns the API key.

  • idstring (uuid)Pflicht

    Your account id.

  • emailstring (email)Pflicht

    Email address of the account.

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

    Language of emails and messages.

  • created_atstring (date-time)Pflicht

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

Zurück zum Inhalt

Error#

Every error response has this shape.

  • errorobjectPflicht
  • 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"Pflicht

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

  • error.messagestringPflicht

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

Zurück zum Inhalt

OpenAPI-JSON herunterladen

Bereit zum Ausprobieren?

Erstellen Sie im Dashboard einen Schlüssel und setzen Sie ihn in die Beispiele oben ein.

API-Schlüssel erstellen