端点

基础 URL：https://api.omniscout.xyz（或你的部署 URL）。

每个响应都包含 request_id（UUID），用于调试与支持。

POST /v0/search

在自有索引上的语义搜索。

请求

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

字段	类型	是否必填	说明
`query`	string	是	搜索查询（1–500 字符）
`limit`	integer	否	最大结果数（1–20，默认 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
    }
  ]
}

流水线

对 Qdrant Cloud 的混合向量 + BM25 查询
使用 omniscout.engines.search.rerank 重排序
返回带分数的 Top 命中

POST /v0/answer

基于网页来源的单句有据回答。

请求

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

字段	类型	是否必填	说明
`query`	string	是	问题（1–500 字符）

响应

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

流水线

Top-3 索引搜索 + 重排序
提取 URL 内容（omniscout 或 trafilatura）
经 Vercel AI Gateway 综合
返回带来源与置信度的答案

会话 API 摘要

POST /v0/search 和 POST /v0/answer 保持不变。会话端点使用相同的 URL 路径，但调用方应注意：

主题	之前	现在
创建响应	`session_id`、`expires_at`	还包括 `session_secret`（请保存）和 `capabilities`
命令认证	API 密钥 + `x-session-secret`	相同——此处明确说明；密钥仅在创建时展示
电脑 + 浏览器	独立会话 / 虚拟机	电脑会话 ID 同时适用于两条路由
浏览器操作	`navigate`、`screenshot`、……	不变（裸操作名）
电脑操作	`computer.*` 前缀	不变
截图 / 文件	仅 Sprite 上的路径	使用 `GET /v0/sessions/{id}/files` 下载字节
上传到浏览器	仅 Sprite 上的路径	先 `POST /v0/sessions/{id}/files`，再执行 `upload` 操作
过期	从创建起的固定 TTL	滑动空闲过期（默认 30 分钟），最长 2 小时
删除会话	API 密钥	仅 API 密钥（无需 `x-session-secret`）

浏览器会话

POST /v0/browser/sessions

创建纯浏览器 Fly Sprite 会话（轻量 Chromium 虚拟机）。

认证：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}`

将会话的 daemon 命令代理到该会话。

请求头：Authorization: Bearer os_live_... 和 x-session-secret: <创建时返回的密钥>

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

字段	类型	是否必填	说明
`action`	string	是	浏览器操作名（例如 `navigate`、`snapshot`、`screenshot`）——无 `browser.` 前缀
`args`	object	否	操作特定参数
`session`	string	否	Daemon 标签组名（默认 `default`）
`timeout_ms`	integer	否	命令超时（毫秒）

具有 capabilities: ["browser", "computer"] 的电脑会话也可在该路由上使用相同 session_id 接受浏览器命令。

纯浏览器会话会以 400 拒绝 computer.* 操作。

`DELETE /v0/browser/sessions/{id}`

销毁会话并释放 Fly 机器。

**请求头：**仅 Authorization: Bearer os_live_...（无需会话密钥）。

电脑会话

统一 Fly Sprite 会话在同一虚拟机上同时包含桌面自动化和浏览器自动化。

方法	路径	说明
`POST`	`/v0/computer/sessions`	创建统一 Sprite（`capabilities: ["browser", "computer"]`）
`POST`	`/v0/computer/sessions/{id}`	代理命令（`computer.*` 操作）
`DELETE`	`/v0/computer/sessions/{id}`	销毁会话（仅需 API 密钥）

命令请求头：Authorization + x-session-secret（与浏览器命令相同）。

电脑命令使用 computer. 前缀：

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

字段	类型	是否必填	说明
`action`	string	是	必须以 `computer.` 开头（例如 `computer.type`、`computer.screenshot`）
`args`	object	否	操作特定参数
`session`	string	否	Daemon 会话名（默认 `default`）

相同的 session_id 可通过 /v0/browser/sessions/{id} 执行浏览器命令——无需第二个浏览器会话。

会话文件

在 Sprite 文件系统上上传和下载文件。

方法	路径	说明
`POST`	`/v0/sessions/{id}/files`	Multipart 上传（`file` 字段，可选 `session` 名）
`GET`	`/v0/sessions/{id}/files?path=...`	下载文件字节
`GET`	`/v0/sessions/{id}/files?path=...&format=base64`	以 JSON 下载 base64 负载

两条路由都需要 Authorization 和 x-session-secret。

上传——multipart/form-data，带 file 字段。可选 session 字段设置 daemon 会话名（默认 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"

典型截图工作流：

POST /v0/browser/sessions/{id}，请求体为 {"action":"screenshot","args":{}}
GET /v0/sessions/{id}/files?path={返回的路径}&format=base64

典型浏览器上传工作流：

POST /v0/sessions/{id}/files 上传文件字节
POST /v0/browser/sessions/{id}，请求体为 {"action":"upload","args":{"selector":"@e1","files":["/path/from/step-1"]}}

OpenAPI

完整 OpenAPI 3.1 规范见：

交互式浏览器：api.omniscout.xyz/docs
JSON：api.omniscout.xyz/api/openapi

该规范由 Zod 路由结构生成，与线上 API 保持同步。

端点

On this page