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 トークン認証。バージョンはパスに: /v1/...。トークン単位で rate-limit 付き、レスポンスは通常の X-RateLimit-* ヘッダーを伴います。
curl 1# すべてのエンドポイントは Authorization ヘッダーで API キーを受け取ります2curl https://api.verbumia.ca/v1/projects \3 -H "Authorization: ApiKey vrb_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }API キーはダッシュボードの Org Settings → API Keys から取得します。同じキーが CLI、MCP サーバー、直接の REST 呼び出しすべてで使えます — API は単に bearer を受け付けるだけです。
ローンチ時に登場するリソース
V1 API が公開するリソースは以下の通りです。フィールド・エラーコード・ページネーションなど正確な形は、OpenAPI spec を公開する時点で確定します。
| リソース | 意味するもの | V1 ops |
|---|---|---|
| Projects | ワークスペース。Create、list、archive、ownership の transfer。 | GET · POST · PATCH · DELETE |
| Locales | プロジェクトスコープのロケール集合。ロケール追加、デフォルト指定、クライアント向け enable/disable。 | GET · POST · PATCH · DELETE |
| Namespaces | プロジェクトごとの論理的なキー束(例: "checkout"、"common")。 | GET · POST · PATCH · DELETE |
| Keys | 翻訳キーと、その説明、スクリーンショット URL、max-length、plural rules。 | GET · POST · PATCH · DELETE |
| Translations | ロケールごとのキー値。draft / in-review / approved の状態と、リビジョン履歴。 | GET · POST · PATCH · DELETE |
| Missing keys | ランタイム SDK のキュー。List、頻度でグルーピング、triaged にマーク。 | GET · PATCH |
| Webhooks | 翻訳イベントへの subscribe。V2。 | V2 |
今日できること
API を使ってやりたいことのほとんどは、すでに CLI、MCP サーバー、ランタイム SDK で出せています。それらを使ってください — API がローンチされたら、コードはやることを変えずに直接 HTTP 呼び出しに差し替えられます。
アーリー開発者向けの Live OpenAPI
Verbumia バックエンドをローカルで動かしているなら、ライブの OpenAPI 3.1 spec が次の場所で公開されます:
ローカル backend Stoplight、Swagger UI、Insomnia、Postman、または OpenAPI 対応の任意のツールをその URL に向けてください。形は動いています — だからこのページはプレースホルダーです — ですが、エンドポイントを早めに探検したい今は、これが信頼できるソースです。
公開リファレンスはいつ?
公開 OpenAPI spec は、V1 サーフェスが固まり次第、https://api.verbumia.ca/openapi.json で配信されます。そのタイミングで、このページはプレースホルダーから完全レンダリングされたリファレンス(Stoplight または spec を上に乗せた同様のビューア)に切り替わります — マーケティングコピーは無く、すべてのエンドポイント、すべてのペイロード、すべてのエラーコードがソースから生成されます。