REST API

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

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

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

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

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

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

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

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 }

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

curl https://api.namescope.dev/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://namescope.dev/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

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