# Manage runtime through the Platform API

URL: https://docs.spacerun.co/docs/platform/guides/runtime-management

> Inspect apps, pools, nodes and sessions, manage mappings, and handle runtime availability.

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](https://docs.spacerun.co/docs/platform/guides/quickstart).

## Inspect before changing configuration

Use [listRuntimeApps](https://docs.spacerun.co/docs/platform/reference/runtime-apps/listRuntimeApps), [listRuntimePools](https://docs.spacerun.co/docs/platform/reference/runtime-pools-and-nodes/listRuntimePools), [listRuntimeNodes](https://docs.spacerun.co/docs/platform/reference/runtime-pools-and-nodes/listRuntimeNodes) and [listRuntimeSessions](https://docs.spacerun.co/docs/platform/reference/runtime-sessions/listRuntimeSessions). Runtime lists use their own cursor/limit fields. A read may return HTTP 200 with `available: false`; checking HTTP status alone is insufficient.

```ts
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](https://docs.spacerun.co/docs/platform/reference/runtime-sessions/listRuntimeSessionEvents) for timeline details and [getRuntimeQueue](https://docs.spacerun.co/docs/platform/reference/runtime-sessions/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](https://docs.spacerun.co/docs/platform/guides/store-publishing) for enabled/default game mappings and [Session lifecycle](https://docs.spacerun.co/docs/platform/guides/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](https://docs.spacerun.co/docs/platform/reference/runtime-sessions/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](https://docs.spacerun.co/docs/platform/guides/realtime).