Naar de inhoudcloudvix

Versie 1.0.0

Cloudvix-API

Bestel, controleer en beheer je servers vanuit je eigen scripts en tools. Alles hier werkt ook in het dashboard.

Overzicht

De referentie van de endpoints hieronder is in het Engels.

Authenticatie

Stuur je API-sleutel bij elk verzoek mee in de Authorization-header. Sleutels maak je in het dashboard onder API: een sleutel zie je maar één keer, bewaar hem dus veilig. Een ingetrokken sleutel werkt meteen niet meer.

Authenticatie

Authorization: Bearer cvx_…
API-sleutel maken

Basis-URL

Alle paden hieronder beginnen bij dit adres. Verzoeken en antwoorden zijn JSON (UTF-8); tijden zijn UTC in ISO 8601.

Basis-URL

https://cloudvix.com/api/v1

Limiet

Elke sleutel mag 60 verzoeken per minuut doen. Daarboven is het antwoord 429 met een Retry-After-header in seconden. Bestellingen en serveracties hebben eigen limieten, die bij elk endpoint staan.

Veilig opnieuw proberen

Stuur bij bestellingen en serveracties een Idempotency-Key-header mee (bijvoorbeeld een UUID). Valt de verbinding weg, herhaal het verzoek dan met dezelfde sleutel: het wordt nooit twee keer uitgevoerd.

Fouten

Elke fout heeft dezelfde JSON-vorm: een vaste code en een bericht in het Engels. Kijk naar de code, niet naar het bericht. Er kunnen nieuwe codes bijkomen.

Fouten

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

Foutcodes

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

Antwoorden

  • 200

    The account.

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

Voorbeeldverzoek

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

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

GET/servers

List your servers#

Antwoorden

  • 200

    Your servers, newest first.

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

Voorbeeldverzoek

curl https://cloudvix.com/api/v1/servers \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Voorbeeldantwoord (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"
      }
    }
  ]
}
Terug naar de inhoud

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-Keystringheaderoptioneel

    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 · verplicht

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

  • namestring or nulloptioneel

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

  • locationstringverplicht

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

  • imagestringverplicht

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

  • planstringverplicht

    Plan code, e.g. R-START.

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

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

    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 nulloptioneel

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

Antwoorden

  • 200

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

    Geeft terug Server

  • 201

    The server was ordered.

    Geeft terug 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.

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

Voorbeeldverzoek

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"
  }'
Voorbeeldantwoord (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
}
Voorbeeldverzoek · 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"
  }'
Voorbeeldantwoord (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"
}
Terug naar de inhoud

GET/servers/{id}

One of your servers#

Parameters

  • idstring (uuid)in padverplicht

Antwoorden

  • 200

    The server.

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

Voorbeeldverzoek

curl https://cloudvix.com/api/v1/servers/3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70 \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Voorbeeldantwoord (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
}
Terug naar de inhoud

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 padverplicht
  • Idempotency-Keystringheaderoptioneel

    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 queryoptioneel

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

Request-body · optioneel

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

  • confirmstringverplicht

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

Antwoorden

  • 200

    The server was deleted (or is being deleted).

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

Voorbeeldverzoek

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"
  }'
Voorbeeldantwoord (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
  }
}
Terug naar de inhoud

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 padverplicht
  • Idempotency-Keystringheaderoptioneel

    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 · verplicht

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

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

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

type: "reboot"

  • type"reboot"verplicht

    Restart a running server (soft reboot).

type: "reinstall"

  • type"reinstall"verplicht

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

  • imagestringverplicht

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

  • access"ssh_key" | "password"verplicht

    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 nulloptioneel

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

  • confirmstringverplicht

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

type: "delete"

  • type"delete"verplicht

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

  • confirmstringverplicht

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

type: "reset_password"

  • type"reset_password"verplicht

    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.

Antwoorden

  • 200

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

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

Voorbeeldverzoek

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"
  }'
Voorbeeldantwoord (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
  }
}
Voorbeeldverzoek · 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"
  }'
Voorbeeldantwoord (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
  }
}
Terug naar de inhoud

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.

Antwoorden

  • 200

    The catalog.

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

Voorbeeldverzoek

curl https://cloudvix.com/api/v1/catalog \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Voorbeeldantwoord (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"
  ]
}
Terug naar de inhoud

GET/balance

Your prepaid balance#

Antwoorden

  • 200

    The balance and the current spending.

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

Voorbeeldverzoek

curl https://cloudvix.com/api/v1/balance \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Voorbeeldantwoord (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
  }
}
Terug naar de inhoud

GET/balance/ledger

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

Parameters

  • limitintegerin queryoptioneel

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

  • beforestring (uuid)in queryoptioneel

    next_cursor of the previous page.

Antwoorden

  • 200

    A page of entries.

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

Voorbeeldverzoek

curl https://cloudvix.com/api/v1/balance/ledger?limit=2 \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Voorbeeldantwoord (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"
}
Terug naar de inhoud

GET/ssh-keys

List your SSH keys#

Antwoorden

  • 200

    Your SSH keys.

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

Voorbeeldverzoek

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

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

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 · verplicht

A public SSH key to add.

  • namestringverplicht

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

  • public_keystringverplicht

    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.

Antwoorden

  • 200

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

    Geeft terug SshKey

  • 201

    The key was added.

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

Voorbeeldverzoek

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

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

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 padverplicht

    SSH key id.

Antwoorden

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

Voorbeeldverzoek

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

HTTP/1.1 204 No Content
Terug naar de inhoud

Objecten

Server#

A server of your account.

  • idstring (uuid)verplicht

    Server id.

  • namestringverplicht

    Hostname: lower-case letters, digits and dashes.

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

    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.

  • locationstringverplicht

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

  • imagestringverplicht

    Operating system, e.g. ubuntu-24.04.

  • planstringverplicht

    Plan code, e.g. R-START.

  • plan_namestringverplicht

    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_linestringnullverplicht

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

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

  • access"ssh_key" | "password"verplicht

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

  • ssh_key_idstring (uuid) or nullverplicht

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

  • ipv4string (ipv4) or nullverplicht

    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 nullverplicht

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

  • priceobjectverplicht

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

  • price.currency"EUR"verplicht
  • price.hourlystringverplicht

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

  • price.dailystringverplicht

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

  • created_atstring (date-time)verplicht

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

  • updated_atstring (date-time)verplicht

    Last status change (UTC, ISO 8601).

  • subscriptionobject or nullverplicht

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

Terug naar de inhoud

ServerActionResult#

The server after the action.

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

    The action that was done.

  • queuedbooleanverplicht

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

  • serverSerververplicht
  • root_passwordstringnulloptioneel

    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.

Terug naar de inhoud

Catalog#

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

  • locationsarray of objectverplicht

    Locations you can order in.

  • imagesarray of objectverplicht

    Operating systems.

  • plansarray of objectverplicht

    Plans with prices and where they can be ordered.

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

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

Terug naar de inhoud

Balance#

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

  • currency"EUR"verplicht
  • balancestringverplicht

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

  • usageobject or nullverplicht

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

  • auto_top_upobject or nullverplicht

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

Terug naar de inhoud

LedgerPage#

A page of the balance history.

  • entriesarray of LedgerEntryverplicht

    Newest first.

  • next_cursorstring (uuid) or nullverplicht

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

Terug naar de inhoud

LedgerEntry#

One movement of the balance.

  • idstring (uuid)verplicht

    Entry id; also the cursor for the next page.

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

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

  • amountstringverplicht

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

  • balance_afterstringverplicht

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

  • descriptionstringnullverplicht

    Reason given by support for an adjustment; otherwise null.

  • server_idstring (uuid) or nullverplicht

    The server a usage entry charges; otherwise null.

  • created_atstring (date-time)verplicht

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

Terug naar de inhoud

SshKey#

A public SSH key of your account.

  • idstring (uuid)verplicht

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

  • namestringverplicht

    Your name for the key.

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

    Key type.

  • fingerprintstringverplicht

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

  • created_atstring (date-time)verplicht

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

Terug naar de inhoud

Account#

The account that owns the API key.

  • idstring (uuid)verplicht

    Your account id.

  • emailstring (email)verplicht

    Email address of the account.

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

    Language of emails and messages.

  • created_atstring (date-time)verplicht

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

Terug naar de inhoud

Error#

Every error response has this shape.

  • errorobjectverplicht
  • 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"verplicht

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

  • error.messagestringverplicht

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

Terug naar de inhoud

OpenAPI-JSON downloaden

Klaar om het te proberen?

Maak een sleutel in het dashboard en plak hem in de voorbeelden hierboven.

API-sleutel maken