DNS et rDNS par API et MCP

Tout ce que permet la page DNS & rDNS est aussi disponible dans l'API client et le serveur MCP YorkHost, avec exactement les mêmes contrôles : propriété des domaines et des IP, validations, NS et SOA protégés, zones cPanel en lecture seule, limite horaire de modifications partagée avec l'espace client.

Cette page détaille la partie DNS et rDNS. Pour la mise en route (double authentification obligatoire, création de la clé, connexion d'un assistant), voir :

Démarrer avec l'API
Serveur MCP : connexion de Claude, ChatGPT, Cursor… et liste complète des outils
Endpoints et Permissions (pages générées depuis l'API)

Permissions

Permission	Libellé dans l'espace client (Clés API)	Ce qu'elle ouvre
`dns:read`	Lire les domaines et zones DNS	Liste des domaines, état DNS, enregistrements, export BIND, état DNSSEC, liste des modèles
`dns:write`	Modifier les enregistrements DNS	Ajout, modification et suppression d'enregistrements, création de zone, import BIND, DNSSEC, application d'un modèle
`rdns:read`	Lire le reverse DNS (PTR) des IP	Liste des IP et de leur PTR
`rdns:write`	Modifier le reverse DNS (PTR) des IP	Modification, remise par défaut et modification en masse des PTR

Le modèle Lecture seule contient dns:read et rdns:read ; le modèle Agent IA (sans action destructive) ajoute dns:write et rdns:write.

À savoir avant d'écrire

NS et SOA protégés : le SOA et les serveurs de noms du domaine lui-même (protected: true dans la liste des enregistrements) ne peuvent être ni modifiés ni supprimés (code rec_err_protected) ; un import les ignore.
Zones cPanel en lecture seule : une zone hébergée sur un cPanel (readonly: true) se lit par l'API mais se modifie dans cPanel. Toute écriture répond 403 zone_err_readonly.
PATCH …/records/{record_id} remplace tout l'enregistrement : envoyez l'enregistrement complet (nom, type, TTL et tous les champs du type), pas seulement le champ modifié. L'identifiant change à chaque modification : utilisez celui renvoyé par la réponse.
Les routes /dns/* ignorent la restriction de services de la clé : un domaine n'est pas un service. Une clé dns:write restreinte à un seul VPS peut modifier tous les domaines du compte. Les routes /rdns* respectent, elles, la restriction (une IP hors des services autorisés répond 404).
Les modifications sont publiques et mises en cache par les résolveurs pendant le TTL.

Authentification

Base : https://api.yorkhost.fr, en-tête Authorization: Bearer <clé>. Les exemples supposent la clé dans une variable :

export YH_KEY="yhk_client_v1_..."

Reverse DNS

Méthode et route	Rôle	Permission
`GET /client/v1/rdns` (`?service_id=`)	IP des services du compte et leur PTR	`rdns:read`
`PUT /client/v1/rdns/{ip}`	Définir le PTR d'une IP (`{"hostname": "…"}`)	`rdns:write`
`DELETE /client/v1/rdns/{ip}`	Remettre le PTR par défaut de YorkHost	`rdns:write`
`POST /client/v1/rdns/bulk`	Modification en masse (512 lignes au plus)	`rdns:write`

Lister les IP

curl -H "Authorization: Bearer $YH_KEY" \
  "https://api.yorkhost.fr/client/v1/rdns?service_id=12345"

Réponse : {"ips": [{ip, service_id, service_name, list, ptr, ipam_value, state, default}]}. state vaut ok, pending, nozone (zone inverse non gérée par YorkHost) ou error. Sans service_id, toutes les IP accessibles à la clé sont renvoyées.

Définir le PTR d'une IP

curl -X PUT https://api.yorkhost.fr/client/v1/rdns/192.0.2.10 \
  -H "Authorization: Bearer $YH_KEY" -H "Content-Type: application/json" \
  -d '{"hostname": "mail.mondomaine.fr"}'

Réponse : {"ip": "192.0.2.10", "hostname": "mail.mondomaine.fr", "warning": null}. Si le nom ne résout pas vers l'IP, warning vaut rdns_warn_forward : ajoutez l'enregistrement A ou AAAA correspondant (voir forward-confirmed reverse DNS). Le nom doit être un nom d'hôte complet.

Remettre le PTR par défaut

curl -X DELETE https://api.yorkhost.fr/client/v1/rdns/192.0.2.10 \
  -H "Authorization: Bearer $YH_KEY"

Réponse : {"ip": "192.0.2.10", "hostname": "<nom par défaut>"}. PUT avec un hostname vide est refusé : utilisez DELETE.

rDNS en masse

# 1. Vérification : rien n'est modifié
curl -X POST https://api.yorkhost.fr/client/v1/rdns/bulk \
  -H "Authorization: Bearer $YH_KEY" -H "Content-Type: application/json" \
  -d '{"check_only": true, "entries": [
        {"ip": "192.0.2.10", "hostname": "mail.mondomaine.fr"},
        {"ip": "192.0.2.11", "hostname": "web1.mondomaine.fr"},
        {"ip": "2001:db8::10", "hostname": null}
      ]}'

# 2. Application : même appel avec "check_only": false

hostname vide ou null : PTR par défaut.
Réponse : {mode, needed, remaining, counts: {ok, unchanged, error, skipped}, rows: [{n, ip, hostname, name, result, error, message, warning}]}. needed est le nombre de modifications du lot, remaining ce qu'il reste dans la limite horaire.
De 1 à 512 lignes par appel, 5 appels par minute et par clé.
Si le lot dépasse la limite horaire restante, il est refusé en entier (429 err_rate) : rien n'est écrit.

check_only est obligatoire

Un appel sans check_only (ou avec une valeur non booléenne) est refusé en 400 bad_request, sans rien modifier. Envoyez d'abord "check_only": true pour vérifier, puis le même appel avec "check_only": false pour appliquer. L'outil MCP rdns_bulk suit la même règle.

Les règles de chaque ligne sont celles de la modification en masse dans l'espace client.

Domaines et zones

Un domaine est désigné par son nom dans le chemin (mondomaine.fr, IDN en Unicode ou en punycode), parmi les domaines et zones DNS de votre compte.

Méthode et route	Rôle	Permission
`GET /client/v1/dns/domains`	Domaines et zones du compte, avec leur état	`dns:read`
`GET /client/v1/dns/domains/{domain}`	État DNS d'un domaine : serveurs de noms et zone	`dns:read`
`GET /client/v1/dns/domains/{domain}/records`	Enregistrements de la zone	`dns:read`
`POST /client/v1/dns/domains/{domain}/records`	Ajouter un enregistrement	`dns:write`
`PATCH /client/v1/dns/domains/{domain}/records/{record_id}`	Remplacer un enregistrement	`dns:write`
`DELETE /client/v1/dns/domains/{domain}/records/{record_id}`	Supprimer un enregistrement	`dns:write`
`POST /client/v1/dns/domains/{domain}/zone`	Créer la zone (« Préparer la zone »)	`dns:write`
`GET /client/v1/dns/domains/{domain}/export`	Exporter la zone au format BIND	`dns:read`
`POST /client/v1/dns/domains/{domain}/import`	Importer une zone BIND (5 par minute et par clé)	`dns:write`
`GET /client/v1/dns/domains/{domain}/dnssec`	État DNSSEC, DS à déclarer, clés	`dns:read`
`PUT /client/v1/dns/domains/{domain}/dnssec`	Activer ou désactiver DNSSEC (`{"enabled": true}`)	`dns:write`
`GET /client/v1/dns/domains/{domain}/presets`	Modèles e-mail applicables	`dns:read`
`POST /client/v1/dns/domains/{domain}/presets/{preset}`	Appliquer un modèle	`dns:write`

Lister les domaines

curl -H "Authorization: Bearer $YH_KEY" https://api.yorkhost.fr/client/v1/dns/domains

Réponse : {"domains": [{domain, display, kind, status, expires, ns_state, zone_exists, readonly, source}]}.

kind : domain ou dnszone ;
ns_state : managed (délégué aux serveurs YorkHost), mixed, external ou unknown. Les enregistrements ne sont servis publiquement que pour managed ; une zone existante (zone_exists: true) se modifie quel que soit cet état ;
readonly: true : zone hébergée sur un cPanel.

GET /client/v1/dns/domains/mondomaine.fr renvoie {domain, display, ns: {state, live, registrar, managed}, zone: {exists, readonly, source, dnssec, serial, count}}.

Lire les enregistrements

curl -H "Authorization: Bearer $YH_KEY" \
  https://api.yorkhost.fr/client/v1/dns/domains/mondomaine.fr/records

Réponse : {"domain": "mondomaine.fr", "records": [{id, name, fqdn, type, ttl, content, protected, …champs du type}]}. name est relatif à la zone (@ pour le domaine lui-même) ; id (32 caractères hexadécimaux) sert à modifier ou supprimer.

Ajouter un enregistrement

curl -X POST https://api.yorkhost.fr/client/v1/dns/domains/mondomaine.fr/records \
  -H "Authorization: Bearer $YH_KEY" -H "Content-Type: application/json" \
  -d '{"name": "www", "type": "A", "value": "192.0.2.10", "ttl": 3600}'

curl -X POST https://api.yorkhost.fr/client/v1/dns/domains/mondomaine.fr/records \
  -H "Authorization: Bearer $YH_KEY" -H "Content-Type: application/json" \
  -d '{"name": "@", "type": "MX", "priority": 10, "target": "mail.mondomaine.fr"}'

Réponse 201 : {"id": "…"}. Champs à envoyer selon le type (les mêmes que le formulaire de l'éditeur de zone) ; toute autre clé est refusée (400 bad_request) :

Type	Champs
A, AAAA, CNAME, ALIAS, TXT, NS, PTR	`value`
MX	`priority`, `target` (ou `value`)
SRV	`priority`, `weight`, `port`, `target` (ou `value`)
CAA	`flags`, `tag` (`issue`, `issuewild`, `iodef`), `value`
TLSA	`usage`, `selector`, `matching`, `data`
SSHFP	`algorithm`, `fptype`, `fingerprint`
DS	`keytag`, `algorithm`, `digesttype`, `digest`
NAPTR	`order`, `preference`, `flags`, `service`, `regexp`, `replacement`

Plus name, type et, facultatif, ttl (60 à 604800 ; TTL par défaut si absent). Pour un TXT, envoyez le texte sans guillemets : {"name": "_dmarc", "type": "TXT", "value": "v=DMARC1; p=none"}.

Modifier un enregistrement

curl -X PATCH https://api.yorkhost.fr/client/v1/dns/domains/mondomaine.fr/records/0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $YH_KEY" -H "Content-Type: application/json" \
  -d '{"name": "www", "type": "A", "value": "192.0.2.20", "ttl": 3600}'

Envoyez l'enregistrement complet. Réponse : {"id": "…"} avec le nouvel identifiant.

Supprimer un enregistrement

curl -X DELETE https://api.yorkhost.fr/client/v1/dns/domains/mondomaine.fr/records/0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $YH_KEY"

Réponse : {"ok": true, "domain": "mondomaine.fr", "id": "…"}.

Créer la zone

curl -X POST https://api.yorkhost.fr/client/v1/dns/domains/mondomaine.fr/zone \
  -H "Authorization: Bearer $YH_KEY"

Réponse : {"created": true}, ou false si la zone existait déjà. Pour un .fr, créez la zone avant de changer les serveurs de noms (voir Faire pointer un domaine vers YorkHost).

Exporter et importer (BIND)

# Export : le fichier de zone est dans le champ "bind"
curl -s -H "Authorization: Bearer $YH_KEY" \
  https://api.yorkhost.fr/client/v1/dns/domains/mondomaine.fr/export | jq -r .bind > mondomaine.fr.zone

# Import : ajoute les enregistrements ("replace": true remplace ceux de même nom et de même type)
jq -Rs '{bind: ., replace: false}' mondomaine.fr.zone | \
  curl -X POST https://api.yorkhost.fr/client/v1/dns/domains/mondomaine.fr/import \
    -H "Authorization: Bearer $YH_KEY" -H "Content-Type: application/json" --data-binary @-

Réponse de l'import : {added, skipped} (skipped liste les lignes ignorées et la raison). SOA et NS du domaine sont toujours ignorés. Fichier de zone de 256 Ko au maximum, 5 imports par minute et par clé.

DNSSEC

curl -X PUT https://api.yorkhost.fr/client/v1/dns/domains/mondomaine.fr/dnssec \
  -H "Authorization: Bearer $YH_KEY" -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Réponse : {enabled, ds}. Déclarez ensuite le DS chez votre registrar. Pour désactiver, retirez d'abord le DS chez le registrar, puis envoyez {"enabled": false} : voir DNSSEC.

Modèles e-mail

curl -H "Authorization: Bearer $YH_KEY" \
  https://api.yorkhost.fr/client/v1/dns/domains/mondomaine.fr/presets

curl -X POST https://api.yorkhost.fr/client/v1/dns/domains/mondomaine.fr/presets/google_workspace \
  -H "Authorization: Bearer $YH_KEY"

Clés des modèles : google_workspace, microsoft365, zoho_eu, protonmail, ovh_mx. Comme dans l'espace client, les MX et le SPF existants sont remplacés (voir Modèles e-mail). Réponse : {"applied": <nombre d'enregistrements>}.

Outils MCP

Outil	Rôle	Permission
`dns_list_domains`	Domaines et zones du compte, état des serveurs de noms, zone en lecture seule	`dns:read`
`dns_get_domain`	État DNS d'un domaine (serveurs de noms, zone, DNSSEC, serial)	`dns:read`
`dns_list_records`	Enregistrements d'une zone, avec leur `id` et `protected`	`dns:read`
`dns_export_zone`	Export BIND de la zone (sauvegarde avant modification)	`dns:read`
`dns_add_record`	Ajouter un enregistrement (A, AAAA, CNAME, MX, TXT, SRV, CAA…)	`dns:write`
`dns_update_record`	Remplacer un enregistrement : l'assistant doit envoyer l'enregistrement complet	`dns:write`
`dns_delete_record`	Supprimer un enregistrement	`dns:write`
`rdns_list`	IP des services et leur PTR	`rdns:read`
`rdns_set`	Définir le PTR d'une IP	`rdns:write`
`rdns_reset`	Remettre le PTR par défaut	`rdns:write`
`rdns_bulk`	rDNS en masse (512 lignes au plus), toujours en vérification (`check_only: true`) d'abord	`rdns:write`

La création de zone, l'import BIND, DNSSEC et les modèles e-mail ne sont pas proposés comme outils MCP : utilisez l'espace client ou l'API REST. Les outils demandent à l'assistant de confirmer avec vous avant toute modification DNS ou rDNS.

Exemples de demandes à un assistant connecté :

« Liste mes domaines et dis-moi lesquels ne pointent pas encore vers YorkHost. »
« Ajoute un enregistrement TXT _dmarc sur mondomaine.fr avec v=DMARC1; p=none. »
« Mets le reverse DNS de 192.0.2.10 sur mail.mondomaine.fr et vérifie que l'enregistrement A existe. »

Limites

Par clé : 120 lectures et 20 écritures par minute (toutes routes confondues).
POST /client/v1/rdns/bulk : 5 appels par minute et par clé, 512 lignes par appel.
POST …/import : 5 appels par minute et par clé.
Limite horaire de modifications DNS et rDNS du compte, partagée avec l'espace client : 429 err_rate une fois atteinte.

Erreurs

Les erreurs suivent le format {"error": "<message>", "code": "<code>"}. Les refus métier portent un message en français, à relire tel quel.

HTTP	`code`	Cause
400	`bad_request`	Paramètre manquant, en trop ou de mauvais type ; IP ou nom de domaine illisible ; `record_id` invalide
400	`rec_err_`, `zone_err_`	Enregistrement ou zone refusé (type non autorisé, nom ou valeur invalide, TTL hors bornes, CNAME en conflit, enregistrement protégé, import illisible…)
400	`rdns_err_hostname`, `rdns_err_nozone`, `rdns_err_forward`, `rdns_bulk_err_*`	Nom d'hôte invalide, zone inverse non gérée, nom qui ne résout pas vers l'IP, lot rDNS invalide
400	`err_preset`	Modèle inconnu
403	`zone_err_readonly`	Zone hébergée sur un cPanel : lecture seule
403	`rdns_err_owner`	IP non modifiable par ce compte
403	`missing_scope`	Permission manquante (`required_scope` indique laquelle)
404	`not_found`	Domaine, IP, service ou enregistrement inconnu, hors restriction de la clé ou appartenant à un autre compte
413	`too_large`	Corps de requête trop volumineux
429	`err_rate`	Limite horaire de modifications atteinte (ou lot rDNS trop grand pour ce qu'il reste)
502	`err_backend`, `err_internal`	Service DNS en erreur ou injoignable : réessayez plus tard
503	`dns_unavailable`	Gestion DNS momentanément indisponible par l'API

Permissions​

Authentification​

Reverse DNS​

Lister les IP​

Définir le PTR d'une IP​

Remettre le PTR par défaut​

rDNS en masse​

Domaines et zones​

Lister les domaines​

Lire les enregistrements​

Ajouter un enregistrement​

Modifier un enregistrement​

Supprimer un enregistrement​

Créer la zone​

Exporter et importer (BIND)​

DNSSEC​

Modèles e-mail​

Outils MCP​

Limites​

Erreurs​