Aller au contenucloudvix

Version 1.0.0

API Cloudvix

Commandez, surveillez et gérez vos serveurs depuis vos propres scripts et outils. Tout ce qui est ici fonctionne aussi dans le tableau de bord.

Vue d’ensemble

La référence des endpoints ci-dessous est en anglais.

Authentification

Envoyez votre clé API dans l’en-tête Authorization de chaque requête. Créez vos clés dans le tableau de bord, rubrique API : une clé n’est affichée qu’une seule fois, conservez-la en lieu sûr. Une clé révoquée cesse de fonctionner immédiatement.

Authentification

Authorization: Bearer cvx_…
Créer une clé API

URL de base

Tous les chemins ci-dessous partent de cette adresse. Les requêtes et réponses sont en JSON (UTF-8) ; les heures sont en UTC au format ISO 8601.

URL de base

https://cloudvix.com/api/v1

Limite de requêtes

Chaque clé peut envoyer 60 requêtes par minute. Au-delà, la réponse est 429 avec un en-tête Retry-After en secondes. Les commandes et les actions sur les serveurs ont leurs propres limites, indiquées pour chaque endpoint.

Répéter sans risque

Envoyez un en-tête Idempotency-Key (par exemple un UUID) avec les commandes et les actions sur les serveurs. Si la connexion coupe, répétez la requête avec la même clé : elle n’est jamais exécutée deux fois.

Erreurs

Chaque erreur a la même forme JSON : un code stable et un message en anglais. Vérifiez le code, pas le message. De nouveaux codes peuvent être ajoutés.

Erreurs

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

Codes d’erreur

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

Réponses

  • 200

    The account.

    Renvoie Account

  • 401

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

    En-têtes : WWW-Authenticate

  • 429

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

    En-têtes : Retry-After

  • 500

    Unexpected error on our side (internal_error).

Exemple de requête

curl https://cloudvix.com/api/v1/account \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Exemple de réponse (200)

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

GET/servers

List your servers#

Réponses

  • 200

    Your servers, newest first.

    Renvoie ServerList

  • 401

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

    En-têtes : WWW-Authenticate

  • 429

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

    En-têtes : Retry-After

  • 500

    Unexpected error on our side (internal_error).

Exemple de requête

curl https://cloudvix.com/api/v1/servers \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Exemple de réponse (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"
      }
    }
  ]
}
Retour au sommaire

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

Paramètres

  • Idempotency-Keystringen-têtefacultatif

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

Corps de la requête · obligatoire

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

  • namestring or nullfacultatif

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

  • locationstringobligatoire

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

  • imagestringobligatoire

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

  • planstringobligatoire

    Plan code, e.g. R-START.

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

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

    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 nullfacultatif

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

Réponses

  • 200

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

    Renvoie Server

  • 201

    The server was ordered.

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

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

    En-têtes : 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).

    En-têtes : 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).

Exemple de requête

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"
  }'
Exemple de réponse (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
}
Exemple de requête · 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"
  }'
Exemple de réponse (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"
}
Retour au sommaire

GET/servers/{id}

One of your servers#

Paramètres

  • idstring (uuid)dans le cheminobligatoire

Réponses

  • 200

    The server.

    Renvoie Server

  • 401

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

    En-têtes : 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).

    En-têtes : Retry-After

  • 500

    Unexpected error on our side (internal_error).

Exemple de requête

curl https://cloudvix.com/api/v1/servers/3f2a9c1e-5b7d-4e8f-9a01-2b3c4d5e6f70 \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Exemple de réponse (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
}
Retour au sommaire

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.

Paramètres

  • idstring (uuid)dans le cheminobligatoire
  • Idempotency-Keystringen-têtefacultatif

    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.

  • confirmstringdans la requêtefacultatif

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

Corps de la requête · facultatif

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

  • confirmstringobligatoire

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

Réponses

  • 200

    The server was deleted (or is being deleted).

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

    En-têtes : 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).

    En-têtes : Retry-After

  • 500

    Unexpected error on our side (internal_error).

Exemple de requête

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"
  }'
Exemple de réponse (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
  }
}
Retour au sommaire

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.

Paramètres

  • idstring (uuid)dans le cheminobligatoire
  • Idempotency-Keystringen-têtefacultatif

    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.

Corps de la requête · obligatoire

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

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

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

type: "reboot"

  • type"reboot"obligatoire

    Restart a running server (soft reboot).

type: "reinstall"

  • type"reinstall"obligatoire

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

  • imagestringobligatoire

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

  • access"ssh_key" | "password"obligatoire

    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 nullfacultatif

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

  • confirmstringobligatoire

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

type: "delete"

  • type"delete"obligatoire

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

  • confirmstringobligatoire

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

type: "reset_password"

  • type"reset_password"obligatoire

    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.

Réponses

  • 200

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

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

    En-têtes : 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).

    En-têtes : 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).

Exemple de requête

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"
  }'
Exemple de réponse (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
  }
}
Exemple de requête · 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"
  }'
Exemple de réponse (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
  }
}
Retour au sommaire

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.

Réponses

  • 200

    The catalog.

    Renvoie Catalog

  • 401

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

    En-têtes : WWW-Authenticate

  • 429

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

    En-têtes : Retry-After

  • 500

    Unexpected error on our side (internal_error).

Exemple de requête

curl https://cloudvix.com/api/v1/catalog \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Exemple de réponse (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"
  ]
}
Retour au sommaire

GET/balance

Your prepaid balance#

Réponses

  • 200

    The balance and the current spending.

    Renvoie Balance

  • 401

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

    En-têtes : WWW-Authenticate

  • 429

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

    En-têtes : Retry-After

  • 500

    Unexpected error on our side (internal_error).

Exemple de requête

curl https://cloudvix.com/api/v1/balance \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Exemple de réponse (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
  }
}
Retour au sommaire

GET/balance/ledger

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

Paramètres

  • limitintegerdans la requêtefacultatif

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

  • beforestring (uuid)dans la requêtefacultatif

    next_cursor of the previous page.

Réponses

  • 200

    A page of entries.

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

    En-têtes : WWW-Authenticate

  • 429

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

    En-têtes : Retry-After

  • 500

    Unexpected error on our side (internal_error).

Exemple de requête

curl https://cloudvix.com/api/v1/balance/ledger?limit=2 \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Exemple de réponse (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"
}
Retour au sommaire

GET/ssh-keys

List your SSH keys#

Réponses

  • 200

    Your SSH keys.

    Renvoie SshKeyList

  • 401

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

    En-têtes : WWW-Authenticate

  • 429

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

    En-têtes : Retry-After

  • 500

    Unexpected error on our side (internal_error).

Exemple de requête

curl https://cloudvix.com/api/v1/ssh-keys \
  -H "Authorization: Bearer $CLOUDVIX_API_KEY"
Exemple de réponse (200)

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

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

Corps de la requête · obligatoire

A public SSH key to add.

  • namestringobligatoire

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

  • public_keystringobligatoire

    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.

Réponses

  • 200

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

    Renvoie SshKey

  • 201

    The key was added.

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

    En-têtes : 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).

    En-têtes : Retry-After

  • 500

    Unexpected error on our side (internal_error).

Exemple de requête

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"
  }'
Exemple de réponse (201)

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

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.

Paramètres

  • idstring (uuid)dans le cheminobligatoire

    SSH key id.

Réponses

  • 204

    The key was removed.

  • 401

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

    En-têtes : 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).

    En-têtes : Retry-After

  • 500

    Unexpected error on our side (internal_error).

Exemple de requête

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

HTTP/1.1 204 No Content
Retour au sommaire

Objets

Server#

A server of your account.

  • idstring (uuid)obligatoire

    Server id.

  • namestringobligatoire

    Hostname: lower-case letters, digits and dashes.

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

    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.

  • locationstringobligatoire

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

  • imagestringobligatoire

    Operating system, e.g. ubuntu-24.04.

  • planstringobligatoire

    Plan code, e.g. R-START.

  • plan_namestringobligatoire

    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_linestringnullobligatoire

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

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

  • access"ssh_key" | "password"obligatoire

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

  • ssh_key_idstring (uuid) or nullobligatoire

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

  • ipv4string (ipv4) or nullobligatoire

    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 nullobligatoire

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

  • priceobjectobligatoire

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

  • price.currency"EUR"obligatoire
  • price.hourlystringobligatoire

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

  • price.dailystringobligatoire

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

  • created_atstring (date-time)obligatoire

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

  • updated_atstring (date-time)obligatoire

    Last status change (UTC, ISO 8601).

  • subscriptionobject or nullobligatoire

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

Retour au sommaire

ServerActionResult#

The server after the action.

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

    The action that was done.

  • queuedbooleanobligatoire

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

  • serverServerobligatoire
  • root_passwordstringnullfacultatif

    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.

Retour au sommaire

Catalog#

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

  • locationsarray of objectobligatoire

    Locations you can order in.

  • imagesarray of objectobligatoire

    Operating systems.

  • plansarray of objectobligatoire

    Plans with prices and where they can be ordered.

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

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

Retour au sommaire

Balance#

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

  • currency"EUR"obligatoire
  • balancestringobligatoire

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

  • usageobject or nullobligatoire

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

  • auto_top_upobject or nullobligatoire

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

Retour au sommaire

LedgerPage#

A page of the balance history.

  • entriesarray of LedgerEntryobligatoire

    Newest first.

  • next_cursorstring (uuid) or nullobligatoire

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

Retour au sommaire

LedgerEntry#

One movement of the balance.

  • idstring (uuid)obligatoire

    Entry id; also the cursor for the next page.

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

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

  • amountstringobligatoire

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

  • balance_afterstringobligatoire

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

  • descriptionstringnullobligatoire

    Reason given by support for an adjustment; otherwise null.

  • server_idstring (uuid) or nullobligatoire

    The server a usage entry charges; otherwise null.

  • created_atstring (date-time)obligatoire

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

Retour au sommaire

SshKey#

A public SSH key of your account.

  • idstring (uuid)obligatoire

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

  • namestringobligatoire

    Your name for the key.

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

    Key type.

  • fingerprintstringobligatoire

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

  • created_atstring (date-time)obligatoire

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

Retour au sommaire

Account#

The account that owns the API key.

  • idstring (uuid)obligatoire

    Your account id.

  • emailstring (email)obligatoire

    Email address of the account.

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

    Language of emails and messages.

  • created_atstring (date-time)obligatoire

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

Retour au sommaire

Error#

Every error response has this shape.

  • errorobjectobligatoire
  • 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"obligatoire

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

  • error.messagestringobligatoire

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

Retour au sommaire

Télécharger le JSON OpenAPI

Prêt à essayer ?

Créez une clé dans le tableau de bord et collez-la dans les exemples ci-dessus.

Créer une clé API