Endpoints de l'API client

Base : https://api.yorkhost.fr. Toutes les routes exigent l'en-tête Authorization: Bearer <clé> et la permission indiquée. Une route qui cible un service renvoie 404 si le service n'appartient pas au compte ou n'est pas dans la liste autorisée de la clé.

Spec OpenAPI complète : openapi-client-v1.yaml.

Page générée

Cette page est générée automatiquement depuis la spec OpenAPI de l'API. Ne la modifiez pas à la main.

Compte

GET /client/v1/account

Profil du compte. Scope : account:read.

Réponses :

• 200 : Profil (e-mail, nom, solde de crédit)
• 401 : Clé absente, invalide, révoquée, expirée, ou A2F inactive (code = missing_token, invalid_token, mfa_required)
• 403 : Scope manquant (missing_scope, avec required_scope) ou IP hors allowlist (ip_not_allowed)

Services

GET /client/v1/services

Liste des services. Scope : services:read. Filtrée par la restriction de services de la clé.

Paramètre	Dans	Type	Description
page	query	integer
limit	query	integer

Réponses :

• 200 : Liste paginée
• 401 : Clé absente, invalide, révoquée, expirée, ou A2F inactive (code = missing_token, invalid_token, mfa_required)
• 403 : Scope manquant (missing_scope, avec required_scope) ou IP hors allowlist (ip_not_allowed)

GET /client/v1/services/{id}

Détail d'un service. Scope : services:read.

Paramètre	Dans	Type	Description
id (requis)	path	integer	ID du service (voir GET /client/v1/services)

Réponses :

• 200 : Service
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client

Facturation

GET /client/v1/invoices

Liste des factures. Scope : billing:read.

Paramètre	Dans	Type	Description
page	query	integer
limit	query	integer

Réponses :

• 200 : Liste paginée

GET /client/v1/invoices/{id}

Détail d'une facture. Scope : billing:read.

Paramètre	Dans	Type	Description
id (requis)	path	integer

Réponses :

• 200 : Facture et lignes
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client

GET /client/v1/invoices/{id}/payment-link

Lien de paiement d'une facture. Scope : billing:read. Statut frais de la facture et, si elle est impayée, payment_url : page sécurisée de l'espace client (3-D Secure, PayPal, crédit). Aucun paiement ne transite par l'API.

Paramètre	Dans	Type	Description
id (requis)	path	integer

Réponses :

• 200 : Statut, total, échéance, payment_url si impayée
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client

GET /client/v1/invoices/{id}/pdf

Lien de téléchargement PDF. Scope : billing:read. Renvoie une URL signée, valable quelques minutes.

Paramètre	Dans	Type	Description
id (requis)	path	integer

Réponses :

• 200 : { url }
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client

Support

GET /client/v1/ticket-departments

Types de demande. Scope : tickets:read.

Réponses :

• 200 : Liste { id, name }

GET /client/v1/tickets

Liste des tickets. Scope : tickets:read.

Réponses :

• 200 : Tickets

POST /client/v1/tickets

Ouvrir un ticket. Scope : tickets:write. Limite : 5 par minute et par clé.

Corps JSON :

Champ	Type	Description
body (requis)	string
requestType	string (HELP, BILLING, CANCELLATION, OTHER)
serviceId	string	ID du service concerné
subject (requis)	string

Réponses :

• 200 : { id, number }
• 429 : Limite atteinte (Retry-After en secondes)

GET /client/v1/tickets/{id}

Détail d'un ticket. Scope : tickets:read.

Paramètre	Dans	Type	Description
id (requis)	path	string	Numéro ou identifiant du ticket

Réponses :

• 200 : Ticket et messages
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client

POST /client/v1/tickets/{id}/reply

Répondre à un ticket. Scope : tickets:write. Limite : 10 par minute et par clé.

Paramètre	Dans	Type	Description
id (requis)	path	string	Numéro ou identifiant du ticket

Corps JSON :

Champ	Type	Description
body (requis)	string

Réponses :

• 200 : Réponse enregistrée
• 429 : Limite atteinte (Retry-After en secondes)

VPS

GET /client/v1/vps/{id}

État d'un VPS. Scope : vps:read.

Paramètre	Dans	Type	Description
id (requis)	path	integer	ID du service (voir GET /client/v1/services)

Réponses :

• 200 : État, ressources, IPs
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client

GET /client/v1/vps/{id}/metrics

Métriques d'un VPS (1 h). Scope : vps:read.

Paramètre	Dans	Type	Description
id (requis)	path	integer	ID du service (voir GET /client/v1/services)

Réponses :

• 200 : Séries CPU / RAM / réseau

POST /client/v1/vps/{id}/power

Démarrer, arrêter ou redémarrer un VPS. Scope : vps:power. Limite : 10 par minute et par clé.

Paramètre	Dans	Type	Description
id (requis)	path	integer	ID du service (voir GET /client/v1/services)

Corps JSON :

Champ	Type	Description
action (requis)	string (start, stop, restart)

Réponses :

• 200 : Action lancée
• 429 : Limite atteinte (Retry-After en secondes)

Serveurs de jeu

GET /client/v1/game-servers/{id}

État d'un serveur de jeu. Scope : game:read.

Paramètre	Dans	Type	Description
id (requis)	path	integer	ID du service (voir GET /client/v1/services)

Réponses :

• 200 : État, adresse, ressources en direct
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client

GET /client/v1/game-servers/{id}/metrics

Métriques d'un serveur de jeu. Scope : game:read.

Paramètre	Dans	Type	Description
id (requis)	path	integer	ID du service (voir GET /client/v1/services)

Réponses :

• 200 : Séries CPU / RAM

POST /client/v1/game-servers/{id}/power

Démarrer, arrêter, redémarrer ou tuer un serveur de jeu. Scope : game:power. Limite : 10 par minute et par clé.

Paramètre	Dans	Type	Description
id (requis)	path	integer	ID du service (voir GET /client/v1/services)

Corps JSON :

Champ	Type	Description
action (requis)	string (start, stop, restart, kill)

Réponses :

• 200 : Action lancée
• 429 : Limite atteinte (Retry-After en secondes)

Anti-DDoS

GET /client/v1/antiddos

Attaques DDoS détectées. Scope : antiddos:read. Cibles et attaques filtrées par la restriction de services de la clé.

Paramètre	Dans	Type	Description
days	query	integer

Réponses :

• 200 : Cibles protégées et attaques

Orders

GET /client/v1/catalog

Produits commandables par API. Scope : services:read. Liste blanche des produits commandables (tarifs par cycle m, q, s, a), plafond de dépense journalier et offres de sandboxes agents.

Réponses :

• 200 : Produits, cycles, plafond, offres sandbox

POST /client/v1/orders

Commander un produit (préflight puis confirmation). Scope : orders:write. Limite : 5 par minute et par clé.

1. Sans confirmation_token : rien n'est commandé. La réponse donne le prix et un confirmation_token (10 min) lié à la clé, au produit, au cycle et au prix.
2. Après accord explicite du client, même appel avec confirmation_token : commande + facture HostBill. Réponse 201 avec invoice_id, total et payment_url (ou invoice_status: paid si le crédit du compte a été imputé).

Le jeton ne sert qu'une fois (409 already_ordered sinon). Plafond de dépense par compte et par jour (403 spend_cap). Sans Redis, les commandes sont refusées (503 order_unavailable).

Corps JSON :

Champ	Type	Description
confirmation_token	string
cycle	string (m, q, s, a)
product_id (requis)	integer

Réponses :

• 200 : Préflight : prix + confirmation_token
• 201 : Commande passée : facture et payment_url
• 403 : Scope manquant ou plafond journalier atteint (spend_cap)
• 404 : Produit non commandable par API (not_orderable)
• 409 : Confirmation expirée ou déjà utilisée (quote_invalid, already_ordered), cycle non proposé
• 429 : Limite atteinte (Retry-After en secondes)

Sandboxes

GET /client/v1/sandboxes

Essais agents du compte. Scope : sandbox:read. VM d'essai pour agents IA (Linux, bureau Linux, bureau Windows), sans IP publique : commande SSH (via la passerelle yorkhost.sh), URL de preview, échéances, et avancement du passage en VPS.

Réponses :

• 200 : Sandboxes vivantes et offres disponibles

POST /client/v1/sandboxes

Créer un essai agent. Scope : sandbox:write. Limite : 3 par minute et par clé, 3 essais par compte (réglable). Gratuit pendant sa fenêtre de fonctionnement (60 min par défaut), puis arrêté ; supprimé avec ses fichiers au bout de 24 h sauf passage en VPS (/keep). Sans IP publique : ssh <id>@yorkhost.sh avec la clé fournie, applications web sur preview_url. Disque, réseau et CPU bridés. desktop_url n'est montrée qu'à la création (voir /links).

Corps JSON :

Champ	Type	Description
kind	string (linux, desktop, windows)
ssh_public_key (requis)	string	Une ligne OpenSSH (ssh-ed25519, ecdsa, rsa ≥ 2048)

Réponses :

• 201 : Sandbox créée (SSH, preview, bureau)
• 400 : Type indisponible ou clé SSH invalide
• 429 : Quota de sandboxes atteint
• 503 : Capacité atteinte ou créations suspendues

POST /client/v1/sandboxes/claim

Réclamer un essai anonyme (ssh yorkhost.sh) et le passer en VPS. Scope : orders:write. Rattache au compte l'essai créé anonymement dont on fournit le jeton yhsc_… (ou le lien complet) et commande un VPS classique (VPS-2) : même préflight / confirmation et mêmes garde-fous que POST /client/v1/orders. Facture payée : HostBill crée le VPS, le dossier /home/agent de l'essai y est copié et vérifié, puis l'essai est supprimé.

Corps JSON :

Champ	Type	Description
claim_token (requis)	string
confirmation_token	string

Réponses :

• 200 : Préflight : prix + confirmation_token
• 201 : Commande passée : facture et payment_url
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 409 : Essai déjà réclamé, expiré, ou confirmation invalide

GET /client/v1/sandboxes/{id}

Détail d'une sandbox. Scope : sandbox:read.

Paramètre	Dans	Type	Description
id (requis)	path	string	ID de la sandbox (voir GET /client/v1/sandboxes)

Réponses :

• 200 : Sandbox
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client

DELETE /client/v1/sandboxes/{id}

Supprimer un essai. Scope : sandbox:write. Supprime la VM et ses fichiers. Un essai en cours de passage en VPS ne se supprime plus ici (409 billed_service).

Paramètre	Dans	Type	Description
id (requis)	path	string	ID de la sandbox (voir GET /client/v1/sandboxes)

Réponses :

• 200 : Supprimée
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client

POST /client/v1/sandboxes/{id}/keep

Passer un essai en VPS. Scope : orders:write. Commande un VPS classique (VPS-2, IP publique, géré dans l'espace client) : préflight / confirmation et garde-fous de POST /client/v1/orders. Facture payée : le dossier /home/agent de l'essai est copié dans le nouveau VPS, puis l'essai est supprimé.

Paramètre	Dans	Type	Description
id (requis)	path	string	ID de la sandbox (voir GET /client/v1/sandboxes)

Corps JSON :

Champ	Type	Description
confirmation_token	string

Réponses :

• 200 : Préflight : prix + confirmation_token
• 201 : Commande passée : facture et payment_url
• 409 : Essai non convertible ou confirmation invalide

POST /client/v1/sandboxes/{id}/links

Nouveau lien bureau. Scope : sandbox:write. Génère un nouveau desktop_url ; l'ancien cesse de fonctionner.

Paramètre	Dans	Type	Description
id (requis)	path	string	ID de la sandbox (voir GET /client/v1/sandboxes)

Réponses :

• 200 : Sandbox avec desktop_url