Riferimento API

Autenticazione

Tutte le richieste API richiedono l’autenticazione tramite una chiave API. Inserire la chiave nell’header Authorization come token Bearer. La chiave API deve iniziare con il prefisso nxd_.

Authorization: Bearer nxd_your_api_key_here

Il livello di autenticazione API è stateless – ogni richiesta viene autenticata in modo indipendente. Non ci sono sessioni o cookie.

Mantenga segreta la Sua chiave API. Non la condivida nel codice lato client, nei repository pubblici o negli URL. Se una chiave viene compromessa, la revochi immediatamente e ne crei una nuova.

Errori di autenticazione

Formato delle risposte

Tutte le risposte sono in formato JSON. Le risposte di successo hanno la seguente struttura:

Risorsa singola

{
    "status": "success",
    "data": {
        "id": 42,
        "public_id": "xK9mP2",
        "name": "example.com",
        ...
    }
}

Lista paginata

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

Risposta di errore

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

ID pubblici

Ogni risorsa è identificata da un id opaco (ad esempio xK9mQ2), usato nei percorsi URL. Gli ID numerici del database non vengono mai esposti né accettati.

Paginazione

Gli endpoint che restituiscono risultati paginati accettano i seguenti parametri di query:

Zone

Gestione delle zone DNS. Richiede zones.read per le operazioni di lettura e zones.write per le operazioni di scrittura.

GET /v1/zones

Elenca tutte le zone dell’utente autenticato.

Parametri di query

• search – filtra le zone per nome
• page, per_page – paginazione

Campi della risposta

id, name, type (master o slave), status, ns_group, created_at, updated_at

GET /v1/zones/{id}

Ottiene informazioni dettagliate su una zona specifica, inclusi i dati SOA, i server dei nomi e il conteggio dei record.

Campi aggiuntivi della risposta

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

POST /v1/zones

Crea una nuova zona DNS. La creazione della zona è bloccata se l’utente ha fatture scadute.

Corpo della richiesta (JSON)

{
    "name": "example.com",
    "type": "master",
    "ns_group_id": 1,
    "master_ip": ""
}

• name (obbligatorio) – nome di dominio
• type – "master" (predefinito) o "slave"
• ns_group – gruppo NS a cui assegnare la zona (opzionale, utilizza quello predefinito se omesso)
• master_ip – obbligatorio per le zone secondarie; deve essere un indirizzo IP valido

Restituisce 201 Created con l’oggetto zona.

DELETE /v1/zones/{id}

Elimina una zona e tutti i suoi record.

Restituisce 204 No Content in caso di successo.

GET /v1/zones/{id}/export

Esporta una zona in formato BIND o come JSON strutturato.

Parametri di query

• format – "bind" (predefinito) restituisce il testo del file di zona BIND; "json" restituisce un array strutturato di record con nome, tipo, contenuto e TTL

Record

Gestione dei record DNS all’interno di una zona. Tutti gli endpoint dei record sono annidati sotto una zona. Richiede records.read per le operazioni di lettura e records.write per le operazioni di scrittura.

GET /v1/zones/{zoneId}/records

Elenca tutti i record in una zona.

Parametri di query

• type – filtra per tipo di record (es. A, CNAME, MX)
• name – filtra per nome del record (corrispondenza parziale)
• search – cerca sia nel nome che nel contenuto

Campi della risposta

id, name, type, content, ttl, disabled, fields (campi specifici del tipo analizzati)

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

Ottiene un singolo record tramite il suo ID.

POST /v1/zones/{zoneId}/records

Crea un nuovo record DNS.

Corpo della richiesta (JSON)

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

• type (obbligatorio) – tipo di record (A, AAAA, CNAME, MX, TXT, SRV, CAA, NS, PTR, ALIAS, DNAME, DS, TLSA)
• name – nome del record relativo alla zona (predefinito: @ per l’apice della zona)
• ttl – tempo di vita in secondi (predefinito: 3600)
• content – valore del record (IP per A/AAAA, hostname per CNAME/NS/PTR, testo per TXT, server di posta per MX)

Campi specifici del tipo

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

Restituisce 201 Created con l’oggetto record.

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

Aggiorna un record esistente. Includere solo i campi da modificare; i campi omessi mantengono i valori correnti.

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

Restituisce 200 OK con l’oggetto record aggiornato. Nota: l’ID del record potrebbe cambiare dopo un aggiornamento poiché viene calcolato dal nome, tipo e contenuto del record.

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

Elimina un record dalla zona.

Restituisce 204 No Content in caso di successo.

DNSSEC

Gestione DNSSEC per le zone. Richiede zones.read per visualizzare lo stato e zones.write per abilitare o disabilitare.

GET /v1/zones/{id}/dnssec

Ottiene lo stato DNSSEC di una zona, incluse le chiavi e i record DS.

Campi della risposta

enabled (booleano), keys (array di record DNSKEY), ds_records (array di record DS da impostare presso il registrar)

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

Abilita DNSSEC per una zona. Genera automaticamente le chiavi di firma.

Restituisce lo stato DNSSEC con le chiavi generate e i record DS.

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

Disabilita DNSSEC per una zona. Rimuove tutte le chiavi di firma.

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

Gruppi NS

Elenca i gruppi di server dei nomi disponibili. Usare l’id di un gruppo come ns_group durante la creazione di una zona. Questo endpoint può essere letto da qualsiasi chiave API valida.

GET /v1/ns-groups

Elenca i gruppi di server dei nomi attivi.

Campi della risposta per gruppo

id, name, slug

Dettagli account

Visualizzazione delle informazioni dell’account e gestione delle chiavi API.

GET /v1/account

Ottiene le informazioni dell’account corrente, inclusi i dettagli dell’abbonamento.

Campi della risposta

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

subscription – oggetto con plan, billing_cycle, status, current_period_start, current_period_end (o null se nessun abbonamento)

GET /v1/account/api-keys

Elenca tutte le chiavi API dell’utente autenticato.

Campi della risposta per chiave

id, name, key_prefix (primi 8 caratteri), permissions (array), last_used_at, expires_at, created_at

POST /v1/account/api-keys

Crea una nuova chiave API.

Corpo della richiesta (JSON)

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

• name (obbligatorio) – nome leggibile (massimo 255 caratteri)
• permissions (obbligatorio) – array di permessi (almeno uno richiesto): zones.read, zones.write, records.read, records.write, webhooks.read, webhooks.write
• expires_at – data di scadenza opzionale (ISO 8601 o YYYY-MM-DD); deve essere nel futuro

La risposta include la chiave API completa nel campo key. Questa è l’unica volta in cui la chiave completa viene restituita. La conservi in modo sicuro.

Restituisce 201 Created con i dettagli della chiave incluso il valore completo key.

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

Revoca (elimina definitivamente) una chiave API.

Restituisce 204 No Content in caso di successo.

Fatturazione

Visualizzazione di abbonamento, piani e fatture. Questi endpoint sono di sola lettura.

GET /v1/billing/subscription

Ottiene i dettagli dell’abbonamento corrente. Restituisce null se non c’è un abbonamento attivo.

Campi della risposta

Campi id, plan, billing_cycle, status, current_period_start, current_period_end, created_at

GET /v1/billing/plans

Elenca tutti i piani disponibili con tariffe e funzionalità.

Campi della risposta per piano

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

GET /v1/billing/invoices

Elenca le fatture dell’utente autenticato, dalle più recenti.

Parametri di query

• status – filtra per stato (draft, issued, sent, void)
• page, per_page – paginazione

GET /v1/billing/invoices/{id}

Ottiene una singola fattura tramite il suo <code>id</code>.

Campi della risposta

Campi id, number, status, amount (lordo), net_amount (netto), tax_amount, tax_rate, currency, issued_at, created_at. Gli importi sono stringhe decimali semplici.

Webhooks

Gestisce gli abbonamenti webhook in uscita per ricevere notifiche in tempo reale sulle modifiche di zone e record. Richiede webhooks.read per la lettura e webhooks.write per creare, modificare o eliminare.

GET /v1/webhooks

Elenca tutti gli abbonamenti webhook dell’utente autenticato.

Campi della risposta per webhook

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

POST /v1/webhooks

Crea un abbonamento webhook.

Corpo della richiesta (JSON)

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

• url (obbligatorio) – endpoint HTTPS che riceverà i payload degli eventi
• events (obbligatorio) – array dei tipi di evento a cui iscriversi
• description – etichetta leggibile facoltativa

La risposta include un secret per verificare le firme dei webhook (HMAC). È l’unica volta in cui il secret viene restituito. Conservarlo in un luogo sicuro.

Restituisce 201 Created con l’id e il secret del webhook.

GET /v1/webhooks/{id}

Ottiene un singolo abbonamento webhook con le sue consegne più recenti.

PUT /v1/webhooks/{id}

Aggiorna un abbonamento webhook. Includere solo i campi da modificare.

Restituisce 200 OK con l’oggetto webhook aggiornato.

DELETE /v1/webhooks/{id}

Elimina un abbonamento webhook.

Restituisce 204 No Content in caso di successo.

POST /v1/webhooks/{id}/test

Invia un evento di test all’endpoint del webhook per verificarne la raggiungibilità.

Mette in coda una consegna di test con un payload "type": "test".

Tipi di evento disponibili

È possibile iscriversi a qualsiasi combinazione di questi tipi di evento:

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

Codici di errore

Tutti gli errori seguono un formato coerente con una stringa di errore code e un message leggibile.

Esempi di codice

Tutti gli esempi utilizzano curl. Sostituire nxd_your_api_key con la Sua chiave API effettiva.

Elencare le zone

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

Creare una zona

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"}'

Aggiungere un record 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"
    }'

Aggiungere un record 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
    }'

Aggiornare un record

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}'

Eliminare un record

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

Esportare una zona (formato BIND)

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

Abilitare DNSSEC

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

Creare una chiave 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"
    }'

Ottenere le informazioni dell’account

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