Authentication

All Cloud API requests require a Bearer token in the Authorization header.

Search and answer endpoints only need this API key. Browser and computer session commands also require a second credential: the session_secret returned when you create a session (see Endpoints → Browser sessions).

API keys

API keys are created in the dashboard. Each key:

Starts with os_live_
Is tied to your account
Has independent usage tracking
Can be revoked at any time

Authorization: Bearer os_live_abc123...

Creating a key

Sign in at api.omniscout.xyz.
Go to Dashboard → API Keys.
Click Create key and copy the value — it is shown only once.

Store keys in environment variables, not in source code:

export OMNISCOUT_API_KEY=os_live_abc123...

Example request

curl -X POST https://api.omniscout.xyz/v0/search \
  -H "Authorization: Bearer $OMNISCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "python async patterns"}'

Session secrets

Session routes use two credentials:

Credential	Header	When
API key	`Authorization: Bearer os_live_...`	Create, command, file upload/download, delete
Session secret	`x-session-secret: <secret>`	Command, file upload/download only

The session secret is returned once in the create response (session_secret). Store it with the session_id — it cannot be retrieved later.

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

# Command (API key + session secret)
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"},"session":"default"}'

Delete only requires the API key (no session secret).

Error responses

Status	Meaning
`401`	Missing or invalid API key
`401`	Invalid `x-session-secret` on session command or file routes
`429`	Daily rate limit exceeded

All error responses include a request_id for debugging:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": {
    "type": "unauthorized",
    "message": "Invalid API key"
  }
}