API リファレンス

完全な API リファレンスは、サーフェスが安定し次第、私たちの OpenAPI 3.1 spec から自動生成します。まだ動く可能性のあるエンドポイントを偽ドキュメントで出すより、プレースホルダーをシップする方がマシです。それまでは、形と、何をカバーするか、そして今日できることをまとめておきます。

形(変更の可能性あり)

HTTPS 上の REST。JSON で入って JSON で出ます。バージョンはパスに: /v1/...。認証スキームは 2 つあり、送ったスキームがあなたがどの種類の 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 が適用されるのは 3 つの surface (feedback, bundle, missing) だけで、その headers はファミリーごとに接頭辞が付きます: X-Feedback-RateLimit-Limit、-Remaining、-Reset、および X-Feedback-Quota-Remaining です。汎用の X-RateLimit-* ヘッダーは存在せず、他のすべての /v1/ endpoints は制限ヘッダーを一切返しません。カウントは 組織単位であり、API キー単位ではありません: 2 本目のキーを発行しても予算は増えず、共有されます。

curl

1# すべてのエンドポイントは Authorization ヘッダーで API キーを受け取ります2curl https://api.sonenta.dev/v1/projects \3  -H "Authorization: ApiKey snt_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 呼び出しに差し替えられます。

CLI

@sonenta/cli

Push、pull、import、export, 多くの自動化ニーズをカバーします。

MCP

Claude Desktop をセットアップ

任意のエージェントからキー読み取り、翻訳提案、PR diff のレビュー。

公開リファレンスはいつ?

公開 OpenAPI spec は、V1 サーフェスが固まり次第、https://api.sonenta.dev/openapi.json で配信されます。そのタイミングで、このページはプレースホルダーから完全レンダリングされたリファレンス(Stoplight または spec を上に乗せた同様のビューア)に切り替わります, マーケティングコピーは無く、すべてのエンドポイント、すべてのペイロード、すべてのエラーコードがソースから生成されます。