Authentication

Include your API key in every request:

x-api-key: osk_your_key_here

Optional: include Idempotency-Key header for safe retries.

Auth failure returns status 401 with code CLOUD_AUTH_FAILED.

Health Check

GET /health

Returns 200 when the service is available.

Browser Sessions

Create Session

POST /sessions

Request body (JSON):

{
  "cloudSessionContractVersion": "v3",
  "sourceType": "local-cloud",
  "clientSessionHint": "my-client-hint",
  "localRunId": "run-123",
  "name": "my-session",
  "model": "gpt-5.1"
}

Response: sessionId, actionWsUrl, cdpWsUrl, actionToken, cdpToken, cloudSessionUrl, cloudSession.

Get Session

GET /sessions/:sessionId

Delete Session

DELETE /sessions/:sessionId

Selector Cache Import

POST /selector-cache/import

Upload local selector cache to cloud for replay continuity.

{
  "entries": [
    {
      "namespace": "my-project",
      "siteOrigin": "https://example.com",
      "method": "click",
      "descriptionHash": "abc123",
      "path": { "selector": "button.submit", "confidence": 1.0 },
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ]
}

Response:

{
  "imported": 1,
  "inserted": 1,
  "updated": 0,
  "skipped": 0
}

Scraper Runs

Queue a Run

POST /scrapers/:slug/runs

{
  "input": { "url": "https://example.com" },
  "webhook": {
    "url": "https://your-server.com/webhook",
    "secret": "whsec_your_secret",
    "events": ["run.succeeded", "run.failed"]
  }
}

Optional: Idempotency-Key header. Response: run object, replayed boolean, links.status, links.logs.

Get Run Status

GET /runs/:runId

Run statuses: queued, running, succeeded, failed, canceled.

Get Run Logs

GET /runs/:runId/logs

Supports pagination with logLimit and beforeLogCursor query params.

Webhooks

Configure webhooks when queueing scraper runs. Events: run.succeeded, run.failed.

Signature header: x-opensteer-signature with format t=<unix_seconds>,v1=<hex_hmac>.

Verify signatures:

import { createHmac, timingSafeEqual } from 'node:crypto'

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string,
): boolean {
  const [tPart, v1Part] = signature.split(',')
  const timestamp = tPart.replace('t=', '')
  const expectedHmac = v1Part.replace('v1=', '')

  const hmac = createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex')

  return timingSafeEqual(Buffer.from(hmac), Buffer.from(expectedHmac))
}

Error Codes

Code	Description
CLOUD_ACTION_FAILED	Action execution failed on cloud runtime
CLOUD_AUTH_FAILED	Authentication failed (401)
CLOUD_CAPACITY_FULL	No runtime capacity available
CLOUD_CDP_UNAVAILABLE	CDP endpoint not reachable
CLOUD_CONFIG_INVALID	Invalid cloud configuration
CLOUD_CONNECTION_LOST	WebSocket connection dropped
CLOUD_CONTRACT_MISMATCH	Client/server contract version mismatch (409)
CLOUD_INTERNAL_ERROR	Unexpected server error
CLOUD_LAUNCH_FAILED	Session launch failed
CLOUD_LAUNCH_TIMEOUT	Session launch timed out
CLOUD_NOT_CONFIGURED	Cloud mode not properly configured
CLOUD_RATE_LIMITED	Request rate limited (respect Retry-After)
CLOUD_RUNTIME_GONE	Runtime instance no longer available
CLOUD_SESSION_CLOSED	Session already closed
CLOUD_SESSION_NOT_FOUND	Session ID not found
CLOUD_TIMEOUT	Operation timed out
CLOUD_UNSUPPORTED_METHOD	Method not available in cloud mode

Error handling:

• 401 auth failures: verify API key and header format
• 409 contract mismatches: upgrade SDK to match server contract version
• Rate limits: respect the Retry-After header