跳到主要内容
ecdsa.com

更新日志

公开 API 的变更，按时间倒序排列。API 的版本号体现在路径中；如有不兼容的变更，将以 /api/v2 发布——v1 的响应可能会新增字段和错误码，但不会删除或修改已有的字段和错误码。

  1. 随 API 密钥推出

    尚未发布

    已合并，尚未发布：这些变更将在 API 密钥随 ecdsa.com 账号一同推出时上线。不带密钥的调用将完全保持现状。

    • 变更

      格式正确但未知、已吊销或已过期的密钥会被拒绝，返回 401 unauthorized 和 WWW-Authenticate 质询，而不再按匿名调用处理。

      错误码：unauthorized

      HTTP 头：WWW-Authenticate

    • 新增

      403 forbidden_scope：密钥有效，但缺少操作所需的范围；错误消息会指出缺少的范围。调用会在消耗任何速率限制额度或配额之前被拒绝。

      错误码：forbidden_scope

    • 新增

      429 quota_exceeded：密钥所属账号的每日或每月配额已用完。Retry-After 给出的等待时间持续到配额重置为止；SDK 从不重试这个错误。

      错误码：quota_exceeded

    • 新增

      对携带密钥的调用，每个响应都会在响应头中给出最先耗尽的那项配额；浏览器也可以读取这些响应头。

      HTTP 头：X-Quota-LimitX-Quota-RemainingX-Quota-Reset

    • 新增

      503 service_unavailable：目前无法验证密钥。携带密钥的调用绝不会被当作匿名调用处理——请稍后重试。

      错误码：service_unavailable

    • 变更

      携带密钥的调用改为按密钥而不是按 IP 限制：免费版每分钟 120 次，专业版每分钟 600 次。测试密钥始终使用免费版的限额。

      错误码：rate_limited

    • 变更

      API 索引中的 auth 字段不再写“no API keys”，而是说明密钥是可选的、使用密钥会带来哪些变化，以及哪些操作需要密钥。

      操作：GET /v1

    • 新增

      Webhook：/api/v1/webhooks 用于列出（GET）和创建（POST）密钥所属账号的端点，/api/v1/webhooks/delete 用于删除端点，/api/v1/webhooks/test 用于发送测试事件。这些操作需要具有 webhooks 范围的密钥，并且只通过 REST 提供——不作为 MCP 工具提供，SDK 中也没有。

      操作：GET /v1/webhooksPOST /v1/webhooksPOST /v1/webhooks/deletePOST /v1/webhooks/test

    • 新增

      每次投递都使用 ECDSA P-256 签名：ECDSA-Signature 携带时间戳、密钥 ID 和签名，公钥是 /.well-known/ecdsa-webhook-keys.json 上的 JWKS——轮换期间两个密钥 ID 会同时有效。每个 SDK 都用 verifyWebhook() 验证投递。

    • 新增

      Webhook 新增的错误码：webhook_url_refused（400）、webhook_limit_reached（403）、webhook_not_found（404）和 webhooks_unavailable（503）。

      错误码：webhook_url_refusedwebhook_limit_reachedwebhook_not_foundwebhooks_unavailable

  2. v1.1.0

    发布于2026年10月22日

    API 核心改为基于声明式操作重建，对域名的扫描现在按被检测的主机共享额度。对现有客户端而言只有新增：每个 v1.0 请求都会得到相同的状态码和相同的响应体，外加新字段。这些变更大多自 2026-10-20 起已经上线；从这个版本开始，API 索引报告的版本号为 1.1.0。

    • 新增

      对域名的实际扫描会消耗所有客户端共享的额度：同一主机每 10 分钟最多 6 次，所有扫描合计每分钟最多 300 次。超出额度的扫描会收到 429 rate_limited 和 Retry-After；来自一小时缓存的响应不消耗额度。

      错误码：rate_limited

      操作：GET /v1/health/{domain}

    • 新增

      错误响应体新增 requestId——报告问题时请附上它——以及指向错误码说明的链接 docs。code 和 message 保持不变。

      字段：error.requestIderror.docs

    • 新增

      每个响应都带有 X-Request-Id。你也可以自己发送这个请求头（1～128 个字母、数字、点、下划线、冒号或连字符）来关联请求：服务器会原样返回。

      HTTP 头：X-Request-Id

    • 变更

      未知路径返回 404 not_found，错误的方法返回 405 method_not_allowed 并附带 Allow 响应头——返回的是带 CORS 的 JSON 信封，而不是 HTML 页面。

      错误码：not_foundmethod_not_allowed

      HTTP 头：Allow

    • 修复

      嵌套超过 64 层的 JSON（包括字符串字段中的 JSON）会收到 JSON 信封格式的 400 invalid_json。以前这种情况会返回非 JSON 格式的 500 错误。

      错误码：invalid_json

    • 新增

      域名健康检查的响应新增 certificate：叶子证书的过期时间、剩余天数、密钥算法和曲线。

      字段：certificate

      操作：GET /v1/health/{domain}

    • 新增

      格式错误的 Authorization 或 X-API-Key 请求头会被拒绝并返回 401 unauthorized，而不是被忽略，这样本想进行身份验证的客户端就能发现拼写错误。在 API 密钥推出之前，格式正确的密钥仍按匿名调用处理。

      错误码：unauthorized

    • 新增

      未能在 10 秒时限内完成的操作会返回 504 timeout。

      错误码：timeout

    • 变更

      浏览器可以跨源发送 Authorization、X-API-Key、X-Request-Id 和 Idempotency-Key，并读取 X-Request-Id。

    • 变更

      OpenAPI 文档由 API 自身的 schema 生成：每个操作都按状态码列出其错误码，并列出示例和 API 密钥所需的范围。

      操作：GET /v1/openapi.json

  3. v1.0.0

    发布于2026年8月20日

    免费签名 API 正式公开。