コンテンツにスキップ
OmniRoute Docs

言語を選択

現在の言語: 日本語

OmniRoute source

API Reference (日本語)

目次

Section titled “目次”

チャット補完

Section titled “チャット補完”
ターミナルウィンドウ
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
}

カスタムヘッダー

Section titled “カスタムヘッダー”
ヘッダー 方向 説明
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 を集計できます。

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

Section titled “排他的マネージドセッションリース”

排他的マネージドセッションリースは、オプトインのクライアントに依存しないルーティング契約です。1つのアクティブな所有者が、1つの適格なOmniRoute接続を保持します。これはモデルをリースしたり、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ボディで世代を提供します。

{ "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"
  }
}

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

誤ったキー、誤った所有者、古い世代、欠落、期限切れ、解放済み、無効化されたルックアップはすべて、接続メタデータなしで同じ409 LEASE_FENCE_STALEエラーを返します。容量待機応答を受け取ったクライアントは、検査するアクティブなバインディングを持っていません。ルーティングがアクティブなリースを移行する際、同じ世代は有効なままであり、ステータスは新しいバインディングをアトミックに返し、古いものは決して返しません。取得、更新、解放、および待機中の応答は以前の形式を保持するため、既存のクライアントは変更されません。

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

その後、すべてのマネージド推論リクエストは両方の制御ヘッダーを提供します。

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

正確な所有者、世代、アクティブな接続、および認証されたAPIキーは、サポートされている各アップストリーム試行の直前に保護されます。同じ接続を許可するキーであっても、別のキーで所有者と世代をリプレイすると失敗します。生の所有者は、永続化、ログ記録、リクエストスナップショットへの保持、またはアップストリームへの転送はされません。

一時的な競合は、Retry-AfterとともにHTTP 429を返します。

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

この応答は、通常の適格なセットが空ではなく、すべての空き候補が外部のアクティブなリースによって保持されていたことを意味するだけです。サポートされていないモデル/プロバイダー、ポリシーの不一致、クールダウン、クォータ、ヘルス、およびその他の通常の適格性失敗は、既存のOmniRoute応答を保持します。

x-omniroute-compression

Section titled “x-omniroute-compression”

リクエストごとの圧縮プランのオーバーライド。最高の優先順位を持ち、ルーティングコンボのオーバーライド、アクティブなプロファイル、自動トリガー、およびパネルのデフォルトよりも優先されます。値：

値 効果
off このリクエストでは圧縮を行いません。
default パネル由来のデフォルトプロファイル（アクティブなプロファイルは無視されます）。非可逆エンジンはオフのままです。
safe 重複排除と空白の折りたたみのみ。
allow-lossy 要約やスタイルの書き換えを含む、このリクエストのオペレータープランを維持します。
engine:&lt;id&gt; 有効な場合、単一のエンジン（例：engine:rtk）。そのエンジンに対するリクエストごとのオプトイン。
&lt;combo&gt; 名前付きコンボ。まず名前（大文字小文字を区別しない）で、次にIDで一致させます。

注記：

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

適用されたプランは、応答ヘッダーでエコーバックされます。

X-OmniRoute-Compression: &lt;mode&gt;; source=<source>

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

埋め込み

Section titled “埋め込み”
ターミナルウィンドウ
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

画像生成

Section titled “画像生成”
ターミナルウィンドウ
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

Section titled “ドキュメント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のポーリングフロー

Section titled “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の認証とエンドポイント解決

Section titled “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によって使用されます。

モデル一覧

Section titled “モデル一覧”
ターミナルウィンドウ
GET /v1/models
Authorization: Bearer your-api-key


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

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

Section titled “モデル 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 拡張機能でもこの方法を使用しています。

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

Section titled “思考なしモデルのバリアント”

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

claude-3-omniroute-no-thinking/&lt;provider&gt;/&lt;model&gt;

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

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

Section titled “プロバイダープラグインマニフェスト”
ターミナルウィンドウ
GET /api/v1/provider-plugin-manifest

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

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

互換性エンドポイント

Section titled “互換性エンドポイント”
Method Path 形式
POST /v1/chat/completions OpenAI
POST /v1/messages Anthropic
POST /v1/responses OpenAI レスポンス
POST /v1/embeddings OpenAI
POST /v1/images/generations OpenAI 画像
POST /v1/images/edits OpenAI 画像 (編集/インペイント)
POST /v1/videos/generations OpenAI スタイルの動画生成
POST /v1/music/generations OpenAI スタイルの音楽生成
POST /v1/audio/transcriptions OpenAI オーディオ (STT)
POST /v1/audio/speech OpenAI TTS (オーディオボディを返します)
POST /v1/rerank Cohere/Voyage スタイルのリランク
POST /v1/classify Jina classify (api.jina.ai)
POST /v1/segment Jina segmenter (segment.jina.ai)
POST /v1/moderations OpenAI モデレーション
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 レスポンスのトークン化されたエイリアス
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 キーも受け入れます。

ターミナルウィンドウ
# リランク (クラウドレジストリプロバイダー、または "&lt;prefix&gt;/&lt;model&gt;" としての OpenAI 互換プロバイダーノード)
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }


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


# Jina segmenter
POST /v1/segment     { "content": "...", "return_chunks": true }


# Jina search (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" }


# 画像編集 (マルチパート)
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": "kie/suno-v4.0",   "prompt": "..." }

リランクプロバイダーノード: POST /v1/rerank は、&lt;node-prefix&gt;/&lt;model&gt; としてアドレス指定される OpenAI 互換プロバイダーノード (oMLX、vLLM、Infinity、ゲートウェイの背後にある TEI など) にもルーティングされます。ループバックノード (localhost、127.0.0.1、172.16.0.0/12) は常に適格です。その他のホスト — LAN ボックスまたは Tailscale ピア — 上のノードは、オペレーターが RERANK_REMOTE_PROVIDER_NODES 機能フラグを有効にし、かつ ノードのベース URL がプロバイダーのアウトバウンド URL ポリシー (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS / OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS) を通過する場合にのみ適格です。クラウドメタデータホストにはルーティングされません。メモリエンジンのリランクステップはこのルートをループバック経由で呼び出すため、メモリ設定の rerankProviderModel も同じルールに従います。

ローカルサーバーの形式: ノードは &lt;base&gt;/v1/rerank で呼び出され、404 の場合は &lt;base&gt;/rerank (Infinity, TEI) で呼び出されます。アップストリームボディは、Cohere/OpenAI の表記 (documents、return_documents) と TEI の表記 (texts、return_text) の両方を持ち、アップストリーム応答は Cohere エンベロープに正規化されます。TEI の生の [{index, score, text}]、シンゲートウェイからの {results: [{index, score}]}、および Voyage スタイルの {data: [...]} はすべて、スコアでソートされ top_n で上限が設定された {results: [{index, relevance_score, document?}]} としてクライアントに返されます。

プロバイダーノードの検出: OpenAI 互換プロバイダーノード上のモデルは、ノードプレフィックスの下の GET /v1/models に表示されます。エンドポイントメタデータを持たない行 (ローカルの /v1/models リストで一般的) は、ノードの apiType を継承するため、embeddings ノードのモデルは type: "embedding" となり、rerank ノードのモデルはデフォルトのチャットではなく type: "rerank" となります。同期された行または手動で追加された行の明示的な supportedEndpoints は、引き続き優先されます。

専用プロバイダールート

Section titled “専用プロバイダールート”
ターミナルウィンドウ
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations

プロバイダープレフィックスが欠落している場合、自動的に追加されます。モデルが一致しない場合、400 が返されます。

Files API

Section titled “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

Section titled “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

Section titled “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

Section titled “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ストリーミング

Section titled “WebSocketストリーミング”
ターミナルウィンドウ
GET /v1/ws?handshake=1

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

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

WebSocket経由のResponses API（codexのみ）

Section titled “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/&lt;group&gt;/codex/&lt;model&gt;" を使用してください。実装は 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を使用

Section titled “モデル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の設定

Section titled “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 を返し、完了結果を ストリーミングします。

クォータと問題の報告

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

認証: Bearer API キー（isAuthenticated）。

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

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

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

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


# 構造化形式 — UI が使用する形式
curl -H "Authorization: Bearer &lt;your-api-key&gt;" \
  "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 で保護されます。

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

Section titled “セマンティックキャッシュ”
ターミナルウィンドウ
# キャッシュ統計を取得
GET /api/cache/stats


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

レスポンス例:

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

レイテンシへの影響

Section titled “レイテンシへの影響”

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

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

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

Section titled “キー単位のキャッシュバイパス”

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

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

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

{ "cacheDefaultMode": "bypass" }

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

Section titled “リクエスト単位のバイパス”

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

X-OmniRoute-No-Cache: true

ダッシュボードと管理

Section titled “ダッシュボードと管理”

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

認証

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

プロバイダー管理

Section titled “プロバイダー管理”
エンドポイント メソッド 説明
/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 フロー

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

ルーティングと設定

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

使用状況と分析

Section titled “使用状況と分析”
エンドポイント メソッド 説明
/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）

設定

Section titled “設定”
エンドポイント メソッド 説明
/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 リクエストログの行とローカルの呼び出しログアーティファクトを消去

コンテキストと圧縮

Section titled “コンテキストと圧縮”
エンドポイント メソッド 説明
/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 圧縮分析のエイリアス

監視

Section titled “監視”
エンドポイント メソッド 説明
/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 ではありません

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

Section titled “バックアップとエクスポート／インポート”
エンドポイント メソッド 説明
/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 アーカイブとしてダウンロード

クラウド同期

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

トンネル

Section titled “トンネル”
エンドポイント メソッド 説明
/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 ツール

Section titled “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 エージェント

Section titled “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）が含まれます。

耐障害性とレート制限

Section titled “耐障害性とレート制限”
エンドポイント メソッド 説明
/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）を必要とします。プロバイダーブレーカー、接続クールダウン、モデルロックアウトの詳しい違いについては、耐障害性（詳細）を参照してください。

評価

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

ポリシー

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

コンプライアンス

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

v1beta（Gemini 互換）

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

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

内部／システム API

Section titled “内部／システム 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+)

Section titled “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"
}

音声文字起こし

Section titled “音声文字起こし”
ターミナルウィンドウ
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 互換性

Section titled “Ollama 互換性”

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

ターミナルウィンドウ
# チャットエンドポイント（Ollama 形式）
POST /v1/api/chat


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

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

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

Section titled “トークン付き 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 外部のテレメトリに記録される可能性があります。デフォルトの認証方式ではなく、互換性のためのオプションとして扱ってください。

テレメトリ

Section titled “テレメトリ”
ターミナルウィンドウ
# レイテンシーテレメトリの概要を取得（プロバイダーごとの 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 }
  }
}

予算

Section titled “予算”
ターミナルウィンドウ
# すべての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 を返します。

トークン制限

Section titled “トークン制限”

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 パイプラインによって一元的に適用されます）。

リクエスト処理

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

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

コンボ管理

Section titled “コンボ管理”

上位レベルのルーティングコンボ（/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

Section titled “Webhook”

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

メソッド パス 説明
GET /api/webhooks Webhook の一覧を取得（シークレットは &lt;prefix&gt;... にマスクされます）
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）。

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

Section titled “登録済みキー（自動管理）”

自動キー管理サブシステムが、基盤となるプロバイダー/アカウントに対して、日次/時間単位のクォータ付き 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 も参照してください。

エージェントプロトコル

Section titled “エージェントプロトコル”

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":"..."}}'

管理プロキシ

Section titled “管理プロキシ”

プロバイダー、アカウント、またはグローバルに割り当て可能な送信 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=&lt;id&gt; を指定します
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 ごとのサブルートはありません。

レジリエンス（拡張）

Section titled “レジリエンス（拡張）”

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 →「レジリエンスのランタイム状態」を参照してください。

スキル

Section titled “スキル”

カスタム実行可能ハンドラーを使用して 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）のいずれかを使用できます。

メモリ

Section titled “メモリ”

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 サーバー

Section titled “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 サーバー

Section titled “A2A サーバー”

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

JSON-RPC

Section titled “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。

エージェントカード

Section titled “エージェントカード”
ターミナルウィンドウ
GET /.well-known/agent.json

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

REST ヘルパー

Section titled “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 を使用します。

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

Section titled “クラウド、評価、アセスメント”

| メソッド | パス | 説明 | | —— | —————————–– | ———————————————————————————————–– | —————————– | ———————————– | | 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）管理

Section titled “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=&lt;agentId&gt;

レスポンス例（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 フレームワークを参照してください。

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

Section titled “分析とオブザーバビリティ”

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

自動ルーティング分析

Section titled “自動ルーティング分析”
メソッド パス 説明
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 }
  ]
}

圧縮分析

Section titled “圧縮分析”
メソッド パス 説明
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
  }
}

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

Section titled “プロバイダー多様性の追跡”
メソッド パス 説明
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 キーが必要です。

管理者向け操作

Section titled “管理者向け操作”

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

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

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

CLI ツール管理

Section titled “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 のエイリアスを設定します

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

エージェントスキル

Section titled “エージェントスキル”

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 キーが必要です。

キャッシュ管理

Section titled “キャッシュ管理”

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

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

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

メモリシステム

Section titled “メモリシステム”

永続メモリ（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

Section titled “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

Section titled “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を参照してください。

プラグイン

Section titled “プラグイン”

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を参照してください。

シャドールーティング

Section titled “シャドールーティング”

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

ガードレール

Section titled “ガードレール”

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

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

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

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

認証

Section titled “認証”

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）を参照してください。

OmniRoute ソースコード (a58000c7685f)

HagiCode

HagiCode は構造化ワークフロー、マルチエージェント実行、Hero Dungeon ビューを備えたエージェント型コーディングワークスペースです。

よりスマートで速く、楽しいエージェント型ワークフローで、使いやすいソフトウェアを形にします。

HagiCode ライトテーマのメイン画面
  • Smart構造化ワークフローは意図をアイデアから変更のリリースまで実行可能な道筋にします。
  • Efficientマルチエージェントのワークフローで調査、実装、レビューを並行して進めます。
  • FunHero Dungeon により長時間のコーディングを視覚的で協力的な体験にします。
HagiCode を見る