Cloud

Cloud APIs

The public cloud API covers session lifecycle, semantic operations, recording, observability, browser profiles, and registry import.

Cloud APIs

The public cloud API centers on one flow: create a managed session, run semantic operations against it, and inspect it from the control plane.

Authentication

For most public control-plane endpoints, use either:

  • Authorization: Bearer <token>
  • x-api-key: <token>

If the bearer token starts with osk_, the control plane treats it like an API key.

Health:

curl "$OPENSTEER_BASE_URL/health"

Sessions

Create a session:

curl -X POST "$OPENSTEER_BASE_URL/v1/sessions" \
  -H "Authorization: Bearer $OPENSTEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo","sourceType":"manual"}'

Core endpoints:

POST   /v1/sessions
GET    /v1/sessions
GET    /v1/sessions/:sessionId
GET    /v1/sessions/:sessionId/runtime/ping
POST   /v1/sessions/:sessionId/access
DELETE /v1/sessions/:sessionId

Semantic operations

Once you have a session, semantic operations are proxied under the protocol REST base path for that session:

POST /v1/sessions/:sessionId/api/v2/operations/...

Example:

curl -X POST "$OPENSTEER_BASE_URL/v1/sessions/$SESSION_ID/api/v2/operations/page/snapshot" \
  -H "Authorization: Bearer $OPENSTEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"action"}'

Recording

GET  /v1/sessions/:sessionId/recording
POST /v1/sessions/:sessionId/recording/start
POST /v1/sessions/:sessionId/recording/stop

Observability

GET   /v1/sessions/:sessionId/observability
PATCH /v1/sessions/:sessionId/observability
GET   /v1/sessions/:sessionId/events
GET   /v1/sessions/:sessionId/events/stream
GET   /v1/sessions/:sessionId/artifacts
GET   /v1/sessions/:sessionId/artifacts/:artifactId
POST  /v1/sessions/:sessionId/annotations

Browser profiles

POST  /browser-profiles
GET   /browser-profiles
GET   /browser-profiles/:profileId
PATCH /browser-profiles/:profileId
POST  /browser-profiles/:profileId/rotate-proxy
POST  /browser-profiles/:profileId/rotate-fingerprint-seed

Profile import endpoints:

POST /v1/browser-profiles/imports
GET  /v1/browser-profiles/imports/:importId
PUT  /v1/browser-profiles/imports/:importId/snapshot

Registry sync

POST /registry/descriptors/import

These endpoints let you move local DOM and extraction descriptors into cloud-managed flows. Raw discovery traffic stays in the runtime-local workspace scratch store instead of being imported into Convex.

Common cloud codes

CLOUD_AUTH_FAILED
CLOUD_INVALID_REQUEST
CLOUD_SESSION_NOT_FOUND
CLOUD_SESSION_STALE
CLOUD_RUNTIME_UNAVAILABLE
CLOUD_RUNTIME_MISMATCH
CLOUD_MODEL_NOT_ALLOWED
CLOUD_CAPACITY_EXHAUSTED
CLOUD_RATE_LIMITED
CLOUD_BILLING_LIMIT_REACHED
CLOUD_PLAN_RESTRICTED
CLOUD_INTERNAL

Browser profile routes can also return profile-specific codes such as CLOUD_BROWSER_PROFILE_BUSY, CLOUD_BROWSER_PROFILE_DISABLED, CLOUD_BROWSER_PROFILE_NOT_READY, CLOUD_BROWSER_PROFILE_PROXY_UNAVAILABLE, and CLOUD_BROWSER_PROFILE_SYNC_FAILED.

Use these codes for programmatic handling. The HTTP status codes still matter, but the cloud error code is the more useful signal.