All Cloud API requests require an x-api-key header. Optionally include Idempotency-Key for safe retries.

curl -H "x-api-key: YOUR_KEY" https://api.opensteer.dev/v1/sessions

Browser Sessions

Create a session:

POST /v1/sessions
{
  "url": "https://example.com",
  "profileId": "optional-profile-id",
  "headless": true
}
# Response: { "sessionId": "...", "viewUrl": "..." }

Get session:

GET /v1/sessions/:sessionId

List sessions:

GET /v1/sessions

Delete session:

DELETE /v1/sessions/:sessionId

Ping session (keep-alive):

GET /v1/sessions/:sessionId/runtime/ping

Browser Profiles

List profiles:

GET /browser-profiles

Create profile:

POST /browser-profiles
{ "name": "my-profile" }

Rotate fingerprint seed:

POST /browser-profiles/:profileId/rotate-fingerprint-seed

Rotate proxy:

POST /browser-profiles/:profileId/rotate-proxy

Import data:

POST /browser-profiles/imports

Selector Cache

Import cached selectors:

POST /v1/selector-cache/import
{
  "entries": [{
    "workspace": "demo",
    "method": "css",
    "descriptionHash": "abc123",
    "path": "#search-input",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }]
}
# Response: { "imported": 1, "inserted": 1, "updated": 0, "skipped": 0 }

Scraper Runs

Create a run:

POST /scrapers/:slug/runs
{ "input": { "query": "laptops" } }
# Response: { "runId": "...", "status": "queued" }

Get run status:

GET /runs/:runId
# Response: { "runId": "...", "status": "running|succeeded|failed|canceled", "output": {...} }

Get run logs:

GET /runs/:runId/logs

Webhooks

Configure webhooks on scraper runs to receive notifications on completion. Payloads are signed with x-opensteer-signature using HMAC-SHA256.

Verify signature:

import crypto from "node:crypto";

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Error Responses

All errors return:

{ "error": { "code": "ERROR_CODE", "message": "Human-readable message" } }

Status	Code	Description
400	CLOUD_INVALID_REQUEST	Invalid request parameters
401	CLOUD_AUTH_FAILED	Invalid API key
404	CLOUD_SESSION_NOT_FOUND	Session not found
429	CLOUD_RATE_LIMITED	Rate limit exceeded
503	CLOUD_CAPACITY_EXHAUSTED	No capacity available
500	CLOUD_INTERNAL	Internal server error