文档

网站基于一个公开 API 构建，含十八个即时端点。下方逐一文档化：功能、限制与请求/响应示例。无需账号；即时结果不存储。本页末尾的管理 API（在线监控、状态页、短链接）是有状态例外：它们以各自的管理密钥持久保存。

状态码

301 — 永久重定向
永久重定向。搜索引擎会将排名信号转移到目标地址。
302 — 临时重定向
临时重定向。原 URL 仍是规范地址。
307 — 临时重定向
保留请求方法和请求体的临时重定向。
308 — 永久重定向
保留请求方法和请求体的永久重定向。
200 — 成功
到达最终目的地。链条在此结束。
404 — 客户端错误
目标不存在 —— 一个失效的重定向目标。
500 — 服务器错误
目标已解析，但服务器未能正确响应。

分类结果，而非错误

在四个即时端点上，被阻止的目标、无法解析的域名和无效 URL 都不是错误：每个格式正确的请求都返回 HTTP 200 和分类结果的 status。只有格式错误的请求、过大的请求体和限流才产生错误响应。

通用限制

协议: http, https
方法: GET
频率限制: 每 IP 每分钟 30 次请求、每天 500 次 —— 所有端点共享
请求体: 最大 10 KiB，严格 JSON

服务目录与社区报告（Phase 14）

精选的公开热门在线服务目录，附匿名社区报告。读取公开且带缓存；报告 POST 是有状态的例外——它会持久化并带频率限制、去重与审核。社区信号与自动检测始终是独立指标；本 API 中的任何取值都不表示「确认宕机」。

GET /api/v1/catalog/services?sort=reports_24h&page=1&page_size=20
→ 200
{ "items": [ { "slug": "chatgpt", "name": "ChatGPT",
               "category": { "slug": "ai-assistants", "name": "AI Assistants" },
               "community": { "signal": "reports_increasing", "reports_15m": 3,
                              "reports_1h": 11, "reports_24h": 42,
                              "last_report_at": "2026-10-20T09:58:12Z" },
               "automated_check": { "state": "operational",
                                    "checked_at": "2026-10-20T09:55:00Z" } } ],
  "page": 1, "page_size": 20, "total": 1 }

POST /api/v1/catalog/services/chatgpt/reports
{ "problem_type": "site_unreachable", "comment": "Login loop on mobile" }
→ 201
{ "service_slug": "chatgpt", "problem_type": "site_unreachable",
  "comment": "Login loop on mobile", "created_at": "2026-10-20T10:01:33Z" }

Reads are public and cached (ETag + max-age=30); unknown/draft/hidden
slugs all answer 404 (no existence oracle); merged slugs 301 to the
target. Reports are anonymous: no account, no network fetch on
submission, rate limited per IP, comments plain text (≤500 chars).
Community signal and the automated check are always separate blocks —
no value on this API means "confirmed down".

分页: page ≥1，page_size 默认 20，最大 100；确定性排序（以 slug 决胜）
报告限制: 每 IP 每服务 10 分钟去重 1 条，然后每 IP 每小时 10 条、每天 30 条；429 + Retry-After；fail-closed
审核与隐私: auto-publish 或 hold-all 策略；终止开关；仅存储每日轮换的伪匿名哈希——绝不存储原始 IP 或 user-agent

Redirect Checker — POST /api/v1/check

跟随完整重定向链并存储结果。

POST /api/v1/check
Content-Type: application/json

{ "url": "https://bit.ly/example" }

{
  "id": "9pr2kxq4",
  "status": "completed",
  "input_url": "https://bit.ly/example",
  "final_url": "https://example.com/product",
  "final_domain": "example.com",
  "final_status": 200,
  "redirect_count": 3,
  "duration_ms": 482,
  "redirects": [
    { "sequence": 0, "requested_url": "https://bit.ly/example",
      "status_code": 301, "next_url": "https://tracker.example/click",
      "duration_ms": 83 },
    { "sequence": 3, "requested_url": "https://example.com/product",
      "status_code": 200, "duration_ms": 184 }
  ],
  "errors": null
}

GET /api/v1/check/{id} —— 通过公开 ID 获取已保存的结果。

最大重定向次数: 20 跳
请求超时: 15 秒

GET /api/v1/check/{id} —— 通过公开 ID 获取已保存的结果。

Uptime Checker — POST /api/v1/uptime-check

检查网站是否有响应。结果会分类：正常响应为 UP，返回 4xx/5xx 为 HTTP_ERROR，另有 TIMEOUT、DNS_ERROR、TLS_ERROR、CONNECTION_ERROR 和 BLOCKED_TARGET。

POST /api/v1/uptime-check
Content-Type: application/json

{ "url": "https://example.com" }

{
  "url": "https://example.com",
  "status": "UP",
  "reachable": true,
  "httpStatus": 200,
  "httpStatusText": "OK",
  "responseTimeMs": 184,
  "finalUrl": "https://example.com/",
  "redirectCount": 1,
  "tls": { "enabled": true, "valid": true }
}

最大重定向次数: 10 跳
请求超时: 10 秒

HTTP Status Checker — POST /api/v1/http-status-check

返回 URL 的最终状态码、最终响应头、重定向链摘要和 TLS 状态。

POST /api/v1/http-status-check
Content-Type: application/json

{ "url": "https://example.com" }

{
  "url": "https://example.com",
  "status": "UP",
  "reachable": true,
  "httpStatus": 200,
  "httpStatusText": "OK",
  "finalUrl": "https://example.com/",
  "redirectCount": 1,
  "headers": {
    "Content-Type": ["text/html; charset=utf-8"],
    "Server": ["nginx"]
  },
  "headers_analysis": {
    "security_missing": ["Strict-Transport-Security", "Content-Security-Policy"],
    "caching": { "Cache-Control": "max-age=604800" }
  },
  "tls": { "enabled": true, "valid": true }
}

最大重定向次数: 10 跳
请求超时: 10 秒

Response Time Checker — POST /api/v1/response-time-check

对同一 URL 进行 1–5 次测量，并按最终 URL 的首字节时间中位数判定速度等级。返回每次测量的耗时、最小/中位/最大/平均值以及最后一跳的耗时分解。

POST /api/v1/response-time-check
Content-Type: application/json

{ "url": "https://example.com", "samples": 3 }

{
  "url": "https://example.com",
  "samples": 3,
  "status": "UP",
  "verdict": "FAST",
  "completed": 3,
  "timesMs": [184, 201, 176],
  "stats": { "minMs": 176, "medianMs": 184, "maxMs": 201, "meanMs": 187 },
  "breakdown": { "dnsMs": 12, "connectMs": 23, "tlsMs": 45, "ttfbMs": 184, "totalMs": 190 },
  "httpStatus": 200,
  "httpStatusText": "OK",
  "finalUrl": "https://example.com/",
  "redirectCount": 1,
  "tls": { "enabled": true, "valid": true }
}

采样次数: 1–5（默认 3）
单次采样超时: 10 秒
总时限: 30 秒

SSL Checker — POST /api/v1/ssl-check

检查主机出示的 TLS 证书：有效期、签发者、SAN、协商的协议与密码套件以及证书链。仅进行 TLS 探测——绝不抓取页面；证书异常时会给出具体原因。

POST /api/v1/ssl-check
Content-Type: application/json

{ "url": "https://example.com" }

{
  "url": "https://example.com",
  "host": "example.com",
  "status": "UP",
  "reachable": true,
  "handshakeMs": 45,
  "tls": {
    "version": "TLS 1.3",
    "cipher": "TLS_AES_256_GCM_SHA384",
    "verified": true,
    "status": "valid",
    "daysRemaining": 89,
    "notBefore": "2026-08-01T00:00:00Z",
    "notAfter": "2026-10-30T00:00:00Z",
    "subject": "CN=example.com",
    "issuer": "CN=R3,O=Let's Encrypt,C=US",
    "sans": ["example.com", "www.example.com"],
    "chain": ["CN=example.com", "CN=R3,O=Let's Encrypt,C=US"]
  }
}

端口: 取自 URL（默认 443）
探测超时: 10 秒

DNS Checker — POST /api/v1/dns-check

查询主机的 A、AAAA、CNAME、MX、TXT 和 NS 记录。仅查询和报告：不建立任何连接，每个解析出的地址都会标注为公开或非公开。

POST /api/v1/dns-check
Content-Type: application/json

{ "url": "example.com" }

{
  "url": "example.com",
  "host": "example.com",
  "status": "UP",
  "durationMs": 38,
  "records": {
    "a": ["93.184.216.34"],
    "aaaa": ["2606:2800:220:1:248:1893:25c8:1946"],
    "cname": [],
    "mx": [{ "host": "mail.example.com", "pref": 10 }],
    "txt": ["v=spf1 include:_spf.example.com ~all"],
    "ns": ["ns1.example.com", "ns2.example.com"]
  },
  "addressLabels": [
    { "address": "93.184.216.34", "classification": "public", "reason": "public" }
  ]
}

记录类型: A、AAAA、CNAME、MX、TXT、NS
查询超时: 总计 10 秒，每类 3 秒

域名到期检查 — POST /api/v1/domain-expiry-check

通过固定的 rdap.org RDAP 流程回答域名何时到期：结论、剩余天数、注册/到期日期和注册局状态。本仓库第一个访问固定第三方服务的工具：每一跳仅限 HTTPS、无代理、重定向与大小受限；被查询的域名绝不被联系。404 转为 not_found 结论（未注册 / 注册局无 RDAP / 未发布记录），429 和 5xx 转为诚实的 UNKNOWN_ERROR。

POST /api/v1/domain-expiry-check
Content-Type: application/json

{ "url": "example.com" }

{
  "url": "example.com",
  "host": "example.com",
  "status": "UP",
  "verdict": "ok",
  "daysRemaining": 214,
  "registration": "2019-01-15T05:00:00Z",
  "expiration": "2027-04-15T04:00:00Z",
  "lastChanged": "2026-08-01T11:20:00Z",
  "registryStatuses": ["ok"],
  "source": "rdap",
  "durationMs": 420
}

结论: ok、expiring（≤30 天）、expired、not_found、unknown
查询超时: 总共 10 秒（DOMAIN_EXPIRY_TIMEOUT）
出站策略: 仅 rdap.org；每一跳 HTTPS；禁用代理；重定向上限 10；大小上限 1 MiB；绝不联系被查询的域名

WHOIS 查询 — POST /api/v1/whois-check

回答注册局对域名知道什么：注册商、域名服务器、日期和状态标志。优先通过 rdap.org 的 RDAP，区域未发布时回退经典 WHOIS（原始 TCP 43）——仓库第一个原始 TCP 出站工具：每个转介必须是 host[:43] 目标，经共享 SSRF 管道解析并拨号到固定的公网地址；转介上限 2，响应上限 64 KiB；绝不联系被查询的域名。RDAP 的 404 触发回退；明确的“域名不存在”回答以 notFound 呈现。

POST /api/v1/whois-check
Content-Type: application/json

{ "url": "mail.ru" }

{
  "url": "mail.ru",
  "host": "mail.ru",
  "status": "UP",
  "source": "whois",
  "registrar": "VK-TECH",
  "nameservers": ["ns1.mail.ru", "ns2.mail.ru"],
  "registration": "1997-10-01T00:00:00Z",
  "expiration": "2026-10-01T00:00:00Z",
  "statuses": ["REGISTERED, DELEGATED, VERIFIED"],
  "durationMs": 640
}

来源: RDAP 经 rdap.org；经典 WHOIS（TCP 43）经 whois.iana.org 转介链
查询超时: 总共 15 秒（WHOIS_TIMEOUT）
出站策略: 转介仅限 host[:43]；拨号前经 SSRF 校验并固定地址；转介上限 2；响应上限 64 KiB；绝不联系被查询的域名

域名可用性 — POST /api/v1/domain-availability

按 TLD 回答“这个名字能否注册”，采用诚实状态机：仅当 RDAP 查询返回 404 且内置 TLD 元数据确认注册局运营 RDAP 时才为 AVAILABLE；仅 WHOIS 未找到保持 UNKNOWN（可能可用）；RESTRICTED 由元数据决定。完整支持 IDN（输入 Unicode，规范 punycode，输出 displayDomain），可选多 TLD 批量查询（每次 1–10 个）。MVP 中 premium 恒为 unknown——定价属于未来的独立子系统。

POST /api/v1/domain-availability
Content-Type: application/json

{ "domain": "пример.рф", "tlds": ["com", "io"] }

{
  "url": "пример.рф",
  "displayDomain": "пример.рф",
  "host": "xn--e1afmkfd.xn--p1ai",
  "status": "UP",
  "results": [
    {
      "tld": "com",
      "availability": "AVAILABLE",
      "reason": "rdap_not_found",
      "confidence": "high",
      "source": "rdap",
      "premium": "unknown",
      "checkedAt": "2026-09-03T12:00:02Z"
    },
    {
      "tld": "io",
      "availability": "UNKNOWN",
      "reason": "tld_rdap_unknown",
      "confidence": "low",
      "source": "tld-metadata",
      "premium": "unknown",
      "checkedAt": "2026-09-03T12:00:02Z"
    }
  ],
  "tldMetaVersion": "2026-09-02",
  "durationMs": 1240
}

每次请求的 TLD: 1–10 个唯一值（Unicode 或 punycode）；同一 15 秒预算内最多 4 个并发查询（DOMAIN_AVAILABILITY_TIMEOUT）
判定: AVAILABLE | REGISTERED | RESTRICTED | INVALID | UNKNOWN | ERROR — UNKNOWN 绝不冒充 AVAILABLE；PREMIUM 在 MVP 中不可达
缓存: di:avail 60秒、di:reg 6小时，fail-open；否定结果绝不缓存

域名年龄 — POST /api/v1/domain-age

报告域名的年龄：来自注册局的准确创建日期和确定性的年/月/日细分。WHOIS 数据之上的轻量投影——缓存窗口内一次提供方查询同时服务可用性、年龄和注册商查询。

POST /api/v1/domain-age
Content-Type: application/json

{ "domain": "example.com" }

{
  "url": "example.com",
  "host": "example.com",
  "status": "UP",
  "age": {
    "known": true,
    "createdAt": "2019-01-15T05:00:00Z",
    "ageInDays": 2809,
    "years": 7,
    "months": 7,
    "days": 20
  },
  "source": "rdap",
  "durationMs": 390
}

年龄计算: 仅使用 UTC 日历日期；通过钳位月份锚点计算完整年月；总天数向下取整
未知年龄: age.known=false + 有界原因（no_data、inconsistent_data）——绝不猜测
缓存: di:reg 6小时，与可用性/注册商共享（fail-open）

注册商查询 — POST /api/v1/domain-registrar

报告域名在哪家注册商注册，按人工维护的别名表归一化（GoDaddy、Namecheap、Cloudflare 等）——未知名称按公布内容原样显示。包含注册局组织和 RDAP/WHOIS 来源；与年龄/可用性共享注册缓存。

POST /api/v1/domain-registrar
Content-Type: application/json

{ "domain": "example.com" }

{
  "url": "example.com",
  "host": "example.com",
  "status": "UP",
  "registrar": "GoDaddy.com, LLC",
  "registrarCanonical": "GoDaddy",
  "registrarIanaId": 625,
  "registry": "Verisign, Inc.",
  "source": "rdap",
  "checkedAt": "2026-09-04T12:00:00Z",
  "durationMs": 410
}

注册商: 显示名称 + 命中时的规范别名徽标；IANA ID 显示“—”（注册局数据尚未包含）
未公布: 隐私代理或脱敏的注册以 UP + 原因 no_data 回答——绝非空壳

域名生成器 — POST /api/v1/domain-generate

从 1–3 个关键词生成候选域名：直接形式、前缀、后缀、组合词和短形式——去重、有序、有上限。纯粹即时：生成期间零注册局调用；逐个候选的可用性检查是独立明确的操作。

POST /api/v1/domain-generate
Content-Type: application/json

{ "keywords": ["coffee", "map"], "tlds": ["com", "io"], "limit": 24 }

{
  "status": "UP",
  "candidates": [
    { "domain": "coffee.com", "strategy": "direct" },
    { "domain": "coffee.io", "strategy": "direct" },
    { "domain": "getcoffee.com", "strategy": "prefix" },
    { "domain": "coffeemap.com", "strategy": "compound" }
  ],
  "total": 24
}

候选: 硬上限 50，默认展示 24；≤10 个 TLD，经 TLD 元数据快照过滤
零注册局流量: 生成过程零注册局调用——逐个候选检查走带自身限额的可用性端点

域名概览 — POST /api/v1/domain-overview

组合式档案：域名自身 TLD 的可用性、带确定性年龄细分的创建日期、注册商（已归一化，含 IANA 号码）、到期投影以及注册局的配置发现。各节相互独立——一次查询失败绝不会清空其他节。

POST /api/v1/domain-overview
Content-Type: application/json

{ "domain": "example.com" }

{
  "url": "example.com",
  "host": "example.com",
  "status": "UP",
  "availability": {
    "tld": "com", "availability": "REGISTERED", "reason": "registered",
    "confidence": "high", "source": "rdap", "premium": "unknown",
    "checkedAt": "2026-09-05T12:00:00Z"
  },
  "registration": {
    "known": true, "createdAt": "2019-01-15T05:00:00Z",
    "ageYears": 7, "ageMonths": 7, "ageDays": 21,
    "registrar": "GoDaddy.com, LLC", "registrarCanonical": "GoDaddy",
    "registrarIanaId": 625, "registry": "Verisign, Inc.", "source": "rdap",
    "checkedAt": "2026-09-05T12:00:01Z"
  },
  "expiry": {
    "host": "example.com", "source": "rdap", "verdict": "ok",
    "daysRemaining": 222, "expiration": "2027-04-15T04:00:00Z",
    "checkedAt": "2026-09-05T12:00:02Z"
  },
  "holds": [],
  "dnssec": [{ "id": "dnssec-absent", "state": "info", "severity": "info", "detail": "unsigned" }],
  "tldMetaVersion": "2026-09-02",
  "durationMs": 1620
}

分节: 可用性（元数据门控）+ 注册（di:reg，6小时共享）+ 到期（rdap.org）+ holds/dnssec 发现
发现即事实: holds/DNSSEC 是注册局的配置信号——绝非安全判定；DNS/SSL 保留在其独立工具中

安全检查 — POST /api/v1/security-check

对一次获取的响应进行被动、咨询式的配置审查：安全响应头（HSTS 深度、CSP 亮点、COOP/COEP/CORP、X-XSS-Protection）、Cookie 标志、TLS 事实、链路降级与信息披露。不探测、不作漏洞断言、不打分；Cookie 值绝不离开后端。HTTP 应用状态不影响审查（可达的 404/500 也会被审查）。

POST /api/v1/security-check
Content-Type: application/json

{ "url": "https://example.com" }

{
  "url": "https://example.com",
  "finalUrl": "https://example.com/",
  "status": "UP",
  "durationMs": 610,
  "summary": { "total": 14, "passed": 9, "warn": 3, "failed": 2 },
  "findings": [
    { "id": "hsts-present", "state": "fail", "severity": "high" },
    { "id": "tls-cert", "state": "pass", "severity": "info", "detail": "valid" }
  ],
  "cookies": [
    { "name": "session", "secure": false, "httpOnly": true, "sameSite": "Lax" }
  ],
  "tls": { "enabled": true, "version": "TLS 1.3", "certStatus": "valid", "daysRemaining": 89 }
}

范围: 约 23 项检查 ID，覆盖响应头/Cookie/TLS/链路/信息披露；仅被动获取
Cookie: 仅名称与标志（Secure/HttpOnly/SameSite）——值绝不离开后端
审查超时: 总共 10 秒（SECURITY_CHECK_TIMEOUT）

URL Analyzer — POST /api/v1/url-analyze

对单个 URL 进行纯语法解析：经脱敏的规范身份（协议、主机、IDN 形式、朴素可注册域名、端口、路径、查询、片段），保留顺序与重复项的参数列表及带版本的跟踪分类，跟踪计数，信息性安全信号与规范化说明。无请求、无 DNS、无存储——分析在本地毫秒级完成。

POST /api/v1/url-analyze
Content-Type: application/json

{ "url": "https://xn--e1afmkfd.xn--p1ai/search?q=thing&utm_source=news&id=7&id=8" }

{
  "status": "UP",
  "identity": {
    "hasCredentials": false,
    "scheme": "https",
    "host": "xn--e1afmkfd.xn--p1ai",
    "displayHost": "пример.рф",
    "registrableDomain": "пример.рф",
    "isIdn": true,
    "path": "/search",
    "query": "q=thing&utm_source=news&id=7&id=8",
    "normalized": "https://xn--e1afmkfd.xn--p1ai/search?q=thing&utm_source=news&id=7&id=8"
  },
  "parameters": [
    { "name": "q", "value": "thing", "classification": { "category": "unknown", "confidence": "none" } },
    { "name": "utm_source", "value": "news", "classification": { "category": "utm", "label": "utm_source", "confidence": "exact" } },
    { "name": "id", "value": "7", "occurrence": 1 },
    { "name": "id", "value": "8", "occurrence": 2 }
  ],
  "tracking": { "utm": 1, "analytics": 0, "adsClickId": 0, "sessionSensitive": 0, "unknown": 3 },
  "signals": ["idn_host"],
  "normalization": { "schemeAssumed": false, "punycodeApplied": true, "defaultPortOmitted": false, "hostLowercased": false },
  "registryVersion": "2026-09-1"
}

范围: 组件 + 有序参数 + 注册表分类 + 信息性信号；零网络访问
脱敏: 永不回显密码；敏感参数值在所有位置掩码为 ***，名称保持可见

URL Expander — POST /api/v1/url-expand

基于共享引擎的即时、免存储重定向链展开：每一跳都经过相同的中心化 SSRF 校验，循环与 10 跳上限以 reason 区分，最终 URL 获得完整跟踪分析。返回的 URL 均经脱敏——密码绝不离开后端。不缓存：重定向链对时间敏感，新鲜度才是正确答案。

POST /api/v1/url-expand
Content-Type: application/json

{ "url": "https://bit.ly/3xyz" }

{
  "url": "https://bit.ly/3xyz",
  "status": "UP",
  "finalUrl": "https://example.com/landing?utm_source=n",
  "hopCount": 2,
  "chain": [
    { "url": "https://bit.ly/3xyz", "status": 301, "location": "https://bit.ly/abc" },
    { "url": "https://bit.ly/abc", "status": 302, "location": "https://example.com/landing?utm_source=n" }
  ],
  "analysis": { "status": "UP", "tracking": { "utm": 1, "analytics": 0, "adsClickId": 0, "sessionSensitive": 0, "unknown": 0 } },
  "source": "engine",
  "durationMs": 820
}

范围: 脱敏的跳转链 + 分类状态（循环 vs 上限）+ 最终 URL 分析；不含逐跳 DNS/TLS/计时（Redirect Checker 的领域）
展开预算: 总计 10 秒（URL_EXPAND_TIMEOUT）；跳数上限 10

UTM Builder — POST /api/v1/utm-build

确定性的无状态营销 URL 构造：无关参数按原顺序保留，规范 UTM 按字段覆盖或保留，重复项折叠至最后一次出现，片段保留，携带凭据的目的地会被 in-band 拒绝。相同输入始终产生逐字节相同的输出。

POST /api/v1/utm-build
Content-Type: application/json

{ "url": "https://example.com/landing?foo=1&utm_source=old#pricing", "utmSource": "newsletter", "utmMedium": "email", "utmCampaign": "spring_sale", "utmContent": "header_cta" }

{
  "status": "UP",
  "generatedUrl": "https://example.com/landing?foo=1&utm_source=newsletter&utm_medium=email&utm_campaign=spring_sale&utm_content=header_cta#pricing",
  "warnings": ["existing_utm_overwritten:utm_source", "empty_field_skipped:utm_term"],
  "parameters": { "utm_source": "newsletter", "utm_medium": "email", "utm_campaign": "spring_sale", "utm_content": "header_cta" }
}

范围: 按固定顺序追加 UTM + 保留/覆盖/折叠策略 + 警告；纯本地，无网络
确定性: 相同输入产生逐字节相同的输出；字段 ≤256 字符；拒绝未知请求字段

Website Health — POST /api/v1/website-health

复合诊断：一个请求先规范化目标，再在现有引擎之上运行有界并发的 lane——一次 HTTP 检查同时供给五个板块（可用性、状态码、响应时间、响应头、安全配置），DNS、TLS 证书探测与域名概览则作为独立 lane 运行。最终给出聚合的整体健康状态、逐项检查明细以及指向独立工具的深链。结论仅描述已执行的检查——绝不构成安全保证。

POST /api/v1/website-health
Content-Type: application/json

{ "url": "https://example.com" }

{
  "target": {
    "canonical": "https://example.com/",
    "displayHost": "example.com",
    "scheme": "https",
    "hasCredentials": false,
    "isDomain": true,
    "isHttp": true,
    "valid": true
  },
  "overall": "WARNING",
  "summaryKey": "health.summary.warning",
  "checks": [
    { "type": "http_availability", "state": "pass",
      "summaryKey": "health.check.httpAvailability.pass",
      "value": "200", "durationMs": 612, "applicable": true,
      "detailUrl": "/uptime-checker" },
    { "type": "http_status", "state": "pass",
      "summaryKey": "health.check.httpStatus.pass",
      "value": "200 OK", "applicable": true,
      "detailUrl": "/http-status-checker" },
    { "type": "response_time", "state": "pass",
      "summaryKey": "health.check.responseTime.pass",
      "value": "612 ms", "applicable": true,
      "detailUrl": "/response-time-checker" },
    { "type": "headers", "state": "warn",
      "summaryKey": "health.check.headers.warn",
      "value": "2 missing", "reason": "findings", "applicable": true,
      "detailUrl": "/security-checker" },
    { "type": "security", "state": "warn",
      "summaryKey": "health.check.security.warn",
      "value": "14 of 21 passed", "reason": "findings", "applicable": true,
      "detailUrl": "/security-checker" },
    { "type": "tls", "state": "pass",
      "summaryKey": "health.check.tls.pass",
      "value": "TLS 1.3 · valid, 89 days", "durationMs": 140,
      "applicable": true, "detailUrl": "/ssl-checker" },
    { "type": "dns", "state": "pass",
      "summaryKey": "health.check.dns.pass",
      "value": "A, AAAA, MX, NS", "durationMs": 95,
      "applicable": true, "detailUrl": "/dns-checker" },
    { "type": "domain", "state": "pass",
      "summaryKey": "health.check.domain.pass",
      "value": "expires in 214 days", "durationMs": 730,
      "applicable": true, "detailUrl": "/domain-overview" }
  ],
  "meta": { "checksTotal": 8, "checksPassed": 6, "checksWarn": 2,
            "checksFailed": 0, "checksUnknown": 0,
            "tldMetaVersion": "2026-09-03", "durationMs": 1480 }
}

范围: 一次 HTTP 执行供给五个板块；DNS/TLS/域名 lane；聚合状态 HEALTHY/WARNING/ERROR/PARTIAL/UNKNOWN
边界: 25 秒总预算 + 各 lane 预算，同时最多 3 个 lane；无效目标 in-band 返回；不缓存——新鲜度优先

Uptime Monitoring — /api/v1/monitors 管理 API

与即时工具不同唯一的有状态例外：为一个 URL 创建监控项，worker 按固定计划检查它——附带执行历史、可用性统计、事故记录与 webhook 通知。所有权是创建时仅显示一次的管理密钥；每次读取和写入都用它验证，错误密钥与不存在的监控项完全无法区分（统一返回 404）。

POST /api/v1/monitors
Content-Type: application/json

{ "url": "https://example.com", "name": "Prod site", "interval": 300 }

201 Created
{
  "monitor": { "id": "b1…", "name": "Prod site",
               "normalizedTarget": "https://example.com/",
               "state": "unknown", "interval": 300 },
  "manageUrl": "/monitors/b1…?key=…",
  "key": "…shown exactly once…"
}

GET /api/v1/monitors/{id}?key=…       detail + stats window + incidents
GET /api/v1/monitors/{id}/history     cursor-paginated executions
GET /api/v1/monitors/{id}/history/daily  per-day buckets (30-day cap)
GET /api/v1/monitors/{id}/incidents   incident episodes
POST /api/v1/monitors/{id}/check      enqueue a priority manual check
PATCH /api/v1/monitors/{id}           name / interval / webhook / pause
DELETE /api/v1/monitors/{id}          cascade delete

Credentials in the target are rejected (credentials_not_allowed); the
target is SSRF-pre-validated at creation and re-validated on every run.

范围: 创建 / 列表 / 详情 / 暂停 / 删除 / 手动检查 / 历史 / 事故；固定间隔 60–3600 秒；创建时带内返回 INVALID_URL 与 BLOCKED_TARGET
密钥管理: 256 位密钥仅显示一次（存储 sha256）；拒绝目标中的凭据；创建时预校验并在每次运行前重新校验 SSRF

公开状态页 — /api/v1/status-pages 管理 API

将您的监控器组合成可分享的状态页：挑选组件、排序、覆盖显示名称，并以固定 slug 发布。状态页与监控器共用同一管理密钥；草稿私密，发布幂等且可撤销，每次变更都会删除公共缓存条目——访问控制在请求内即时生效。

POST /api/v1/status-pages
Content-Type: application/json
X-Monitor-Key: <your key>

{ "name": "Prod API" }

201 Created
{
  "page": { "publicId": "p1…", "name": "Prod API",
            "slug": "prod-api", "published": false },
  "manageUrl": "/status-pages/p1…?key=…"
}

GET  /api/v1/status-pages/{id}?key=…   editor payload (members + monitors)
PATCH /api/v1/status-pages/{id}        name/description/slug + membership
POST /api/v1/status-pages/{id}/publish      → live at /status/{slug}
POST /api/v1/status-pages/{id}/unpublish    → removed within the request
DELETE /api/v1/status-pages/{id}       cascade delete

GET /api/v1/public/status-pages/{slug}   the public DTO (no key; cached 60s)

Membership is same-key only (≤25 monitors, replace-list semantics);
publish requires ≥1 visible member; the public DTO is an explicit
projection — target URLs, keys and internal ids never cross.

范围: 创建 / 列表 / 编辑 / 成员替换列表（≤25，仅限同密钥）/ 发布 / 取消发布 / 删除；slug 为 3-63 字符并带保留字列表；每密钥最多 5 页
公开面: GET /api/v1/public/status-pages/{slug} + /status/{slug}；仅显式公开 DTO——目标 URL、密钥、通知主机与内部 id 绝不外泄；Redis 缓存 60 秒，fail-open

URL 缩短器 — /api/v1/short-links 管理 API

把长 URL 变成可管理的 /go/{code} 短链接：目标地址经过验证，代码由密码学随机生成，点击统计包含今日/7 天/30 天窗口。短链接与您的监控器和状态页共用同一个管理密钥——创建会附加到现有密钥，绝不会铸造新密钥。创建和编辑时会对目标进行验证（语法、拒绝凭据、SSRF 分类）；公开重定向本身从不抓取任何内容，并以 302 无缓存响应。

POST /api/v1/short-links
Content-Type: application/json
X-Monitor-Key: <your key>

{ "destinationUrl": "https://example.com/launch?utm_source=newsletter" }

201 Created
{
  "link": { "id": "sl1…", "code": "a3f9k2mz",
            "shortUrl": "/go/a3f9k2mz",
            "destination": "https://example.com/launch?utm_source=newsletter" }
}

GET    /api/v1/short-links?key=…              your links (newest first)
GET    /api/v1/short-links/{id}?key=…         full link + stats
PATCH  /api/v1/short-links/{id}?key=…         destination/title/expiry (re-validated)
POST   /api/v1/short-links/{id}/disable       public 404, stats kept (enable restores)
DELETE /api/v1/short-links/{id}?key=…         soft delete (idempotent)
GET    /api/v1/short-links/{id}/stats?key=…   total + today/7d/30d clicks

GET /go/a3f9k2mz   → 302 Found + Location (Cache-Control: no-store);
                     unknown/disabled/expired/deleted all answer 404.

Destinations are validated at create/update (http/https, credentials
rejected, SSRF classification); the redirect itself never fetches.

范围: 创建 / 列表 / 编辑 / 停用 / 启用 / 软删除 / 统计；每个密钥最多 100 条活跃链接，每个密钥每小时 30 次创建；每次修改都会重新验证目标地址
公开重定向: GET /go/{code} → 302 + no-store；未知/停用/过期/已删除一律返回相同的中性 404；重定向是纯查找——不接受目标参数，也从不解析或抓取目标；不存储 IP 和 user-agent

举报短链接 — 匿名滥用举报 API

如果某个 /go/{code} 链接疑似钓鱼、恶意软件、垃圾信息或诈骗，请举报——无需账号，也不会收到回复。举报进入运营者的审核队列；只有运营者能下线链接。对所有格式正确的举报，端点的响应完全一致：举报者无法得知代码是否存在。

POST /api/v1/short-link-reports
Content-Type: application/json

{ "code": "a3f9k2mz", "reason": "phishing",
  "detail": "Imitates a login page" }

202 Accepted
{ "status": "received" }

Reasons: phishing | malware | spam | scam | other (detail ≤500 chars,
optional plain text). The SAME 202 comes back for unknown, disabled
and deleted codes — no existence oracle. Limits per IP: one report
per code per 10 min, 10/hour, 30/day (429 + Retry-After; Redis
failure = 503, fail-closed). Reports go to the operator queue; only
the operator can take a link down (the owner key cannot override).

限制与隐私: 每个 IP 每个代码每 10 分钟 1 次举报，之后 10 次/小时、30 次/天（429 + Retry-After；Redis 故障时 503，fail-closed）；理由 phishing | malware | spam | scam | other；无账号、无邮箱、不存原始 IP——仅存每日轮换的指纹
统一响应: 所有格式正确的举报都得到相同的 202 received——对活跃、停用、已删除和不存在的代码一视同仁（无存在性预言）；格式错误的代码或未知理由在任何查询之前返回 400

账户与 API 密钥 — /api/v1/auth/register 和 /api/v1/api-keys

浏览器账户（邮箱 + 密码，开放注册；此版本不验证邮箱），会话保存在服务端并通过强化的 Cookie 传递。API 密钥通过资源族的显式白名单为服务器间调用提供身份验证。登录失败是通用的——未知邮箱与错误密码完全无法区分，连响应时序也一样。

POST /api/v1/auth/register
Content-Type: application/json

{ "email": "you@example.com", "password": "…", "displayName": "…" }

201 Created + Set-Cookie: wg_session (HttpOnly; Secure; SameSite=Lax)
{ "account": { "id": "acc…", "email": "you@example.com", … } }

POST /api/v1/auth/login     200 + Set-Cookie (401 generic on failure)
POST /api/v1/auth/logout    deletes the server-side session
GET  /api/v1/account        the session's own profile
PATCH /api/v1/account       update display name (displayName)
GET  /api/v1/account/summary  account-owned resource counts
POST /api/v1/account/claim  management key → re-own key-held resources

POST /api/v1/api-keys               (SESSION) create; secret shown ONCE
{ "name": "CI", "scopes": ["monitors:read"] }
GET  /api/v1/api-keys               (SESSION) list — no secrets
POST /api/v1/api-keys/{id}/revoke   (SESSION) immediate 401 on next use

Bearer access (Authorization: Bearer wg_live_…) is an EXPLICIT
allowlist only: account GET/PATCH, monitors CRUD + reads, status-pages
GET, short-links CRUD + stats; everything else refuses API keys.
Missing/unknown/revoked → generic 401; wrong scope → 403; per-key and
per-account rate limits → 429 + Retry-After.

Bearer 白名单: account GET/PATCH（account:read）、监控（读/写）、状态页 GET（读）、短链接（读/写）；其余端点一律拒绝 API 密钥。未通过 claim-by-key 关联的密钥资源不可见。
密钥处理: 完整的 wg_live_ 密钥只在创建时显示一次；服务端仅存储单向哈希。缺失/未知/已吊销的密钥统一返回 401；范围不足 → 403；限流 → 429 + Retry-After。

账号邮箱身份（确认与恢复）

Phase J 邮箱基础：确认地址、找回密码，并为敏感操作证明近期知晓密码。

POST /api/v1/auth/verification/request     (SESSION) 202 {accepted:true}
POST /api/v1/auth/verification/confirm     { "token": "…" } → 200 {verified:true}
POST /api/v1/auth/password-reset/request   { "email": "you@example.com" } → 202 (always the same answer)
POST /api/v1/auth/password-reset/confirm   { "token": "…", "password": "…" } → 200 {reset:true}
POST /api/v1/auth/reauthenticate           (SESSION) { "password": "…" } → 200 {confirmed:true}

Reset revokes ALL sessions in the same transaction; API keys stay
active. Tokens ride mail links as URL fragments — never query strings —
and every mismatch (wrong account, replay, expiry, unknown) answers the
same generic 404.

令牌: 一次性，24 小时（确认）/ 30 分钟（重置），仅存于片段，任何不匹配均返回相同的 404
重置: 原子式注销所有会话；API 密钥保持有效
重新认证: 5 分钟，服务端绑定会话
工作空间: GET /api/v1/workspaces — 个人 + 组织成员身份，no-store，仅限会话
组织: 创建/列表/读取/重命名/删除 + 所有权转移；需验证会话、乐观版本控制，破坏性操作需重新认证
邀请: 电子邮件邀请，含 7 天一次性链接、四个固定角色、预留席位的上限及必需的频率窗口
组织资源: /organizations/{orgId} 下的共享监控/页面/链接；会话 RBAC、带版本的变更、SQL 层排除旧密钥
资源转移: 将个人监控/页面/链接原子式移入组织（闭包 ≤100、版本校验、幂等）
组织密钥: 组织服务密钥（wg_live_…），仅显示一次、带范围、创建者离开后仍然有效、吊销即时生效
组织审计: 已提交组织变更的只追加历史（365 天），Owner/Admin 可读，参与者最少披露