Référence API

Authentification

Toutes les requêtes API nécessitent une authentification via une clé API. Transmettez la clé dans l’en-tête Authorization en tant que token Bearer. La clé API doit commencer par le préfixe nxd_.

Exigence du plan : l’API REST, l’API compatible ISPmanager et les webhooks sont disponibles à partir du plan Pro, tout comme les deux fonctionnalités que cette référence couvre également : DNSSEC et zones secondaires (slave). Une clé rattachée à un plan qui ne les inclut pas reçoit une réponse 403.

Authorization: Bearer nxd_your_api_key_here

La couche d’authentification API est sans état – chaque requête est authentifiée indépendamment. Il n’y a ni sessions ni cookies.

Gardez votre clé API secrète. Ne la partagez pas dans du code côté client, des dépôts publics ou des URL. Si une clé est compromise, révoquez-la immédiatement et créez-en une nouvelle.

Erreurs d’authentification

Format de réponse

Toutes les réponses sont en JSON. Les réponses réussies ont la structure suivante :

Ressource unique

{
    "status": "success",
    "data": {
        "id": "xK9mQ2",
        "name": "example.com",
        ...
    }
}

Liste paginée

{
    "status": "success",
    "data": [ ... ],
    "meta": {
        "total": 150,
        "page": 1,
        "per_page": 25,
        "last_page": 6
    }
}

Réponse d’erreur

{
    "status": "error",
    "error": {
        "code": "validation_error",
        "message": "Validation failed.",
        "details": {
            "name": ["Domain name is required."]
        }
    }
}

Les erreurs levées plus profondément dans la plateforme – un quota, un domaine bloqué, une défaillance des serveurs de noms – portent le même objet error, mais sans champ status. Branchez votre code sur error.code, qui est stable, plutôt que sur la présence de status. Par contrat, les messages sont en anglais sur toutes les instances et dans toutes les langues ; error.code est la partie exploitable par une machine.

Identifiants publics

Chaque ressource est identifiée par un id opaque (par exemple xK9mQ2), utilisé dans les chemins d’URL. Les identifiants numériques de la base de données ne sont jamais exposés ni acceptés.

Pagination des listes

Les points de terminaison de liste qui renvoient des résultats paginés acceptent les paramètres de requête suivants :

Limitation de débit

Les requêtes sont comptées par compte, et non par clé, dans une fenêtre glissante d’une minute ; le budget dépend de votre plan – le comparatif des plans, sur la page des tarifs, en donne le chiffre. Les requêtes non authentifiées sont comptées par adresse IP. Chaque réponse indique l’état courant de votre budget, vous n’avez donc rien à deviner :

Pour les traitements en masse – import d’une grande zone, réconciliation de centaines d’enregistrements – lisez X-RateLimit-Remaining et mettez le traitement en pause avant que ce compteur n’atteigne zéro, plutôt que de réessayer après une réponse 429. Le CLI le fait pour vous.

Quelques opérations disposent de leur propre fenêtre, plus longue, en plus du quota de requêtes : une zone peut être déplacée vers un autre groupe de serveurs de noms trois fois par jour. La réponse indique quelle limite a été atteinte.

Zones DNS

Gérez les zones DNS. Nécessite zones.read pour les opérations de lecture et zones.write pour les opérations d’écriture.

GET /v1/zones

Liste toutes les zones de l’utilisateur authentifié.

Paramètres de requête

• search – filtrer les zones par nom
• page, per_page – paramètres de pagination

Champs de réponse

Champs : id, name, type (master/slave), status, ns_group, created_at, updated_at

GET /v1/zones/{id}

Obtenir des informations détaillées sur une zone spécifique, y compris les données SOA, les serveurs de noms et le nombre d’enregistrements.

Champs de réponse supplémentaires

records_count, soa (primary_ns, admin_email, serial, refresh, retry, expire, minimum), nameservers (tableau), ns_group (id, slug, name)

POST /v1/zones

Créer une nouvelle zone DNS. Refusée avec un code 409 si le domaine existe déjà ou chevauche la zone d’un autre compte, et avec un code 422 si la limite de zones du plan est atteinte ou si le domaine est bloqué.

Corps de la requête (JSON)

{
    "name": "example.com",
    "type": "master",
    "ns_group": "eu"
}

Une zone secondaire (slave) à la place :

{
    "name": "example.com",
    "type": "slave",
    "master_ip": "203.0.113.10"
}

• name (obligatoire) – nom de domaine
• type – "master" (par défaut) ou "slave"
• ns_group – groupe NS auquel assigner la zone (optionnel, utilise le groupe par défaut si omis)
• master_ip – obligatoire pour les zones secondaires ; doit être une adresse IP publique valide

Renvoie 201 Created avec l’objet zone.

PATCH /v1/zones/{id}

Déplace la zone vers un autre groupe de serveurs de noms. C’est le seul PATCH de l’API. Portée : zones.write.

Corps de la requête (JSON)

{
    "ns_group": "eu"
}

Renvoie la zone dans son état après le déplacement, sous la même forme que GET /v1/zones/{id}. Le groupe est désigné par son slug – les valeurs que GET /v1/ns-groups renvoie pour votre compte ; toute autre valeur est rejetée avec un code 400.

La zone continue de répondre pendant toute l’opération : les nouveaux serveurs de noms sont provisionnés avant la réponse et les précédents continuent de servir le temps que les résolveurs se rafraîchissent. Mettez ensuite à jour la délégation chez votre registrar. Une zone peut être déplacée trois fois par jour ; au-delà, l’appel renvoie 429.

DELETE /v1/zones/{id}

Supprimer une zone et tous ses enregistrements.

Renvoie 204 No Content en cas de succès.

GET /v1/zones/{id}/export

Exporter une zone au format BIND ou en JSON structuré.

Paramètres de requête

• format – "bind" (par défaut) renvoie le texte du fichier de zone BIND ; "json" renvoie un tableau structuré d’enregistrements avec name, type, content et ttl

Enregistrements

Gérez les enregistrements DNS au sein d’une zone. Tous les points de terminaison des enregistrements sont imbriqués sous une zone. Nécessite records.read pour les opérations de lecture et records.write pour les opérations d’écriture.

GET /v1/zones/{zoneId}/records

Liste tous les enregistrements d’une zone.

Paramètres de requête

• type – filtrer par type d’enregistrement (ex. : A, CNAME, MX)
• name – filtrer par nom d’enregistrement (correspondance de sous-chaîne)
• search – rechercher dans le nom et le contenu

Champs de réponse

id, name, type, content, ttl, disabled, fields (champs analysés spécifiques au type)

GET /v1/zones/{zoneId}/records/{recordId}

Obtenir un enregistrement unique par son identifiant.

POST /v1/zones/{zoneId}/records

Créer un nouvel enregistrement DNS.

Corps de la requête (JSON)

{
    "type": "A",
    "name": "www",
    "ttl": 3600,
    "content": "93.184.216.34"
}

• type (obligatoire) – type d’enregistrement (A, AAAA, CNAME, MX, TXT, SRV, CAA, NS, PTR, ALIAS, DNAME, DS, TLSA)
• name – nom de l’enregistrement relatif à la zone (par défaut : @ pour l’apex de la zone)
• ttl – durée de vie en secondes (par défaut : 3600)
• content – valeur de l’enregistrement (IP pour A/AAAA, nom d’hôte pour CNAME/NS/PTR, texte pour TXT, serveur de messagerie pour MX)

Champs spécifiques au type

• MX : priority (par défaut : 10)
• SRV : priority, weight, port
• CAA : flags (par défaut : 0), tag (par défaut : "issue")
• DS : keytag, algorithm, digest_type
• TLSA : usage, selector, matching_type

Pour MX, SRV, CAA, DS et TLSA, content ne porte que la valeur principale – le serveur de messagerie, la cible SRV, le domaine de l’autorité de certification, l’empreinte hexadécimale seule – tout le reste passe par les champs ci-dessus. L’envoi de données d’enregistrement déjà assemblées (par exemple 0 issue "letsencrypt.org" comme contenu CAA) est rejeté avec un code 400 qui nomme le champ.

Le TTL appartient à l’ensemble d’enregistrements. Omettez ttl lorsque vous ajoutez une valeur à un nom qui existe déjà : le TTL en place est conservé. Si vous en envoyez un, il s’applique à toutes les valeurs portant ce nom. Pour un nom entièrement nouveau, la valeur par défaut est de 3600 secondes.

Renvoie 201 Created avec l’objet enregistrement.

PUT /v1/zones/{zoneId}/records/{recordId}

Mettre à jour un enregistrement existant. N’incluez que les champs que vous souhaitez modifier ; les champs omis conservent leurs valeurs actuelles.

{
    "content": "93.184.216.35",
    "ttl": 7200
}

Renvoie 200 OK avec l’objet enregistrement mis à jour. Remarque : l’identifiant de l’enregistrement peut changer après une mise à jour car il est calculé à partir du nom, du type et du contenu de l’enregistrement.

DELETE /v1/zones/{zoneId}/records/{recordId}

Supprimer un enregistrement de la zone.

Renvoie 204 No Content en cas de succès.

DNSSEC

Gérez DNSSEC pour vos zones. Nécessite zones.read pour consulter le statut et zones.write pour activer ou désactiver.

GET /v1/zones/{id}/dnssec

Obtenir le statut DNSSEC d’une zone, y compris les clés et les enregistrements DS.

Champs de réponse

enabled (booléen), keys (tableau d’enregistrements DNSKEY), ds_records (tableau d’enregistrements DS à configurer auprès du bureau d’enregistrement)

POST /v1/zones/{id}/dnssec/enable

Activer DNSSEC pour une zone. Génère automatiquement les clés de signature.

Renvoie le statut DNSSEC avec les clés générées et les enregistrements DS.

POST /v1/zones/{id}/dnssec/disable

Désactiver DNSSEC pour une zone. Supprime toutes les clés de signature.

Renvoie {"enabled": false, "keys": [], "ds_records": []}.

Groupes NS

Liste les groupes de serveurs de noms disponibles. Utilisez l’id d’un groupe comme ns_group lors de la création d’une zone. Toute clé d’API valide peut lire cet endpoint.

GET /v1/ns-groups

Liste les groupes de serveurs de noms actifs.

Champs de réponse par groupe

id, name, slug

Compte

Consulter les informations du compte et gérer les clés API.

GET /v1/account

Obtenir les informations du compte actuel, y compris les détails de l’abonnement.

Champs de réponse

Champs : id (UUID), email, name, role, status, language, timezone, created_at

subscription – objet avec plan, billing_cycle, status, current_period_start, current_period_end (ou null si aucun abonnement)

GET /v1/account/api-keys

Liste toutes les clés API de l’utilisateur authentifié.

Champs de réponse par clé

id, name, key_prefix (8 premiers caractères), permissions (tableau), last_used_at, expires_at, created_at

POST /v1/account/api-keys

Créer une nouvelle clé API.

Corps de la requête (JSON)

{
    "name": "CI/CD Pipeline",
    "permissions": ["zones.read", "records.read", "records.write"],
    "expires_at": "2027-01-01"
}

• name (obligatoire) – nom lisible (max. 255 caractères)
• permissions (obligatoire) – tableau de permissions (au moins une requise) : zones.read, zones.write, records.read, records.write, webhooks.read, webhooks.write
• expires_at – date d’expiration optionnelle (ISO 8601 ou YYYY-MM-DD) ; doit être dans le futur

La réponse inclut la clé API complète dans le champ key. C’est la seule fois où la clé complète est renvoyée. Stockez-la en lieu sûr.

Renvoie 201 Created avec les détails de la clé, y compris la valeur complète de la key.

DELETE /v1/account/api-keys/{id}

Révoquer (supprimer définitivement) une clé API.

Renvoie 204 No Content en cas de succès.

Facturation

Consulter l’abonnement, les plans et les factures. Ces points de terminaison sont en lecture seule.

GET /v1/billing/subscription

Obtenir les détails de l’abonnement actuel. Renvoie null si aucun abonnement actif.

Champs de réponse

Champs : id, plan, billing_cycle, status, current_period_start, current_period_end, created_at

GET /v1/billing/plans

Liste tous les plans disponibles avec les tarifs et les fonctionnalités.

Champs de réponse par plan

id, name, slug, description, price_monthly, price_yearly, currency, max_domains, max_records, features (tableau)

GET /v1/billing/invoices

Liste les factures de l’utilisateur authentifié, les plus récentes d’abord.

Paramètres de requête

• status – filtrer par statut (draft, issued, sent, void)
• page, per_page – paramètres de pagination

GET /v1/billing/invoices/{id}

Obtient une facture via son <code>id</code>.

Champs de réponse

Champs : id, number, status, amount (TTC), net_amount (HT), tax_amount, tax_rate, currency, issued_at, created_at. Les montants sont des chaînes décimales simples.

Webhooks

Gérez les abonnements webhook sortants pour recevoir des notifications en temps réel sur les modifications de zones et d’enregistrements. Nécessite webhooks.read pour la lecture et webhooks.write pour créer, modifier ou supprimer.

GET /v1/webhooks

Liste tous les abonnements webhook de l’utilisateur authentifié.

Champs de réponse par webhook

id, url, events (tableau), description, is_active, failure_count, last_triggered_at, created_at

POST /v1/webhooks

Crée un abonnement webhook.

Corps de la requête (JSON)

{
    "url": "https://example.com/webhook",
    "events": ["zone.created", "record.created"],
    "description": "Production webhook"
}

• url (obligatoire) – endpoint HTTPS qui recevra les charges utiles des événements
• events (obligatoire) – tableau des types d’événements auxquels s’abonner
• description – libellé lisible facultatif

La réponse inclut un secret pour vérifier les signatures de webhook (HMAC). C’est la seule fois où le secret est renvoyé. Conservez-le en lieu sûr.

Renvoie 201 Created avec l’id et le secret du webhook.

GET /v1/webhooks/{id}

Obtient un abonnement webhook avec ses livraisons les plus récentes.

PUT /v1/webhooks/{id}

Met à jour un abonnement webhook. N’incluez que les champs à modifier.

Renvoie 200 OK avec l’objet webhook mis à jour.

DELETE /v1/webhooks/{id}

Supprime un abonnement webhook.

Renvoie 204 No Content en cas de succès.

POST /v1/webhooks/{id}/test

Envoie un événement de test à l’endpoint du webhook pour vérifier qu’il est joignable.

Met en file d’attente une livraison de test avec une charge utile "type": "test".

Vérifier une livraison

Chaque livraison est signée avec le secret renvoyé à la création du webhook et porte quatre en-têtes :

X-NexDNS-Signature: sha256=<hmac>
X-NexDNS-Timestamp: 1785370265
X-NexDNS-Event: record.created
X-NexDNS-Delivery: 42

Recalculez HMAC-SHA256 sur le corps brut exact de la requête avec votre secret, puis comparez le résultat à l’empreinte hexadécimale qui suit sha256=, en temps constant. Une différence signifie que la requête ne vient pas de nous. X-NexDNS-Delivery identifie la tentative : les nouvelles tentatives d’un même événement partagent donc l’id de l’événement, mais pas le numéro de livraison.

Charge utile de la livraison

{
    "id": "evt_szpj9u04z8u0",
    "type": "record.created",
    "created_at": "2026-07-30 00:31:05",
    "data": {
        "zone": { "name": "example.com" },
        "record": { "name": "www.example.com.", "type": "A", "content": "203.0.113.10", "ttl": 3600 }
    }
}

Types d’événements disponibles

Abonnez-vous à n’importe quelle combinaison de ces types d’événements :

zone.created, zone.updated, zone.deleted, record.created, record.updated, record.deleted, dnssec.enabled, dnssec.disabled, zone.health.problem, zone.health.resolved

Codes d’erreur

Toutes les erreurs suivent un format cohérent avec un code d’erreur sous forme de chaîne et un message lisible.

Exemples de code

Tous les exemples utilisent curl. Remplacez nxd_your_api_key par votre clé API réelle.

Lister vos zones

curl -s "https://api.nexdns.tech/v1/zones" \
    -H "Authorization: Bearer nxd_your_api_key"

Créer une zone

curl -s -X POST "https://api.nexdns.tech/v1/zones" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"name": "example.com"}'

Ajouter un enregistrement A

curl -s -X POST "https://api.nexdns.tech/v1/zones/{zoneId}/records" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "type": "A",
        "name": "www",
        "ttl": 3600,
        "content": "93.184.216.34"
    }'

Ajouter un enregistrement MX

curl -s -X POST "https://api.nexdns.tech/v1/zones/{zoneId}/records" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "type": "MX",
        "name": "@",
        "ttl": 3600,
        "content": "mail.example.com",
        "priority": 10
    }'

Mettre à jour un enregistrement

curl -s -X PUT "https://api.nexdns.tech/v1/zones/{zoneId}/records/{recordId}" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"content": "93.184.216.35", "ttl": 7200}'

Supprimer un enregistrement

curl -s -X DELETE "https://api.nexdns.tech/v1/zones/{zoneId}/records/{recordId}" \
    -H "Authorization: Bearer nxd_your_api_key"

Exporter une zone (format BIND)

curl -s "https://api.nexdns.tech/v1/zones/{zoneId}/export" \
    -H "Authorization: Bearer nxd_your_api_key"

Activer DNSSEC

curl -s -X POST "https://api.nexdns.tech/v1/zones/{zoneId}/dnssec/enable" \
    -H "Authorization: Bearer nxd_your_api_key"

Créer une clé API

curl -s -X POST "https://api.nexdns.tech/v1/account/api-keys" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Read-only key",
        "permissions": ["zones.read", "records.read"],
        "expires_at": "2027-12-31"
    }'

Obtenir les informations du compte

curl -s "https://api.nexdns.tech/v1/account" \
    -H "Authorization: Bearer nxd_your_api_key"