Reference API

Autentizace

Všechny API požadavky vyžadují autentizaci pomocí API klíče. Předejte klíč v hlavičce Authorization jako Bearer token. API klíč musí začínat předponou nxd_.

Požadavek na tarif: REST API, API kompatibilní s ISPmanagerem a webhooky jsou dostupné v tarifu Pro a vyšším, stejně jako dvě funkce, které tato reference také popisuje: DNSSEC a sekundární (slave) zóny. Klíč z tarifu, který je neobsahuje, dostane odpověď 403.

Authorization: Bearer nxd_your_api_key_here

API firewall je bezstavový – každý požadavek je autentizován nezávisle. Neexistují žádné relace ani cookies.

Udržujte svůj API klíč v tajnosti. Nesdílejte ho v klientském kódu, veřejných repozitářích ani URL adresách. Pokud dojde ke kompromitaci klíče, okamžitě ho zneplatněte a vytvořte nový.

Chyby autentizace

Formát odpovědi

Všechny odpovědi jsou ve formátu JSON. Úspěšné odpovědi mají následující strukturu:

Jednotlivý zdroj

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

Stránkovaný seznam

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

Chybová odpověď

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

Chyby, které vznikají hlouběji v platformě – limit tarifu, blokovaná doména, výpadek nameserveru – nesou stejný objekt error, ale bez pole status. Rozhodujte se podle error.code, který je stabilní, nikoli podle přítomnosti status. Zprávy jsou podle kontraktu v angličtině na každé instanci a v každém jazyce; error.code je strojově čitelná část.

Veřejná ID

Každý zdroj je identifikován neprůhledným id (například xK9mQ2), které se používá v URL cestách. Numerická databázová ID nejsou nikdy vystavena ani přijímána.

Stránkování

Endpointy pro výpis, které vrací stránkované výsledky, přijímají následující parametry dotazu:

Omezení počtu požadavků

Požadavky se počítají na účet, nikoli na klíč, v posuvném jednominutovém okně a rozpočet vychází z vašeho tarifu – konkrétní číslo najdete v porovnání tarifů na stránce ceníku. Neautentizované požadavky se počítají podle IP adresy. Každá odpověď nese aktuální stav vašeho rozpočtu, takže nemusíte nic odhadovat:

Při hromadné práci, jako je import velké zóny nebo srovnání stovek záznamů, čtěte X-RateLimit-Remaining a udělejte pauzu dřív, než dosáhne nuly, místo opakování po chybě 429. CLI to za vás dělá samo.

Několik operací má nad rámec rozpočtu požadavků vlastní, delší okno: jednu zónu lze přesunout do jiné skupiny nameserverů třikrát denně. Odpověď uvede, který limit byl vyčerpán.

Zóny

Správa DNS zón. Vyžaduje zones.read pro operace čtení a zones.write pro operace zápisu.

GET /v1/zones

Výpis všech zón autentizovaného uživatele.

Parametry dotazu

• search – filtrování zón podle názvu
• page, per_page – stránkování

Pole odpovědi

Pole odpovědi: id, name, type (master/slave), status, ns_group, created_at, updated_at

GET /v1/zones/{id}

Získání podrobných informací o konkrétní zóně, včetně dat SOA, nameserverů a počtu záznamů.

Další pole odpovědi

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

POST /v1/zones

Vytvoření nové DNS zóny. Odmítnuto s kódem 409, pokud domína již existuje nebo se překrývá se zónou jiného účtu, a s kódem 422, pokud je dosažen limit zón tarifu nebo je domína blokovaná.

Tělo požadavku (JSON)

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

Místo toho sekundární (slave) zóna:

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

• name (povinné) – název domény
• type – "master" (výchozí) nebo "slave"
• ns_group – NS skupina, ke které bude zóna přiřazena (volitelné, pokud není uvedeno, použije se výchozí)
• master_ip – povinné pro sekundární zóny; musí být platná veřejná IP adresa

Vrací 201 Created s objektem zóny.

PATCH /v1/zones/{id}

Přesune zónu do jiné skupiny nameserverů. Jde o jediný PATCH v celém API. Oprávnění: zones.write.

Tělo požadavku (JSON)

{
    "ns_group": "eu"
}

Vrací zónu ve stavu po přesunu, ve stejné podobě jako GET /v1/zones/{id}. Skupina se určuje svým slugem – hodnotami, které pro váš účet vypíše GET /v1/ns-groups; cokoli jiného je odmítnuto chybou 400.

Zóna po celou dobu odpovídá: nové nameservery jsou připraveny před odesláním odpovědi a předchozí obsluhují dotazy, dokud se resolvery neaktualizují. Poté upravte delegaci u svého registrátora. Zónu lze přesunout třikrát denně; poté volání vrátí 429.

DELETE /v1/zones/{id}

Smazání zóny a všech jejích záznamů.

Vrací 204 No Content při úspěchu.

GET /v1/zones/{id}/export

Export zóny ve formátu BIND nebo jako strukturovaný JSON.

Parametry dotazu

• format – "bind" (výchozí) vrací text souboru zóny BIND; "json" vrací strukturované pole záznamů s name, type, content a ttl

Záznamy

Správa DNS záznamů v rámci zóny. Všechny endpointy pro záznamy jsou vnořeny pod zónu. Vyžaduje records.read pro operace čtení a records.write pro operace zápisu.

GET /v1/zones/{zoneId}/records

Výpis všech záznamů v zóně.

Parametry dotazu

• type – filtrování podle typu záznamu (např. A, CNAME, MX)
• name – filtrování podle názvu záznamu (hledání podřetězce)
• search – vyhledávání v názvu i obsahu

Pole odpovědi

id, name, type, content, ttl, disabled, fields (rozparsovaná pole podle typu)

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

Získání jednoho záznamu podle jeho ID.

POST /v1/zones/{zoneId}/records

Vytvoření nového DNS záznamu.

Tělo požadavku (JSON)

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

• type (povinné) – typ záznamu (A, AAAA, CNAME, MX, TXT, SRV, CAA, NS, PTR, ALIAS, DNAME, DS, TLSA)
• name – název záznamu relativní k zóně (výchozí: @ pro apex zóny)
• ttl – doba životnosti v sekundách (výchozí: 3600)
• content – hodnota záznamu (IP pro A/AAAA, název hostitele pro CNAME/NS/PTR, text pro TXT, poštovní server pro MX)

Pole specifická pro typ

• MX: priority (výchozí: 10)
• SRV: priority, weight, port (hodnoty záznamu)
• CAA: flags (výchozí: 0), tag (výchozí: „issue")
• DS: keytag, algorithm, digest_type (hodnoty záznamu)
• TLSA: usage, selector, matching_type (hodnoty záznamu)

U typů MX, SRV, CAA, DS a TLSA nese content pouze primární hodnotu – poštovní server, cíl SRV, doménu certifikační autority, samotný hexadecimální digest – a všechno ostatní patří do polí výše. Odeslání složených dat záznamu (například 0 issue "letsencrypt.org" jako obsah CAA) je odmítnuto chybou 400, která pojmenuje dané pole.

TTL patří celé sadě záznamů. Když přidáváte další hodnotu k názvu, který už existuje, a ttl vynecháte, zachová se stávající TTL; pokud ho pošlete, přenastaví se u všech hodnot na tomto názvu. Zcela nový název má výchozí hodnotu 3600 sekund.

Vrací 201 Created s objektem záznamu.

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

Aktualizace existujícího záznamu. Uveďte pouze pole, která chcete změnit; vynechaná pole si zachovají aktuální hodnoty.

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

Vrací 200 OK s aktualizovaným objektem záznamu. Poznámka: ID záznamu se může po aktualizaci změnit, protože je vypočítáno z názvu, typu a obsahu záznamu.

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

Smazání záznamu ze zóny.

Vrací 204 No Content při úspěchu.

DNSSEC

Správa DNSSEC pro vaše zóny. Vyžaduje zones.read pro zobrazení stavu a zones.write pro aktivaci nebo deaktivaci.

GET /v1/zones/{id}/dnssec

Získání stavu DNSSEC pro zónu, včetně klíčů a záznamů DS.

Pole odpovědi

enabled (boolean), keys (pole záznamů DNSKEY), ds_records (pole záznamů DS pro nastavení u registrátora)

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

Aktivace DNSSEC pro zónu. Automaticky vygeneruje podepisovací klíče.

Vrací stav DNSSEC s vygenerovanými klíči a záznamy DS.

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

Deaktivace DNSSEC pro zónu. Odstraní všechny podepisovací klíče.

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

Skupiny NS

Vypíše dostupné skupiny name serverů. Použijte id skupiny jako ns_group při vytváření zóny. Tento endpoint může číst jakýkoli platný API klíč.

GET /v1/ns-groups

Vypíše aktivní skupiny name serverů.

Pole odpovědi pro každou skupinu

id, name, slug

Účet

Zobrazení informací o účtu a správa API klíčů.

GET /v1/account

Získání aktuálních informací o účtu, včetně údajů o předplatném.

Pole odpovědi

Pole odpovědi: id (UUID), email, name, role, status, language, timezone, created_at

subscription – objekt s plan, billing_cycle, status, current_period_start, current_period_end (nebo null, pokud nemáte předplatné)

GET /v1/account/api-keys

Výpis všech API klíčů autentizovaného uživatele.

Pole odpovědi pro každý klíč

id, name, key_prefix (prvních 8 znaků), permissions (pole), last_used_at, expires_at, created_at

POST /v1/account/api-keys

Vytvoření nového API klíče.

Tělo požadavku (JSON)

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

• name (povinné) – lidsky čitelný název (max. 255 znaků)
• permissions (povinné) – pole oprávnění (alespoň jedno je vyžadováno): zones.read, zones.write, records.read, records.write, webhooks.read, webhooks.write
• expires_at – volitelné datum expirace (ISO 8601 nebo YYYY-MM-DD); musí být v budoucnosti

Odpověď obsahuje úplný API klíč v poli key. Toto je jediný okamžik, kdy je úplný klíč zobrazen. Uložte ho bezpečně.

Vrací 201 Created s detaily klíče včetně úplné hodnoty key.

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

Zneplatnění (trvalé smazání) API klíče.

Vrací 204 No Content při úspěchu.

Fakturace

Zobrazení předplatného, tarifů a faktur. Tyto endpointy jsou pouze pro čtení.

GET /v1/billing/subscription

Získání aktuálních údajů o předplatném. Vrací null, pokud není aktivní předplatné.

Pole odpovědi

Pole odpovědi: id, plan, billing_cycle, status, current_period_start, current_period_end, created_at

GET /v1/billing/plans

Výpis všech dostupných tarifů s cenami a funkcemi.

Pole odpovědi pro každý tarif

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

GET /v1/billing/invoices

Vypíše faktury autentizovaného uživatele, nejnovější první.

Parametry dotazu

• status – filtrování podle stavu (draft, issued, sent, void)
• page, per_page – stránkování

GET /v1/billing/invoices/{id}

Získá jednu fakturu podle jejího <code>id</code>.

Pole odpovědi

Pole odpovědi: id, number, status, amount (s daní), net_amount (bez daně), tax_amount, tax_rate, currency, issued_at, created_at. Peněžní hodnoty jsou jednoduché desetinné řetězce.

Webhooks

Správa odchozích webhook odběrů pro příjem oznámení o změnách zón a záznamů v reálném čase. Vyžaduje webhooks.read pro čtení a webhooks.write pro vytváření, úpravu nebo mazání.

GET /v1/webhooks

Vypíše všechny webhook odběry autentizovaného uživatele.

Pole odpovědi pro každý webhook

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

POST /v1/webhooks

Vytvoří webhook odběr.

Tělo požadavku (JSON)

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

• url (povinné) – HTTPS endpoint, který bude přijímat data událostí
• events (povinné) – pole typů událostí k odběru
• description – volitelný čitelný popisek

Odpověď obsahuje secret pro ověření podpisů webhooku (HMAC). Toto je jediný okamžik, kdy je secret vrácen. Uložte jej na bezpečné místo.

Vrací 201 Created s id a secret webhooku.

GET /v1/webhooks/{id}

Získá jeden webhook odběr spolu s jeho nejnovějšími doručeními.

PUT /v1/webhooks/{id}

Upraví webhook odběr. Uveďte pouze pole, která chcete změnit.

Vrací 200 OK s aktualizovaným objektem webhooku.

DELETE /v1/webhooks/{id}

Smaže webhook odběr.

Vrací 204 No Content při úspěchu.

POST /v1/webhooks/{id}/test

Odešle testovací událost na endpoint webhooku pro ověření dostupnosti.

Zařadí do fronty testovací doručení s daty "type": "test".

Ověření doručení

Každé doručení je podepsáno tajným klíčem, který se vrátí při vytvoření webhooku, a nese čtyři hlavičky:

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

Přepočítejte HMAC-SHA256 nad přesným nezpracovaným tělem požadavku pomocí svého tajného klíče a výsledek porovnejte s hexadecimálním digestem za sha256= porovnáním s konstantní dobou běhu. Neshoda znamená, že požadavek nepřišel od nás. X-NexDNS-Delivery identifikuje jednotlivý pokus, takže opakovaná doručení téže události mají shodné id události, ale jiné číslo doručení.

Data doručení

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

Dostupné typy událostí

Přihlaste se k odběru libovolné kombinace těchto typů událostí:

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

Chybové kódy

Všechny chyby mají jednotný formát s řetězcem chybového code a lidsky čitelnou message.

Příklady kódu

Všechny příklady používají curl. Nahraďte nxd_your_api_key svým skutečným API klíčem.

Výpis vašich zón

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

Vytvoření zóny

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

Přidání záznamu 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"
    }'

Přidání záznamu 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
    }'

Aktualizace záznamu

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

Smazání záznamu

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

Export zóny (formát BIND)

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

Aktivace DNSSEC

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

Vytvoření API klíče

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

Informace o účtu

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