エンドポイント

ベースURL：https://api.omniscout.xyz（またはデプロイ先URL）。

すべてのレスポンスにはデバッグ・サポート用のrequest_id（UUID）が含まれます。

POST /v0/search

独自インデックスに対するセマンティック検索。

リクエスト

{
  "query": "rust async runtimes",
  "limit": 10
}

レスポンス

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "query": "rust async runtimes",
  "count": 10,
  "hits": [
    {
      "url": "https://tokio.rs/",
      "title": "Tokio - An asynchronous Rust runtime",
      "snippet": "...",
      "source": "common_crawl",
      "score": 0.94,
      "rank": 1
    }
  ]
}

パイプライン

1. Qdrant Cloudに対するハイブリッドベクトル＋BM25クエリ
2. omniscout.engines.search.rerankでリランク
3. スコア付き上位ヒットを返す

POST /v0/answer

Webソースに基づく一文の根拠付き回答。

リクエスト

{
  "query": "What is the latest stable Rust version?"
}

レスポンス

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "query": "What is the latest stable Rust version?",
  "answer": "Rust 1.85.0 is the latest stable release as of February 2025.",
  "status": "answered",
  "confidence": 0.87,
  "sources": [
    { "url": "https://blog.rust-lang.org/", "title": "Rust Blog" }
  ]
}

根拠が不十分な場合、statusはinsufficient_information、answerはnullになります。

パイプライン

1. 上位3件のインデックス検索＋リランク
2. URLコンテンツを抽出（omniscoutまたはtrafilatura）
3. Vercel AI Gatewayで統合
4. 出典・信頼度付きの回答を返す

セッションAPI概要

POST /v0/searchとPOST /v0/answerは変更なしです。セッションエンドポイントは同じURLパスですが、利用者は次に注意してください：

ブラウザセッション

POST /v0/browser/sessions

ブラウザ専用Fly Spriteセッションを作成します（軽量Chromium VM）。

認証：Authorization: Bearer os_live_...

{
  "request_id": "...",
  "session_id": "j57abc...",
  "type": "browser",
  "capabilities": ["browser"],
  "expires_at": 1710000000000,
  "sprite_url": "https://omniscout-sprites.fly.dev",
  "session_secret": "48-char-hex-secret-returned-once"
}

セッションは非アクティブ後（SESSION_INACTIVITY_MS、デフォルト30分）またはハードTTL到達時（SESSION_MAX_TTL_MS、デフォルト2時間）に期限切れになります。各コマンドで非アクティブ枠が延長されます。

POST /v0/browser/sessions/{id}

デーモンコマンドをセッションにプロキシします。

ヘッダー：Authorization: Bearer os_live_...とx-session-secret: <作成時のsecret>

{
  "action": "navigate",
  "args": { "url": "https://example.com" },
  "session": "default"
}

capabilities: ["browser", "computer"]を持つコンピューターセッションも、同じsession_idでこのルートのブラウザコマンドを受け付けます。

ブラウザ専用セッションはcomputer.*アクションを400で拒否します。

DELETE /v0/browser/sessions/{id}

セッションを破棄してFly Machineを解放します。

ヘッダー：Authorization: Bearer os_live_...のみ（セッションシークレット不要）。

コンピューターセッション

統合Fly Spriteセッションは、同じVM上でデスクトップ自動化とブラウザ自動化の両方を含みます。

コマンド用ヘッダー：Authorization＋x-session-secret（ブラウザコマンドと同じ）。

コンピューターコマンドはcomputer.プレフィックスを使います：

{
  "action": "computer.type",
  "args": { "text": "hello" },
  "session": "default"
}

同じsession_idは/v0/browser/sessions/{id}経由のブラウザコマンドにも使えます — 2つ目のブラウザセッションは不要です。

セッションファイル

Spriteファイルシステムとのファイルのアップロード・ダウンロード。

両ルートともAuthorizationとx-session-secretが必要です。

アップロード — fileフィールド付きmultipart/form-data。任意のsessionフィールドでデーモンセッション名を設定します（デフォルトdefault）。

curl -X POST "https://api.omniscout.xyz/v0/sessions/$SESSION_ID/files" \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "x-session-secret: $SESSION_SECRET" \
  -F "file=@./document.pdf"

ダウンロード — クエリパラメータpath（screenshotなどのコマンド結果から取得）：

curl "https://api.omniscout.xyz/v0/sessions/$SESSION_ID/files?path=/tmp/...&format=base64" \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "x-session-secret: $SESSION_SECRET"

典型的なスクリーンショットワークフロー：

1. {"action":"screenshot","args":{}}でPOST /v0/browser/sessions/{id}
2. GET /v0/sessions/{id}/files?path={返却パス}&format=base64

典型的なブラウザアップロードワークフロー：

1. ファイルバイトをPOST /v0/sessions/{id}/files
2. {"action":"upload","args":{"selector":"@e1","files":["/path/from/step-1"]}}でPOST /v0/browser/sessions/{id}

OpenAPI

完全なOpenAPI 3.1仕様はこちら：

• 対話式エクスプローラー：api.omniscout.xyz/docs
• JSON：api.omniscout.xyz/api/openapi

仕様はZodルートスキーマから生成され、ライブAPIと同期しています。