Cloud API Overview

OmniScout Cloud is the hosted API for search, answers, and remote browser sessions. If the local CLI is not an option — for example, you want to run from a server or share access across a team — Cloud gives you the same capabilities over HTTPS.

What you get

Capability	Endpoint	What it does for you
Search	`POST /v0/search`	Ranked web results for any query
Answer	`POST /v0/answer`	A direct answer with sources and confidence
Browser sessions	`POST /v0/browser/sessions`	A remote browser you can drive with clicks, fills, and screenshots
Computer sessions	`POST /v0/computer/sessions`	A remote session with browser plus desktop control
Session files	`POST/GET /v0/sessions/{id}/files`	Upload files to, or download screenshots and PDFs from, a session

What changed for session callers

POST /v0/search and POST /v0/answer are unchanged.

Session endpoints use the same paths as before, with these differences:

Save session_secret from the create response — you need it on every command and file request via x-session-secret.
Computer sessions are unified — one session_id supports both browser commands (POST /v0/browser/sessions/{id}) and computer commands (POST /v0/computer/sessions/{id}). You no longer need a separate browser session when you already have a computer session.
Action names — browser actions use short names (navigate, screenshot); computer actions start with computer. (computer.type, computer.screenshot).
File routes are new — use /v0/sessions/{id}/files to upload files or download screenshots and PDFs from the session.
Sessions stay alive while you use them — each command extends the session (around 30 minutes of inactivity by default, up to 2 hours total). You do not need to track an expiry time yourself.

# 1. Create unified computer session (API key only)
curl -X POST https://api.omniscout.xyz/v0/computer/sessions \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY"

# Response includes session_id, session_secret, capabilities: ["browser","computer"]

# 2. Browser command on the same session (both headers)
curl -X POST "https://api.omniscout.xyz/v0/browser/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "x-session-secret: $SESSION_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"action":"navigate","args":{"url":"https://example.com"}}'

# 3. Computer command on the same session
curl -X POST "https://api.omniscout.xyz/v0/computer/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "x-session-secret: $SESSION_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"action":"computer.type","args":{"text":"hello"}}'

Quick start

Sign up at api.omniscout.xyz (or your deployment URL).
Create an API key in the dashboard — keys start with os_live_.
Send your first request:

curl -X POST https://api.omniscout.xyz/v0/search \
  -H "Authorization: Bearer os_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "rust async runtimes", "limit": 10}'

CLI vs Cloud

	CLI	Cloud API
Setup	Install on your machine, uses your browser	No install — send HTTPS requests from anywhere
Search & answers	Runs locally	Hosted, always up to date
Browser	Drives the browser on your machine	Remote browser session you control over the API
Auth	None (runs locally)	API key (`os_live_...`)
Billing	Free, open source	Free tier + usage-based pricing

The local CLI is unchanged. Cloud is additive — use whichever fits your setup.

Next steps

Authentication & API keys — how to create and use keys
Endpoints — request and response examples for every route
Rate limits — usage guards and spending caps
OpenAPI reference — interactive API explorer