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/sandbox-keys

Clés SSH du compte pour les essais. Scope : sandbox:read. Clés publiques (10 au plus) acceptées par la passerelle sur tous les essais créés depuis le compte (ssh <id>@yorkhost.sh), et posées dans les essais créés ensuite. Jamais sur les essais anonymes.

Réponses :

• 200 : keys (empreinte, nom, clé publique, date) et max

POST /client/v1/sandbox-keys

Enregistrer une clé SSH. Scope : sandbox:write. Limite : 20 modifications par minute et par clé API. Clé publique ed25519, ecdsa ou rsa ≥ 2048 bits ; une clé privée est refusée.

Corps JSON :

Champ	Type	Description
name	string	Libellé (défaut : commentaire de la clé)
public_key (requis)	string	Une ligne OpenSSH (contenu du fichier .pub)

Réponses :

• 201 : Clé enregistrée
• 400 : Clé invalide ou clé privée
• 409 : Clé déjà enregistrée (key_exists) ou 10 clés atteintes (limit_reached)

DELETE /client/v1/sandbox-keys

Retirer une clé SSH. Scope : sandbox:write. La passerelle ne l'accepte plus pour les essais du compte (hors essai créé avec cette clé).

Paramètre	Dans	Type	Description
fingerprint (requis)	query	string	Empreinte SHA256:… (voir GET /client/v1/sandbox-keys), encodée pour une URL

Réponses :

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

GET /client/v1/sandbox-secrets

Secrets du compte pour les essais. Scope : sandbox:read. Noms et dates de mise à jour des variables d'environnement injectées dans les essais Linux du compte (20 au plus). Les valeurs ne sont jamais renvoyées. 503 secrets_disabled si la fonctionnalité n'est pas configurée sur le serveur.

Réponses :

• 200 : secrets (nom, updated_at), max et chemin du fichier dans l'essai
• 503 : Secrets non disponibles (secrets_disabled)

PUT /client/v1/sandbox-secrets/{name}

Créer ou remplacer un secret. Scope : sandbox:write. Chiffré au repos (AES-256-GCM), jamais relu. Exporté (export NOM='valeur' dans /home/agent/.config/yorkhost/env, chargé par ~/.profile et ~/.bashrc) dans les essais créés ensuite ; les essais existants gardent leur environnement.

Paramètre	Dans	Type	Description
name (requis)	path	string	Nom de la variable (ex. ANTHROPIC_API_KEY) ; PATH, HOME, LD_, SSH_… sont réservés

Corps JSON :

Champ	Type	Description
value (requis)	string	Valeur (4 Kio au plus, sans caractère NUL)

Réponses :

• 200 : Enregistré (nom et date, sans la valeur)
• 400 : Nom ou valeur invalide
• 409 : 20 secrets atteints (limit_reached)
• 503 : Secrets non disponibles (secrets_disabled)

DELETE /client/v1/sandbox-secrets/{name}

Supprimer un secret. Scope : sandbox:write.

Paramètre	Dans	Type	Description
name (requis)	path	string	Nom de la variable (ex. ANTHROPIC_API_KEY) ; PATH, HOME, LD_, SSH_… sont réservés

Réponses :

• 200 : Supprimé
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 503 : Secrets non disponibles (secrets_disabled)

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 (2 h par défaut pour un essai créé depuis le compte, contre 60 min sans compte), 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 ou une clé enregistrée sur le compte (/sandbox-keys), applications web sur preview_url. Les secrets du compte (/sandbox-secrets) sont exportés dans l'essai Linux sauf inject_secrets: false (secrets_injected dans la réponse, warnings si un réglage du compte n'a pas pu être appliqué). Disque, réseau et CPU bridés. desktop_url n'est montrée qu'à la création (voir /links).

Corps JSON :

Champ	Type	Description
inject_secrets	boolean	Exporter les secrets du compte dans l'essai (Linux et bureau Linux)
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}/exec

Exécuter une commande dans un essai. Scope : sandbox:write. Pour les agents sans SSH (connecteurs web). Lance bash -lc <command> sous l'utilisateur agent de la VM (jamais root ; sudo sans mot de passe disponible), dans /home/agent ou cwd. Essais linux et desktop en marche uniquement. Délai 60 s par défaut, 300 s au plus : la commande et ses enfants sont tués à l'échéance. Un processus d'arrière-plan doit rediriger ses sorties (nohup cmd > /tmp/cmd.log 2>&1 &). 4 commandes simultanées par essai, 60 par minute et par compte.

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

Corps JSON :

Champ	Type	Description
command (requis)	string	Commande shell (syntaxe bash), 32 Kio au plus
cwd	string	Dossier sous /home/agent (défaut /home/agent)
stdin	string	Entrée standard, 32 Kio au plus
timeout_seconds	integer

Réponses :

• 200 : Résultat : exit_code (non nul n'est pas une erreur HTTP), stdout et stderr (256 Kio chacun au plus, stdout_truncated / stderr_truncated), timed_out, duration_ms, cwd
• 400 : Commande, délai ou cwd invalide ; essai Windows
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 409 : Essai arrêté ou en cours de passage en VPS (not_running)
• 429 : 4 commandes déjà en cours dans l'essai (busy) ou plafond du compte
• 503 : La VM ne répond pas encore (guest_unavailable)

GET /client/v1/sandboxes/{id}/files

Lister un dossier d'un essai. Scope : sandbox:read. Parcouru par l'utilisateur agent : nom (relatif à path), type (file, dir, symlink, other), taille, droits et date de modification. 1 000 entrées au plus (truncated), liens symboliques non suivis.

Paramètre	Dans	Type	Description
id (requis)	path	string	ID de la sandbox (voir GET /client/v1/sandboxes)
path	query	string	Dossier sous /home/agent ou /tmp (relatif : depuis /home/agent)
depth	query	integer

Réponses :

• 200 : path, depth, entries, truncated, warnings (sous-dossiers illisibles)
• 400 : Chemin hors de /home/agent et /tmp, ou profondeur invalide
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 422 : Pas un dossier (file_error)

GET /client/v1/sandboxes/{id}/files/content

Lire un fichier d'un essai. Scope : sandbox:read. Lu par l'utilisateur agent (ses droits s'appliquent). Premier Mio du fichier : texte UTF-8 tel quel, sinon base64.

Paramètre	Dans	Type	Description
id (requis)	path	string	ID de la sandbox (voir GET /client/v1/sandboxes)
path (requis)	query	string	Fichier sous /home/agent ou /tmp (relatif : depuis /home/agent)

Réponses :

• 200 : path, size, encoding (utf-8 ou base64), content, truncated
• 400 : Chemin hors de /home/agent et /tmp
• 403 : Accès refusé à l'utilisateur agent (permission_denied)
• 404 : Essai ou fichier introuvable (file_not_found)

PUT /client/v1/sandboxes/{id}/files/content

Écrire un fichier dans un essai. Scope : sandbox:write. Écrit ou remplace le fichier sous l'utilisateur agent, dossiers parents créés ; le fichier n'apparaît qu'une fois complet. 1 Mio au plus. Sans mode, un fichier remplacé garde ses droits.

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

Corps JSON :

Champ	Type	Description
content (requis)	string
encoding	string (utf-8, base64)
mode	string	Droits en octal, ex. 644 ou 755
path (requis)	string	Fichier sous /home/agent ou /tmp

Réponses :

• 200 : path, size, mode
• 400 : Chemin, encodage ou mode invalide
• 403 : Accès refusé à l'utilisateur agent (permission_denied)
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 413 : Contenu au-delà de 1 Mio

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