Swap the running app without WebRTC teardown (owner or admin).
const url = 'http://localhost:8080/v1/sessions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/swap';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"app_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}use serde_json::json;use reqwest;
#[tokio::main]pub async fn main() { let url = "http://localhost:8080/v1/sessions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/swap";
let payload = json!({"app_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"});
let mut headers = reqwest::header::HeaderMap::new(); headers.insert("Authorization", "Bearer <token>".parse().unwrap()); headers.insert("Content-Type", "application/json".parse().unwrap());
let client = reqwest::Client::new(); let response = client.post(url) .headers(headers) .json(&payload) .send() .await;
let results = response.unwrap() .json::<serde_json::Value>() .await .unwrap();
dbg!(results);}curl --request POST \ --url http://localhost:8080/v1/sessions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/swap \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "app_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'STEAM LIBRARY DISCOVERY PHASE 2 adds a NEW TERMINAL CONDITION here - 403 forbidden when the SESSION’S OWNER is not entitled to the target app. The status code itself already existed on this endpoint for the ownership check; what is new is a second way to reach it.
WHY IT EXISTS AT ALL (it is not in the spec’s enforcement list; the implementation added it): a swap IS a launch of a different app into a live session, so without this check the launch gate is defeatable in two requests - launch an app you are entitled to, then swap into one you are not, and the launch check never sees the second app.
KEYED ON THE SESSION OWNER, NOT THE CALLER, and that is the load-bearing half. Swap is owner-OR-ADMIN, so keying on the caller would let an admin swapping someone else’s session launder their own entitlements into it: the session would end up running an app its owner may not launch, and its owner keeps the stream. The question is “may this session run this app”, and a session’s access is its owner’s.
STEAM LIBRARY DISCOVERY PHASE 3 ADDS TWO 409 CONDITIONS HERE, both additive (409 was already declared on this endpoint and Error.code is an open string).
409 home_not_provisioned - the swap target is a DERIVED TILE and THIS SESSION’S HOST holds no live user_homes row for its parent. A swap is pinned to the live session’s host and has NO PLACEMENT STEP, so unlike a launch there is nowhere to re-pin it to: a tile whose library lives on another host, or does not exist yet, cannot be swapped into. Launch it directly instead - the launch path resolves the home host and pins there. Standard error envelope, no extra fields. This was reported as 500 internal until a review found it: the sentinel survived the wrap and only the mapping was missing, so an ordinary, user-correctable condition surfaced as a server fault.
409 parent_app_disabled - the swap target is a DERIVED TILE whose parent is disabled. Same rule and same reasoning as POST /v1/sessions; see that endpoint.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
Examplegenerated
{ "app_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}Responses
Section titled “Responses”Swapped.
object
object
First-run-experience §S5. Machine-readable classification of a terminal failure - “app_exited_early” today. Sits beside error_message (free-text prose that may be rewritten freely); the UI branches on THIS. Always serialized; null unless a failure warranted it.
First-run-experience §S5. The app container’s own captured log tail (newline-joined, oldest first, ~100 lines bound) - the only surviving copy, since app containers run –rm. Always serialized; null unless a failure warranted capturing it. Rendered preformatted, distinct from error_message’s prose rendering.
The profile the session was launched from; null for a legacy/tier/override launch. UI-P4: this is now a LAUNCH PROFILE id, i.e. the USER’S PICK. The rung it resolved to is stream_profile_id.
UI-P4: the RUNG this launch resolved to (e.g. “1080p60-h264”). Always serialized; null for every pre-UI-P4 session and for any legacy/tier/override/console launch. profile_id answers “what did the user pick”, this answers “what did they get” - and because a rung carries its own resolution, the two can legitimately disagree about width/height/fps/ bitrate. The stream block below is always the truth for the running session.
object
Multi-codec: the resolved session video codec on session.stream; absent on an app’s display_stream. Additive; h264 for every pre-multi-codec session. h264_profile applies only when codec is h264.
AS-02: tier-selected initial receiver playout target (ms) on session.stream; absent on an app’s display_stream.
Microphone capture (2026-08-02): the GRANTED state on session.stream (request mic AND instance mic_capture_enabled); absent on an app’s display_stream and on pre-amendment sessions (absent = false).
Session-display-stream (approved 2026-08-16) (2026-08-16, approved — PR #15). Current EXTERNAL (encoded/streamed) width on session.stream; absent on an app’s display_stream. PRESENT WHENEVER THE CONTROL PLANE KNOWS the current external size — i.e. it has seen a 202 from PATCH /v1/sessions/{id}/display or a session_metrics sample reporting it — INCLUDING when that size equals the launch width/height. ABSENT MEANS UNKNOWN (a fresh control plane, or no such signal yet for this session), NOT “at launch size” — do not infer launch size from absence. Ephemeral, in-memory control-plane cache of the last-known value (agent session_metrics is the authoritative source), lost on a control-plane restart until the next 202 or session_metrics sample repopulates it. See control-api.md for the INTERNAL-vs-EXTERNAL vocabulary.
Session-display-stream (approved 2026-08-16). Pairs with external_width; see its description.
Session-display-stream (approved 2026-08-16). Whether the assigned host’s encoder can live-resize the stream at all (readback of agent-api.md session_metrics.external_resize_supported). Absent until an amendment-aware agent reports = unknown, never false.
Abr-resolution-fps-ladder (approved 2026-08-16) amendment (2026-08-16, approved — PR #15). Who currently owns the live external size on session.stream: “auto” (the host’s ABR resolution ladder) or “pinned” (a PATCH /v1/sessions/{id}/display stream_width/ stream_height set it to a non-launch size, which suspends the ladder for the rest of the session or until released). Readback of agent-api.md session_metrics.external_owner. PRESENT ONLY WHEN KNOWN AND external_width/ external_height differ from the launch width/height — mirrors external_width’s presence rule, since the agent reports external_owner only in that same window. Absent on every pre-amendment session and while the external size sits at launch.
Session-display-stream (approved 2026-08-16). The fixed, aspect-ratio-filtered table of [width,height] pairs this session’s stream_width/stream_height may be set to via PATCH /v1/sessions/{id}/display (always <= the launch size, launch size always included). Always present on session.stream for a running session; absent on an app’s display_stream. Not the admin-configured stream-profile “rungs” (AS10-01) — a separate, fixed table unrelated to the admin encode-rung catalog. 21:9 family membership is by a set of reduced ratios {43:18, 64:27, 7:3} — 3440x1440 reduces to 43:18, 2560x1080 to 64:27 — control-api.md’s table is the reference, not a computed tolerance.
UI-P6: how this session’s rung/codec was resolved. Persisted at launch and echoed on every session body; null for every pre-UI-P6 session and for any launch that walked no rung chain (console, or a legacy/tier launch that resolved no launch profile).
THE THREE OUTCOMES ARE DELIBERATELY DISTINGUISHABLE and a client must not collapse them, because stream.codec is identical in all three. Won on merit: selected with rejected_by=null, clamps_bypassed=false, floor=false, override=null. Operator override: override names the forced codec and the selected rung has clamps_bypassed=true with rejected_by=null (it SKIPPED clamps 2/3, 4, 5 and 6 rather than surviving them). Floor: floor=true and the selected rung is clamps_bypassed=true WHILE STILL CARRYING the rejected_by that killed it - it was dispatched despite being rejected. floor and clamps_bypassed answer different questions (“did anything survive?” vs “was THIS rung measured?”) and the override case sets the second without the first; do not merge them.
object
The dispatched rung id.
Multi-codec: the WIRE session video codec (h265 is HEVC). Resolved server-side at launch; the client answers the single codec the host offers. Distinct from CatalogCodec, which spells HEVC ‘hevc’.
NO rung survived the clamp chain and the unconditional h264 floor fired.
Every rung WALKED, in position order. The walk stops at the first survivor, so a clean top-rung win lists exactly one entry - that is the whole decision, not a truncation.
UI-P6: one rung’s verdict in the resolution walk.
object
Wire vocabulary (h264|h265|av1), except when rejected_by is unknown_codec, where it is the raw unmappable catalog value - the only useful thing to show for a hand-edited row.
UI-P6: the clamp that rejected a rung during the walk. Treat this set as OPEN - render an unrecognised value rather than assuming the list is closed. host_encoder=clamp 1, client_decode=clamp 2/3 (codec), decode_height=clamp 2/3 (resolution), decode_history=clamp 4, hardware_encoder=clamp 5, encoder_throughput=clamp 6 (#506: the host’s reported sustained encode throughput for this codec cannot carry the LAUNCH-EFFECTIVE width x height x fps - the rung’s values with any explicit stream.* size override applied - see agent-api.md capacity.codec_throughput; a host that reports no hint never rejects this way), unknown_codec=a rung whose catalog codec does not map (hand-edited data; codec then carries the raw catalog value).
The rung that was actually dispatched. Exactly one entry per recorded decision.
This rung was dispatched WITHOUT being measured against the full clamp chain - the clamp-0 override path (clamps 2/3/4/5/6 skipped) or the floor (every clamp skipped). Never set on a rung that won the walk.
UI-P6: the wire codec the CLIENT reports it is actually decoding (normalised getStats mimeType), beside stream.codec, which is what the SERVER resolved. They should agree; when they do not, that is how a silent fallback or a mis-negotiated m-line presents, so both are kept and neither is reconciled away. NOT constrained to the Codec enum - a value the server never resolves (vp9) is preserved rather than dropped, because it is the loudest disagreement there is. Always serialized; null until the client reports one.
AS10-06: computed stream-health classification; present only when the session is running/unsustainable.
AS10-06: optional human explanation accompanying a degraded health state.
Steam game-exit lifecycle amendment (2026-08-02): coarse in-container application launch state last reported by the agent (agent-api.md session_metrics. app_launch_state, the normative definition). Read-only; there is no request field. OMITTED when the app image does not report launch state - absence means UNKNOWN, and a client must treat an absent field and an unrecognised value identically and fall back to transport-level readiness. A hint and a metric, never a session-state authority and never access control: state remains the only progress signal.
Example
{ "session": { "state": "pending", "stream": { "h264_profile": "constrained-baseline", "codec": "h264", "external_owner": "auto" }, "codec_decision": { "result_codec": "h264", "override": "h264", "considered": [ { "rejected_by": "host_encoder" } ] }, "health_state": "healthy", "app_launch_state": "starting" }}Missing/invalid/expired/revoked token.
object
object
E.g. validation_failed, unauthorized, forbidden, not_found, conflict, session_quota_exceeded, home_in_use, home_not_provisioned, parent_app_disabled, profile_ineligible, profile_not_launchable_for_app, no_host_available, capacity_exhausted, restart_required, rate_limited, internal. Open string, not an enum: new codes are additive and an unknown one falls through to a client’s generic per-status branch.
Present on restart_required.
Steam library discovery Phase 3, ADDITIVE: present on home_in_use when the guard could name the CONFLICTING live session - the one already holding the home. It is here so the client can offer “go to your running session” with a link instead of a dead-end toast. OMITTED rather than empty when the conflict is known but the session is not, so a client branches on presence and never renders a link to nowhere. Load-bearing once derived tiles exist: the lock is held by the PARENT’s home, so a user who clicks a game tile can be refused because a DIFFERENT app (the Steam launcher, or another game from the same install) is running, and without the session id the refusal reads as a bug. See control-api.md §Derived tiles.
Steam library discovery Phase 3, ADDITIVE: present on the 409 conflict from DELETE /v1/apps/{id} when the app has derived tiles and ?delete_derived=true was not sent. A LIST, not a count - the point of the confirmation is that the admin sees what they are about to destroy. Capped; an empty array means the tiles could not be listed, never that there are none.
object
Examplegenerated
{ "error": { "code": "example", "message": "example", "live_sessions": 1, "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "derived_tiles": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example" } ] }}Caller is neither owner nor admin; or (Phase 2) the SESSION OWNER holds no entitlement for the target app.
object
object
E.g. validation_failed, unauthorized, forbidden, not_found, conflict, session_quota_exceeded, home_in_use, home_not_provisioned, parent_app_disabled, profile_ineligible, profile_not_launchable_for_app, no_host_available, capacity_exhausted, restart_required, rate_limited, internal. Open string, not an enum: new codes are additive and an unknown one falls through to a client’s generic per-status branch.
Present on restart_required.
Steam library discovery Phase 3, ADDITIVE: present on home_in_use when the guard could name the CONFLICTING live session - the one already holding the home. It is here so the client can offer “go to your running session” with a link instead of a dead-end toast. OMITTED rather than empty when the conflict is known but the session is not, so a client branches on presence and never renders a link to nowhere. Load-bearing once derived tiles exist: the lock is held by the PARENT’s home, so a user who clicks a game tile can be refused because a DIFFERENT app (the Steam launcher, or another game from the same install) is running, and without the session id the refusal reads as a bug. See control-api.md §Derived tiles.
Steam library discovery Phase 3, ADDITIVE: present on the 409 conflict from DELETE /v1/apps/{id} when the app has derived tiles and ?delete_derived=true was not sent. A LIST, not a count - the point of the confirmation is that the admin sees what they are about to destroy. Capped; an empty array means the tiles could not be listed, never that there are none.
object
Examplegenerated
{ "error": { "code": "example", "message": "example", "live_sessions": 1, "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "derived_tiles": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example" } ] }}No such resource.
object
object
E.g. validation_failed, unauthorized, forbidden, not_found, conflict, session_quota_exceeded, home_in_use, home_not_provisioned, parent_app_disabled, profile_ineligible, profile_not_launchable_for_app, no_host_available, capacity_exhausted, restart_required, rate_limited, internal. Open string, not an enum: new codes are additive and an unknown one falls through to a client’s generic per-status branch.
Present on restart_required.
Steam library discovery Phase 3, ADDITIVE: present on home_in_use when the guard could name the CONFLICTING live session - the one already holding the home. It is here so the client can offer “go to your running session” with a link instead of a dead-end toast. OMITTED rather than empty when the conflict is known but the session is not, so a client branches on presence and never renders a link to nowhere. Load-bearing once derived tiles exist: the lock is held by the PARENT’s home, so a user who clicks a game tile can be refused because a DIFFERENT app (the Steam launcher, or another game from the same install) is running, and without the session id the refusal reads as a bug. See control-api.md §Derived tiles.
Steam library discovery Phase 3, ADDITIVE: present on the 409 conflict from DELETE /v1/apps/{id} when the app has derived tiles and ?delete_derived=true was not sent. A LIST, not a count - the point of the confirmation is that the admin sees what they are about to destroy. Capped; an empty array means the tiles could not be listed, never that there are none.
object
Examplegenerated
{ "error": { "code": "example", "message": "example", "live_sessions": 1, "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "derived_tiles": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example" } ] }}Session_not_swappable / swap_exceeds_reservation / conflict (pre-existing), or (Phase 3) home_not_provisioned - the target tile’s parent has no home on THIS session’s host - or parent_app_disabled.
object
object
E.g. validation_failed, unauthorized, forbidden, not_found, conflict, session_quota_exceeded, home_in_use, home_not_provisioned, parent_app_disabled, profile_ineligible, profile_not_launchable_for_app, no_host_available, capacity_exhausted, restart_required, rate_limited, internal. Open string, not an enum: new codes are additive and an unknown one falls through to a client’s generic per-status branch.
Present on restart_required.
Steam library discovery Phase 3, ADDITIVE: present on home_in_use when the guard could name the CONFLICTING live session - the one already holding the home. It is here so the client can offer “go to your running session” with a link instead of a dead-end toast. OMITTED rather than empty when the conflict is known but the session is not, so a client branches on presence and never renders a link to nowhere. Load-bearing once derived tiles exist: the lock is held by the PARENT’s home, so a user who clicks a game tile can be refused because a DIFFERENT app (the Steam launcher, or another game from the same install) is running, and without the session id the refusal reads as a bug. See control-api.md §Derived tiles.
Steam library discovery Phase 3, ADDITIVE: present on the 409 conflict from DELETE /v1/apps/{id} when the app has derived tiles and ?delete_derived=true was not sent. A LIST, not a count - the point of the confirmation is that the admin sees what they are about to destroy. Capped; an empty array means the tiles could not be listed, never that there are none.
object
Examplegenerated
{ "error": { "code": "example", "message": "example", "live_sessions": 1, "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "derived_tiles": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example" } ] }}