REST API

Anahtarı Ayarlar → API anahtarları altından oluşturun. Düz metin anahtar yalnız bir kez gösterilir ve sonradan geri alınamaz; okunabilir biçimde saklanan tek şey ön ekidir. Her istekte bearer token olarak gönderin.

curl https://api.namescope.dev/v1/usage \
  -H "Authorization: Bearer ns_live_..."

Her anahtar bir kapsam kümesi taşır. Anahtarda olmayan bir kapsamı gerektiren istek 403 ile reddedilir; böylece salt okuma yapan bir entegrasyona verdiğiniz anahtar ücretli tarama başlatamaz.

API taramaları krediyle ödenir: bir tarama 100 kredidir. Arayüzden başlattığınız taramalar farklıdır — aylık plan kotanızı kullanır ve bakiyeye hiç dokunmaz.

Ücret, iş kuyruğa girmeden önce yazılır; böylece ödenemeyecek bir tarama hiç çalışmaz ve geride satır bırakmaz. Ücret alındıktan sonra kuyruğa alma başarısız olursa krediler otomatik iade edilir.

• Bakiye yetersiz → 429; gövdede eksik miktar yazar
• API içermeyen plan → 402 ve yükseltme bağlantısı
• Çalışma alanında kredi harcaması kapalı → 403

POST /v1/scans taramayı kuyruğa alır ve hemen 202 döner. Tarama eşzamansızdır: yanıt sonucu değil, bir scanId taşır.

curl -X POST https://api.namescope.dev/v1/scans \
  -H "Authorization: Bearer ns_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "tion studios",
    "regions": ["TR", "EM", "US"],
    "niceClasses": [9, 41],
    "tlds": ["com", "io"],
    "modules": ["trademark", "domain", "social"]
  }'

{ "scanId": "scn_...", "totalJobs": 12, "creditsSpent": 100, "balance": 1900 }

status alanı completed ya da completed_partial olana kadar GET /v1/scans/{id} yoklayın. Tipik bir tarama bir dakikanın altında biter; saniyede bir yoklayıp aralığı kademeli genişletin, böylece uzun bir tarama hız limitinizi yemez.

curl https://api.namescope.dev/v1/scans/scn_... \
  -H "Authorization: Bearer ns_live_..."

checks içindeki her kayıt, bir kaynağın bir hedef hakkındaki cevabıdır: kendi verdikti, okunduğu sourceUrl ve fetchedAt zaman damgasıyla. summary nesnesi tarama bitince görünür; skoru, risk bandını ve marka sayımını taşır.

Dört referans ucu, bir tarama isteğinin neler içerebileceğini anlatır. reference:read kapsamını ister, ücretsizdir.

Hatalar application/problem+json olarak gönderilen RFC 9457 belgeleridir. type alanı hatayı tanımlar, detail açıklar; bazıları upgradeUrl gibi ek alanlar taşır.

{
  "type": "https://namescope.dev/errors/quota-exceeded",
  "title": "Quota exceeded",
  "status": 429,
  "detail": "Not enough API credits (balance 0, need 100). Top up to continue."
}

Hız limitleri anahtar başına kayan bir dakika içinde sayılır ve her yanıtta bildirilir; böylece reddedilmeden önce geri çekilebilirsiniz.

x-ratelimit-limit: 60
x-ratelimit-remaining: 58
x-ratelimit-reset: 41

Makine tarafından okunabilir tam tanım /v1/openapi.json adresinde sunulur. Kimlik doğrulama istemez, yani anahtarınız olmadan da ondan istemci üretebilirsiniz.