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

キャッシュ管理 API リファレンス

すべてのエンドポイントには、管理者認証(admin ロールの Bearer トークン)が必要です。ベースパスは /api です。

キャッシュ設定​

GET /organizations/{id}/cache-settings​

組織ごとのキャッシュ設定を取得します。

レスポンス: 200 OK

{
"org_id": "abc-123",
"cache_enabled": true,
"cache_mode": "semantic"
}

PATCH /organizations/{id}/cache-settings​

組織ごとのキャッシュ設定を更新します。ルート管理者のみです。

リクエスト:

{
"cache_enabled": true,
"cache_mode": "exact"
}

モード: off、exact、semantic 検証: 無効なモード → 400 Bad Request。組織がない → 404 Not Found。非ルート → 403 Forbidden。


キャッシュ操作​

POST /cache/flush?org_id=&model_tier=​

キャッシュエントリをフラッシュします。org_id または model_tier が必要です。ルート管理者のみです。

レスポンス: 200 OK — {"status": "flushed", "org_id": "...", "reason": "manual"}

GET /cache/analytics​

グローバルなキャッシュ利用分析(ヒット率、組織数)を取得します。

レスポンス: 200 OK — {"total_hits": {"exact": 1500, "semantic": 300}, "total_misses": 800, "org_count": 42}

POST /cache/warm(非推奨)​

削除されました。ウォーマーは署名のないエントリを書き込んでおり、RT-05 の検索は常にそれを拒否していました。セマンティックキャッシュは、ライブトラフィックからのみ学習します。

レスポンス: 410 Gone

POST /models/{name}/bump-version​

キャッシュを無効化するため、モデルのバージョンを上げます。ルート管理者のみです。


キャッシュ利用分析​

GET /analytics/{org_id}/cache?from=&to=​

組織ごとのキャッシュヒット率と節約の利用分析を取得します。

クエリパラメータ:

  • from: 開始時刻(RFC3339、デフォルトは 24 時間前)
  • to: 終了時刻(RFC3339、デフォルトは現在)

レスポンス: 200 OK

{
"total_requests": 1000,
"hits_exact": 350,
"hits_semantic": 150,
"misses": 500,
"cache_hit_rate": 0.5,
"savings_usd": 2.45,
"counterfactual_cost_usd": 4.90,
"avg_similarity": 0.973
}

A/B 実験​

POST /cache/experiments​

新しいキャッシュ実験を作成します。ルート管理者のみです。

リクエスト:

{
"name": "cache-ab-test-1",
"org_id": "abc-123",
"traffic_pct": 50
}

レスポンス: 201 Created — 決定的な割り当てを持つ実験オブジェクトです。

GET /cache/experiments?org_id=&enabled=​

実験を一覧します。任意のクエリパラメータは org_id と enabled=true です。

レスポンス: 200 OK — 実験オブジェクトの配列です。

GET /cache/experiments/{exp_id}/results​

実験について、バリアントごとの節約額を取得します。

レスポンス: 200 OK

{
"control_savings_usd": 0.50,
"treatment_savings_usd": 1.20
}

エラーレスポンス​

ステータスコード説明
400invalid_request不正な JSON、または無効なモード
403permission_deniedルート専用エンドポイントに対する非ルート管理者
404not_found組織、モデル、または実験が見つからない
500internal_errorデータベースエラー、またはキャッシュサービスの障害