API referansı

Kimlik doğrulama

Tüm API istekleri bir API anahtarı kullanarak kimlik doğrulaması gerektirir. Anahtarı Authorization başlığında Bearer token olarak geçirin. API anahtarı nxd_ öneki ile başlamalıdır.

Plan gereksinimi: REST API, ISPmanager uyumlu API ve webhook'lar Pro ve üzeri planlarda kullanılabilir. Bu referansın kapsadığı diğer iki özellik – DNSSEC ve ikincil (slave) bölgeler – için de aynısı geçerlidir. Bunları içermeyen bir plana ait anahtar 403 yanıtı alır.

Authorization: Bearer nxd_your_api_key_here

API güvenlik duvarı durumsuz çalışır – her istek bağımsız olarak doğrulanır. Oturum veya çerez kullanılmaz.

API anahtarınızı gizli tutun. İstemci tarafı kodunda, herkese açık depolarda veya URL'lerde paylaşmayın. Bir anahtar ele geçirilirse hemen iptal edin ve yenisini oluşturun.

Kimlik doğrulama hataları

Yanıt formatı

Tüm yanıtlar JSON formatındadır. Başarılı yanıtlar aşağıdaki yapıya sahiptir:

Tekil kaynak

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

Sayfalanmış liste

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

Hata yanıtı

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

Platformun derinlerinde oluşan hatalar – kota aşımı, engellenmiş bir alan adı, bir ad sunucusu arızası – aynı error nesnesini taşır ancak status alanı içermez. Koşullarınızı status alanının varlığına değil, kararlı olan error.code değerine göre kurun. Mesajlar sözleşme gereği her kurulumda ve her dilde İngilizcedir; makine tarafından okunan kısım error.code değeridir.

Genel kimlikler

Her kaynak, URL yollarında kullanılan opak bir id (örneğin xK9mQ2) ile tanımlanır. Ham sayısal veritabanı kimlikleri asla açığa çıkarılmaz veya kabul edilmez.

Sayfalama

Sayfalanmış sonuçlar döndüren liste uç noktaları aşağıdaki sorgu parametrelerini kabul eder:

Hız sınırları

İstekler anahtar başına değil, hesap başına ve kayan bir dakikalık pencerede sayılır; bütçe planınızdan gelir – rakam için fiyatlandırma sayfasındaki plan karşılaştırmasına bakın. Kimliği doğrulanmamış istekler IP adresine göre sayılır. Her yanıt, bütçenizin güncel durumunu taşır; böylece tahmin etmeniz gerekmez:

Toplu işlerde – büyük bir bölgeyi içe aktarırken, yüzlerce kaydı eşitlerken – X-RateLimit-Remaining değerini okuyun ve 429 aldıktan sonra yeniden denemek yerine sıfıra düşmeden önce durun. CLI bunu sizin için yapar.

Bazı işlemlerin istek bütçesinin üzerinde kendi daha uzun penceresi vardır: bir bölge günde üç kez başka bir ad sunucusu grubuna taşınabilir. Yanıt, hangi sınıra ulaşıldığını belirtir.

Bölgeler

DNS bölgelerini yönetin. Okuma işlemleri için zones.read, yazma işlemleri için zones.write gerektirir.

GET /v1/zones

Kimliği doğrulanmış kullanıcının tüm bölgelerini listeler.

Sorgu parametreleri

• search – bölgeleri ada göre filtrele
• page, per_page – sayfalama

Yanıt alanları

Döndürülen alanlar: id, name, type (master/slave), status, ns_group, created_at, updated_at

GET /v1/zones/{id}

SOA verileri, ad sunucuları ve kayıt sayısı dahil belirli bir bölge hakkında ayrıntılı bilgi alır.

Ek yanıt alanları

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

POST /v1/zones

Yeni bir DNS bölgesi oluşturur. Alan adı zaten mevcutsa veya başka bir hesabın bölgesiyle çakışıyorsa 409, planın bölge limiti dolduysa veya alan adı engellendiyse 422 ile reddedilir.

İstek gövdesi (JSON)

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

Bunun yerine ikincil (slave) bölge:

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

• name (zorunlu) – alan adı
• type – "master" (varsayılan) veya "slave"
• ns_group – bölgenin atanacağı NS grubu (isteğe bağlı, belirtilmezse varsayılan kullanılır)
• master_ip – ikincil bölgeler için zorunlu; geçerli bir genel IP adresi olmalıdır

201 Created ile bölge nesnesini döndürür.

PATCH /v1/zones/{id}

Bölgeyi başka bir ad sunucusu grubuna taşır. API'deki tek PATCH işlemidir. Kapsam: zones.write.

İstek gövdesi (JSON)

{
    "ns_group": "eu"
}

Taşıma sonrasındaki bölgeyi, GET /v1/zones/{id} ile aynı yapıda döndürür. Grup, slug değeriyle belirtilir – GET /v1/ns-groups çağrısının hesabınız için listelediği değerler; bunun dışındaki her şey 400 ile reddedilir.

Bölge işlem boyunca yanıt vermeyi sürdürür: yeni ad sunucuları yanıt gönderilmeden önce hazırlanır, önceki sunucular ise çözümleyiciler yenilenene kadar hizmet vermeye devam eder. İşlemden sonra kayıt kuruluşunuzdaki yetkilendirmeyi güncelleyin. Bir bölge günde üç kez taşınabilir; sonrasında çağrı 429 döndürür.

DELETE /v1/zones/{id}

Bir bölgeyi ve tüm kayıtlarını siler.

Başarılı olduğunda 204 No Content döndürür.

GET /v1/zones/{id}/export

Bir bölgeyi BIND formatında veya yapılandırılmış JSON olarak dışa aktarır.

Sorgu parametreleri

• format – "bind" (varsayılan) BIND bölge dosyası metni döndürür; "json" ad, tür, içerik ve TTL ile yapılandırılmış bir kayıt dizisi döndürür

Kayıtlar

Bir bölge içindeki DNS kayıtlarını yönetin. Tüm kayıt uç noktaları bir bölge altında iç içe yerleştirilmiştir. Okuma işlemleri için records.read, yazma işlemleri için records.write gerektirir.

GET /v1/zones/{zoneId}/records

Bir bölgedeki tüm kayıtları listeler.

Sorgu parametreleri

• type – kayıt türüne göre filtrele (örn. A, CNAME, MX)
• name – kayıt adına göre filtrele (alt dize eşleşmesi)
• search – hem ad hem de içerikte ara

Yanıt alanları

id, name, type, content, ttl, disabled, fields (türe özgü ayrıştırılmış alanlar)

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

Kimliğine göre tek bir kayıt alır.

POST /v1/zones/{zoneId}/records

Yeni bir DNS kaydı oluşturur.

İstek gövdesi (JSON)

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

• type (zorunlu) – kayıt türü (A, AAAA, CNAME, MX, TXT, SRV, CAA, NS, PTR, ALIAS, DNAME, DS, TLSA)
• name – bölgeye göre kayıt adı (varsayılan: bölge kökü için @)
• ttl – saniye cinsinden yaşam süresi (varsayılan: 3600)
• content – kayıt değeri (A/AAAA için IP, CNAME/NS/PTR için ana bilgisayar adı, TXT için metin, MX için posta sunucusu)

Türe özgü alanlar

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

MX, SRV, CAA, DS ve TLSA kayıtlarında content yalnızca birincil değeri taşır – posta sunucusu, SRV hedefi, CA alan adı, çıplak onaltılık özet – geri kalan her şey yukarıdaki alanlara girer. Birleştirilmiş kayıt verisi göndermek (örneğin CAA içeriği olarak 0 issue "letsencrypt.org") 400 ile reddedilir ve yanıt, hangi alanın hatalı olduğunu belirtir.

TTL kayıt kümesine aittir. Zaten var olan bir ada başka bir değer eklerken ttl alanını atlarsanız mevcut TTL korunur; gönderirseniz o addaki her değerin süresi yeniden ayarlanır. Yepyeni bir ad için varsayılan 3600 saniyedir.

201 Created ile kayıt nesnesini döndürür.

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

Mevcut bir kaydı günceller. Yalnızca değiştirmek istediğiniz alanları ekleyin; atlanmış alanlar mevcut değerlerini korur.

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

Güncellenmiş kayıt nesnesiyle birlikte 200 OK döndürür. Not: kayıt kimliği, kaydın adı, türü ve içeriğinden hesaplandığı için güncelleme sonrasında değişebilir.

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

Bölgeden bir kaydı siler.

Başarılı olduğunda 204 No Content döndürür.

DNSSEC

Bölgeleriniz için DNSSEC'i yönetin. Durumu görüntülemek için zones.read, etkinleştirmek veya devre dışı bırakmak için zones.write gerektirir.

GET /v1/zones/{id}/dnssec

Anahtarlar ve DS kayıtları dahil bir bölgenin DNSSEC durumunu alır.

Yanıt alanları

enabled (boolean), keys (DNSKEY kayıtları dizisi), ds_records (kayıt şirketine eklenecek DS kayıtları dizisi)

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

Bir bölge için DNSSEC'i etkinleştirir. İmzalama anahtarlarını otomatik olarak oluşturur.

Oluşturulan anahtarlar ve DS kayıtlarıyla birlikte DNSSEC durumunu döndürür.

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

Bir bölge için DNSSEC'i devre dışı bırakır. Tüm imzalama anahtarlarını kaldırır.

{"enabled": false, "keys": [], "ds_records": []} döndürür.

NS grupları

Kullanılabilir ad sunucusu gruplarını listeler. Bir bölge oluştururken grubun id değerini ns_group olarak kullanın. Bu uç noktayı geçerli herhangi bir API anahtarı okuyabilir.

GET /v1/ns-groups

Etkin ad sunucusu gruplarını listeler.

Grup başına yanıt alanları

id, name, slug

Hesap

Hesap bilgilerini görüntüleyin ve API anahtarlarını yönetin.

GET /v1/account

Abonelik ayrıntıları dahil mevcut hesap bilgilerini alır.

Yanıt alanları

Döndürülen alanlar: id (UUID), email, name, role, status, language, timezone, created_at

subscription – plan, billing_cycle, status, current_period_start, current_period_end alanlarına sahip nesne (abonelik yoksa null)

GET /v1/account/api-keys

Kimliği doğrulanmış kullanıcının tüm API anahtarlarını listeler.

Anahtar başına yanıt alanları

id, name, key_prefix (ilk 8 karakter), permissions (dizi), last_used_at, expires_at, created_at

POST /v1/account/api-keys

Yeni bir API anahtarı oluşturur.

İstek gövdesi (JSON)

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

• name (zorunlu) – okunabilir ad (en fazla 255 karakter)
• permissions (zorunlu) – izinler dizisi (en az bir tane gerekli): zones.read, zones.write, records.read, records.write, webhooks.read, webhooks.write
• expires_at – isteğe bağlı son kullanma tarihi (ISO 8601 veya YYYY-MM-DD); gelecekte olmalıdır

Yanıt, key alanında tam API anahtarını içerir. Tam anahtar yalnızca bu kez döndürülür. Güvenli bir şekilde saklayın.

Tam key değeri dahil anahtar ayrıntılarıyla birlikte 201 Created döndürür.

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

Bir API anahtarını iptal eder (kalıcı olarak siler).

Başarılı olduğunda 204 No Content döndürür.

Faturalama

Abonelik, planlar ve faturaları görüntüleyin. Bu uç noktalar salt okunurdur.

GET /v1/billing/subscription

Mevcut abonelik ayrıntılarını alır. Aktif abonelik yoksa null döndürür.

Yanıt alanları

Döndürülen alanlar: id, plan, billing_cycle, status, current_period_start, current_period_end, created_at

GET /v1/billing/plans

Fiyatlandırma ve özelliklerle birlikte tüm mevcut planları listeler.

Plan başına yanıt alanları

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

GET /v1/billing/invoices

Kimliği doğrulanmış kullanıcının faturalarını listeler, en yeniler önce.

Sorgu parametreleri

• status – duruma göre filtrele (draft, issued, sent, void)
• page, per_page – sayfalama

GET /v1/billing/invoices/{id}

Bir faturayı <code>id</code> değeriyle alır.

Yanıt alanları

Döndürülen alanlar: id, number, status, amount (vergi dahil), net_amount (vergi hariç), tax_amount, tax_rate, currency, issued_at, created_at. Parasal değerler düz ondalık dizelerdir.

Webhooks

Bölge ve kayıt değişiklikleri hakkında gerçek zamanlı bildirim almak için giden webhook aboneliklerini yönetin. Okuma için webhooks.read, oluşturma, değiştirme veya silme için webhooks.write gerektirir.

GET /v1/webhooks

Kimliği doğrulanmış kullanıcının tüm webhook aboneliklerini listeler.

Webhook başına yanıt alanları

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

POST /v1/webhooks

Bir webhook aboneliği oluşturur.

İstek gövdesi (JSON)

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

• url (zorunlu) – olay verilerini alacak HTTPS uç noktası
• events (zorunlu) – abone olunacak olay türleri dizisi
• description – isteğe bağlı okunabilir etiket

Yanıt, webhook imzalarını (HMAC) doğrulamak için bir secret içerir. Secret yalnızca bu sefer döndürülür. Güvenli bir yerde saklayın.

Webhook'un id ve secret değerleriyle 201 Created döndürür.

GET /v1/webhooks/{id}

Tek bir webhook aboneliğini en son teslimatlarıyla birlikte alır.

PUT /v1/webhooks/{id}

Bir webhook aboneliğini günceller. Yalnızca değiştirmek istediğiniz alanları ekleyin.

Güncellenmiş webhook nesnesiyle 200 OK döndürür.

DELETE /v1/webhooks/{id}

Bir webhook aboneliğini siler.

Başarılı olduğunda 204 No Content döndürür.

POST /v1/webhooks/{id}/test

Erişilebilirliği doğrulamak için webhook uç noktasına bir test olayı gönderir.

"type": "test" verisiyle bir test teslimatını kuyruğa alır.

Teslimatı doğrulama

Her teslimat, webhook oluşturulduğunda döndürülen gizli anahtarla imzalanır ve dört başlık taşır:

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

Gizli anahtarınızla, isteğin ham gövdesi üzerinden HMAC-SHA256 değerini yeniden hesaplayın ve sha256= ifadesinden sonraki onaltılık özetle sabit zamanlı olarak karşılaştırın. Eşleşmemesi, isteğin bizden gelmediği anlamına gelir. X-NexDNS-Delivery başlığı denemeyi tanımlar; bu nedenle aynı olayın yeniden denemeleri aynı olay id değerini paylaşır, ancak teslimat numarasını paylaşmaz.

Teslimat verisi

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

Kullanılabilir olay türleri

Bu olay türlerinin herhangi bir kombinasyonuna abone olabilirsiniz:

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

Hata kodları

Tüm hatalar, bir hata code dizesi ve okunabilir bir message ile tutarlı bir format izler.

Kod örnekleri

Tüm örnekler curl kullanır. nxd_your_api_key yerine gerçek API anahtarınızı yazın.

Bölgelerinizi listeleyin

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

Bölge oluşturun

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

A kaydı ekleyin

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

MX kaydı ekleyin

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

Kaydı güncelleyin

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

Kaydı silin

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

Bölgeyi dışa aktarın (BIND formatı)

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

DNSSEC'i etkinleştirin

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

API anahtarı oluşturun

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

Hesap bilgilerini alın

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