API 参考

完整的 API 参考会在 surface 稳定的那一刻,从我们的 OpenAPI 3.1 spec 自动生成。我们宁可发布一个 placeholder,也不愿对仍可能改动的 endpoint 做假文档。在此之前,这里给出形态、它将覆盖什么、以及今天该怎么做。

形态(可能变化)

HTTPS 上的 REST。JSON 进,JSON 出。版本写在路径里:/v1/...。存在两种认证方案,你发送的那一种声明了你是哪类 principal:程序化调用用 Authorization: ApiKey <prefix>.<secret>,已登录会话用 Authorization: Bearer <token>。每条路由自己决定接受哪些类型,所以从 URL 推断不出任何东西:大多数项目路由两者都接受,/v1/mcp/* 只接受 API 密钥,账户和 staff 路由只接受会话。其他情况一律返回 401。API 密钥的 scopes 会在权限检查之前映射为项目角色(project:read 变成 viewer,project:write 或 cdn:write 变成 developer)。注意 Bearer:在 /v1/feedback/* 和 /v1/in-context/* 上,它携带的是范围受限的终端用户令牌,与会话属于不同的令牌家族;请确认该 surface 期望的是哪一种。rate limit 只作用于三个 surface(feedback、bundle、missing),它们的 headers 按家族加前缀:X-Feedback-RateLimit-Limit、-Remaining、-Reset,以及 X-Feedback-Quota-Remaining。不存在通用的 X-RateLimit-* 头,其余所有 /v1/ endpoints 完全不返回限流头。计数是 按组织,而不是按 API 密钥:再发一把密钥不会提高你的额度,只会共享它。

curl

1# 每个 endpoint 都在 Authorization header 接收 API key2curl https://api.sonenta.dev/v1/projects \3  -H "Authorization: ApiKey snt_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }

API key 来自 dashboard 的 Org Settings → API Keys。同一把 key 可用于 CLI、MCP 服务器与直接的 REST 调用, API 只消费 bearer。

上线时你会看到的资源

以下是 V1 API 将公开的资源。具体形态, 字段、错误码、分页, 会在我们发布 OpenAPI spec 时确定。

资源	代表什么	V1 ops
Projects	Workspace。Create、list、archive、转移 ownership。	GET · POST · PATCH · DELETE
Locales	项目范围的 locale 集合。新增 locale、设为默认、对客户端启用/禁用。	GET · POST · PATCH · DELETE
Namespaces	项目内 key 的逻辑分桶(例如 "checkout"、"common")。	GET · POST · PATCH · DELETE
Keys	翻译 key,带描述、截图 URL、最大长度、复数规则。	GET · POST · PATCH · DELETE
Translations	key 的逐 locale 值。Draft、in-review、approved 状态;修订历史。	GET · POST · PATCH · DELETE
Missing keys	运行时 SDK 队列。列表、按频率分组、标记为已 triage。	GET · PATCH
Webhooks	订阅翻译事件。V2。	V2

今天可以做什么

几乎所有你会找 API 做的事情,CLI、MCP 服务器或运行时 SDK 都已暴露。先用它们, 等 API 上线后,你的代码可以无感切换到直接 HTTP 调用,行为不变。

CLI

@sonenta/cli

Push、pull、import、export, 覆盖大多数自动化需求。

MCP

配置 Claude Desktop

在任何 agent 里读 key、提交翻译、Review PR diff。

公开参考什么时候发布?

等 V1 surface 冻结,公开 OpenAPI spec 就会发布在 https://api.sonenta.dev/openapi.json。届时,这个页面会从 placeholder 变成完整渲染的参考(Stoplight 或类似的 spec 查看器), 没有营销文案,只有从源头生成的每一个 endpoint、每一份 payload、每一个错误码。