メインコンテンツまでスキップ

API 契約 (NEXT-19)

機械可読版: contracts/api-contract.json(schema_version 1)。 テストで検証します: pkg/gateway/api_contract_test.go(ゲートウェイ)、 sdks/go/yabanin_test.go(SDK の同等性)。形状の変更は破壊的です。schema_version を上げ、すべての同等性テストを更新してください。

1. エラーエンベロープ​

2xx 以外の JSON レスポンスは、厳密に {"error":{message,type,param?,code?}} です。message と type は空ではありません。SSE エラーは同じエンベロープを data イベントとして使い、data: [DONE] で終端します。

2. 成功ボディ / null 許容​

  • chat.completion: id/object/choices(空でない配列)。content は空でない文字列です(null にはなりません)。usage のトークンは数値です。
  • 不明なコストは null または欠落であり、決して 0 ではありません(0 は、正直に無料またはローカルであるレスポンスを意味します)。ゲートウェイ契約に対して検証されています。UI はこの規則に従います。

3. ページネーション​

{page>=1, page_size, total (from COUNT — honest), total_pages} は、すべての管理一覧エンドポイントにあります。ダッシュボードのクライアント型は、この形状を固定します。

4. 単位​

API 上の金額は *_usd(cost_usd/cost_in_usd)の浮動小数です。マイクロ USD は内部の台帳フィクスチャ表現であり、API を越えることはありません。トークンは数値です。

5. SSE​

チャンクは object=chat.completion.chunk を持ちます。ストリームは、エラーの後を含め、リテラルの data: [DONE] で終わります。クライアントのキャンセルは上流へ伝播し(cancel)、部分的な usage は観測されたものとして記録されます(会計ウィンドウについては ADR-0001 を参照)。

6. 管理ルートファミリー(方針 / プロンプト / アイデンティティの同等性)​

ベータ以降に追加された、組織スコープのファミリーです。それぞれが組織の権限(org:<perm> — root はバイパスします)でゲートされ、組織スコープのストア(RLS)を通して読み取ります。そのため、パス内にある他組織のリソース id は 404 となり、他組織のデータを返すことはありません。未接続(ストア未設定)のルートは 503 を返します。ルートはインベントリで固定され、配線は導入に依存します。

方針パイプライン(org:policies.manage — 方針はセキュリティオブジェクトです。バージョン履歴は不変です):

GET|POST /api/organizations/{id}/policies
GET|PUT|DELETE /api/organizations/{id}/policies/{policyId}
GET /api/organizations/{id}/policies/drift managed | drift | unmanaged
GET /api/organizations/{id}/policy-decisions ?page&page_size&verdict&mode&policy_id

契約規則: ボディは yaml(ypp/v1 の Policy ドキュメント)と attachments(key_label、model_pattern、endpoint、priority)を持ちます。すべての変更は新しい不変バージョンを追記し、組織のバージョンキーを増やします。管理プレーンは YAML の構文のみを検証します(完全なコンパイルはロード時にゲートウェイ側で行われます。未知の detector 名は保存でき、decision ログで目に見えて失敗します)。Decision 行が公開するのは、verdict(allow|flag|mask|deny)、mode(shadow|enforce)、方針の id/version、ハッシュ化された証拠だけです。引用された内容は永続化しません(保持期間は 90 日)。

プロンプトスタジオ(org:policies.manage — プロンプトはパイプライン入力です。

judge プロンプトが verdict を決めます。partial は方針とプロンプトのボディへ置換されます):

GET|POST /api/organizations/{id}/prompts
GET|PUT|DELETE /api/organizations/{id}/prompts/{promptId}
POST /api/organizations/{id}/prompts/{promptId}/labels bind {label, version}
GET|POST /api/organizations/{id}/partials
PUT|DELETE /api/organizations/{id}/partials/{partialName}

契約規則: 名前は参照安全な [A-Za-z0-9_.-]+ で、組織ごとに一意です。編集は不変バージョンを APPEND します(ラベルバインディングが可変のポインタです)。ボディは {{var}} / {{partials.name}} プレースホルダを持てます。レンダリングは render/render-template パスで行われ、保存済みバージョンを変更することはありません。

MCP 資格情報(管理 CRUD は root。ゲートウェイフローでは org のエージェント認証):

PUT|GET|DELETE /api/organizations/{id}/mcp/servers/{name}/credential
POST /api/mcp/credentials/{server} agent key; headers submit/rotate
POST /api/mcp/auth/{server}/begin agent key; oauth consent URL
GET /api/mcp/auth/{server}/callback public (IdP redirect target)

シークレット表示の契約は §7 を、認証チェーンの意味は MCP ゲートウェイ を参照してください。

SCIM プロビジョニング(トークンは org:members.manage。サーバーは bearer の scim 認証):

POST|GET /api/organizations/{id}/scim/tokens
DELETE /api/organizations/{id}/scim/tokens/{tokenID}
/scim/v2/ServiceProviderConfig | /scim/v2/Users[/{id}] | /scim/v2/Groups[/{id}]

7. シークレット表示の契約​

生のシークレットが API を越えるのは、作成時の一度だけで、フローがそれを必要とする場合に限ります(SCIM の bearer トークン、エージェントキー)。保存されるものはすべて、マスクされて読み戻されます。資格情報の行は secret_last4 と has_secret を公開し、平文や暗号文は公開しません。保管時のシークレットは enc: エンベロープです。設定された encryptor がない書き込みは失敗します。暗黙の平文フォールバックはありません。