API 参考
公开 REST API 的逐项操作说明。这些页面由 API 的 OpenAPI 文档生成，因此字段、示例和错误码正是 API 自身实际校验和返回的内容。
- 基础 URL
https://ecdsa.com/api/v1- OpenAPI 3.1 文档
- https://ecdsa.com/api/v1/openapi.json
操作
Signatures
ECDSA signature verification and DER ⇄ raw r‖s conversion.
JWT
Decoding JSON Web Tokens and verifying ES256/ES384/ES512 signatures.
Certificates
X.509 certificate and chain decoding with assessments.
Domain health
TLS signature-health grades of public domains. These operations connect to the domain.
Webhooks
Webhook endpoints of the API key's account and test deliveries. These operations need an API key with the webhooks scope; deliveries are signed with ECDSA P-256 (ES256).
约定
基础 URL 与版本
所有操作都位于 https://ecdsa.com/api 之下，后接各自的路径，例如 /v1/verify。版本号是路径的一部分：在 v1 内，响应只会新增字段和错误码，因此应忽略未知的成员，并按 HTTP 状态码处理未知的错误码。
身份验证
无需身份验证：所有操作都可以匿名调用。API 密钥将是可选的——以 Authorization: Bearer … 形式发送，或放在 X-API-Key 请求头中——携带密钥的调用不再受按 IP 计算的限额约束，改用该密钥自己的限额。API 密钥将随 ecdsa.com 账号一同推出。格式错误的密钥请求头会被拒绝并返回 unauthorized，而不是被忽略。
请求
POST 请求体是不超过 100 KB 的 JSON 对象，数组和对象最多嵌套 64 层（字符串字段中的 JSON 文档也计算在内）。GET 操作从路径中获取输入。
响应头
API 发送的响应头及其适用场景：
| 响应头 | 携带的信息 |
|---|---|
| X-Request-Id | Identifier of this request, also quoted in every error body. A caller's own X-Request-Id (1–128 characters of A–Z, a–z, 0–9, '.', '_', ':' and '-') is echoed unless it contains an API key; otherwise one is generated. |
| X-RateLimit-Limit | Requests allowed per window by the limit reported on this response. |
| X-RateLimit-Remaining | Requests left in the current window. |
| X-RateLimit-Reset | Unix time (seconds) at which the current window ends. |
| X-Quota-Limit | Calls made with an API key only: the size of the account's quota that runs out first for this operation — daily or monthly quota units, or daily domain scans. |
| X-Quota-Remaining | Calls made with an API key only: what is left of that quota after this call. |
| X-Quota-Reset | Calls made with an API key only: Unix time (seconds) at which that quota starts over. |
| Retry-After | Seconds to wait before retrying; for quota_exceeded, until the quota starts over. |
| Allow | The methods this path accepts. |
| WWW-Authenticate | The bearer challenge (RFC 6750), e.g. `Bearer realm="ecdsa.com", error="invalid_token"`. |
错误
调用失败时，API 返回 4xx 或 5xx 状态码和下面的 JSON 信封；错误表列出了所有错误码。
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
| error | object | 是 | |
| error.code | string | 是 | Machine-readable error code. Each response lists the codes it can carry; new codes may be added within v1, so treat an unknown code by its HTTP status. |
| error.message | string | 是 | Human-readable explanation (English). |
| error.requestId | string | 否 | The X-Request-Id of this request — quote it when reporting a problem. Sent since v1.1. |
| error.detail | object | 否 | Structured context for the error, such as the offending field; omitted when there is none.
|
| error.docs | string | 否 | Where the error codes are explained. Sent since v1.1.
|
速率限制
整个 API 统一限制为每个 IP 每分钟 60 次请求，扫描域名的操作另有每分钟 10 次的限额。429 响应带有 Retry-After。
私钥
切勿发送私钥。请求中任何位置只要包含私钥内容——PEM PRIVATE KEY 块，OpenSSH、SSH2 或 PuTTY 私钥，或者带有“d”的 JWK——都会在任何其他处理之前被拒绝，并返回 private_key_rejected。