Dokumentacja API

Autoryzacja

Wszystkie zapytania API wymagają autoryzacji za pomocą klucza API. Przekaż klucz w nagłówku Authorization jako token Bearer. Klucz API musi zaczynać się od prefiksu nxd_.

Wymagany plan: REST API, API zgodne z ISPmanagerem i webhooki są dostępne w planie Pro i wyższych – podobnie jak dwie możliwości omówione w tej dokumentacji: DNSSEC oraz strefy podrzędne (slave). Klucz w planie, który ich nie obejmuje, otrzymuje odpowiedź 403.

Authorization: Bearer nxd_your_api_key_here

Warstwa autoryzacji API jest bezstanowa – każde zapytanie jest autoryzowane niezależnie. Nie ma sesji ani ciasteczek.

Przechowuj klucz API w tajemnicy. Nie udostępniaj go w kodzie po stronie klienta, publicznych repozytoriach ani adresach URL. Jeśli klucz zostanie skompromitowany, natychmiast go unieważnij i utwórz nowy.

Błędy autoryzacji

Format odpowiedzi

Wszystkie odpowiedzi są w formacie JSON. Pomyślne odpowiedzi mają następującą strukturę:

Pojedynczy zasób

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

Lista z paginacją

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

Odpowiedź z błędem

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

Błędy zgłaszane głębiej w platformie – limit, zablokowana domena, awaria serwera nazw – zawierają ten sam obiekt error, ale bez pola status. Rozgałęziaj logikę na stabilnym polu error.code, a nie na obecności pola status. Zgodnie z kontraktem komunikaty są po angielsku na każdej instancji i w każdym języku; error.code to część czytelna dla maszyn.

Publiczne identyfikatory

Każdy zasób jest identyfikowany przez nieprzejrzysty id (na przykład xK9mQ2), używany w ścieżkach URL. Numeryczne identyfikatory z bazy danych nigdy nie są ujawniane ani akceptowane.

Paginacja

Endpointy list zwracające wyniki z paginacją akceptują następujące parametry zapytania:

Limit zapytań

Zapytania są liczone na konto, a nie na klucz, w przesuwnym oknie jednej minuty, a wielkość budżetu wynika z planu – konkretną liczbę podaje porównanie planów w cenniku. Zapytania nieuwierzytelnione są liczone na adres IP. Każda odpowiedź zawiera bieżący stan budżetu, więc nie trzeba niczego zgadywać:

Przy pracy masowej – import dużej strefy, uzgadnianie setek rekordów – odczytuj X-RateLimit-Remaining i wstrzymaj wysyłanie, zanim wartość spadnie do zera, zamiast ponawiać zapytania po kodzie 429. CLI robi to za Ciebie.

Kilka operacji ma własne, dłuższe okno poza budżetem zapytań: jedną strefę można przenieść do innej grupy serwerów nazw trzy razy dziennie. Odpowiedź wskazuje, który limit został wyczerpany.

Strefy

Zarządzaj strefami DNS. Wymaga zones.read do operacji odczytu i zones.write do operacji zapisu.

GET /v1/zones

Wyświetl wszystkie strefy uwierzytelnionego użytkownika.

Parametry zapytania

• search – filtruj strefy według nazwy
• page, per_page – paginacja

Pola odpowiedzi

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

GET /v1/zones/{id}

Pobierz szczegółowe informacje o konkretnej strefie, w tym dane SOA, serwery nazw i liczbę rekordów.

Dodatkowe pola odpowiedzi

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

POST /v1/zones

Tworzy nową strefę DNS. Odrzucane z kodem 409, jeśli domena już istnieje lub pokrywa się ze strefą innego konta, oraz z kodem 422, jeśli osiągnięto limit stref w planie lub domena jest zablokowana.

Treść zapytania (JSON)

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

Zamiast tego strefa wtórna (slave):

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

• name (wymagane) – nazwa domeny
• type – "master" (domyślnie) lub "slave"
• ns_group – grupa NS do przypisania strefy (opcjonalne, używa domyślnej jeśli pominięte)
• master_ip – wymagane dla stref podrzędnych; musi być prawidłowym publicznym adresem IP

Zwraca 201 Created z obiektem strefy.

PATCH /v1/zones/{id}

Przenosi strefę do innej grupy serwerów nazw. To jedyny PATCH w API. Uprawnienie: zones.write.

Treść zapytania (JSON)

{
    "ns_group": "eu"
}

Zwraca strefę w stanie po przeniesieniu, w tym samym formacie co GET /v1/zones/{id}. Grupę wskazuje się jej slugiem – wartością z listy zwracanej przez GET /v1/ns-groups dla danego konta; każda inna wartość jest odrzucana z kodem 400.

Strefa odpowiada przez cały czas: nowe serwery nazw są przygotowywane przed odesłaniem odpowiedzi, a poprzednie obsługują zapytania, dopóki resolwery się nie odświeżą. Następnie zaktualizuj delegację u swojego rejestratora. Strefę można przenieść trzy razy dziennie; powyżej tego limitu wywołanie zwraca 429.

DELETE /v1/zones/{id}

Usuń strefę i wszystkie jej rekordy.

Zwraca 204 No Content w przypadku powodzenia.

GET /v1/zones/{id}/export

Eksportuj strefę w formacie BIND lub jako ustrukturyzowany JSON.

Parametry zapytania

• format – "bind" (domyślnie) zwraca tekst pliku strefy BIND; "json" zwraca ustrukturyzowaną tablicę rekordów z polami name, type, content i ttl

Rekordy

Zarządzaj rekordami DNS w strefie. Wszystkie endpointy rekordów są zagnieżdżone pod strefą. Wymaga records.read do operacji odczytu i records.write do operacji zapisu.

GET /v1/zones/{zoneId}/records

Wyświetl wszystkie rekordy w strefie.

Parametry zapytania

• type – filtruj według typu rekordu (np. A, CNAME, MX)
• name – filtruj według nazwy rekordu (dopasowanie podciągu)
• search – szukaj w nazwie i treści

Pola odpowiedzi

id, name, type, content, ttl, disabled, fields (pola specyficzne dla typu)

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

Pobierz pojedynczy rekord po jego ID.

POST /v1/zones/{zoneId}/records

Utwórz nowy rekord DNS.

Treść zapytania (JSON)

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

• type (wymagane) – typ rekordu (A, AAAA, CNAME, MX, TXT, SRV, CAA, NS, PTR, ALIAS, DNAME, DS, TLSA)
• name – nazwa rekordu względem strefy (domyślnie: @ dla wierzchołka strefy)
• ttl – czas życia w sekundach (domyślnie: 3600)
• content – wartość rekordu (IP dla A/AAAA, nazwa hosta dla CNAME/NS/PTR, tekst dla TXT, serwer pocztowy dla MX)

Pola specyficzne dla typu

• MX: priority (domyślnie: 10)
• SRV (usługa): priority, weight, port
• CAA: flags (domyślnie: 0), tag (domyślnie: "issue")
• DS (delegacja DNSSEC): keytag, algorithm, digest_type
• TLSA (DANE): usage, selector, matching_type

W przypadku MX, SRV, CAA, DS i TLSA pole content zawiera tylko wartość główną – serwer pocztowy, cel SRV, domenę urzędu certyfikacji, sam skrót szesnastkowy – a wszystko pozostałe trafia do pól powyżej. Przesłanie złożonych danych rekordu (na przykład 0 issue "letsencrypt.org" jako treści CAA) jest odrzucane z kodem 400 wskazującym pole.

TTL należy do zestawu rekordów. Jeśli dodajesz kolejną wartość do już istniejącej nazwy, pomiń ttl – dotychczasowy TTL zostanie zachowany; podaj go, a każda wartość pod tą nazwą otrzyma nowy czas życia. Dla całkiem nowej nazwy domyślną wartością jest 3600 sekund.

Zwraca 201 Created z obiektem rekordu.

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

Zaktualizuj istniejący rekord. Uwzględnij tylko pola, które chcesz zmienić; pominięte pola zachowują swoje bieżące wartości.

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

Zwraca 200 OK z zaktualizowanym obiektem rekordu. Uwaga: ID rekordu może się zmienić po aktualizacji, ponieważ jest obliczane na podstawie nazwy, typu i treści rekordu.

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

Usuń rekord ze strefy.

Zwraca 204 No Content w przypadku powodzenia.

DNSSEC

Zarządzaj DNSSEC dla stref. Wymaga zones.read do wyświetlania statusu i zones.write do włączania lub wyłączania.

GET /v1/zones/{id}/dnssec

Pobierz status DNSSEC dla strefy, w tym klucze i rekordy DS.

Pola odpowiedzi

enabled (wartość logiczna), keys (tablica rekordów DNSKEY), ds_records (tablica rekordów DS do ustawienia u rejestratora)

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

Włącz DNSSEC dla strefy. Automatycznie generuje klucze podpisywania.

Zwraca status DNSSEC z wygenerowanymi kluczami i rekordami DS.

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

Wyłącz DNSSEC dla strefy. Usuwa wszystkie klucze podpisywania.

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

Grupy NS

Wyświetla dostępne grupy serwerów nazw. Użyj id grupy jako ns_group podczas tworzenia strefy. Ten endpoint może odczytać dowolny prawidłowy klucz API.

GET /v1/ns-groups

Wyświetla aktywne grupy serwerów nazw.

Pola odpowiedzi dla każdej grupy

id, name, slug

Konto

Wyświetl informacje o koncie i zarządzaj kluczami API.

GET /v1/account

Pobierz informacje o bieżącym koncie, w tym szczegóły subskrypcji.

Pola odpowiedzi

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

subscription – obiekt z polami plan, billing_cycle, status, current_period_start, current_period_end (lub null, jeśli brak subskrypcji)

GET /v1/account/api-keys

Wyświetl wszystkie klucze API uwierzytelnionego użytkownika.

Pola odpowiedzi dla każdego klucza

id, name, key_prefix (pierwsze 8 znaków), permissions (tablica), last_used_at, expires_at, created_at

POST /v1/account/api-keys

Utwórz nowy klucz API.

Treść zapytania (JSON)

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

• name (wymagane) – czytelna nazwa (maks. 255 znaków)
• permissions (wymagane) – tablica uprawnień (wymagane co najmniej jedno): zones.read, zones.write, records.read, records.write, webhooks.read, webhooks.write
• expires_at – opcjonalna data wygaśnięcia (ISO 8601 lub YYYY-MM-DD); musi być w przyszłości

Odpowiedź zawiera pełny klucz API w polu key. To jedyny raz, gdy pełny klucz jest zwracany. Przechowuj go bezpiecznie.

Zwraca 201 Created ze szczegółami klucza, w tym pełną wartością key.

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

Unieważnij (trwale usuń) klucz API.

Zwraca 204 No Content w przypadku powodzenia.

Rozliczenia

Wyświetl subskrypcję, plany i faktury. Te endpointy są tylko do odczytu.

GET /v1/billing/subscription

Pobierz bieżące szczegóły subskrypcji. Zwraca null, jeśli brak aktywnej subskrypcji.

Pola odpowiedzi

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

GET /v1/billing/plans

Wyświetl wszystkie dostępne plany z cenami i funkcjami.

Pola odpowiedzi dla każdego planu

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

GET /v1/billing/invoices

Wyświetla faktury uwierzytelnionego użytkownika, od najnowszych.

Parametry zapytania

• status – filtruj według statusu (draft, issued, sent, void)
• page, per_page – paginacja

GET /v1/billing/invoices/{id}

Pobiera pojedynczą fakturę po jej <code>id</code>.

Pola odpowiedzi

Pola: id, number, status, amount (brutto), net_amount (netto), tax_amount, tax_rate, currency, issued_at, created_at. Wartości pieniężne to proste ciągi dziesiętne.

Webhooks

Zarządzaj wychodzącymi subskrypcjami webhook, aby otrzymywać powiadomienia o zmianach stref i rekordów w czasie rzeczywistym. Wymaga webhooks.read do odczytu oraz webhooks.write do tworzenia, modyfikowania i usuwania.

GET /v1/webhooks

Wyświetla wszystkie subskrypcje webhook uwierzytelnionego użytkownika.

Pola odpowiedzi dla każdego webhooka

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

POST /v1/webhooks

Tworzy subskrypcję webhook.

Treść zapytania (JSON)

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

• url (wymagane) – endpoint HTTPS, który będzie odbierać dane zdarzeń
• events (wymagane) – tablica typów zdarzeń do subskrypcji
• description – opcjonalna czytelna etykieta

Odpowiedź zawiera secret do weryfikacji podpisów webhook (HMAC). To jedyny raz, gdy secret jest zwracany. Przechowuj go w bezpiecznym miejscu.

Zwraca 201 Created z id i secret webhooka.

GET /v1/webhooks/{id}

Pobiera pojedynczą subskrypcję webhook wraz z jej najnowszymi dostawami.

PUT /v1/webhooks/{id}

Aktualizuje subskrypcję webhook. Uwzględnij tylko pola, które chcesz zmienić.

Zwraca 200 OK ze zaktualizowanym obiektem webhooka.

DELETE /v1/webhooks/{id}

Usuwa subskrypcję webhook.

Zwraca 204 No Content w przypadku powodzenia.

POST /v1/webhooks/{id}/test

Wysyła zdarzenie testowe na endpoint webhooka, aby sprawdzić jego dostępność.

Kolejkuje testową dostawę z danymi "type": "test".

Weryfikacja dostawy

Każda dostawa jest podpisana sekretem zwróconym przy tworzeniu webhooka i zawiera cztery nagłówki:

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

Oblicz ponownie HMAC-SHA256 z dokładnej, surowej treści zapytania przy użyciu swojego sekretu i porównaj wynik ze skrótem szesnastkowym po sha256=, stosując porównanie o stałym czasie. Niezgodność oznacza, że zapytanie nie pochodzi od nas. X-NexDNS-Delivery identyfikuje próbę, więc ponowienia tego samego zdarzenia mają wspólne id zdarzenia, ale inny numer dostawy.

Dane dostawy

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

Dostępne typy zdarzeń

Możesz subskrybować dowolną kombinację tych typów zdarzeń:

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

Kody błędów

Wszystkie błędy mają spójny format z ciągiem kodu błędu code i czytelnym komunikatem message.

Przykłady kodu

Wszystkie przykłady używają curl. Zastąp nxd_your_api_key swoim rzeczywistym kluczem API.

Wyświetl swoje strefy

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

Utwórz strefę

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

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

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

Zaktualizuj rekord

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

Usuń rekord

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

Eksportuj strefę (format BIND)

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

Włącz DNSSEC

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

Utwórz klucz 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"
    }'

Pobierz informacje o koncie

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