OmniRoute/docs/i18n/ja/docs/reference/API_REFERENCE.md

API Reference (日本語)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

OmniRoute API の主要リファレンスです。公開されている /v1 インターフェースと、最もよく使用される管理エンドポイントを取り上げています。網羅的な情報源については、機械可読な docs/openapi.yaml と src/app/api/ 配下のルートツリーを参照してください。

---

目次

• チャット補完
• 排他的マネージドセッションリース
• 埋め込み
• 画像生成
• ドキュメントOCR
• モデル一覧
• プロバイダープラグインマニフェスト
• 互換性エンドポイント
• Files API
• Batches API
• Search API
• WebSocketストリーミング
• クォータと問題の報告
• セマンティックキャッシュ
• ダッシュボードと管理
• コンボ管理
• Webhook
• 登録済みキー（自動管理）
• エージェントプロトコル
• 管理プロキシ
• 耐障害性（拡張）
• スキル
• メモリ
• MCPサーバー
• A2Aサーバー
• クラウド、評価、アセスメント
• リクエスト処理
• 認証

---

チャット補完

POST /v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "関数を作成してください..."}
  ],
  "stream": true
}

カスタムヘッダー

ヘッダー	方向	説明
X-OmniRoute-No-Cache	リクエスト	キャッシュをバイパスするにはtrueに設定します
x-omniroute-no-memory	リクエスト	このリクエストでメモリとスキルの注入をスキップするにはtrueに設定します（no-cacheと同様に動作し、呼び出しごとのトークン／コストのオーバーヘッドを回避します）
X-OmniRoute-Progress	リクエスト	進捗イベントを有効にするにはtrueに設定します
X-Session-Id	リクエスト	外部セッションアフィニティ用の固定セッションキー
x_session_id	リクエスト	アンダースコア形式も受け付けます（直接HTTP通信）
X-OmniRoute-Session-Id	リクエスト	呼び出し元が指定するセッション／会話タグ（メモリにも渡されます）。指定された場合、セッションごとのコスト帰属用に、そのままcall_logs.session_tagへ永続化されます（#8249）。指定されていない場合は生成されません
Idempotency-Key	リクエスト	重複排除キー（5秒間のウィンドウ）
X-Request-Id	リクエスト	代替の重複排除キー
X-OmniRoute-Cache	レスポンス	HITまたはMISS（非ストリーミング）
X-OmniRoute-Idempotent	レスポンス	重複排除された場合はtrue
X-OmniRoute-Progress	レスポンス	進捗追跡が有効な場合はenabled
X-OmniRoute-Session-Id	レスポンス	OmniRouteが使用した実効セッションID
X-OmniRoute-Request-Id	レスポンス	リクエスト相関ID（判明している場合）
X-OmniRoute-Version	レスポンス	OmniRouteのビルドバージョン（常に含まれます）
X-OmniRoute-Cost-Saved	レスポンス	HITによってキャッシュが節約した金額（USD、キャッシュヒット時のみ）
X-OmniRoute-Decision	レスポンス	ルーティングトレース：strategy=<name>; provider=<alias>; latency_ms=<n>（<name>はコンボ戦略、コンボ以外のリクエストではsingle）。完了レスポンスには常に含まれます

Nginxに関する注記：アンダースコアを含むヘッダー（例：x_session_id）を利用する場合は、underscores_in_headers on;を有効にしてください。

コストテレメトリヘッダー: 非ストリーミングの成功レスポンスには、X-OmniRoute-* コストテレメトリセットも含まれます。これには、X-OmniRoute-Response-Cost（USD、固定小数点以下10桁。無料または価格未設定の場合は 0.0000000000）、X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out、X-OmniRoute-Model、X-OmniRoute-Provider、X-OmniRoute-Latency-Ms、X-OmniRoute-Cache-Hit、X-OmniRoute-Fallback-Attempts（0より大きい場合のみ）、さらに X-OmniRoute-Request-Id と X-OmniRoute-Version が含まれます。これらは、チャット補完、/v1/responses、/v1/messages、およびメディアエンドポイント（/v1/embeddings、/v1/images/generations、/v1/audio/speech、/v1/audio/transcriptions、/v1/rerank、/v1/videos/generations、/v1/music/generations、/v1/moderations（コストは常に 0））から出力されます。メディアのコストは、価格情報が利用可能な場合はモダリティごと（画像単位、秒単位、文字単位、検索単位）に計算され、それ以外の場合は 0 になります（フェイルオープン）。

キャッシュヒット時のコストのセマンティクス: セマンティックキャッシュのヒット時（X-OmniRoute-Cache-Hit: true）にはアップストリーム呼び出しが行われないため、X-OmniRoute-Response-Cost は 0.0000000000（ヒットを提供するための増分コスト）になります。元のコスト、つまりキャッシュがなければ発生していたはずのコストは、X-OmniRoute-Cost-Saved で別途報告されます。請求処理を行うコンシューマーは X-OmniRoute-Response-Cost を合計してください（ヒットのコストはゼロです）。キャッシュ分析では、X-OmniRoute-Cost-Saved を集計できます。

排他的マネージドセッションリース

排他的マネージドセッションリースは、オプトイン方式のクライアント中立なルーティング契約です。1つのアクティブな所有者が、適格なOmniRoute接続を1つ保持します。モデルをリースするものではなく、OAuthを必要とせず、特定のクライアントを識別せず、特定のプロバイダーも必要としません。

認証に使用するAPIキーには、スコープlease:exclusiveと、明示的かつ空でないallowedConnectionsリストが必要です。データベースのミューテーション境界では、キーの作成時および部分更新時に、これら両方のフィールドがまとめて強制されます。

POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>

{"action":"acquire","model":"glm/glm-4.6"}

取得、更新、解放に成功したレスポンスでは、タイムスタンプ、state、および正確な正のgenerationが公開されますが、選択された接続や認証情報は決して公開されません。更新と解放では、JSON本文でgenerationを指定します。

{ "action": "renew", "generation": 1 }

{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }

アクティブなリース所有者は、現在のバインディングについて、プライバシーに配慮した表示メタデータを明示的に要求できます。

{ "action": "status", "generation": 1 }

{
  "state": "ACTIVE",
  "generation": 1,
  "acquiredAt": "2026-08-28T12:00:00.000Z",
  "renewedAt": "2026-08-28T12:00:30.000Z",
  "expiresAt": "2026-08-28T12:02:30.000Z",
  "connection": {
    "displayName": "Primary Codex",
    "provider": "codex"
  }
}

このオプトインのstatusアクションは、単一のデータベーストランザクション内で、不透明な所有者、認証済みのマネージドAPIキー、および正確なアクティブgenerationによってフェンシングされます。displayNameは、設定された接続名をトリミングしたものに限られ、安全な設定済み名称が存在しない場合はnullになります。OmniRouteがメールアドレスや生成されたアカウントIDを代用することはありません。プロバイダー値は機密性のない表示ラベルであり、生成された互換プロバイダー識別子ではありません。認証情報、トークン、Cookie、生の接続IDまたはAPIキーID、所有者ハッシュ、フェンシングシークレット、および内部ルーティングデータは除外されます。

誤ったキー、誤った所有者、古いgeneration、存在しない、期限切れ、解放済み、無効化済みのいずれの検索も、接続メタデータを含まない同一の409 LEASE_FENCE_STALEエラーを返します。容量待機レスポンスを受け取ったクライアントには、確認可能なアクティブなバインディングがありません。ルーティングによってアクティブなリースが移行した場合も、同じgenerationが有効なままとなり、statusは古いバインディングではなく新しいバインディングをアトミックに返します。取得、更新、解放、および待機レスポンスは従来の形式を維持するため、既存のクライアントには影響しません。

このサーバー契約によって、標準のOpenAI Codex /statusが変更されることはありません。現在、標準のCodexはモデルプロバイダーと組み込みの認証／アカウント状態を報告しますが、任意のカスタムプロバイダーのアカウントメタデータは表示しません。今後のクライアント統合では、このアクションを呼び出し、connection.displayNameの表示方法を決定する必要があります。

以降、マネージド推論リクエストごとに、次の両方の制御ヘッダーを指定します。

X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1

サポート対象の各アップストリーム試行の直前に、正確な所有者、generation、アクティブな接続、および認証済みAPIキーがフェンシングされます。別のキーが同じ接続を許可している場合でも、そのキーで所有者とgenerationを再利用すると失敗します。生の所有者情報が永続化、ログ記録、リクエストスナップショットへの保持、またはアップストリームへの転送の対象になることはありません。

一時的な競合が発生した場合、HTTP 429がRetry-Afterおよび次の内容とともに返されます。

{
  "state": "WAITING_FOR_CAPACITY",
  "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
  "reason": "NO_FREE_ELIGIBLE_CONNECTION",
  "retryAfter": 30
}

このレスポンスが意味するのは、通常の適格セットが空ではなく、空いている候補がすべて別のアクティブなリースによって保持されていたということだけです。サポートされていないモデル／プロバイダー、ポリシーの不一致、クールダウン、クォータ、正常性、およびその他の通常の適格性エラーでは、既存のOmniRouteレスポンスが維持されます。

x-omniroute-compression

リクエスト単位で圧縮プランを上書きします。優先順位は最も高く、ルーティングコンボの上書き、アクティブプロファイル、自動トリガー、およびパネルのDefaultより優先されます。値は次のとおりです。

値	効果
off	このリクエストでは圧縮しません。
default	パネルから派生したDefaultプロファイルを使用します（アクティブプロファイルは無視されます）。
engine:<id>	有効な場合に単一のエンジンを使用します（例：engine:rtk）。
<combo>	名前付きコンボ。最初に名前（大文字と小文字を区別しない）、次にidで照合されます。

注意事項：

• 不明な値は無視され（リクエストが拒否されることはありません）、解決処理は通常のオペレーター優先順位にフォールスルーします。
• 複数のコンボが同じ名前を共有する場合、決定的に照合するにはコンボのidを渡してください。
• 名前がoffまたはdefaultのコンボは、名前では選択できません（これらのキーワードが先に解釈されます）。そのようなコンボはidで参照してください。
• マスター圧縮スイッチは強制的なゲートです。圧縮がグローバルに無効になっている場合、このヘッダーで有効にすることはできません。

適用されたプランは、次のレスポンスヘッダーで返されます。

X-OmniRoute-Compression: <mode>; source=<source>

ここで、<source>はrequest-header、routing-override、active-profile、auto-trigger、default、またはoffのいずれかです。

---

埋め込み

POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "nebius/Qwen/Qwen3-Embedding-8B",
  "input": "The food was delicious"
}

利用可能なプロバイダー: Nebius、OpenAI、Mistral、Together AI、Fireworks、NVIDIA、OpenRouter、Jina AI。

カタログ ID は provider/model 形式です（例: jina-ai/jina-embeddings-v5-omni-small）。レジストリに存在する、プロバイダー名の付いていない Jina モデル ID（例: jina-embeddings-v5-text-small、jina-reranker-v3.5）も解決されます。Jina の embed/rerank/classify/segment では、まずダッシュボードの jina-ai 認証情報が使用されます。JINA_AI_API_KEY は、ダッシュボードキーが存在しない場合にのみフォールバックとして使用されます。jina-reader カードは Reader / r.jina.ai 専用（POST /v1/web/fetch）であり、埋め込みやリランキングには使用されません。

マルチモーダル対応を明示しているレジストリモデルでは、プロバイダーに依存しない構造化アイテムを最大 32 件まで受け付けます。メディアアイテムの種類は text、image、audio、video、document です。メディアの source は、{"type":"url","url":"https://..."} または {"type":"base64","data":"...","media_type":"..."} のいずれかです。

Jina v5 Omni（jina-ai/jina-embeddings-v5-omni-small、jina-ai/jina-embeddings-v5-omni-nano、およびファミリーエイリアス jina-ai/jina-embeddings-v5-omni → omni-small）は、Jina ネイティブの EmbeddingsV5Request ドキュメントも受け付け、それらをそのまま https://api.jina.ai/v1/embeddings に転送します。

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "task": "retrieval.query",
  "normalized": true,
  "input": [
    { "text": "a red bicycle" },
    { "image": "https://example.com/bike.png" },
    {
      "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }]
    }
  ]
}

ネイティブの { image | audio | video | pdf } 値には、公開 HTTPS URL、data: URI、または未加工の base64 を使用できます。OmniRoute はこれらのオブジェクトを文字列化せず、ネイティブ画像 URL も取得しません。公開メディアは Jina 自身が取得します。追加の Jina フィールド（task、normalized、truncate、embedding_type）も転送されます。テキスト専用の Jina SKU では、引き続きテキスト以外のドキュメントが拒否されます。

セキュリティおよび転送上の制限:

• リモートメディア URL は公開 HTTPS である必要があります。正規形式の {type,source:url} アイテムはサーバー側で取得され（リダイレクトの再検証、タイムアウト、サイズ制限、公開 DNS、接続先の固定を実施）、プロバイダー呼び出しの前にインライン化されます。Jina ネイティブの {image:"https://..."} アイテムは、同じ公開 HTTPS チェック後にそのまま転送され、Jina が URL を取得します。
• インライン base64 メディアは、デコード後のサイズでアイテムあたり 8 MiB、リクエスト全体で 16 MiB に制限されます。

プロバイダー向けの変換（正規形式のアイテムが変更されずに転送されることはありません）:

• Jina マルチモーダルモデル: 各トップレベルアイテムは、インラインメディアに data URI を使用した、モダリティをキーとする単一のオブジェクト（text / image / audio / video / pdf）になります。トップレベルアイテムごとに 1 つのベクトルが生成されます。
• Gemini Embedding 2 ファミリー: 1 つのトップレベル配列は、content.parts（text または inline_data）を持つ単一のネイティブ models/{model}:embedContent リクエストになります。
• 明示的なモダリティメタデータを持たない不明なモデルまたは動的モデルでは、構造化入力が HTTP 400 で拒否されます。

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}

サポートされていないモデルとモダリティの組み合わせでは、アイテムを強制変換せずに HTTP 400 が返されます。従来の文字列／トークンリクエストに含まれる入力以外の拡張フィールドは、引き続き変更されずにそのまま渡されます。

# すべての埋め込みモデルを一覧表示
GET /v1/embeddings

---

画像生成

POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "openai/gpt-image-2",
  "prompt": "山々に沈む美しい夕日",
  "size": "1024x1024"
}

利用可能なプロバイダー: OpenAI (GPT Image 2)、xAI (Grok Image)、Together AI (FLUX)、Fireworks AI、Nebius (FLUX)、Hyperbolic、NanoBanana、OpenRouter、SD WebUI (ローカル)、ComfyUI (ローカル)。

# すべての画像モデルを一覧表示
GET /v1/images/generations

---

ドキュメントOCR

POST /v1/ocr
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "mistral/mistral-ocr-latest",
  "document": {
    "type": "document_url",
    "document_url": "https://example.com/invoice.pdf"
  }
}

model は、provider/model プレフィックスを使用してOCRプロバイダーを選択します。プロバイダーを含まないモデルID（例: mistral-ocr-latest）は登録済みのプロバイダーに解決され、model を省略した場合はデフォルトで Mistral（mistral-ocr-latest）が使用されます。登録済みプロバイダー（open-sse/config/ocrRegistry.ts）:

プロバイダーID	モデルID	model の値	備考
mistral	mistral-ocr-latest	mistral/mistral-ocr-latest（または mistral-ocr-latest）	同期式 — 単一のアップストリーム呼び出しからレスポンスが直接返されます。
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	非同期アップストリーム（analyze + ポーリング）— 以下を参照してください。
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	Vertex AIのopenapi/chat/completionsパートナーエンドポイント経由の同期式 — 認証/URLについては以下を参照してください。

3つのプロバイダーはすべて、同じMistral形式の本文で応答します:

{
  "pages": [{ "index": 0, "markdown": "# 抽出されたテキスト..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}

Azure Document Intelligenceのポーリングフロー

Azure Document Intelligenceのanalyze APIは非同期です。最初のリクエストでは本文の代わりに Operation-Locationヘッダーが返されるため、結果をポーリングする必要があります。ハンドラー （open-sse/handlers/ocr.ts）は、そのURLを1秒ごとに最大30回ポーリングします。ポーリングレスポンスがokでない場合、またはステータスが"failed"の場合は即座に失敗し（ポーリングを 継続せず）、試行回数の上限に達した後も処理が実行中の場合は504を返します。Azureの最終レスポンスは、 呼び出し元へ返される前に、Mistralで使用されるものと同じpages/markdown形式へ正規化されるため、 クライアントコードでプロバイダーごとの特別な処理を行う必要はありません。

Vertex AI DeepSeek OCRの認証とエンドポイント解決

vertex-deepseek-ocrは、OmniRouteがチャット/画像トラフィック向けにすでにサポートしているものと同じ Vertex AI認証（open-sse/executors/vertex.ts）を再利用します。接続のAPIキーには、 Service Account JSON認証情報（JWTベアラーフローを介して短期間有効なOAuthアクセストークンと交換される）、 または発行済みのOAuthアクセストークンをそのまま使用できます。アップストリームエンドポイントURLは、 接続のプロジェクトとリージョンから構築される、Vertexの汎用openapi/chat/completionsパートナーエンドポイントです。 明示的なproviderSpecificData.project/providerSpecificData.regionが常に優先されます。 それ以外の場合、プロジェクトはService Account JSONのproject_idから取得され、リージョンのデフォルトは us-central1です。どちらの解決もopen-sse/handlers/ocr.ts （resolveVertexOcrAccessToken、resolveVertexOcrBaseUrl）で行われ、 handleOcrへ処理を渡す前にsrc/app/api/v1/ocr/route.tsによって使用されます。

---

モデル一覧

GET /v1/models
Authorization: Bearer your-api-key

→ すべてのチャット、埋め込み、画像モデル、および組み合わせを OpenAI 形式で返します

モデル ID のプレフィックス（?prefix=）

ほとんどのモデルは、プロバイダープレフィックス付きで公開されます。使用されるプレフィックスは、MODELS_CATALOG_PREFIX_MODE 機能フラグによって制御され、クエリパラメーターを使用してリクエストごとに上書きできます。これは、他のすべてのユーザーに適用されるサーバー全体の設定を変更せずに、クリーンな一覧を取得したいクライアントに便利です。

GET /v1/models?prefix=alias        # モデルごとに 1 つの ID — 短いエイリアスプレフィックス
GET /v1/models?prefix=dual         # 両方の形式（サーバーのデフォルト）
GET /v1/models?prefix=canonical    # 完全なプロバイダー ID プレフィックスのみ

モード	出力	注記
dual	cc/claude-sonnet-4-6 および claude/claude-sonnet-4-6	デフォルト。 両方の ID が同じモデルにルーティングされます。いずれかの形式をハードコードしたクライアント設定が引き続き動作するよう維持されています。カタログのサイズはおおよそ 2 倍になります。
alias	cc/claude-sonnet-4-6	モデルごとに 1 つのエントリ。個別のエイリアスがないプロバイダーも引き続きエントリを出力するため、何も失われません。
canonical	claude/claude-sonnet-4-6	完全なプロバイダー ID プレフィックスの下で、モデルごとに 1 つのエントリ。個別のエイリアスがないプロバイダー（例：antigravity/…、agy/…）も、ここで単一の ID を出力するため、何も失われません。

dual モードのミラーは、クエリパラメーターがなくても識別できます。プライマリ ID を指す parent フィールドが含まれています。

モデルピッカーを表示するクライアントは、?prefix=alias をリクエストする必要があります。OmniCopilot VS Code 拡張機能でもこの方法を使用しています。

思考なしモデルのバリアント

思考機能に対応した Claude モデルについては、/v1/models は ID の先頭に claude-3-omniroute-no-thinking/ が付いた思考なしバリアントも公開します。

claude-3-omniroute-no-thinking/<provider>/<model>

この ID を選択すると（たとえば、常に thinking ブロックを付加する Claude Code 設定内で）、推論を抑制した状態で実際の <provider>/<model> に解決されます。具体的には、/v1/messages パスでは thinking:{type:"disabled"} が設定され、/v1/chat/completions パスでは reasoning/reasoning_effort フィールドが削除されます。このバリアントは、思考をサポートし、かつ disabled を受け入れる Claude ファミリーのモデルに対してのみ一覧表示されます（そのため、たとえば disabled を拒否する adaptive-only モデルは除外されます）。運用者は、ModelSpec.noThinkingAlias を使用して、モデルごとにこのバリアントを強制的に有効または無効にできます。

---

プロバイダープラグインマニフェスト

GET /api/v1/provider-plugin-manifest

Bifrost、CLIProxyAPI、および将来のサイドカールーターで使用される、JSON セーフなプロバイダープラグインマニフェストを返します。レスポンスは TypeScript のプロバイダーレジストリから生成され、OAuth クライアントシークレット、実行時の環境解決、エグゼキューター関数、リクエストヘッダー、およびアカウントデータは意図的に除外されています。

サイドカーがプロセス外で実行され、open-sse/config/providerPluginManifestRegistry.ts を直接インポートできない場合は、このエンドポイントを使用してください。

---

互換性エンドポイント

メソッド	パス	形式
POST	/v1/chat/completions	OpenAI
POST	/v1/messages	Anthropic
POST	/v1/responses	OpenAI Responses
POST	/v1/embeddings	OpenAI
POST	/v1/images/generations	OpenAI Images
POST	/v1/images/edits	OpenAI Images（編集／インペイント）
POST	/v1/videos/generations	OpenAI 形式の動画生成
POST	/v1/music/generations	OpenAI 形式の音楽生成
POST	/v1/audio/transcriptions	OpenAI Audio（STT）
POST	/v1/audio/speech	OpenAI TTS（音声本文を返す）
POST	/v1/rerank	Cohere/Voyage 形式の再ランキング
POST	/v1/classify	Jina 分類（api.jina.ai）
POST	/v1/segment	Jina セグメンター（segment.jina.ai）
POST	/v1/moderations	OpenAI Moderations
GET	/v1/models	OpenAI
POST	/v1/messages/count_tokens	Anthropic
GET	/v1beta/models	Gemini
POST	/v1beta/models/{...path}	Gemini generateContent
POST	/v1/api/chat	Ollama
GET	/api/v1/vscode/{token}/	OpenAI カタログエイリアス
GET	/api/v1/vscode/{token}/models	OpenAI モデルエイリアス
POST	/api/v1/vscode/{token}/chat/completions	OpenAI トークン付きエイリアス
POST	/api/v1/vscode/{token}/responses	OpenAI Responses トークン付きエイリアス
POST	/api/v1/vscode/{token}/api/chat	Ollama トークン付きエイリアス
GET	/api/v1/vscode/{token}/api/tags	Ollama タグのトークン付きエイリアス

すべての POST ルートは同じ形式に従います。Bearer your-api-key と、Zod で検証された JSON 本文（v1RerankSchema、v1ModerationSchema、v1AudioSpeechSchema など。src/shared/validation/schemas.ts を参照）を使用します。スキーマ検証に失敗すると 4xx が返されます。

Authorization: Bearer ... を付与できないクライアント向けに、OmniRoute は、クエリ文字列による互換方式（?token=...、?apiKey=...、?api_key=...、?key=...）または以下で説明する専用の /api/v1/vscode/{token}/... エンドポイントを介して、URL 内の API キーも受け付けます。

# 再ランキング
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina 分類（Foundation API 認証情報）
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina セグメンター
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina 検索（s.jina.ai、プロバイダーエイリアス：jina-search、jina-ai、jina）
POST /v1/search      { "query": "...", "provider": "jina-search" }

# モデレーション
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — audio/mpeg（または指定された形式）の本文を返す
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# 画像編集（multipart）
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# 動画／音楽生成（プロバイダー接頭辞付きモデル ID）
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

プロバイダー専用ルート

POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations

プロバイダー接頭辞がない場合は、自動的に追加されます。モデルが一致しない場合は 400 が返されます。

---

Files API

バッチ入出力およびファイル用途別アップロードに対応する、OpenAI 互換のファイルエンドポイント。

メソッド	パス	説明
POST	/v1/files	ファイルをアップロード（マルチパート: file、purpose、expires_after[anchor]、expires_after[seconds]）— 最大 512 MiB
GET	/v1/files	認証済み API キーのファイルを一覧表示
GET	/v1/files/[id]	ファイルのメタデータを取得
DELETE	/v1/files/[id]	ファイルを削除
GET	/v1/files/[id]/content	未加工のファイル本体をストリーミングで返す

認証: Bearer API キー — ファイルのスコープは、getApiKeyRequestScope を介して API キーごとに設定されます。キーから 表示、ダウンロード、削除できるのは、そのキーが所有するファイルのみです。キーを使用しないダッシュボードセッションは インスタンス全体を読み取れます。所有者のないファイル（匿名またはダッシュボードセッションによるアップロード）は、セッションを使用しない すべての呼び出し元に対してアクセスが拒否されます。GET /v1/files は、REQUIRE_API_KEY=false の場合でも、すべてのテナントの ファイルを一覧表示する代わりに、匿名の呼び出し元、および解決できない提示済みキーに対して 401 を返します （GHSA-m3hp-hq9g-fpmv、GHSA-2jm2-mpx8-6523）。

---

Batches API

OpenAI 互換のバッチ処理。

メソッド	パス	説明
POST	/v1/batches	バッチを作成 — 本文は v1BatchCreateSchema（input_file_id、endpoint、completion_window）によって検証されます
GET	/v1/batches	バッチを一覧表示
GET	/v1/batches/[id]	バッチのステータスと request_counts を取得
DELETE	/v1/batches/[id]	完了または失敗したバッチを削除
POST	/v1/batches/[id]/cancel	進行中のバッチをキャンセル

認証: Bearer API キー。バッチのスコープは、ファイルと同じ 3 通りのルールに基づいて API キーごとに設定されます。 アクセスできるのは自身のキーのみ、ダッシュボードセッションはインスタンス全体、所有者が null のレコードはセッションを使用しない すべての呼び出し元に対してアクセスが拒否されます（取得、削除、キャンセル、および作成時の input_file_id チェック）。 GET /v1/batches は、REQUIRE_API_KEY=false の場合でも、匿名の呼び出し元に対して 401 を返します。

---

Search API

Web/検索プロバイダーの抽象化レイヤー（Tavily、Brave、Exa、Serper など）。

メソッド	パス	説明
GET	/v1/search	設定済みの検索プロバイダーと機能を一覧表示
POST	/v1/search	検索クエリを実行 — リクエストボディは v1SearchSchema で検証され、キャッシュ/コアレッシングをサポート
GET	/v1/search/analytics	プロバイダーごとのヒット数/レイテンシ/キャッシュ統計

認証: Bearer APIキー（extractApiKey + isValidApiKey）。検索ポリシーは enforceApiKeyPolicy によって適用されます。

---

Web Fetch API

設定済みのWebフェッチプロバイダー（Firecrawl、Jina Reader、Tavily Extract、TinyFish Fetch、Nimble Extract）を使用して、URLからコンテンツを抽出します。

メソッド	パス	説明
POST	/v1/web/fetch	URLを取得/スクレイピング — リクエストボディは v1WebFetchSchema で検証されます

認証: Bearer APIキー（extractApiKey + isValidApiKey）。ポリシーは enforceApiKeyPolicy によって適用されます。

クォータを考慮したフォールバック（#8297）: 明示的な provider が指定されていない場合、プール （firecrawl → jina-reader → tavily-search → tinyfish → nimble-search）は、 固定された 優先順位（fill-first）で走査されます。レート制限中であっても設定済みのプロバイダーは、 リクエストをそこで終了させる代わりにスキップされます。また、再試行可能な障害またはクォータに起因するアップストリーム障害 （HTTP 429 は常に対象。Firecrawl/Tavily/TinyFish のクォータ方式の無料枠では 402/403 も対象 — Jina Reader では対象外であり、通常の 400 bad request は一切対象外）は、リクエスト時に、 まだ試行されていない認証情報設定済みの次のプロバイダーへフォールスルーします。プール内のすべてのプロバイダーを 使い果たした場合、エンドポイントは従来の汎用的な 400 の代わりに、単一の 429（Retry-After ヘッダー付き）を返します。明示的な provider が要求された場合、サイレントフォールバックは 行われません。レート制限中または失敗した明示的なプロバイダーは、それ自身のエラーを返します（レート制限中は 429、それ以外はアップストリームの ステータス）。

---

WebSocketストリーミング

GET /v1/ws?handshake=1

WebSocketアップグレードのハンドシェイクを検証し、ワイヤープロトコルのメッセージ例（request、cancel）を返します。実際のWSフレームは、Next.jsのルートテーブル外にある同梱のWSサーバーによって処理されます。

認証: ハンドシェイク時のBearer APIキー。

WebSocket経由のResponses API（codexのみ）

# HTTP APIと同じhost:port（デフォルトは20128）を使用し、接続をアップグレードします:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# （または: -H "Authorization: Bearer <OMNIROUTE_API_KEY>"）

# 最初のフレームは必ずresponse.createでなければなりません:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Responses-API-over-WebSocketプロキシは、codex 専用（ChatGPT バックエンド）として接続されています。API/ダッシュボードと同じポートで、パス /v1/responses、 /responses、/api/v1/responses をリッスンします。最初の response.create フレームで、 内部の codex-responses-ws ブリッジを介して認証と準備を行い、codex OAuth接続を 選択し、wreq-js トランスポート経由で wss://chatgpt.com/backend-api/codex/responses へトンネリングします。codex以外のモデルは拒否されます（codex_ws_provider_required）。 クォータ共有ルーティングには model: "qtSd/<group>/codex/<model>" を使用してください。実装は app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts にあります。

認証: ハンドシェイク時のBearer APIキー。同梱のHTTPサーバー（server-ws.mjs）が 有効なエントリーポイントである必要があります（app/server-ws.mjs が存在する場合、デフォルトで有効です）。

モデルID: codex/ プレフィックスなしのChatGPT IDを使用

OpenAI Codex CLI は、supports_websockets = true の場合に クライアント側でモデル名を検証し、codex/gpt-5.5 のような プロバイダープレフィックス付きIDを拒否します（The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account）。プレフィックスなしのID（例: gpt-5.5）を送信してください。OmniRouteのブリッジは codex専用であるため、アップストリームへトンネリングする前に、プレフィックスなしのIDをcodexモデルとして 再解決します（resolveCodexWsModelInfo）。これは、プレフィックスなしの gpt-5.5 がHTTP経由では本来別のプロバイダーにルーティングされる場合でも同様です。

OpenAI Codex CLIの設定

WebSocketをサポートするカスタムプロバイダーを ~/.codex/config.toml に追加して、 Codex CLIの接続先をOmniRouteに設定します（既存の設定に影響を与えないよう、別の CODEX_HOME を使用してください）。

model = "gpt-5.5"                 # プレフィックスなしのID — "codex/gpt-5.5"ではありません
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # 末尾にスラッシュを付けません。WS URLはここから導出されます（本番環境ではhttps/wssを使用してください）
wire_api = "responses"                    # 2026年2月以降でサポートされる唯一の値
supports_websockets = true                # Responses-over-WSトランスポートを有効にします
env_key = "OMNIROUTE_API_KEY"             # OmniRoute APIキー（Bearer）を保持します

export OMNIROUTE_API_KEY=sk-...           # OmniRoute APIキー（REQUIRE_API_KEY=falseの場合は任意のキー）
codex exec "Responda apenas: PONG"

CLIは base_url + /responses をWebSocketへアップグレードし、OmniRouteは選択された codex OAuth接続へトンネリングします。ローカル サーバーに対してエンドツーエンドで検証済みです。ChatGPTは codex.rate_limits + response.created を返し、完了結果を ストリーミングします。

---

クォータと問題の報告

メソッド	パス	説明
GET	/v1/quotas/check	登録済みキーを発行する前に、provider + accountId のクォータを事前検証します
POST	/v1/issues/report	クォータまたはキー発行の失敗を GitHub に報告します（GITHUB_ISSUES_REPO + トークンが必要）

認証: Bearer API キー（isAuthenticated）。

---

セルフサービスでの使用状況確認（/api/usage/om-usage）

どの API キーでも、管理者認証なしで 自身の 使用状況とクォータを確認できます。これは、 クライアント（CLI、OmniCopilot パネル）がキーホルダーに利用額を表示するために使用するエンドポイントです。

# テキスト形式（従来の仕様 — ターミナル向けのプレーンテキスト）
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# 構造化形式 — UI が使用する形式
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

キーでは allowUsageCommand が有効になっている必要があります（デフォルトでは無効です。ダッシュボードの API キーマネージャーでキーごとに切り替えます）。有効でない場合、エンドポイントは 403 を返します。

?format=json は判別可能な形式を返すため、呼び出し元が拒否レスポンスからデータフィールドを 読み取ることはありません。成功時:

{
  "allowed": true,
  // キーでキー単位の使用上限（1 日あたり／1 週間あたりの USD）を有効にした場合にのみ存在:
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // 選択されたプロバイダーのクォータスナップショット。まだ何もキャッシュされていない場合は null:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // 各接続のスナップショット。UI で複数のプロバイダーを並べて表示可能:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

拒否時（不正なキーの場合は 401／許可されていない場合は 403）、同じルートが { "allowed": false, "error": { "message": "…" } } を返します。存在するものの空の personal/provider （キーは許可されているが、まだ情報を取得していない状態）は拒否とは異なる状態であり、これらを 区別できるのは JSON 形式のみです。

認証: 呼び出し元自身の Bearer API キー。isValidApiKey で検証されます。これは 管理インターフェース（/api/keys/…）ではなく、管理インターフェースは引き続き requireManagementAuth で保護されます。

---

セマンティックキャッシュ

# キャッシュ統計を取得
GET /api/cache/stats

# すべてのキャッシュをクリア
DELETE /api/cache/stats

レスポンス例:

{
  "semanticCache": {
    "memorySize": 42,
    "memoryMaxSize": 500,
    "dbSize": 128,
    "hitRate": 0.65
  },
  "idempotency": {
    "activeKeys": 3,
    "windowMs": 5000
  }
}

レイテンシへの影響

セマンティックキャッシュが HIT した場合、アップストリーム呼び出しなしで キャッシュからレスポンスが返されるため、報告される X-OmniRoute-Response-Latency は （元のアップストリームレイテンシに関係なく）ほぼゼロになります。レイテンシを重視するクライアント （ベンチマーク、p50/p99 モニタリング）は、X-OmniRoute-Cache-Latency レスポンスヘッダーを確認する必要があります。

値	意味
synthetic	キャッシュから返されたレスポンス。レイテンシは実際のアップストリーム時間ではありません
(なし)	実際のアップストリーム呼び出しからのレスポンス

キー単位のキャッシュバイパス

API キーでは、cacheDefaultMode を使用してセマンティックキャッシュの読み取りを無効にできます。

値	動作
legacy	通常のキャッシュ動作（デフォルト）
bypass	キャッシュ検索を完全にスキップし、常にアップストリームを呼び出します

キーの作成時（POST /api/keys）に設定するか、更新時（PATCH /api/keys/[id]）に変更します。

{ "cacheDefaultMode": "bypass" }

リクエスト単位のバイパス

キーの設定に関係なく、任意のリクエストでキャッシュをバイパスできます。

X-OmniRoute-No-Cache: true

---

ダッシュボードと管理

管理ルート（公開の認証/ログインを除く /api/*）は、通常の推論 API キーでは認可されません。認証情報の種類、スコープ、curl の例については、以下を参照してください： 管理認証。

認証

エンドポイント	メソッド	説明
/api/auth/login	POST	ログイン
/api/auth/logout	POST	ログアウト
/api/settings/require-login	GET/PUT	ログイン必須設定の切り替え

プロバイダー管理

エンドポイント	メソッド	説明
/api/providers	GET/POST	プロバイダーの一覧表示 / 作成
/api/providers/[id]	GET/PUT/DELETE	プロバイダーの管理
/api/providers/[id]/test	POST	プロバイダー接続のテスト
/api/providers/[id]/models	GET	プロバイダーモデルの一覧表示
/api/providers/validate	POST	プロバイダー設定の検証
/api/providers/bulk	POST	1 つのプロバイダーに API キーを一括追加
/api/providers/import	POST	解析済みの CSV/JSON ファイルから異種プロバイダーのリストをインポート（#6836）。行ごとの部分的な失敗結果を返す
/api/provider-nodes*	各種	プロバイダーノードの管理
/api/provider-models	GET/POST/PATCH/DELETE	カスタムモデル（追加、更新、非表示/表示、削除）

OAuth フロー

エンドポイント	メソッド	説明
/api/oauth/[provider]/[action]	各種	プロバイダー固有の OAuth

ルーティングと設定

エンドポイント	メソッド	説明
/api/models/alias	GET/POST	モデルエイリアス
/api/models/catalog	GET	プロバイダーおよびタイプ別の全モデル
/api/combos*	各種	コンボ管理
/api/keys*	各種	API キー管理
/api/pricing	GET	モデルの価格設定

使用状況と分析

エンドポイント	メソッド	説明
/api/usage/history	GET	使用履歴
/api/usage/logs	GET	使用ログ
/api/usage/request-logs	GET	リクエスト単位のログ
/api/usage/[connectionId]	GET	接続ごとの使用状況
/api/usage/token-limits	GET/POST/DELETE	APIキーごとのトークン上限予算
/api/usage/model-latency-stats	GET	プロバイダー／モデルごとのローリングレイテンシ集計（平均値／p50／p95／p99、成功率）。フィルター：windowHours／minSamples／maxRows／provider／model（#6873）
/api/usage/cache-health	GET	call_logs に基づくプロンプトキャッシュの健全性サマリー — 書き込み／読み取り比率、書き込みサイズ分布のp50／p90／p99、大量書き込みの集中度、モデルごとの内訳、および healthy／degraded／thrash／no-data の判定。クエリパラメーターは range（1h|24h|7d|30d、デフォルトは 24h）と、任意の model（#8827）

設定

エンドポイント	メソッド	説明
/api/settings	GET/PUT/PATCH	一般設定
/api/settings/proxy	GET/PUT	ネットワークプロキシ設定
/api/settings/proxy/test	POST	プロキシ接続をテスト
/api/settings/ip-filter	GET/PUT	IP許可リスト／ブロックリスト
/api/settings/thinking-budget	GET/PUT	思考／推論リクエストの書き換えモード（パススルー／自動削除／カスタム／適応型）。圧縮とは独立しています。THINKING_BUDGET.md を参照してください。
/api/settings/system-prompt	GET/PUT	グローバルシステムプロンプト
/api/settings/compression	GET/PUT	グローバル圧縮設定
/api/settings/purge-request-history	POST	リクエストログの行とローカルの呼び出しログアーティファクトを消去

コンテキストと圧縮

エンドポイント	メソッド	説明
/api/compression/preview	POST	off/lite/standard/aggressive/ultra/RTK/stacked 圧縮をプレビュー
/api/compression/language-packs	GET	利用可能な Caveman 言語パックを一覧表示
/api/compression/rules	GET	Caveman ルールのメタデータを一覧表示
/api/context/caveman/config	GET/PUT	Caveman 固有設定のエイリアス
/api/context/rtk/config	GET/PUT	カスタムフィルターと生出力の保持を含む、RTK 固有の設定
/api/context/rtk/filters	GET	RTK フィルターカタログとカスタムフィルターの診断
/api/context/rtk/test	POST	テキストペイロードに対して RTK のプレビュー／テストを実行
/api/context/rtk/raw-output/[id]	GET	ポインター ID を使用して、保持された編集済み生出力を読み取り
/api/context/combos	GET/POST	圧縮コンボの一覧表示／作成
/api/context/combos/[id]	GET/PUT/DELETE	圧縮コンボの詳細表示／更新／削除
/api/context/combos/[id]/assignments	GET/PUT	圧縮コンボをルーティングコンボに割り当て
/api/context/analytics	GET	圧縮分析のエイリアス

監視

エンドポイント	メソッド	説明
/api/sessions	GET	アクティブなセッションの追跡
/api/rate-limits	GET	アカウントごとのレート制限
/api/monitoring/health	GET	ヘルスチェックとプロバイダーの概要（catalogCount、configuredCount、activeCount、monitoredCount）。管理ビューには credentialHealth が含まれます。内容は、プローブキャッシュのスカラー値、failed>0 の場合の failedConnections、および staleDbNonOkCount（ゲージではなく SQLite の固定 test_status）です。MONITORING_GUIDE.mdを参照してください。
/api/cache/stats	GET/DELETE	キャッシュの統計／クリア
/api/modality-bridge/stats	GET	メモリ内の attempts、成功数／bridged、失敗数、キャッシュヒット数、totalLatencyMs、latencySamples、サンプル数を分母とする averageLatencyMs、および最終使用時刻（再起動時にリセット、管理認証が必要）
/api/modality-bridge/video/runtime	GET	管理認証／プローブの前に厳格な信頼済みループバックチェックを実施。サニタイズされた FFmpeg/ffprobe の可用性とバージョンを返します（no-store）
/api/modality-bridge/video/extract	POST	内部向けの認証済み信頼済みループバック用バイトブローカー。入力上限は 50 MiB、キューは制限付き、出力上限は 32 MiB、容量超過時は 503、切断時は 499、期限超過時は 504。公開アップロード API ではありません

バックアップとエクスポート／インポート

エンドポイント	メソッド	説明
/api/db-backups	GET	利用可能なバックアップを一覧表示
/api/db-backups	PUT	手動バックアップを作成
/api/db-backups	POST	指定したバックアップから復元
/api/db-backups/export	GET	データベースを .sqlite ファイルとしてダウンロード
/api/db-backups/import	POST	.sqlite ファイルをアップロードしてデータベースを置換
/api/db-backups/exportAll	GET	完全なバックアップを .tar.gz アーカイブとしてダウンロード

クラウド同期

エンドポイント	メソッド	説明
/api/sync/cloud	各種	クラウド同期操作
/api/sync/initialize	POST	同期を初期化
/api/cloud/*	各種	クラウド管理

トンネル

エンドポイント	メソッド	説明
/api/tunnels/cloudflared	GET	ダッシュボード向けに Cloudflare Quick Tunnel のインストール／実行状況を取得
/api/tunnels/cloudflared	POST	Cloudflare Quick Tunnel を有効化または無効化（action=enable/disable）
/api/tunnels/ngrok	GET	ダッシュボード向けに ngrok Tunnel の実行状況を取得
/api/tunnels/ngrok	POST	ngrok Tunnel を有効化または無効化（action=enable/disable）

CLI ツール

エンドポイント	メソッド	説明
/api/cli-tools/claude-settings	GET	Claude CLI の状態
/api/cli-tools/codex-settings	GET	Codex CLI の状態
/api/cli-tools/droid-settings	GET	Droid CLI の状態
/api/cli-tools/openclaw-settings	GET	OpenClaw CLI の状態
/api/cli-tools/runtime/[toolId]	GET	汎用 CLI ランタイム

CLI のレスポンスには、installed、runnable、command、commandPath、runtimeMode、reason が含まれます。

ACP エージェント

エンドポイント	メソッド	説明
/api/acp/agents	GET	検出されたすべてのエージェント（組み込み + カスタム）を状態とともに一覧表示
/api/acp/agents	POST	カスタムエージェントを追加、または検出キャッシュを更新
/api/acp/agents	DELETE	id クエリパラメーターで指定したカスタムエージェントを削除

GET レスポンスには、agents[]（id、name、binary、version、installed、protocol、isCustom）および summary（total、installed、notFound、builtIn、custom）が含まれます。

耐障害性とレート制限

エンドポイント	メソッド	説明
/api/resilience	GET/PATCH	リクエストキュー、接続クールダウン、プロバイダーブレーカー、および待機設定を取得／更新
/api/resilience/reset	POST	プロバイダーのサーキットブレーカーをリセット
/api/resilience/model-cooldowns	GET	有効な（プロバイダー、接続、モデル）単位のロックアウトを残り時間順で一覧表示
/api/resilience/model-cooldowns	DELETE	モデルのロックアウトを解除 — 本文に {provider, model}、またはすべて削除する場合は {all: true} を指定
/api/rate-limits	GET	アカウントごとのレート制限状態
/api/rate-limit	GET	グローバルなレート制限設定

4 つの /api/resilience/* ルートはすべて 管理認証（requireManagementAuth）を必要とします。プロバイダーブレーカー、接続クールダウン、モデルロックアウトの詳しい違いについては、耐障害性（詳細）を参照してください。

評価

エンドポイント	メソッド	説明
/api/evals	GET/POST	評価スイートを一覧表示／評価を実行

ポリシー

エンドポイント	メソッド	説明
/api/policies	GET/POST/DELETE	ルーティングポリシーを管理

コンプライアンス

エンドポイント	メソッド	説明
/api/compliance/audit-log	GET	コンプライアンス監査ログ（直近 N 件）

v1beta（Gemini 互換）

エンドポイント	メソッド	説明
/v1beta/models	GET	Gemini 形式でモデルを一覧表示
/v1beta/models/{...path}	POST	Gemini の generateContent エンドポイント

これらのエンドポイントは、ネイティブな Gemini SDK との互換性を必要とするクライアント向けに、Gemini の API 形式を再現しています。

内部／システム API

エンドポイント	メソッド	説明
/api/init	GET	アプリケーションの初期化チェック（初回実行時に使用）
/api/tags	GET	Ollama 互換のモデルタグ（Ollama クライアント用）
/api/restart	POST	サーバーの正常な再起動を開始
/api/shutdown	POST	サーバーの正常なシャットダウンを開始
/api/system/env/repair	POST	OAuth プロバイダーの環境変数を修復

注: これらのエンドポイントは、システム内部または Ollama クライアントとの互換性のために使用されます。通常、エンドユーザーが呼び出すことはありません。

OAuth 環境の修復 (v3.6.1+)

POST /api/system/env/repair
Content-Type: application/json

{
  "provider": "claude-code"
}

特定のプロバイダーについて、欠落または破損した OAuth 環境変数を修復します。以下を返します。

{
  "success": true,
  "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
  "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}

---

音声文字起こし

POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data

設定済みの任意の STT プロバイダーを使用して、音声ファイルを文字起こしします。最初のパス セグメントでネイティブプロバイダー（openai/…、deepgram/…）を選択します。別ベンダーの モデルを再公開するゲートウェイでは、修飾された ID （openrouter/deepgram/nova-3）を使用します。

リクエスト:

curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@recording.mp3" \
  -F "model=openai/whisper-1"

レスポンス:

{
  "text": "こんにちは。これは文字起こしされた音声コンテンツです。",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}

モデル ID の例: openai/whisper-1（OpenAI キーが必要）、 openrouter/deepgram/nova-3（OpenRouter キーが必要）、 deepgram/nova-3（ネイティブの Deepgram キーが必要）。修飾されていない deepgram/nova-3 リクエストでは、OpenRouter は使用されません。

対応形式: mp3、wav、m4a、flac、ogg、webm。

---

Ollama 互換性

Ollama の API 形式を使用するクライアント向け:

# チャットエンドポイント（Ollama 形式）
POST /v1/api/chat

# モデル一覧（Ollama 形式）
GET /api/tags

リクエストは、Ollama 形式と内部形式の間で自動的に変換されます。

トークン付き VS Code / ヘッダーなしエイリアス

インテグレーションで Authorization ヘッダーを挿入できず、API キーをベース URL に埋め込む必要がある場合は、これらのエイリアスを使用してください。

# OpenAI 形式のカタログエイリアス
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# OpenAI 形式のチャットエイリアス
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Ollama 形式のエイリアス
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

例:

curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'

注意:

• トークン付きエイリアスは /v1/* および /api/tags と同じハンドラーを再利用するため、レスポンス形式は同一です。
• クライアントがカスタムヘッダーをサポートしている場合は、可能な限り Authorization: Bearer ... を使用してください。
• URL ベースのトークンは、リバースプロキシのログ、ブラウザー履歴、および OmniRoute 外部のテレメトリに記録される可能性があります。デフォルトの認証方式ではなく、互換性のためのオプションとして扱ってください。

---

テレメトリ

# レイテンシーテレメトリの概要を取得（プロバイダーごとの p50/p95/p99）
GET /api/telemetry/summary

レスポンス:

{
  "providers": {
    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
  }
}

---

予算

# すべての API キーの予算状況を取得
GET /api/usage/budget

# 予算を設定または更新
POST /api/usage/budget
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "dailyLimitUsd": 5.00,
  "weeklyLimitUsd": 30.00,
  "monthlyLimitUsd": 100.00,
  "warningThreshold": 0.8,
  "resetInterval": "monthly"
}

スキーマに関する注意事項 (setBudgetSchema): apiKeyId は必須です。dailyLimitUsd、weeklyLimitUsd、monthlyLimitUsd のうち、少なくとも1つはゼロより大きい値である必要があります。オプションのフィールド: warningThreshold（0～1）、resetInterval（daily | weekly | monthly）、resetTime（HH:MM）。従来の {keyId, limit, period} 形式を使用すると、400 Bad Request が返されます。

トークン制限

API キーごとの トークン 予算（上記の USD ベースの予算とは別）。リクエストパス上でインラインに適用されます。キーの現在のウィンドウ使用量が上限に達すると、リクエストは 429 Too Many Requests で拒否されます。制限は、特定の model、provider にスコープ設定することも、キー全体に global に適用することもできます。複数の制限がリクエストに一致する場合は、最も厳しい制限が優先されます。

# キーのトークン制限を一覧表示（現在のウィンドウ使用量を含む）
GET /api/usage/token-limits?apiKeyId=key-123

# トークン制限を作成または更新
POST /api/usage/token-limits
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "scopeType": "model",
  "scopeValue": "openai/gpt-4o",
  "tokenLimit": 1000000,
  "resetInterval": "monthly",
  "enabled": true
}

# ID を指定してトークン制限を削除
DELETE /api/usage/token-limits?id=tl-abc

スキーマに関する注記（setTokenLimitSchema）：apiKeyId と scopeType（model | provider | global）は必須です。scopeType が global でない限り、scopeValue は必須です（例：model スコープではモデル ID、provider スコープではプロバイダー ID）。tokenLimit は正の整数である必要があります（文字列から変換されます）。任意項目：id（作成時は省略し、更新時は指定）、resetInterval（daily | weekly | monthly、デフォルトは monthly）、resetTime（HH:MM）、enabled（デフォルトは true）。GET レスポンスでは、各制限に tokensUsed、remaining、windowStart、periodStartAt、nextResetAt が追加されます。これは管理クラスのエンドポイントです（認証は authz パイプラインによって一元的に適用されます）。

リクエスト処理

1. クライアントが /v1/* にリクエストを送信
2. ルートハンドラーが handleChat、handleEmbedding、handleAudioTranscription、または handleImageGeneration を呼び出す
3. モデルを解決（プロバイダー/モデルの直接指定、またはエイリアス/コンボ）
4. アカウントの可用性をフィルタリングし、ローカル DB から認証情報を選択
5. チャットの場合：handleChatCore がセマンティック/シグネチャキャッシュを確認し、コンボの圧縮設定を解決
6. 有効な場合、プロバイダー向け変換の前にプロアクティブ圧縮を実行（lite、Caveman、RTK、またはそれらのスタック）
7. プロバイダーエグゼキューターがアップストリームリクエストを送信
8. レスポンスをクライアント形式に再変換（チャット）するか、そのまま返却（埋め込み/画像/音声）
9. 使用量、圧縮分析、リクエストログを記録
10. エラー発生時、コンボルールに従ってフォールバックを適用

アーキテクチャの完全なリファレンス：ARCHITECTURE.md

---

コンボ管理

上位レベルのルーティングコンボ（/api/combos* で概要を説明済み）は、モデル ID パターンから 1:1 でマッピングすることもでき、OpenAI 形式のモデル ID をコンボへ透過的にリダイレクトできます。

メソッド	パス	説明
GET	/api/model-combo-mappings	すべてのモデル→コンボマッピングを一覧表示
POST	/api/model-combo-mappings	マッピングを作成 — 本文：{pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	単一のマッピングを取得
PUT	/api/model-combo-mappings/[id]	既存のマッピングのフィールドを更新
DELETE	/api/model-combo-mappings/[id]	マッピングを削除

認証： 管理セッション/API キー（requireManagementAuth）。

---

Webhook

OmniRoute イベント（リクエスト完了、クォータ枯渇、キーのローテーションなど）に対する送信 Webhook サブスクリプション。

メソッド	パス	説明
GET	/api/webhooks	Webhook の一覧を取得（シークレットは <prefix>... にマスクされます）
POST	/api/webhooks	Webhook を作成 — ボディ: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	Webhook を取得
PUT	/api/webhooks/[id]	url/events/secret/description を更新
DELETE	/api/webhooks/[id]	Webhook を削除
POST	/api/webhooks/[id]/test	Webhook URL にテストペイロードを送信し、配信ステータスを返す

認証: 管理セッション/API キー（requireManagementAuth）。

---

登録済みキー（自動管理）

自動キー管理サブシステムが、基盤となるプロバイダー/アカウントに対して、日次/時間単位のクォータ付き API キーを発行およびローテーションするために使用します。

メソッド	パス	説明
GET	/api/v1/registered-keys	登録済みキーの一覧を取得（マスクされたプレフィックスのみ）
POST	/api/v1/registered-keys	新しい登録済みキーを発行 — ボディ: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}。生のキーは 一度だけ 返されます。クォータにより拒否された場合は 429 を返します。
GET	/api/v1/registered-keys/[id]	登録済みキーのメタデータを取得（生のキー情報は含まれません）
DELETE	/api/v1/registered-keys/[id]	登録済みキーを失効
POST	/api/v1/registered-keys/[id]/revoke	明示的な失効エンドポイント（DELETE と同じ効果）

認証: Bearer API キー（isAuthenticated）。/v1/quotas/check および /v1/issues/report も参照してください。

---

エージェントプロトコル

OmniRoute ユーザーに代わってリモートで実行されるクラウドエージェントタスク（Claude Code、Codex Cloud、OpenHands など）。

メソッド	パス	説明
GET	/api/v1/agents/tasks	タスクを一覧表示 — 任意の ?provider=、?status=、?limit=（1～500、デフォルトは 50）
POST	/api/v1/agents/tasks	タスクを作成 — リクエストボディは CreateCloudAgentTaskSchema（providerId、prompt、source、options?）で検証されます。タスクエンベロープとともに 201 を返します
DELETE	/api/v1/agents/tasks?id=...	タスクを削除
GET	/api/v1/agents/tasks/[id]	タスクを読み取り — external_id が設定されている場合、上流のクラウドエージェントからステータスを同期的に更新します
POST	/api/v1/agents/tasks/[id]	判別可能なアクション：{action: "approve"}、{action: "message", message}、または {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	id で指定されたタスクを削除

認証： すべてのメソッドで管理認証（requireCloudAgentManagementAuth）が必要です。v3.8.0 より前は認証不要でした。破壊的変更についてはコミット 588a0333 を参照してください。

# Claude Code のクラウドタスクを作成
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'

---

管理プロキシ

プロバイダー、アカウント、またはグローバルに割り当て可能な送信 HTTP(S)/SOCKS プロキシ。

メソッド	パス	説明
GET	/api/v1/management/proxies	プロキシを一覧表示（?id= を指定すると 1 件を返し、?id=&where_used=1 を指定すると割り当てグラフを返します）
POST	/api/v1/management/proxies	プロキシを作成 — リクエストボディは createProxyRegistrySchema で検証されます
PATCH	/api/v1/management/proxies	プロキシを更新 — リクエストボディは updateProxyRegistrySchema で検証されます（id が必要）
DELETE	/api/v1/management/proxies?id=...&force=1	プロキシを削除（割り当てを解除するには force=1 を使用）
GET	/api/v1/management/proxies/assignments	割り当てを一覧表示 — proxy_id、scope、scope_id でフィルタリング可能。接続に対するアクティブなプロキシを解決するには resolve_connection_id=<id> を指定します
PUT	/api/v1/management/proxies/assignments	割り当て — リクエストボディは proxyAssignmentSchema（{scope, scopeId?, proxyId?}）で検証されます。ディスパッチャーキャッシュをクリアします
PUT	/api/v1/management/proxies/bulk-assign	一括割り当て — リクエストボディは bulkProxyAssignmentSchema（{scope, scopeIds[], proxyId?}）で検証されます
GET	/api/v1/management/proxies/health?hours=24	指定期間内のプロキシの稼働状態（成功数／失敗数、レイテンシ）を集計します

認証： すべてのルートで管理セッション/API キー（requireManagementAuth）が必要です。

タスク説明にある POST /api/v1/management/proxies/[id]/assignments および POST /api/v1/management/proxies/[id]/health は、上記のフラットな /assignments および /health ルートによって提供されます。コードベースに ID ごとのサブルートはありません。

---

レジリエンス（拡張）

OmniRoute は、互いに独立した 3 つの一時的障害メカニズムを提供します。以下の管理エンドポイントを使用して、運用担当者はそれらの状態を確認および上書きできます。

スコープ	状態の保存先	参照	リセット / クリア
プロバイダーブレーカー	domain_circuit_breakers + インメモリ	/api/monitoring/health	POST /api/resilience/reset
接続クールダウン	プロバイダー接続の rateLimitedUntil	/api/rate-limits, /api/providers/[id]	（遅延方式で再有効化。プロバイダーの PUT でクリア）
モデルロックアウト	インメモリのモデル可用性レジストリ	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience は、providerBreaker.oauth および providerBreaker.apikey でプロバイダーブレーカーのオーバーライドを受け付けます。各プロファイルは degradationThreshold、failureThreshold、resetTimeoutMs をサポートします。同じフィールドは「Dashboard → Settings → Resilience」にも表示されます。

# 単一モデルのロックアウトをクリア
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o-mini"}'

# すべてのロックアウトを削除
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

概念の完全なリファレンスおよびブレーカーのデフォルト値については、CLAUDE.md →「レジリエンスのランタイム状態」を参照してください。

---

スキル

カスタム実行可能ハンドラーを使用して OmniRoute を拡張するためのスキルフレームワークと、マーケットプレイス連携です。

メソッド	パス	説明
GET	/api/skills	インストール済みのスキルを一覧表示 — ?q=、?mode=on|off|auto、?source=skillsmp|skillssh|local で絞り込み可能、ページネーション対応
GET	/api/skills/[id]	1 つのスキルを取得
PUT	/api/skills/[id]	スキルを更新（名前、説明、モード、スキーマ、ハンドラー、タグ）
DELETE	/api/skills/[id]	スキルをアンインストール
POST	/api/skills/install	未加工のマニフェストからスキルをインストール — 本文: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	最近のスキル実行を一覧表示（入力、出力、実行時間を含む監査証跡）
GET	/api/skills/marketplace?q=...	SkillsMP マーケットプレイスから検索結果または人気スキル一覧を取得（skillsmpApiKey 設定が必要）
POST	/api/skills/marketplace/install	SkillsMP から ID を指定してスキルをインストール
GET	/api/skills/skillssh?q=&limit=	skills.sh レジストリを検索
POST	/api/skills/skillssh/install	skills.sh から ID を指定してスキルをインストール

認証: 管理セッション/API キー。マーケットプレイス検索ルートでは、管理認証または Bearer API キー（isAuthenticated）のいずれかを使用できます。

---

メモリ

API キー／セッション単位でスコープ設定された、永続的な会話／事実メモリストア。

メソッド	パス	説明
GET	/api/memory	メモリ一覧 — ?apiKeyId=, ?type=, ?sessionId=, ?q=、および offset/limit または page/limit によるページネーション
POST	/api/memory	メモリを作成 — Zod によって検証される本文: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	単一のメモリを取得
DELETE	/api/memory/[id]	メモリを削除
GET	/api/memory/health	メモリサブシステムの健全性（DB 接続、埋め込みバックエンド、ベクトルインデックスの状態）

認証: 管理セッション／API キー（requireManagementAuth）。type の列挙値: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL（src/lib/memory/types.ts の MemoryType を参照）。

---

MCP サーバー

OmniRoute には、3 つのトランスポート（stdio、SSE、streamable-http）とスコープ付きツールを備えた Model Context Protocol サーバーが組み込まれています。以下のダッシュボードエンドポイントは、ステータス／監査データを読み取り、HTTP トランスポートをプロキシします。

メソッド	パス	説明
GET	/api/mcp/status	ハートビート、トランスポート、オンライン状態、最終呼び出し、上位ツール、24 時間の成功率
GET	/api/mcp/tools	name, description, scopes, phase, auditLevel, sourceEndpoints を含む MCP ツール一覧
GET	/api/mcp/sse	SSE トランスポート用の SSE ストリームを開く（MCP が無効、またはトランスポートが一致しない場合は 503 を返す）
POST	/api/mcp/sse	SSE トランスポートで JSON-RPC フレームを送信
GET	/api/mcp/stream	Streamable HTTP トランスポートの SSE 側を開く（サーバー起点のメッセージ）
POST	/api/mcp/stream	Streamable HTTP トランスポートで JSON-RPC フレームを送信
DELETE	/api/mcp/stream	Streamable HTTP セッションを終了
GET	/api/mcp/audit	監査ログを照会 — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	監査統計を集計（合計、成功率、平均所要時間、上位ツール）

認証: sse／stream トランスポートは MCP 固有の認証方式（mcp スコープを持つ Bearer API キー）に従います。status／tools／audit* ルートはダッシュボードから読み取り可能です（ダッシュボードホストへのアクセスに必要な認証以外に、追加の認証は不要です）。

どちらの HTTP トランスポートも settings.mcpEnabled と settings.mcpTransport によって制御されます。トランスポートが一致しない場合は 400、MCP が無効な場合は 503 が返されます。

---

A2A サーバー

OmniRoute は、A2A（Agent-to-Agent）JSON-RPC 2.0 エンドポイントに加え、確認やダッシュボードで使用するための REST ラッパーを公開します。

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # OMNIROUTE_API_KEY が設定されていない場合は省略可能
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Route this coding task"}]
  }
}

サポートされるメソッド（すべて settings.a2aEnabled によって制御されます）：

メソッド	説明
message/send	スキルを同期実行し、{task, artifacts, metadata} を返します
message/stream	同じスキルセットをストリーミング SSE で実行します
tasks/get	taskId を指定してタスクを取得します
tasks/cancel	taskId を指定してタスクをキャンセルします

組み込みスキル：smart-routing、quota-management、provider-discovery、cost-analysis、health-report。

エージェントカード

GET /.well-known/agent.json

公開 A2A エージェントカード（名前、説明、機能、スキルカタログ、認証スキーム）を返します。公開キャッシュの有効期間は 1 時間です。認証は不要です。

REST ヘルパー

メソッド	パス	説明
GET	/api/a2a/status	A2A の有効状態、タスク統計、キャッシュされたエージェントカードの概要
GET	/api/a2a/tasks	タスク一覧 — ?state=submitted|working|completed|failed|cancelled、?skill=、?limit=（≤200）、?offset=
POST	/api/a2a/tasks	（REST ヘルパーとしては未実装 — JSON-RPC の message/send を使用して作成）
GET	/api/a2a/tasks/[id]	1 件のタスクを取得
POST	/api/a2a/tasks/[id]/cancel	タスクをキャンセル

認証： REST ヘルパーは管理認証なしで動作し、ダッシュボードから参照できます。JSON-RPC の /a2a ルートは、設定されている場合に Bearer OMNIROUTE_API_KEY を使用します。

---

クラウド、評価、アセスメント

メソッド	パス	説明
POST	/api/cloud/auth	Bearer キーを検証し、マスクされたプロバイダー接続とモデルエイリアスをクラウド同期クライアント向けに返します
POST	/api/cloud/credentials/update	クラウド同期されたプロバイダーの暗号化済み認証情報を更新します
POST	/api/cloud/model/resolve	ローカルルーティングテーブルを使用して、論理モデル ID を具体的なプロバイダー／モデルに解決します
GET	/api/cloud/models/alias	クラウド同期に公開されるモデルエイリアスの一覧を取得します
GET	/api/assess	最新のアセスメント分類（プロバイダー／モデルごと）を読み取ります
POST	/api/assess	アセスメントを実行 — 本文：`{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	組み込み評価スイートと最新の実行結果を一覧表示します
POST	/api/evals	評価の実行を開始します
POST	/api/evals/suites	カスタム評価スイートを作成 — 本文は evalSuiteSaveSchema によって検証されます
GET	/api/evals/suites/[id]	カスタム評価スイートを取得します

認証： /api/cloud/auth は Bearer キーを直接検証します。その他の /api/cloud/*、/api/evals/*、および /api/assess ルートには、管理セッションまたは API キーが必要です。/api/assess の POST は、判別可能なユニオン型のスコープスキーマとともに validateBody を使用します。

---

ACP（Agent Client Protocol）管理

子プロセスとして実行されます。これらのエンドポイントは、ACP エージェントの検出とカスタムエージェントの登録を管理します。

メソッド	パス	説明
GET	/api/acp/agents	既知のすべての CLI エージェント（組み込み + カスタム）を、インストール状態、バージョン、バイナリとともに一覧表示
POST	/api/acp/agents	カスタム ACP エージェントを登録、またはキャッシュを更新 — 本文: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} または {action: "refresh"}
DELETE	/api/acp/agents	カスタム ACP エージェントを削除 — クエリパラメーター: ?id=<agentId>

レスポンス例（GET /api/acp/agents）:

{
  "agents": [
    {
      "id": "claude",
      "name": "Claude Code CLI",
      "binary": "claude",
      "version": "1.0.45",
      "installed": true,
      "protocol": "stdio",
      "providerAlias": "claude",
      "isCustom": false
    },
    {
      "id": "my-custom-cli",
      "name": "My Custom CLI",
      "installed": false,
      "protocol": "stdio",
      "providerAlias": "my-provider",
      "isCustom": true
    }
  ],
  "cacheTtlMs": 60000,
  "cacheAge": 1234
}

認証: 管理セッション（ダッシュボードの auth_token cookie）または 管理スコープの API キーが必要です。

詳細については、ACP フレームワークを参照してください。

---

分析とオブザーバビリティ

ルーティング、圧縮、プロバイダーの多様性を監視するためのリアルタイム分析エンドポイントです。これらは /dashboard/analytics/* ページで使用されます。

自動ルーティング分析

メソッド	パス	説明
GET	/api/analytics/auto-routing	自動ルーティングの集計統計: 総呼び出し数、戦略分布、階層分布、上位プロバイダー
GET	/api/analytics/auto-routing?days=7	時間枠を指定した統計（デフォルトは 24 時間）

レスポンス例:

{
  "window": "24h",
  "totalCalls": 1234,
  "strategyBreakdown": {
    "rules": 800,
    "cost": 200,
    "latency": 150,
    "sla-aware": 50,
    "lkgp": 34
  },
  "tierBreakdown": {
    "ultra": 100,
    "pro": 500,
    "standard": 400,
    "free": 234
  },
  "topProviders": [
    { "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
    { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
  ]
}

圧縮分析

メソッド	パス	説明
GET	/api/analytics/compression	圧縮の集計統計: 削減されたトークン数、削減率、モード分布、エンジン使用状況

レスポンス例:

{
  "window": "24h",
  "totalOriginalTokens": 5000000,
  "totalCompressedTokens": 3500000,
  "totalSavings": 1500000,
  "savingsPct": 30.0,
  "modeBreakdown": {
    "lite": 400,
    "standard": 600,
    "aggressive": 100,
    "ultra": 50,
    "rtk": 84
  },
  "engineBreakdown": {
    "caveman": 800,
    "rtk": 434
  }
}

プロバイダー多様性の追跡

メソッド	パス	説明
GET	/api/analytics/diversity	Shannon エントロピーに基づく多様性追跡: プロバイダーの分散度を測定し、単一障害点を防止

レスポンス例:

{
  "window": "24h",
  "shannonEntropy": 2.45,
  "maxEntropy": 3.17,
  "diversityRatio": 0.77,
  "providerUsage": {
    "openai": 0.4,
    "anthropic": 0.25,
    "google": 0.2,
    "kiro": 0.15
  },
  "warnings": ["OpenAI がトラフィックの 40% を占めています — 分散を検討してください"]
}

認証: 管理セッションまたは管理スコープの API キーが必要です。

---

管理者向け操作

運用管理用の管理者専用エンドポイント。

メソッド	パス	説明
GET	/api/admin/concurrency	現在の同時実行数制限（グローバルおよびプロバイダーごと）を取得
POST	/api/admin/concurrency	同時実行数制限を更新 — 本文: {global?: number, perProvider?: Record<string, number>}

認証: 管理者スコープを持つ管理セッションが必要です。

---

CLI ツール管理

OmniRoute と統合する CLI ツール（antigravity、commandCode、 devin-cli など）を管理します。完全な一覧については、プロバイダーリファレンスを参照してください。

メソッド	パス	説明
GET	/api/cli-tools/all-statuses	すべての CLI ツールのステータス（インストール状況、バージョン、最終確認日時）
GET	/api/cli-tools/status	1 つの CLI ツールの詳細なステータス（?tool= クエリ）
POST	/api/cli-tools/apply	ツール用に生成された設定を書き込みます（dryRun ではプレビューを表示。コンテナ化されている場合は 422 + containerEphemeralTarget。migration は従来の Codex YAML に関する注記）
GET	/api/cli-tools/backups	CLI ツール設定のバックアップを一覧表示します
POST	/api/cli-tools/backups	すべての CLI ツール設定のバックアップを作成します
POST	/api/cli-tools/backups	復元：同じエンドポイントの本文に {tool, backupId} を指定すると、そのバックアップを復元します
GET	/api/cli-tools/antigravity-mitm	Antigravity MITM プロキシのステータス（「antigravity-mitm」CLI ツール）
POST	/api/cli-tools/antigravity-mitm/alias	antigravity-mitm のエイリアスを設定します

認証: 管理セッションが必要です。

---

エージェントスキル

AI エージェントスキル（OpenAI のカスタム GPT に似たエージェント向け機能）を管理します。

メソッド	パス	説明
GET	/api/agent-skills	すべてのエージェントスキル（組み込み + カスタム）の一覧を取得
GET	/api/agent-skills/[id]	特定のエージェントスキルを取得
POST	/api/agent-skills	カスタムエージェントスキルを作成 — 本文: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	カスタムエージェントスキルを更新
DELETE	/api/agent-skills/[id]	カスタムエージェントスキルを削除
GET	/api/agent-skills/[id]/raw	未加工のプロンプトとメタデータを取得（実行なし）
POST	/api/agent-skills/generate	自然言語による説明から新しいスキルを AI で生成

認証: 管理セッションまたは管理スコープの API キーが必要です。

---

キャッシュ管理

セマンティックキャッシュと推論キャッシュを管理します。

メソッド	パス	説明
GET	/api/cache	キャッシュの概要：エントリ総数、ヒット率、ディスク上のサイズ
GET	/api/cache/entries	キャッシュ済みエントリの一覧（ページネーション対応）
DELETE	/api/cache/entries	キャッシュエントリを削除（クエリパラメータでフィルタリング）
GET	/api/cache/stats	キャッシュの詳細統計（プロバイダー別、モデル別）
GET	/api/cache/reasoning	推論キャッシュの状態（推論の再現用）
DELETE	/api/cache/reasoning	推論キャッシュをクリア — クエリパラメータ：?toolCallId=<id>（単一）、?provider=<p>、またはパラメータなし（すべて）

認証： 管理セッションが必要です。

---

メモリシステム

永続メモリ（FTS5 + ベクトル埋め込み）を管理します。

メソッド	パス	説明
GET	/api/memory	メモリエントリの一覧（スコープ、タイプ、検索クエリでフィルタリング）
POST	/api/memory	新しいメモリエントリを作成 — 本文：{scope, type, content, metadata?}
GET	/api/memory/[id]	特定のメモリエントリを取得
PUT	/api/memory/[id]	メモリエントリを更新
DELETE	/api/memory/[id]	メモリエントリを削除
GET	/api/memory?q=	メモリを検索（FTS5 + ベクトル）— 同じレスポンスに統計情報も含まれます

認証： 管理セッションまたは管理スコープの API キーが必要です。

---

Webhook

イベントの Webhook サブスクリプションを管理します。

メソッド	パス	説明
GET	/api/webhooks	すべての Webhook サブスクリプションを一覧表示
POST	/api/webhooks	Webhook サブスクリプションを作成 — 本文：{url, events[], secret?, active?}
GET	/api/webhooks/[id]	特定の Webhook サブスクリプションを取得
PUT	/api/webhooks/[id]	Webhook サブスクリプションを更新
DELETE	/api/webhooks/[id]	Webhook サブスクリプションを削除
GET	/api/webhooks/[id]/deliveries	Webhook の配信履歴（成功／失敗ログ）を一覧表示
POST	/api/webhooks/[id]/test	Webhook にテストイベントを送信

認証： 管理セッションが必要です。

すべてのイベントタイプについては、Webhook フレームワークを参照してください。

---

Skills Framework

Skills（エージェント拡張フレームワーク）を管理します。

メソッド	パス	説明
GET	/api/skills	インストール済みのすべてのSkill（組み込み + カスタム）を一覧表示します
POST	/api/skills/install	ローカルパスまたはURLからSkillをインストールします
DELETE	/api/skills/[id]	Skillをアンインストールします
PUT	/api/skills/[id]	Skillを有効化または無効化します — body: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	Skillを実行します — body: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	すべてのSkillの実行履歴を一覧表示します（?apiKeyId=でフィルタリング）

認証: 管理セッションまたは管理スコープのAPIキーが必要です。

詳細については、Skills Frameworkを参照してください。

---

プラグイン

OmniRouteプラグイン（サードパーティ製拡張機能）を管理します。

メソッド	パス	説明
GET	/api/plugins	インストール済みのプラグインを一覧表示します
POST	/api/plugins/marketplace/install	マーケットプレイスからプラグインをインストールします
DELETE	/api/plugins/[name]	プラグインをアンインストールします
POST	/api/plugins/[name]/activate	プラグインを有効化します
POST	/api/plugins/[name]/deactivate	プラグインを無効化します
GET	/api/plugins/[name]/config	プラグイン設定を取得します
PUT	/api/plugins/[name]/config	プラグイン設定を更新します

認証: 管理セッションが必要です。

詳細については、Plugins Frameworkを参照してください。

---

シャドールーティング

プロバイダーのシャドー/A-B比較は、独立したRESTインターフェースではありません。コンボルーティングを通じて設定します（Auto-Comboを参照）。コンボごとの比較メトリクスは、GET /api/combos/metricsで提供されます。

---

ガードレール

ランタイムガードレール（PII検出、プロンプトインジェクション検出、ビジョンブリッジング）を確認します。ガードレールはすべてのリクエストで実行されます。呼び出しごとにオプトアウトするには、x-omniroute-disabled-guardrailsリクエストヘッダーを使用します。永続的な有効化/無効化を行うインターフェースはありません。

メソッド	パス	説明
GET	/api/guardrails	登録済みガードレールとそのステータス（名前/有効/優先度）を一覧表示します
POST	/api/guardrails/test	サンプル入力に対して呼び出し前パイプラインをドライランします — body: {input, disabledGuardrails?}

認証: 管理セッションが必要です。

詳細については、セキュリティ > ガードレールを参照してください。

---

---

認証

4つの認証情報ファミリー（ダッシュボードセッション、ローカルCLIトークン、oma_live_… Access Token、管理スコープ付きAPIキー）と、推論キーとの違いについては、管理認証を参照してください。

• ダッシュボードルート（/dashboard/*）では、auth_token Cookieを使用します
• ログインでは保存済みのパスワードハッシュを使用し、利用できない場合はINITIAL_PASSWORDにフォールバックします
• requireLoginは/api/settings/require-login経由で切り替えられます
• REQUIRE_API_KEY=trueの場合、/v1/*ルートではBearer APIキーが必要になることがあります
• このリファレンスにおける「管理トークン」/「管理スコープ付きAPIキー」は、上記ガイドに記載されているファミリーのいずれかを意味し、未定義の追加シークレット種別を指すものではありません

破壊的変更（v3.8.0） — /api/v1/agents/tasks/*およびクールダウン管理エンドポイントでは、管理認証（ダッシュボードのauth_token Cookieまたは管理スコープ付きAPIキー）が必須になりました。以前、認証なしでこれらのルートを呼び出していたクライアントは、401 Unauthorizedを受け取ります。コミット588a0333（fix(auth): require management auth for agent and cooldown APIs）を参照してください。