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.namesight.app/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.

Her tarama krediyle ödenir; ister buradan ister arayüzden başlatın. Taramanın fiyatı çalıştırdığı modüllerin toplamıdır: beş varsayılan modülle 100 kredi, bir modülü dışarıda bırakınca daha az. Planınız her ay kredi verir; harcanmayan kredi devreder.

Ü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.namesight.app/v1/scans \
  -H "Authorization: Bearer ns_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lumina labs",
    "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.namesight.app/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://namesight.app/errors/quota-exceeded",
  "title": "Quota exceeded",
  "status": 429,
  "detail": "Not enough credits (balance 0, need 100). Top up or switch off a module 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

Bir anahtar taramayı başlatıp okumanın ötesinde yeniden çalıştırabilir, cevap veremeyen kaynakları yeniden deneyebilir, silebilir, raporunu paylaşabilir, çalışma alanının projelerini listeleyebilir ve isim fikri üretebilir. Her biri gösterilen kapsamı ister.

Güvenli yeniden deneme: POST /v1/scans ya da rescan ile birlikte Idempotency-Key başlığı (herhangi benzersiz bir dize) gönderin. Aynı anahtarla 24 saat içinde gelen tekrar, ikinci bir tarama başlatıp ücret almak yerine ilk cevabı yineler; yanıtta Idempotent-Replayed: true görünür. Aynı anahtar farklı gövdeyle 409 ile reddedilir.

curl -X POST https://api.namesight.app/v1/scans \
  -H "Authorization: Bearer ns_live_..." \
  -H "Idempotency-Key: 4f7c2c1e-order-1187" \
  -H "Content-Type: application/json" \
  -d '{"name":"Lumina Labs","modules":["trademark","domain"]}'

Polling'siz bekleme: GET /v1/scans/{id}?wait=60000 isteği tarama bitene ya da süre (en çok 60 saniye) dolana kadar tutar, sonra taramayı olduğu haliyle döner. Tek istek, tek hız limiti hakkı, döngü yok.

Sayfalama: GET /v1/scans items ve nextCursor döner. Sonraki sayfa için nextCursor'ı cursor olarak geri gönderin; null son sayfadır. status virgülle ayrılmış bir ya da daha çok duruma göre süzer.

Yoklamak yerine bir https ucu kaydedin ve tarama bitince imzalı bir POST alın. Uçlar Ayarlar → API altından ya da webhooks:manage kapsamıyla /v1/webhooks üzerinden yönetilir; bir çalışma alanı on uç tutabilir. İmza gizli anahtarı oluşturma ve yenileme sırasında bir kez gösterilir.

Her teslimat dört başlık taşır: x-namesight-event, x-namesight-delivery (her yeniden denemede aynı id; tekilleştirme için), x-namesight-timestamp (unix saniye) ve x-namesight-signature. İmza, v1= ve ardından gizli anahtarınızla "<timestamp>.<ham gövde>" üzerinden alınan hex HMAC-SHA256'dır. Ham istek gövdesine karşı doğrulayın; beş dakikadan eski zaman damgalarını reddedin.

import { createHmac, timingSafeEqual } from "node:crypto";

// Express-style handler; keep the RAW body — a re-serialised JSON will not match.
app.post("/hooks/namesight", express.raw({ type: "*/*" }), (req, res) => {
  const ts = req.header("x-namesight-timestamp");
  const sig = req.header("x-namesight-signature");            // "v1=<hex>"
  const body = req.body.toString("utf8");
  const expected = "v1=" + createHmac("sha256", process.env.NAMESIGHT_WEBHOOK_SECRET)
    .update(`${ts}.${body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  if (!fresh || expected.length !== sig.length || !timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
    return res.status(401).end();
  }
  const event = JSON.parse(body);                              // { id, event, createdAt, test, data }
  res.status(202).end();                                       // ack first, work later
  if (!event.test) handleScanCompleted(event.data);            // data.scanId, data.status, data.score, data.url
});

On saniye içinde herhangi bir 2xx dönün, işi sonra yapın. Diğer her yanıt 30 saniye, 2, 10 ve 60 dakika sonra dört kez daha denenir. Her denemesi başarısız olan on ardışık teslimat ucu kapatır; yeniden açmak sayacı sıfırlar. Test düğmesi test: true işaretli yapay bir scan.completed gönderir.

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.