API HelloServ (v1)
L'API permet à vos propres outils de faire ce que vous faites dans votre espace client : lister vos services et leurs caractéristiques, lire leur état en direct et leurs adresses IP, démarrer, redémarrer ou arrêter un serveur, réinstaller un VPS ou un serveur dédié, récupérer vos factures, et commander des serveurs de jeu et des VPS payés avec le solde de votre compte. C'est une API REST en JSON, sur HTTPS.
https://panel.helloserv.fr/api/v1
Authentification et droits
Créez une clé dans votre espace client, dans Mon Profil > Sécurité > Clés d'API. La création demande la double authentification sur votre compte (application ou clé d'accès). La clé n'est affichée qu'une fois : gardez-la comme un mot de passe. Vous pouvez la révoquer à tout moment depuis la même page, qui montre aussi les derniers appels faits avec vos clés.
Envoyez la clé dans l'en-tête Authorization de chaque requête :
curl https://panel.helloserv.fr/api/v1/account \
-H "Authorization: Bearer hsk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Chaque clé a des droits, choisis à sa création :
| Droit | Donne accès à |
|---|---|
read | Compte, services, caractéristiques, état, adresses IP, systèmes disponibles, factures. Toujours inclus. |
power | Alimentation : démarrer, arrêter, redémarrer (et arrêt ou redémarrage forcé sur un serveur dédié). |
reinstall | Réinstallation d'un VPS ou d'un serveur dédié. Toutes les données du serveur sont effacées. |
order | Commandes de serveurs de jeu et de VPS, payées avec le solde de votre compte. Jamais donné par défaut. |
Le corps d'une requête, quand il y en a un, est un objet JSON envoyé avec Content-Type: application/json. Les dates sont au format ISO 8601 avec le décalage horaire de Paris. Les montants sont en euros : subtotal hors taxes, total TTC, tax_rate en fraction (0.2 = 20 %).
Limites
- 120 requêtes par minute et par clé. Chaque réponse porte
X-RateLimit-LimitetX-RateLimit-Remaining; au-delà, la réponse est429avecRetry-After. - 6 actions (alimentation, réinstallation) par minute sur un même service. Un serveur dédié accepte en plus une action d'alimentation par minute.
- Des clés invalides répétées depuis une même adresse la bloquent un moment (
429 too_many_failures). - 10 commandes par 24 heures avec une même clé (
429 order_limit_reached).
Erreurs
Une erreur arrive avec un statut HTTP et un code stable :
{"error": {"code": "service_not_found", "message": "Service not found."}}
| Statut | Codes |
|---|---|
| 400 | idempotency_key_required, unknown_field, invalid_json, invalid_parameter, invalid_action, weak_password, unknown_system, invalid_hostname, invalid_ssh_key, invalid_disk_layout, invalid_request |
| 401 | missing_key, invalid_key (inconnue ou révoquée) |
| 402 | insufficient_balance, payment_failed |
| 403 | insufficient_scope, ip_not_allowed |
| 404 | not_found, service_not_found, invoice_not_found, product_not_found |
| 405 | method_not_allowed |
| 409 | out_of_stock, order_in_progress, service_not_active, not_supported, action_in_progress, reinstall_in_progress, not_supported_by_hardware, management_unavailable, reinstall_finished, too_late, disk_inventory_missing, needs_staff |
| 413 | body_too_large |
| 422 | invalid_product, invalid_offer, invalid_period, invalid_os, invalid_addon, country_required, idempotency_key_reused |
| 429 | rate_limited, too_many_actions, too_soon, too_many_failures, order_limit_reached |
| 502, 503 | hypervisor_unavailable, hypervisor_error, management_error, gamepanel_unavailable, gamepanel_error, reinstall_unavailable, api_disabled : réessayez plus tard |
Adresses autorisées
Chaque clé peut être limitée à des adresses ou des plages (IPv4, IPv6, notation CIDR comme 203.0.113.0/24 ou 2001:db8::/48), 20 au plus. Donnez la liste à la création de la clé, ou plus tard sur la même page (votre double authentification est redemandée). Une clé sans liste marche depuis toutes les adresses. Un appel venu d'une autre adresse est refusé avec 403 ip_not_allowed et figure dans votre journal des appels. Un serveur qui a de l'IPv6 appelle souvent en IPv6 : mettez ses deux adresses.
Compte
GET/account
Votre compte et la clé utilisée pour l'appel.
{"data": {
"account": {"id": 1234, "name": "Jeanne Martin", "created_at": "2026-03-02T10:15:00+01:00", "balance": 50.00, "currency": "EUR"},
"key": {"name": "supervision", "prefix": "hsk_1a2b3c4d", "scopes": ["read", "power"], "ip_allowlist": ["203.0.113.0/24"], "created_at": "2026-11-21T18:00:00+01:00"}
}}
Services
GET/services
Tous vos services. Filtres facultatifs : status (active, suspended, pending, provisioning, cancelled, expired) et type (dedicated, vps, game, protection).
curl "https://panel.helloserv.fr/api/v1/services?status=active&type=dedicated" \
-H "Authorization: Bearer $HELLOSERV_KEY"
{"data": [
{"id": 3543, "name": "DED-Xeon-1", "type": "dedicated", "product": "dedicatedservers", "status": "active",
"created_at": "2026-11-16T13:00:20+01:00", "expires_at": "2026-12-16T13:00:20+01:00",
"primary_ip": "203.0.113.10", "actions": {"power": true, "reinstall": true}}
]}
GET/services/{id}
Un service avec ses caractéristiques, ses informations de facturation et son réseau. Pour un serveur dédié, network donne l'adresse IPv4 principale et les additionnelles, puis le préfixe, la passerelle et les serveurs DNS quand la gestion à distance les connaît. Pour un serveur de jeu, il donne les ports.
{"data": {
"id": 3543, "name": "DED-Xeon-1", "type": "dedicated", "product": "dedicatedservers", "status": "active",
"created_at": "2026-11-16T13:00:20+01:00", "expires_at": "2026-12-16T13:00:20+01:00",
"primary_ip": "203.0.113.10", "actions": {"power": true, "reinstall": true},
"billing": {"period": "monthly", "auto_renewal": true, "cancellation_requested": false},
"specs": {"offer": "Xeon E5", "cpu": "1x Intel Xeon E5-2640v2 @ 3.0GHz", "cpu_details": "Total: 6 Cores / 12 Threads",
"ram_gb": 32, "ram_type": "DDR3", "disks": [{"type": "SSD", "size_gb": 250, "quantity": 1}], "os": "Ubuntu 24.04"},
"network": {"primary_ip": "203.0.113.10", "ips": ["203.0.113.10", "203.0.113.11", "203.0.113.12"],
"prefix": 24, "gateway": "203.0.113.1", "dns": ["1.1.1.1", "9.9.9.9"]}
}}
VPS : specs donne cpu_cores, ram_gb, storage_gb, os, hostname. Serveur de jeu : network donne primary_ip, primary_port et ports.
État
GET/services/{id}/status
État en direct, lu sur la carte de gestion du serveur (dédié), sur l'hyperviseur (VPS) ou sur le panel de jeu. Services actifs seulement.
{"data": {
"power": "on", "read_from_hardware": true, "model": "PowerEdge R630",
"available_actions": ["start", "stop", "restart", "poweroff", "reset"],
"current_action": null,
"recent_actions": [{"id": 812, "action": "restart", "status": "done", "by": "customer", "at": "2026-11-21T18:02:11+01:00"}]
}}
Dédié : power vaut on, off ou unknown ; le status d'une action vaut in_progress, done, failed, timeout ou superseded. VPS : power vaut running, stopped, suspended, rescue ou unknown, avec cpu_percent, memory, disk, installing et l'opération d'alimentation en cours (power_operation). Serveur de jeu : power vaut running, offline, starting, stopping, installing ou install_failed, avec le processeur, la mémoire et les joueurs.
Alimentation
POST/services/{id}/power droit power
| Service | action |
|---|---|
| Serveur dédié | start, stop (arrêt propre), restart, poweroff (arrêt forcé), reset (redémarrage forcé) |
| VPS | start, stop, restart : l'arrêt et le redémarrage demandent d'abord au système de s'arrêter proprement, puis le forcent après un délai |
| Serveur de jeu | start, stop, restart |
curl -X POST https://panel.helloserv.fr/api/v1/services/3543/power \
-H "Authorization: Bearer $HELLOSERV_KEY" -H "Content-Type: application/json" \
-d '{"action": "restart"}'
{"data": {"action": "restart", "accepted": true, "operation_id": 813}}
La réponse est 202 : l'action est acceptée et s'exécute en arrière-plan. Suivez-la avec GET /services/{id}/status.
Réinstallation
GET/services/{id}/reinstall
Ce qui peut être installé. VPS : systems avec leur id. Serveur dédié : systems avec leur code, les disks, si vous choisissez le disque (disk_choice), raid1_possible, les languages, et la réinstallation en cours (current) s'il y en a une.
{"data": {"available": true,
"systems": [{"code": "ubuntu-24.04", "name": "Ubuntu 24.04", "family": "linux"}, {"code": "debian-13", "name": "Debian 13", "family": "linux"}],
"disks": [{"ref": "sda", "number": 1, "size_bytes": 480103981056, "type": "ssd"}],
"disk_choice": true, "raid1_possible": false, "languages": ["fr", "en"], "password_min_length": 12,
"current": null}}
POST/services/{id}/reinstall droit reinstall
Tout le contenu du serveur est effacé. Sans password, un mot de passe est tiré au hasard et rendu une seule fois, dans cette réponse.
Champs pour un VPS : os_id (obligatoire), password (12 caractères ou plus).
curl -X POST https://panel.helloserv.fr/api/v1/services/2210/reinstall \
-H "Authorization: Bearer $HELLOSERV_KEY" -H "Content-Type: application/json" \
-d '{"os_id": 1194}'
Champs pour un serveur dédié :
| Champ | |
|---|---|
os | Obligatoire : le code d'un système de GET …/reinstall. |
hostname | Obligatoire. 15 caractères au plus sous Windows. |
language, timezone | Obligatoires : une des languages, et un fuseau horaire comme Europe/Paris. |
password | Facultatif, 12 à 128 caractères, trois familles de caractères sur quatre. |
ssh_key | Clé publique facultative (Linux). |
disk | ref du disque, obligatoire quand disk_choice vaut true. |
raid1, data_disks, partitioning | Facultatifs (Linux) : true, une liste de ref de disques, simple ou lvm. |
curl -X POST https://panel.helloserv.fr/api/v1/services/3543/reinstall \
-H "Authorization: Bearer $HELLOSERV_KEY" -H "Content-Type: application/json" \
-d '{"os": "ubuntu-24.04", "hostname": "node-1", "language": "fr", "timezone": "Europe/Paris", "disk": "sda", "ssh_key": "ssh-ed25519 AAAA… moi@machine"}'
{"data": {"accepted": true, "password": "tiré-une-seule-fois",
"reinstall": {"status": "in_progress", "step": 1, "progress": 5, "phase": null, "cancellable": true,
"system": "Ubuntu 24.04", "hostname": "node-1", "requested_by": "customer",
"created_at": "2026-11-21T18:10:00+01:00", "finished_at": null}}}
Suivez-la avec GET /services/{id}/reinstall (current) : status passe à installing puis ready, ou failed, cancelled, expired.
POST/services/{id}/reinstall/cancel droit reinstall
Serveurs dédiés, tant que cancellable vaut true (rien n'est encore écrit sur les disques).
Factures
GET/invoices
Les plus récentes d'abord. Pagination : page (à partir de 1) et per_page (20 par défaut, 100 au plus).
{"data": [
{"number": "INV-2026-000812", "type": "renewal", "status": "paid", "issued_at": "2026-11-09T13:00:00+01:00",
"due_date": "2026-11-16T13:00:00+01:00", "paid_at": "2026-11-09T13:02:41+01:00", "currency": "EUR",
"subtotal": 100, "discount": 0, "tax_rate": 0.2, "tax": 20, "total": 120, "pdf": "/api/v1/invoices/INV-2026-000812/pdf"}
], "meta": {"page": 1, "per_page": 20, "total": 7}}
status : pending, processing, overdue, paid, cancelled, expired. Un avis pas encore payé a un numéro qui commence par AE- ; il reçoit son numéro INV- au paiement.
GET/invoices/{number}
Les mêmes champs, plus les lignes items (name, description, quantity, unit_price, total, hors taxes).
GET/invoices/{number}/pdf
curl -o facture.pdf https://panel.helloserv.fr/api/v1/invoices/INV-2026-000812/pdf \
-H "Authorization: Bearer $HELLOSERV_KEY"
Catalogue
GET/catalog
Les produits que l'API peut commander (serveurs de jeu et VPS), avec le nombre d'offres en vente aujourd'hui.
{"data": [{"type": "minecraft", "category": "game", "name": "Minecraft", "offers": 6},
{"type": "vpsintel", "category": "vps", "name": "VPS Intel", "offers": 5}]}
GET/catalog/{type}
Les offres d'un produit avec leurs caractéristiques et leurs prix pour votre compte : excl_tax (hors taxes) et total, ce que vous payez, TVA comprise selon votre pays et votre statut. Aussi les durées et leur remise, les systèmes d'un VPS (os) et les options mensuelles. Les valeurs ci-dessous sont un exemple.
{"data": {"type": "vpsintel", "category": "vps", "name": "VPS Intel", "currency": "EUR", "tax": {"base": "incl_tax", "rate": 0.2},
"periods": [{"id": "monthly", "months": 1, "discount_percent": 0}, {"id": "annually", "months": 12, "discount_percent": 10}],
"os": [{"id": "debian12", "label": "Debian 12"}], "os_default": "debian12",
"addons": [{"id": 12, "name": "Sauvegardes", "price_monthly_excl_tax": null, "price_percent_of_offer": 20, "max_quantity": 1}],
"offers": [{"id": 3, "name": "VPS-2", "cpu_cores": 2, "ram_gb": 4, "storage_gb": 60, "in_stock": true,
"prices": {"monthly": {"excl_tax": 8.00, "total": 9.60}, "annually": {"excl_tax": 86.40, "total": 103.68}}}]}}
Commandes
Commandez un serveur de jeu ou un VPS payé avec le solde de votre compte (à alimenter depuis votre espace client). Prix, TVA, facture et livraison automatique sont les mêmes que pour une commande passée dans l'espace client. Demande le droit order.
POST/orders droit order
| Champ | Valeur |
|---|---|
type | Le produit, donné par GET /catalog. |
offer_id | L'offre, donnée par GET /catalog/{type}. |
period | monthly (par défaut), quarterly ou annually. |
os | Système d'un VPS, pris dans le catalogue. Système par défaut s'il manque. |
addons | Facultatif : numéros d'options, ou objets {"id": 12, "quantity": 2}. |
dry_run | Booléen JSON. true : rend le prix exact pour votre compte et votre solde, sans rien commander. |
Tout autre champ est refusé (400 unknown_field), de même qu'un dry_run qui n'est pas un booléen JSON : une faute de frappe ne change jamais un devis en commande. Chaque vraie commande demande un en-tête Idempotency-Key (8 à 64 caractères : lettres, chiffres, - _ . :), différent pour chaque commande. Renvoyer la même clé (délai dépassé, erreur réseau) ne commande jamais deux fois : vous recevez la première réponse, avec Idempotent-Replayed: true. Une commande refusée avant toute création (solde trop bas, offre épuisée) libère sa clé : corrigez la cause et renvoyez-la.
curl -X POST https://panel.helloserv.fr/api/v1/orders \
-H "Authorization: Bearer $HELLOSERV_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: commande-7f3a9c21" \
-d '{"type": "vpsintel", "offer_id": 3, "period": "monthly", "os": "debian12"}'
201 : la facture payée et les services créés. Un service commence en pending : suivez-le avec GET /services/{id} jusqu'à active.
{"data": {
"order": {"id": 42, "status": "paid", "idempotency_key": "commande-7f3a9c21"},
"invoice": {"number": "INV-2026-001234", "status": "paid", "total": 9.60, "currency": "EUR", "pdf": "/api/v1/invoices/INV-2026-001234/pdf"},
"services": [{"id": 5678, "name": "vps-2", "status": "pending", "url": "/api/v1/services/5678"}],
"balance": 40.40
}}
Solde trop bas : 402 insufficient_balance, rien n'est créé. Les options payées une fois (prestations d'installation) ne se commandent pas par l'API. Votre pays doit être renseigné dans votre profil, il fixe la TVA : sinon 422 country_required.
GET/orders
Les commandes passées par l'API sur votre compte, de la plus récente à la plus ancienne (?page, ?per_page jusqu'à 100) : état, clé utilisée, produit, total, facture et services.
Une question, une fonction qui manque : ouvrez un ticket depuis votre espace client.