API 更新日志

每日配额计数器在每个 UTC 日开始时无一例外地重置。每个响应都带有 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset，因此配额用尽的客户端可以按重置时间戳安排重试，而不必轮询接口。

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1786060800

带版本的端点现在会发送 Access-Control-Expose-Headers，浏览器中运行的代码因此可以读取 X-API-Version、Deprecation、Sunset 和 Link。这些响应头一直存在于响应中，但跨源 JavaScript 无法看到。

Access-Control-Expose-Headers: X-API-Version, Deprecation, Sunset, Link

对 v1 的改动只做加法：字段不会被移除或重命名，破坏性变更将以新的版本路径发布，并事先通过 Deprecation 与 Sunset 响应头公告。由于随时可能新增字段，客户端应忽略无法识别的字段。随此约定，X-API-Version 升至 1.1.0。

X-API-Version: 1.1.0

按产品拆分的密钥已合并为一把 ak_ 密钥。创建时你可以选择该密钥可访问的作用域——tools、data、analytics、analyze、news 和 workflow——超出这些作用域的端点调用会被拒绝。此变更之前创建的密钥保留原有访问权限。

POST /api/v1/keys

{
  "name": "production",
  "scopes": ["tools", "data", "news"]
}

免费账户可创建 1 把 API 密钥，每天最多 50 次请求，突发速率为每秒 2 次。批量、链式调用、Webhook、预设与分析导出仍属于 Akousa Pro。

所有 v1 响应现在都包含 X-API-Version: 1.0.0 响应头。客户端可使用此响应头验证是哪个 API 版本提供了响应，并在集成中实现版本感知逻辑。

X-API-Version: 1.0.0

/api/v1/data/* 下的端点使用同一种外层结构响应：负载放在 data 中，投递信息放在 meta 中——由哪个服务应答、上游来源、响应是否来自缓存以及耗时。同一套解析代码适用于所有数据集。

{
  "data": [ ... ],
  "meta": {
    "service": "earthquakes",
    "source": "usgs",
    "cached": true,
    "executionMs": 34
  }
}

API 通过 URL 路径进行版本控制，当前版本为 v1，重大变更将发布新版本。

Deprecation: @1772323200
Link: </docs/api/changelog#changelog-deprecationHeaders>; rel="deprecation", </api/v1/tools/{slug}>; rel="successor-version"

API 使用标准 HTTP 状态码，错误响应包含 JSON 格式的 error 字段，描述具体问题。

{
  "ok": false,
  "error": "Invalid API key",
  "code": "UNAUTHORIZED",
  "status": 401
}

使用单个 API 密钥进行身份验证，发送标准 HTTP 请求，并接收可预测的 JSON 响应。完整的 OpenAPI 3.1 规范和 8 种语言的交互式代码示例让集成快速便捷。