Cloud quickstart

OmniScout Cloud is the hosted API: search, answers, and remote browser sessions with no install. The local CLI is unchanged — Cloud is additive.

1. Get an API key

Sign in at api.omniscout.xyz.
Go to Dashboard → API Keys → Create key. Copy the value — it starts with os_live_ and is shown only once.
Export it:

export OMNISCOUT_API_KEY=os_live_YOUR_KEY
export OMNISCOUT_BASE_URL=https://api.omniscout.xyz

How keys work and the second credential (session secrets): Authentication.

2. First search

curl -X POST $OMNISCOUT_BASE_URL/v0/search \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "rust async runtimes", "limit": 5}'

You get ranked hits with url, title, snippet, score, and rank, plus a request_id for support. See Endpoints.

3. First answer

curl -X POST $OMNISCOUT_BASE_URL/v0/answer \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the latest stable Rust version?"}'

You get an answer with sources and confidence — or status: insufficient_information with a null answer when evidence is thin. See Endpoints.

4. First browser session

Sessions run the same commands as the CLI, on a remote machine. Lifecycle: create → wait until ready → act → delete.

# Create (API key only) — save session_id AND session_secret
CREATE=$(curl -sS -X POST $OMNISCOUT_BASE_URL/v0/sessions \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"computer"}')

SESSION_ID=$(echo "$CREATE" | jq -r .session_id)
SESSION_SECRET=$(echo "$CREATE" | jq -r .session_secret)

# Poll until ready
curl -sS $OMNISCOUT_BASE_URL/v0/sessions/$SESSION_ID \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" | jq .status

# Act (API key + session secret)
curl -sS -X POST $OMNISCOUT_BASE_URL/v0/sessions/$SESSION_ID/actions \
  -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"}}'

# Destroy (API key only)
curl -sS -X DELETE $OMNISCOUT_BASE_URL/v0/sessions/$SESSION_ID \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY"

Types: "browser" is a lightweight browser-only session; "computer" adds desktop control on the same session id. Sessions close after inactivity (around 30 minutes, up to 2 hours) — every command keeps them alive longer.

Prefer SDKs? See SDKs for the same flow in Python and TypeScript.

5. Check usage

curl -sS $OMNISCOUT_BASE_URL/v0/usage \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" | jq .

Billing is usage-based — you pay only for what you use. See Usage & Billing.

Next steps

Authentication — keys, session secrets, headers
Endpoints — every route's schemas
SDKs — Python, TypeScript, curl
Errors — error envelope and retry rules
Rate limits — abuse guards and spending caps