Endpoints

Base URL: https://api.omniscout.xyz (or your deployment URL).

Every response includes a request_id (UUID) for debugging and support.

POST /v0/search

Semantic search over the owned index.

Request

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

Field	Type	Required	Description
`query`	string	yes	Search query (1–500 chars)
`limit`	integer	no	Max results (1–20, default 10)

Response

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

POST /v0/answer

Grounded one-sentence answer from web sources.

Request

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

Field	Type	Required	Description
`query`	string	yes	Question (1–500 chars)

Response

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

When evidence is insufficient, status is insufficient_information and answer is null.

Session API summary

POST /v0/search and POST /v0/answer are unchanged. Session endpoints use the same URL paths, but callers should note:

Topic	Before	Now
Create response	`session_id`, `expires_at`	Also `session_secret` (store it) and `capabilities`
Command auth	API key + `x-session-secret`	Same — shown only when the session is created, so save it
Computer + browser	Separate sessions	One computer session id works for both routes
Browser actions	`navigate`, `screenshot`, …	Unchanged (short action names)
Computer actions	`computer.*` prefix	Unchanged
Screenshots / files	Path on the session only	Use `GET /v0/sessions/{id}/files` to download the file
Upload to browser	Paths on the session only	`POST /v0/sessions/{id}/files` first, then the `upload` action
Expiry	Fixed time from create	Stays alive while you use it (around 30 min idle, 2 hr max)
Delete session	API key	API key only (no `x-session-secret`)

Browser sessions

POST /v0/browser/sessions

Create a browser-only remote session.

Auth: 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"
}

Sessions stay alive while you use them (around 30 minutes of inactivity, up to 2 hours total). Every command extends the window.

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

Proxy a daemon command to the session.

Headers: Authorization: Bearer os_live_... and x-session-secret: <secret from create>

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

Field	Type	Required	Description
`action`	string	yes	Browser action name (e.g. `navigate`, `snapshot`, `screenshot`) — no `browser.` prefix
`args`	object	no	Action-specific arguments
`session`	string	no	Session name (default `default`)
`timeout_ms`	integer	no	Command timeout in milliseconds

Computer sessions with capabilities: ["browser", "computer"] also accept browser commands on this route using the same session_id.

Browser-only sessions reject computer.* actions with 400.

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

Destroy the session and release it.

Headers: Authorization: Bearer os_live_... only (session secret not required).

Computer sessions

One computer session gives you both desktop control and browser control on the same session id.

Method	Path	Description
`POST`	`/v0/computer/sessions`	Create a session with browser + desktop (`capabilities: ["browser", "computer"]`)
`POST`	`/v0/computer/sessions/{id}`	Proxy command (`computer.*` actions)
`DELETE`	`/v0/computer/sessions/{id}`	Destroy session (API key only)

Headers for commands: Authorization + x-session-secret (same as browser commands).

Computer commands use the computer. prefix:

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

Field	Type	Required	Description
`action`	string	yes	Must start with `computer.` (e.g. `computer.type`, `computer.screenshot`)
`args`	object	no	Action-specific arguments
`session`	string	no	Session name (default `default`)

The same session_id works for browser commands via /v0/browser/sessions/{id} — you do not need a second browser session.

Session files

Upload files to, or download files from, a session.

Method	Path	Description
`POST`	`/v0/sessions/{id}/files`	Multipart upload (`file` field, optional `session` name)
`GET`	`/v0/sessions/{id}/files?path=...`	Download file bytes
`GET`	`/v0/sessions/{id}/files?path=...&format=base64`	Download as JSON with base64 payload

Both routes require Authorization and x-session-secret.

Upload — multipart/form-data with a file field. Optional session field sets the session name (default 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"

Download — query parameter path (from a command result such as 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"

Typical screenshot workflow:

POST /v0/browser/sessions/{id} with {"action":"screenshot","args":{}}
GET /v0/sessions/{id}/files?path={returned_path}&format=base64

Typical browser upload workflow:

POST /v0/sessions/{id}/files with the file bytes
POST /v0/browser/sessions/{id} with {"action":"upload","args":{"selector":"@e1","files":["/path/from/step-1"]}}

OpenAPI

Try every endpoint in your browser:

Interactive explorer: api.omniscout.xyz/docs
JSON: api.omniscout.xyz/api/openapi

Endpoints

On this page