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
ip	query	string	Limite cibles et attaques à une adresse du compte (page par IP) ; la réponse porte alors ip

Réponses :

• 200 : { attacks, ipam_ips, game_servers, protection_active, protection_checked, days, rules_enabled, rules_backend, generated_at[, ip] }
• 400 : IP illisible (ip_invalid)

GET /client/v1/antiddos/rules

Règles anti-DDoS du compte. Scope : antiddos:read. Même contenu que la page Anti-DDoS de l'espace client : niveau du compte (standard ou extended), politiques que le compte peut choisir, plafonds, IP IPv4 éligibles (destinations possibles) et règles. Statut d'une règle : pending (demandée, pas encore appliquée par le NOC), active, suspended, dormant ou rejected ; position = ordre d'évaluation parmi les règles de la même IP (1 = en premier). Avec une clé restreinte, seules les IP de ses services et leurs règles apparaissent.

Paramètre	Dans	Type	Description
ip	query	string	Limite eligible_ips et rules à cette adresse

Réponses :

• 200 : { backend, account_level, policies: [{ name, protocols, restricted, extended_only }], limits: { max_rules_per_ip, max_allow_list_sources, max_list_entries, max_description }, eligible_ips (IP d'un VPS ou d'un serveur dédié seulement), rules: [AntiDDoSRule][, beta: { enabled, capacity, used, full }][, dns_revocations: [{ rule_id, ip, zone, at, code, reason }]][, ip] }
• 400 : IP illisible (ip_invalid)
• 403 : Règles client inactives sur ce serveur (rules_disabled) ou scope manquant
• 502 : Service de règles anti-DDoS injoignable (netops_unavailable) ; réessayer plus tard

POST /client/v1/antiddos/rules

Créer une règle anti-DDoS. Scope : antiddos:write. Même validation que l'espace client (plan protection DDoS v2) : destination = une IP IPv4 éligible du compte (/32), politique autorisée pour le niveau du compte, protocoles et ports compatibles, plafonds. La règle est créée avec le statut pending : le NOC l'applique ensuite. Limite : 10 écritures par minute et par clé, en plus du délai entre deux modifications imposé par le service de règles (429).

Corps JSON :

Champ	Type	Description
description	string	Note libre (longueur limitée par limits.max_description)
dport_list	array	Ports de destination : 30120 ou plage 27015-27030
ip (requis)	string	IPv4 éligible du compte (eligible_ips : IP d'un VPS ou d'un serveur dédié), /32 toléré
policy (requis)	string	Nom d'une politique de policies (ex. FiveM UDP, Drop, Rate Limiter Low)
position	integer	Position parmi les règles de l'IP (1 = en premier) ; absente = en dernier
proto_list	array	Protocoles (requis selon la politique)
sip_list	array	Adresses ou réseaux source (obligatoires pour Allow List)
sport_list	array	Ports source

Réponses :

• 201 : { backend: netops, rule: AntiDDoSRule }
• 400 : Règle refusée : code (policy_unknown, proto_mismatch, ports_required, full_range, source_invalid, too_many_entries…) et field désignent le champ à corriger
• 403 : IP hors du compte ou de la restriction de la clé, ou IP qui n'est pas celle d'un VPS ou d'un serveur dédié (serveur de jeu, hébergement web…) (ip_not_owned), politique réservée aux comptes étendus (extended_required), règles inactives (rules_disabled) ou scope manquant
• 409 : Plafond de règles atteint pour cette IP (rules_per_ip_limit), ou bêta complète : toutes les places de test sont attribuées (beta_full)
• 422 : Refus du service de règles (code et field relayés)
• 429 : Limite atteinte (Retry-After en secondes)
• 502 : Service de règles anti-DDoS injoignable (netops_unavailable) ; réessayer plus tard

POST /client/v1/antiddos/rules/dns-authoritative

Ouvrir l'UDP 53 d'un serveur DNS faisant autorité. Scope : antiddos:write. Préréglage « DNS faisant autorité » pour une IP éligible du compte (VPS ou serveur dédié). Le service de règles vérifie d'abord le serveur en TCP 53 : réponse avec autorité (bit AA) pour zone, récursion refusée, transfert de zone (AXFR) refusé, réponses ANY minimales (RFC 8482). Si tout passe, une règle kind: dns_authoritative est créée (politique General UDP Countermeasure, udp, port 53, aucune source) : le trafic reste mitigé, mais la liste blanche de résolveurs ne s'applique plus à cette IP. Le serveur est re-vérifié chaque semaine ; la règle est retirée automatiquement si la récursion ou l'AXFR deviennent ouverts (dns_revocations de GET /client/v1/antiddos/rules). Retrait manuel : DELETE /client/v1/antiddos/rules/{id}. Une vérification par délai entre deux modifications.

Corps JSON :

Champ	Type	Description
ip (requis)	string	IPv4 du serveur DNS, parmi eligible_ips
zone (requis)	string	Domaine dont le serveur fait autorité, ex. example.com

Réponses :

• 201 : { backend: netops, rule: AntiDDoSRule, checks: { soa, recursion, axfr, any } }
• 400 : IP ou zone illisible (ip_invalid, dns_zone_invalid)
• 403 : IP hors du compte, de la restriction de la clé, ou qui n'est pas celle d'un VPS ou d'un serveur dédié (ip_not_owned) ; règles inactives (rules_disabled) ou scope manquant
• 409 : UDP 53 déjà ouvert sur cette IP (dns_preset_exists), bêta complète (beta_full) ou plafond de règles atteint (rules_per_ip_limit)
• 422 : Serveur non conforme, error explique quoi corriger : injoignable en TCP 53 (dns_unreachable), pas d'autorité sur la zone (dns_not_authoritative), résolveur ouvert (dns_open_resolver), AXFR ouvert (dns_axfr_open), réponse ANY trop grande (dns_any_large), zone invalide (dns_zone_invalid), IP hors des réseaux protégés (ip_not_protected)
• 429 : Limite atteinte (Retry-After en secondes)
• 502 : Service de règles anti-DDoS injoignable (netops_unavailable) ; réessayer plus tard

DELETE /client/v1/antiddos/rules/{id}

Supprimer une règle anti-DDoS. Scope : antiddos:write. Demande le retrait de la règle (appliqué par le service de règles).

Paramètre	Dans	Type	Description
id (requis)	path	string	Identifiant de la règle (rules[].id de GET /client/v1/antiddos/rules)

Réponses :

• 200 : { backend: netops, rule_id }
• 403 : Règles client inactives sur ce serveur (rules_disabled) ou scope manquant
• 404 : Règle inconnue pour ce compte ou hors restriction de la clé (rule_not_found)
• 429 : Limite atteinte (Retry-After en secondes)
• 502 : Service de règles anti-DDoS injoignable (netops_unavailable) ; réessayer plus tard

POST /client/v1/antiddos/rules/{id}/move

Déplacer une règle anti-DDoS. Scope : antiddos:write. Place la règle à position parmi les règles de la même IP (1 = évaluée en premier ; une position trop grande la met en dernier).

Paramètre	Dans	Type	Description
id (requis)	path	string	Identifiant de la règle (rules[].id de GET /client/v1/antiddos/rules)

Corps JSON :

Champ	Type	Description
position (requis)	integer

Réponses :

• 200 : { backend: netops, rule: AntiDDoSRule } (position finale)
• 400 : position absente ou < 1 (bad_request)
• 403 : Règles client inactives sur ce serveur (rules_disabled) ou scope manquant
• 404 : Règle inconnue pour ce compte ou hors restriction de la clé (rule_not_found)
• 429 : Limite atteinte (Retry-After en secondes)
• 502 : Service de règles anti-DDoS injoignable (netops_unavailable) ; réessayer plus tard

Domaines et DNS

GET /client/v1/dns/domains

Domaines et zones DNS du compte. Scope : dns:read. Domaines et zones DNS seules du client, avec l'état de délégation (ns_state : managed, mixed, external, unknown), l'existence de la zone chez YorkHost et readonly (zone hébergée sur un cPanel : lecture seule ici). Un domaine n'est pas un service : la restriction de services de la clé ne s'applique pas aux routes /dns/*.

Réponses :

• 200 : { domains: [{ domain, display, kind, status, expires, ns_state, zone_exists, readonly, source }] }
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard
• 503 : Gestion DNS indisponible sur ce serveur (dns_unavailable)

GET /client/v1/dns/domains/{domain}

État DNS d'un domaine. Scope : dns:read. Serveurs de noms (état, délégation constatée, registrar) et zone YorkHost (existence, lecture seule, DNSSEC, serial, nombre d'enregistrements).

Paramètre	Dans	Type	Description
domain (requis)	path	string	Nom de domaine du compte, par exemple example.com (IDN en Unicode ou en punycode)

Réponses :

• 200 : { domain, display, ns, zone }
• 400 : Nom de domaine illisible
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client

GET /client/v1/dns/domains/{domain}/dnssec

État DNSSEC. Scope : dns:read. Activation, enregistrements DS à déclarer chez le registrar, clés.

Paramètre	Dans	Type	Description
domain (requis)	path	string	Nom de domaine du compte, par exemple example.com (IDN en Unicode ou en punycode)

Réponses :

• 200 : { enabled, ds, keys }
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard

PUT /client/v1/dns/domains/{domain}/dnssec

Activer ou désactiver DNSSEC. Scope : dns:write. Après activation, publier les DS renvoyés chez le registrar ; désactiver DNSSEC alors que des DS sont publiés rend le domaine injoignable pour les résolveurs qui valident.

Paramètre	Dans	Type	Description
domain (requis)	path	string	Nom de domaine du compte, par exemple example.com (IDN en Unicode ou en punycode)

Corps JSON :

Champ	Type	Description
enabled (requis)	boolean

Réponses :

• 200 : { enabled, ds }
• 403 : Zone en lecture seule
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard

GET /client/v1/dns/domains/{domain}/export

Exporter la zone (BIND). Scope : dns:read. Fichier de zone au format BIND, dans le champ bind d'une réponse JSON.

Paramètre	Dans	Type	Description
domain (requis)	path	string	Nom de domaine du compte, par exemple example.com (IDN en Unicode ou en punycode)

Réponses :

• 200 : { bind }
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard

POST /client/v1/dns/domains/{domain}/import

Importer une zone (BIND). Scope : dns:write. replace: true remplace les enregistrements existants (hors NS et SOA protégés) ; sinon ils sont ajoutés. Corps de 1 Mo au plus ; 5 imports par minute et par clé.

Paramètre	Dans	Type	Description
domain (requis)	path	string	Nom de domaine du compte, par exemple example.com (IDN en Unicode ou en punycode)

Corps JSON :

Champ	Type	Description
bind (requis)	string	Fichier de zone au format BIND
replace	boolean

Réponses :

• 200 : { added, skipped }
• 400 : Fichier de zone refusé (zone_err_*)
• 403 : Zone en lecture seule
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 413 : Corps trop volumineux (too_large)
• 429 : Limite atteinte (Retry-After en secondes)
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard

GET /client/v1/dns/domains/{domain}/presets

Modèles d'enregistrements. Scope : dns:read. Modèles applicables à la zone (messagerie, vérifications…), avec les enregistrements qu'ils créent.

Paramètre	Dans	Type	Description
domain (requis)	path	string	Nom de domaine du compte, par exemple example.com (IDN en Unicode ou en punycode)

Réponses :

• 200 : { domain, presets: [{ key, label, records }] }
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client

POST /client/v1/dns/domains/{domain}/presets/{preset}

Appliquer un modèle. Scope : dns:write. Ajoute les enregistrements du modèle preset (clé de la liste des modèles).

Paramètre	Dans	Type	Description
domain (requis)	path	string	Nom de domaine du compte, par exemple example.com (IDN en Unicode ou en punycode)
preset (requis)	path	string	Clé du modèle (key de la liste)

Réponses :

• 200 : { applied } (nombre d'enregistrements ajoutés)
• 403 : Zone en lecture seule
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard

GET /client/v1/dns/domains/{domain}/records

Enregistrements de la zone. Scope : dns:read. protected: true marque les enregistrements gérés par YorkHost (NS et SOA de l'apex), non modifiables.

Paramètre	Dans	Type	Description
domain (requis)	path	string	Nom de domaine du compte, par exemple example.com (IDN en Unicode ou en punycode)

Réponses :

• 200 : { domain, records: [{ id, name, fqdn, type, ttl, content, protected, …champs du type }] } : name relatif (@ pour l'apex), content au format PowerDNS, puis les champs du formulaire (value ; MX et SRV : priority, weight, port, target, la cible étant aussi sous value ; CAA : flags, tag, value…)
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard

POST /client/v1/dns/domains/{domain}/records

Ajouter un enregistrement. Scope : dns:write. Champs du type uniquement (toute autre clé : 400 bad_request). NS et SOA de l'apex sont protégés ; une zone hébergée sur un cPanel est en lecture seule (403 zone_err_readonly). Les erreurs de validation portent un code rec_err_* ou zone_err_*, avec un message en français.

Paramètre	Dans	Type	Description
domain (requis)	path	string	Nom de domaine du compte, par exemple example.com (IDN en Unicode ou en punycode)

Corps JSON :

Champ	Type	Description
flags	integer	Drapeaux CAA
name (requis)	string	Nom relatif à la zone (@ ou vide pour l'apex, www, _dmarc…) ou nom complet dans la zone
port	integer	Port SRV
priority	integer	Priorité MX et SRV
tag	string (issue, issuewild, iodef)	Étiquette CAA
target	string	Cible MX et SRV
ttl	integer	TTL en secondes (défaut du module si absent)
type (requis)	string	A, AAAA, CNAME, MX, TXT, SRV, CAA, TLSA, SSHFP, DS, NAPTR…
value	string	Valeur : IP, nom cible, texte, valeur CAA…
weight	integer	Poids SRV

Réponses :

• 201 : { id }
• 400 : Enregistrement refusé (rec_err_*, zone_err_*)
• 403 : Zone en lecture seule (zone_err_readonly) ou scope manquant
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 429 : Limite atteinte (Retry-After en secondes)
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard

PATCH /client/v1/dns/domains/{domain}/records/{record_id}

Modifier un enregistrement. Scope : dns:write. Envoyer l'enregistrement complet (mêmes champs qu'à la création) ; record_id vient de la liste des enregistrements.

Paramètre	Dans	Type	Description
domain (requis)	path	string	Nom de domaine du compte, par exemple example.com (IDN en Unicode ou en punycode)
record_id (requis)	path	string	Identifiant renvoyé par la liste des enregistrements

Corps JSON :

Champ	Type	Description
flags	integer	Drapeaux CAA
name (requis)	string	Nom relatif à la zone (@ ou vide pour l'apex, www, _dmarc…) ou nom complet dans la zone
port	integer	Port SRV
priority	integer	Priorité MX et SRV
tag	string (issue, issuewild, iodef)	Étiquette CAA
target	string	Cible MX et SRV
ttl	integer	TTL en secondes (défaut du module si absent)
type (requis)	string	A, AAAA, CNAME, MX, TXT, SRV, CAA, TLSA, SSHFP, DS, NAPTR…
value	string	Valeur : IP, nom cible, texte, valeur CAA…
weight	integer	Poids SRV

Réponses :

• 200 : { id }
• 400 : Enregistrement refusé (rec_err_*, zone_err_*)
• 403 : Zone en lecture seule (zone_err_readonly)
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard

DELETE /client/v1/dns/domains/{domain}/records/{record_id}

Supprimer un enregistrement. Scope : dns:write. NS et SOA de l'apex ne peuvent pas être supprimés.

Paramètre	Dans	Type	Description
domain (requis)	path	string	Nom de domaine du compte, par exemple example.com (IDN en Unicode ou en punycode)
record_id (requis)	path	string	Identifiant renvoyé par la liste des enregistrements

Réponses :

• 200 : { ok: true, domain, id }
• 403 : Zone en lecture seule ou enregistrement protégé
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard

POST /client/v1/dns/domains/{domain}/zone

Créer la zone DNS chez YorkHost. Scope : dns:write. Crée la zone du domaine si elle n'existe pas encore (sans effet sinon).

Paramètre	Dans	Type	Description
domain (requis)	path	string	Nom de domaine du compte, par exemple example.com (IDN en Unicode ou en punycode)

Réponses :

• 200 : { created } (false si la zone existait déjà)
• 403 : Création refusée pour ce domaine
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard

Reverse DNS

GET /client/v1/rdns

Reverse DNS des IP du compte. Scope : rdns:read. IP des services du client, filtrées par la restriction de services de la clé, avec leur PTR actuel et par défaut, et un état (ok, pending, nozone, error). service_id limite la liste à un service (404 s'il est hors restriction).

Paramètre	Dans	Type	Description
service_id	query	integer	ID d'un service (voir GET /client/v1/services)

Réponses :

• 200 : { ips: [{ ip, service_id, service_name, list, ptr, ipam_value, state, default }] }
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard
• 503 : Gestion DNS indisponible sur ce serveur (dns_unavailable)

POST /client/v1/rdns/bulk

Reverse DNS en masse. Scope : rdns:write. Jusqu'à 512 lignes ; hostname vide ou null rétablit le PTR par défaut. Avec check_only: true, rien n'est modifié : la réponse est le rapport (résultat, erreur et avertissement par ligne). Limite : 5 appels par minute et par clé.

Corps JSON :

Champ	Type	Description
check_only (requis)	boolean	Obligatoire. true : simulation, rapport sans écriture ; false : application. Absent ou non booléen : 400
entries (requis)	array	Lignes { ip, hostname }

Réponses :

• 200 : Rapport { mode, needed, remaining, counts, rows } ; chaque ligne de rows : n, ip, hostname, name, result, error, message, warning (une IP hors de la restriction de la clé donne l'erreur rdns_err_owner)
• 400 : Corps invalide ou nombre de lignes hors bornes (bad_request, rdns_bulk_err_*)
• 429 : Lot refusé : il dépasse la limite horaire de modifications du compte (err_rate, partagée avec l'espace client)
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard

PUT /client/v1/rdns/{ip}

Définir le reverse DNS d'une IP. Scope : rdns:write. L'IP doit appartenir à un service du compte (et à la restriction de la clé), sinon 404. Si le nom ne résout pas vers cette IP, le PTR est posé avec warning: rdns_warn_forward.

Paramètre	Dans	Type	Description
ip (requis)	path	string	Adresse IPv4 ou IPv6 d'un service du compte (voir GET /client/v1/rdns)

Corps JSON :

Champ	Type	Description
hostname (requis)	string	Nom complet, par exemple mail.example.com

Réponses :

• 200 : { ip, hostname, warning } (warning vaut null ou rdns_warn_forward)
• 400 : IP illisible (bad_request) ou nom refusé (rdns_err_hostname)
• 403 : IP non modifiable par ce compte (rdns_err_owner) ou scope manquant
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 429 : Limite atteinte (Retry-After en secondes)
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard

DELETE /client/v1/rdns/{ip}

Rétablir le reverse DNS par défaut. Scope : rdns:write. Remet le PTR par défaut de YorkHost.

Paramètre	Dans	Type	Description
ip (requis)	path	string	Adresse IPv4 ou IPv6 d'un service du compte (voir GET /client/v1/rdns)

Réponses :

• 200 : { ip, hostname } (PTR par défaut)
• 404 : Ressource inexistante, hors restriction de la clé, ou appartenant à un autre client
• 502 : Serveur DNS en erreur (err_backend, err_internal) ou injoignable (bridge_unreachable) ; réessayer plus tard

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