REST API

在「设置 → API 密钥」中创建密钥。明文密钥只显示一次，之后无法找回；系统仅以可读形式保存它的前缀。每次请求都需将它作为 bearer 令牌发送。

curl https://api.namesight.app/v1/usage \
  -H "Authorization: Bearer ns_live_..."

每个密钥都带有一组作用域。若请求需要该密钥不具备的作用域，会被拒绝并返回 403，因此你交给只读集成使用的密钥无法发起付费扫描。

每一次扫描都以积分计费，无论从这里还是网页应用发起。费用是所运行模块的总和：五个默认模块共 100 积分，少选一个即更便宜。套餐每月发放积分，未用完的可结转。

扣费发生在任何任务入队之前，因此无法付费的扫描永远不会运行，也不会留下任何记录。如果扣费后入队失败，积分会自动退回。

• 余额不足 → 429，并在 problem 响应体中说明缺口
• 套餐不含 API 访问权限 → 402，并附升级链接
• 工作区已关闭积分消费 → 403

POST /v1/scans 会将扫描入队并立即返回 202。扫描是异步的：响应携带的是 scanId，而不是结果。

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 }

轮询 GET /v1/scans/{id}，直到 status 变为 completed 或 completed_partial。一次典型扫描在一分钟内完成；建议每秒轮询一次，并随着等待逐步拉长间隔，以免长时间扫描耗尽你的速率限额。

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

checks 中的每一条都是一个来源针对一个目标给出的回答，包含各自的判定结果、读取时所用的 sourceUrl 以及 fetchedAt 时间戳。summary 对象在扫描结束后出现，携带评分、风险等级和商标统计。

四个查询端点说明了扫描请求可以包含哪些内容。它们需要 reference:read 作用域，且完全免费。

错误以 RFC 9457 problem 文档的形式返回，内容类型为 application/problem+json。type 字段标识失败类型，detail 进行说明，部分错误还会附带 upgradeUrl 等额外字段。

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

速率限制按密钥在一分钟的滑动窗口内计数，并在每个响应中回报，因此你可以在被拒绝之前主动降速。

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

除了发起和读取检测，密钥还可以重新运行检测、重试未能回答的来源、删除检测、分享报告、列出工作区的项目并生成名称创意。每项操作都需要所示的权限范围。

安全重试：随 POST /v1/scans 或 rescan 发送 Idempotency-Key 头（任意唯一字符串）。24 小时内携带同一密钥的重试会重放第一次的响应（响应带 Idempotent-Replayed: true），而不是发起并扣费第二次检测。同一密钥配不同请求体会被 409 拒绝。

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

无需轮询的等待：GET /v1/scans/{id}?wait=60000 会保持请求直到检测完成或等待到期（最多 60 秒），然后返回当前状态的检测。一次请求、一个限速名额、无循环。

分页：GET /v1/scans 返回 items 与 nextCursor。把 nextCursor 作为 cursor 传回即可取下一页；null 表示最后一页。status 按一个或多个以逗号分隔的状态过滤。

无需轮询：注册一个 https 端点，检测完成时即可收到带签名的 POST。端点在设置 → API 中管理，或通过带 webhooks:manage 范围的 /v1/webhooks 管理；每个工作区最多十个。签名密钥仅在创建和轮换时显示一次。

每次投递携带四个头：x-namesight-event、x-namesight-delivery（每次重试都是同一 id，便于去重）、x-namesight-timestamp（unix 秒）和 x-namesight-signature。签名为 v1= 加上用你的密钥对 "<timestamp>.<原始请求体>" 计算的十六进制 HMAC-SHA256。请针对原始请求体验证，并拒绝超过五分钟的时间戳。

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
});

十秒内返回任意 2xx，之后再处理。其他响应会再重试四次：30 秒、2 分钟、10 分钟和 60 分钟后。连续十次全部尝试失败的投递会停用端点；重新启用会清零计数。测试按钮会发送带 test: true 的模拟 scan.completed。

完整的机器可读描述由 /v1/openapi.json 提供。它无需认证，因此你在拿到密钥之前就可以据此生成客户端。