Manage runtime through the Platform API

These are Platform staff proxy operations under /v1/admin/runtime, authenticated with a user JWT and runtime.read or runtime.write. They are not the separate runtime service's direct API. Prerequisites: a configured backend runtime connection and apiRequest.

Inspect before changing configuration

Use listRuntimeApps, listRuntimePools, listRuntimeNodes and listRuntimeSessions. Runtime lists use their own cursor/limit fields. A read may return HTTP 200 with available: false; checking HTTP status alone is insufficient.

const result = await apiRequest("/v1/admin/runtime/sessions?limit=25");
if (!result.available) {
  console.log("Runtime is unavailable; keep the last known view");
} else {
  console.log(result);
}

Inspect the response envelope in each reference operation rather than assuming a common data/meta/total shape. Use listRuntimeSessionEvents for timeline details and getRuntimeQueue with a valid poolId for queue inspection.

Configure and launch

Runtime app runner/stream objects are adapter-specific and validated downstream. Reuse a configuration supported by the deployment; an empty object can pass Platform validation while still being unusable in the runtime. Create/configure pools and apps before mapping the app to a store game. Ruleset limits need a valid pool_id before user session creation can succeed.

Use Store publishing for enabled/default game mappings and Session lifecycle for user launch preferences. Runtime session IDs are opaque strings; store IDs and user UUIDs are different identifiers.

Operations and failure handling

stopRuntimeSession accepts an optional reason and returns 204. Drain/undrain nodes to manage placement, and inspect the queue before changing capacity. Writes can return 404 for missing resources, 409 conflicts, 422 invalid_request from downstream validation, or 503 unavailable. Platform staff routes remain callable in maintenance mode, but the runtime dependency can still fail.

API-key management and webhook registration/delivery replay are staff workflows in the reference. Keep runtime service keys in backend/operator tools; they are not user JWTs. Replaying a webhook can repeat downstream processing, so inspect delivery/event identifiers first. The internal signed webhook receiver remains excluded from public callable reference pages. User lifecycle notifications are covered in Realtime.