REST API
即将上线API reference
The full API reference will be auto-generated from our OpenAPI 3.1 spec the moment the surface is stable. We'd rather ship a placeholder than fake-doc endpoints that might still move. In the meantime, here's the shape, what it'll cover, and what to do today.
形态(可能变化)
HTTPS 上的 REST。JSON 进,JSON 出。每个请求都用 Bearer token 认证。版本写在路径里:/v1/...。按 token 做 rate-limit;响应带常规的 X-RateLimit-* headers。
curl 1# 每个 endpoint 都在 Authorization header 接收 API key2curl https://api.verbumia.ca/v1/projects \3 -H "Authorization: ApiKey vrb_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 调用,行为不变。
面向早期开发者的 Live OpenAPI
如果你在本地跑 Verbumia 后端,实时的 OpenAPI 3.1 spec 暴露在:
本地后端 把 Stoplight、Swagger UI、Insomnia、Postman 或任何兼容 OpenAPI 的工具指向那个 URL。形态正在变 — 所以本页是 placeholder — 但如果你想提前探索 endpoint,它现在就是事实来源。
公开参考什么时候发布?
等 V1 surface 冻结,公开 OpenAPI spec 就会发布在 https://api.verbumia.ca/openapi.json。届时,这个页面会从 placeholder 变成完整渲染的参考(Stoplight 或类似的 spec 查看器) — 没有营销文案,只有从源头生成的每一个 endpoint、每一份 payload、每一个错误码。