# Cloud API Overview (/en/docs/cloud)



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 [#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 [#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:

1. **Save `session_secret`** from the create response — you need it on every command and file request via `x-session-secret`.
2. **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.
3. **Action names** — browser actions use short names (`navigate`, `screenshot`); computer actions start with `computer.` (`computer.type`, `computer.screenshot`).
4. **File routes are new** — use `/v0/sessions/{id}/files` to upload files or download screenshots and PDFs from the session.
5. **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.

```bash
# 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 [#quick-start]

1. Sign up at [api.omniscout.xyz](https://api.omniscout.xyz) (or your deployment URL).
2. Create an API key in the dashboard — keys start with `os_live_`.
3. Send your first request:

```bash
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-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, Modified MIT                         | Free tier + usage-based pricing                 |

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

## Next steps [#next-steps]

* [Authentication & API keys](/docs/authentication) — how to create and use keys
* [Endpoints](/docs/endpoints) — request and response examples for every route
* [Rate limits](/docs/rate-limits) — usage guards and spending caps
* [OpenAPI reference](https://api.omniscout.xyz/docs) — interactive API explorer
