概览：REST API、作用域密钥、速率限制、OpenAPI
REST 读写
读取发行、曲目、Smartlink 和数据统计 — 并通过简洁的 HTTPS 创建或编辑你的 Smartlink 和草稿发行。返回 JSON 格式，支持 limit/offset 分页，结构可预测。分发和提交功能不在 API 范围内。
作用域 API 密钥
使用 ogr_pk_ 开头的密钥作为 Bearer Token 或在 X-API-Key 头中认证。每个密钥明确指定作用域：read:releases、read:smartlinks、read:stats、write:smartlinks、write:releases，且可在仪表盘随时轮换或撤销。
速率限制 + 头信息
每条响应均包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头。超出配额返回 429 错误并附带 Retry-After。免费密钥每日 1,000 次请求，商业密钥每日 100,000 次。
自托管 OpenAPI 3.0
完整的机器可读规范位于 /api/v1/public/openapi.json，可在本页渲染为交互式参考文档 — 无需第三方文档托管，无外部调用。
用于上线的端点。
每个端点均通过作用域 API 密钥认证，并由 https://api.og-records.com 提供服务。读取端点 + 针对 Smartlink 和草稿发行的所有者作用域写入 — 分发和提交功能不对外暴露。
当你的发行状态发生变化时，及时收到通知。
注册一个 HTTPS 端点，一旦你的发行作品被下发、被拒或下架，我们将向该端点发送已签名的 JSON 事件。端点管理在仪表盘中完成——每个端点都有独立的签名密钥，仅显示一次。
发布事件
- release.delivered —— 发行作品已送达各商店。
- release.rejected —— 某家商店或质检环节拒绝了该发行作品。
- release.takedown — 该作品已下架。
- release.live — 该作品现已上线各大平台。
每次推送都会携带以下头部信息
- X-Webhook-Signature — 使用你的签名密钥（Signing-Secret）对原始请求体进行 lowercase-hex HMAC-SHA256 加密。
- X-Webhook-Timestamp — ISO-8601 格式的时间戳，与请求体中的 created_at 一致。
- X-Webhook-Event — 事件名称，例如 release.delivered。
- X-Webhook-Id — 此次推送的唯一 ID。
Payload 为包含 id、event、created_at 和 data 对象（含 release_id）的 JSON 格式请求体。验证时，请使用你的 Signing-Secret 对原始请求体重新计算 HMAC-SHA256，并与 X-Webhook-Signature 进行安全比对；同时检查 X-Webhook-Timestamp 是否在 5 分钟内，以防止重放攻击。
推送失败时会采用指数退避重试。连续失败 15 次后，端点将自动停用，需重新注册方可继续。
管理 Webhooks 在你的仪表盘中。
带作用域的 API 密钥
在你的 仪表盘 中创建密钥，并通过 Authorization: Bearer ogr_pk_… 或 X-API-Key 头部发送。每个密钥都有作用域限制 —— read:releases、read:smartlinks、read:stats、write:smartlinks、write:releases —— 确保集成仅获取所需权限。密钥可随时轮换或撤销。写权限为所有者作用域，不会触发分发；OAuth 不在本次发布范围内。
你的密钥可执行的操作
每个新密钥的默认配置，适用于仪表盘、定时同步和原型开发。
为生产环境集成提供更高日限额，需申请开通。
每次响应均包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset。当日限额用尽后，返回 429 错误，并附带 Retry-After 头部，表示距离窗口重置还有多少秒。