unom/punktfunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 25 Wiki Activity
Files
9ea5c2a1292dbb6e2661f35954b3556f0806a2eb
punktfunk/api/openapi.json
T
enricobuehler 63efe0ecd5
apple / swift (push) Successful in 1m18s
Details
apple / screenshots (push) Successful in 4m22s
Details
ci / web (push) Successful in 53s
Details
ci / docs-site (push) Successful in 1m3s
Details
decky / build-publish (push) Successful in 20s
Details
docker / build-push (--build-arg FEDORA_VERSION=44, ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora44-rpm) (push) Successful in 9s
Details
docker / build-push (., web/Dockerfile, punktfunk-web) (push) Successful in 33s
Details
docker / build-push (ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora-rpm) (push) Successful in 9s
Details
docker / build-push (ci, ci/rust-ci.Dockerfile, punktfunk-rust-ci) (push) Successful in 9s
Details
docker / build-push (docs-site, docs-site/Dockerfile, punktfunk-docs) (push) Successful in 8s
Details
ci / bench (push) Successful in 5m3s
Details
android / android (push) Successful in 17m6s
Details
arch / build-publish (push) Successful in 16m51s
Details
deb / build-publish (push) Successful in 12m16s
Details
ci / rust (push) Successful in 25m22s
Details
rpm / build-publish (43, bazzite, punktfunk-fedora-rpm) (push) Successful in 14m16s
Details
rpm / build-publish (44, fedora-44, punktfunk-fedora44-rpm) (push) Successful in 14m17s
Details
windows-host / package (push) Has been cancelled
Details
docker / deploy-docs (push) Failing after 19s
Details
feat(host/hooks): per-app prep/undo commands (M2b — Sunshine prep-cmd parity) 
`prep: [{"do": …, "undo": …}]` arrays on GameStream apps.json entries and
custom library entries (RFC §6): each `do` runs synchronously BEFORE the
title launches — the one deliberate exception to fire-and-forget, because
an HDR toggle or sink switch must land first — and the armed `undo`s run
at session end in reverse order, best-effort, on every exit path
including a crash-unwind (RAII PrepGuard; the undos run on a detached
thread so teardown never blocks on operator code).

- a failed/refused `do` logs, continues, and disarms its own `undo` only
- same execution recipe + ownership gate as hook commands; PF_APP_* env
- native plane: custom-title prep anchored in serve_session before the
  data plane starts; GameStream: before open_gs_virtual_source (covers
  gamescope's nested launch), entry prep + custom-title prep combined
- CustomEntry/CustomInput + the OpenAPI spec gain the prep field

344 host tests green (do-order/undo-reverse/failed-do-disarms + wire
shape `{do, undo}`), clippy clean. On-glass with a real client session
owed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-16 22:02:35 +02:00

4537 lines
143 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"openapi": "3.1.0",
"info": {
"title": "punktfunk management API",
"description": "Control-plane API for managing a punktfunk streaming host: host capabilities, runtime status, paired clients, the pairing PIN flow, and session control. Authentication: HTTP bearer token, enforced on every route except `/api/v1/health` when the host is started with a management token (mandatory for non-loopback binds).",
"contact": {
"name": "unom"
},
"license": {
"name": "MIT OR Apache-2.0",
"identifier": "MIT OR Apache-2.0"
},
"version": "0.12.0"
},
"paths": {
"/api/v1/clients": {
"get": {
"tags": [
"clients"
],
"summary": "List paired clients",
"operationId": "listPairedClients",
"responses": {
"200": {
"description": "All certificate-pinned clients",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PairedClient"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/clients/{fingerprint}": {
"delete": {
"tags": [
"clients"
],
"summary": "Unpair a client",
"description": "Removes the client's certificate from the pairing store. Caveat: the nvhttp TLS layer\ndoes not yet reject unlisted certificates (`gamestream/tls.rs` accepts any well-formed\nclient cert — a planned hardening step), so until that lands this removes the client\nfrom the listing without severing its ability to reconnect.",
"operationId": "unpairClient",
"parameters": [
{
"name": "fingerprint",
"in": "path",
"description": "Hex SHA-256 fingerprint of the client certificate DER (64 chars, case-insensitive)",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Client unpaired"
},
"400": {
"description": "Malformed fingerprint",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No paired client with that fingerprint",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/compositors": {
"get": {
"tags": [
"host"
],
"summary": "Available compositor backends",
"description": "Lists every backend the host knows how to drive, flags which are usable right now, and marks\nthe one an unspecified (`Auto`) client request resolves to. Clients pass an `id` to their\n`--compositor` flag (or `PUNKTFUNK_COMPOSITOR_*` over the C ABI) to request it.",
"operationId": "listCompositors",
"responses": {
"200": {
"description": "Compositor backends with availability + the auto-detected default",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AvailableCompositor"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/display/layout": {
"put": {
"tags": [
"display"
],
"summary": "Arrange virtual displays",
"description": "Set the **manual** desktop arrangement — per-identity-slot `(x, y)` offsets so a multi-monitor\ngroup (§6A/§6B) comes back where the operator placed it. Persisted into the policy's layout block\nand switched to manual mode; applied from the next connect (a live group re-applies on its next\nacquire). Locks in the current effective behavior as explicit fields, so arranging displays never\nsilently changes keep-alive/topology/conflict/identity. See `design/display-management.md` §6.2.",
"operationId": "setDisplayLayout",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisplayLayoutRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Layout stored; the new settings state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisplaySettingsState"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Layout could not be persisted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/display/presets": {
"get": {
"tags": [
"display"
],
"summary": "List the saved custom presets",
"description": "The operator's named field-bundles (`display-presets.json`). These also ride the\n`GET /display/settings` response (`custom_presets`), so the console rarely needs this directly.",
"operationId": "listCustomPresets",
"responses": {
"200": {
"description": "The saved custom presets",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomPreset"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
},
"post": {
"tags": [
"display"
],
"summary": "Save a custom preset",
"description": "Stores a named bundle of the display-behavior axes (+ the game-session axis) the operator can\napply later. The host assigns a stable id, returned in the body. Applying a preset is a\n`PUT /display/settings` with a `Custom` policy carrying its `fields` — no separate apply route.",
"operationId": "createCustomPreset",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomPresetInput"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Preset created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomPreset"
}
}
}
},
"400": {
"description": "Empty name",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Could not persist the catalog",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/display/presets/{id}": {
"put": {
"tags": [
"display"
],
"summary": "Update a custom preset",
"operationId": "updateCustomPreset",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The custom preset id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomPresetInput"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Preset updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomPreset"
}
}
}
},
"400": {
"description": "Empty name",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No custom preset with that id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Could not persist the catalog",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
},
"delete": {
"tags": [
"display"
],
"summary": "Delete a custom preset",
"description": "Removes it from the catalog. The active policy is untouched — if this preset was the one applied,\nthe running behavior stays exactly as it was (the catalog and `display-settings.json` are decoupled).",
"operationId": "deleteCustomPreset",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The custom preset id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Preset deleted"
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No custom preset with that id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Could not persist the catalog",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/display/release": {
"post": {
"tags": [
"display"
],
"summary": "Release kept virtual displays",
"description": "Tear down lingering/pinned displays now — so a physical-screen user gets their screen back\nwithout waiting out the linger. `slot` releases one; omit it to release all kept displays.\nActive (streaming) displays are never torn down here (that is session control).",
"operationId": "releaseDisplay",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReleaseDisplayRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "The number of kept displays released",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReleaseDisplayResult"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/display/settings": {
"get": {
"tags": [
"display"
],
"summary": "Display-management policy",
"description": "The stored virtual-display policy (lifecycle, topology, conflict handling, identity, layout),\nevery preset's expansion, and which options this build enforces yet. See\n`design/display-management.md`.",
"operationId": "getDisplaySettings",
"responses": {
"200": {
"description": "Stored policy + preset expansions + enforced options",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisplaySettingsState"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
},
"put": {
"tags": [
"display"
],
"summary": "Set the display-management policy",
"description": "Persists a new policy (validated + clamped) and applies it from the next connect/teardown — a\nrunning session keeps the display it opened on. `keep_alive: forever` (the gaming-rig preset) is\nhonored (the display is Pinned; free it via `POST /display/release`).",
"operationId": "setDisplaySettings",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisplayPolicy"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Policy stored; the new state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisplaySettingsState"
}
}
}
},
"400": {
"description": "Malformed policy body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Policy could not be persisted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/display/state": {
"get": {
"tags": [
"display"
],
"summary": "Live virtual displays",
"description": "The host's managed virtual displays right now — active (streaming), lingering (kept after\ndisconnect, counting down to teardown), or pinned (kept indefinitely). See\n`design/display-management.md`.",
"operationId": "getDisplayState",
"responses": {
"200": {
"description": "The live/kept virtual displays",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisplayStateResponse"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/events": {
"get": {
"tags": [
"events"
],
"summary": "Stream host lifecycle events (SSE)",
"description": "Server-Sent Events stream of the host's lifecycle events: client connect/disconnect, session\nand stream start/end, pairing decisions, display create/release, library changes, host\nstart/stop — both protocol planes. Frames carry `id:` = the event's monotonic `seq`,\n`event:` = its kind, and `data:` = the event JSON (schema-versioned, additive-only).\n\nResume: standard `Last-Event-ID` (or `?since=`) replays from the in-memory ring; a consumer\nthat fell off the ring receives an `event: dropped` frame first and should resync via the\nREST snapshots. Keep-alive comments are sent every 15 s.",
"operationId": "streamEvents",
"parameters": [
{
"name": "since",
"in": "query",
"description": "Resume cursor: only events with `seq` greater than this are sent (the ring keeps the newest ~1024). `Last-Event-ID` takes precedence.",
"required": false,
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0
}
},
{
"name": "kinds",
"in": "query",
"description": "Comma-separated server-side kind filter: exact kinds (`pairing.pending`) or `domain.*` prefixes (`stream.*`).",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "Last-Event-ID",
"in": "header",
"description": "SSE auto-reconnect cursor — the `id:` of the last received frame.",
"required": false,
"schema": {
"type": [
"integer",
"null"
],
"format": "int64",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "SSE stream; each frame's `data:` is one HostEvent",
"content": {
"text/event-stream": {
"schema": {
"$ref": "#/components/schemas/HostEvent"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"503": {
"description": "Concurrent event-stream cap reached — retry shortly",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/gpus": {
"get": {
"tags": [
"gpu"
],
"summary": "GPU inventory and selection",
"description": "Lists the host's hardware GPUs, the persisted auto/manual preference, the GPU the next session\nwill use (and why), and the GPU live sessions encode on right now.",
"operationId": "listGpus",
"responses": {
"200": {
"description": "GPU inventory + selection state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GpuState"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/gpus/preference": {
"put": {
"tags": [
"gpu"
],
"summary": "Set the GPU preference",
"description": "`auto` restores automatic selection (`PUNKTFUNK_RENDER_ADAPTER` pin, else max dedicated VRAM);\n`manual` pins capture + encode to the given GPU. Persisted across restarts; applies to the\n**next** session (a running session keeps its GPU). If the preferred GPU is absent at session\nstart the host falls back to automatic selection rather than failing.",
"operationId": "setGpuPreference",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetGpuPreference"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Preference stored; the new selection state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GpuState"
}
}
}
},
"400": {
"description": "Unknown mode, or `gpu_id` missing / not a listed GPU",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Preference could not be persisted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/health": {
"get": {
"tags": [
"host"
],
"summary": "Liveness probe",
"description": "Always available without authentication.",
"operationId": "getHealth",
"responses": {
"200": {
"description": "Host is up",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
}
}
},
"security": [
{}
]
}
},
"/api/v1/hooks": {
"get": {
"tags": [
"hooks"
],
"summary": "Get the hook configuration",
"description": "The operator's `hooks.json`: commands and webhooks fired on host lifecycle events. Empty\nwhen unconfigured.",
"operationId": "getHooks",
"responses": {
"200": {
"description": "The stored hook configuration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HooksConfig"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
},
"put": {
"tags": [
"hooks"
],
"summary": "Replace the hook configuration",
"description": "Validates and persists a full `hooks.json` document (this is a whole-document PUT, not a\npatch). Applies from the next event — no restart. Hook commands run as the host user\n(interactive user session on Windows): treat this configuration as operator-privileged.",
"operationId": "setHooks",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HooksConfig"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Configuration stored; the new state",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HooksConfig"
}
}
}
},
"400": {
"description": "Structurally invalid configuration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Configuration could not be persisted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/host": {
"get": {
"tags": [
"host"
],
"summary": "Host identity and capabilities",
"operationId": "getHostInfo",
"responses": {
"200": {
"description": "Host identity, versions, codecs, and port map",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HostInfo"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/library": {
"get": {
"tags": [
"library"
],
"summary": "List the game library",
"description": "Every installed-store title (Steam, read from the host's local files — no Steam API key)\nmerged with the user's custom entries, sorted by title. Artwork fields are URLs the client\nfetches directly (the public Steam CDN for Steam titles).",
"operationId": "getLibrary",
"responses": {
"200": {
"description": "Unified library across all stores",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GameEntry"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/library/art/{id}/{kind}": {
"get": {
"tags": [
"library"
],
"summary": "Fetch one cover-art image for a library entry",
"description": "Resolves `kind` (`portrait` | `hero` | `logo` | `header`) for the given library id and streams\nthe image bytes. For a Steam title, the host's own local Steam cache is tried first (exact —\nit's what the user's Steam client already shows for it), the public Steam CDN's flat URL\nconvention as a fallback (newer titles' CDN assets can live at a per-asset-hash path the host\ncan't predict, in which case this 404s and the client falls through to its next art candidate).\nOnly Steam ids are backed today; any other store 404s.",
"operationId": "getLibraryArt",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The store-qualified library id, e.g. `steam:570`",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "kind",
"in": "path",
"description": "`portrait` | `hero` | `logo` | `header`",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Image bytes",
"content": {
"image/jpeg": {}
}
},
"401": {
"description": "Missing or invalid credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No art of that kind for that id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/library/custom": {
"post": {
"tags": [
"library"
],
"summary": "Add a custom library entry",
"description": "Creates a user-curated title (e.g. a non-Steam game, an emulator, a ROM) with caller-supplied\nartwork URLs. The host assigns a stable id, returned in the body.",
"operationId": "createCustomGame",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomInput"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Entry created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomEntry"
}
}
}
},
"400": {
"description": "Empty title",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Could not persist the catalog",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/library/custom/{id}": {
"put": {
"tags": [
"library"
],
"summary": "Update a custom library entry",
"operationId": "updateCustomGame",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The custom entry id (without the `custom:` prefix)",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomInput"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Entry updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomEntry"
}
}
}
},
"400": {
"description": "Empty title",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No custom entry with that id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Could not persist the catalog",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
},
"delete": {
"tags": [
"library"
],
"summary": "Delete a custom library entry",
"operationId": "deleteCustomGame",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The custom entry id (without the `custom:` prefix)",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Entry deleted"
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No custom entry with that id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Could not persist the catalog",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/local/summary": {
"get": {
"tags": [
"host"
],
"summary": "Local status summary for the tray icon",
"description": "Non-sensitive status (counts and booleans only — no PIN values, no fingerprints, no device\nnames). Unauthenticated, but served to loopback peers only.",
"operationId": "getLocalSummary",
"responses": {
"200": {
"description": "Non-sensitive local host status (loopback peers only)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LocalSummary"
}
}
}
},
"401": {
"description": "Non-loopback peer",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
},
"security": [
{}
]
}
},
"/api/v1/logs": {
"get": {
"tags": [
"logs"
],
"summary": "Host logs",
"description": "The host's recent log entries — an in-memory ring of the newest few thousand, captured at\nDEBUG and above regardless of `RUST_LOG`. Follow live by polling with `after` set to the last\nresponse's `next` cursor; a `dropped: true` means entries were evicted between polls (the ring\nwrapped). Bearer-only: logs can reference client identities and host paths, so this is part of\nthe loopback-only admin surface, never the LAN-readable mTLS one.",
"operationId": "logsGet",
"parameters": [
{
"name": "after",
"in": "query",
"description": "Return entries with seq greater than this (omitted/0 = oldest retained)",
"required": false,
"schema": {
"type": "integer",
"format": "int64",
"minimum": 0
}
},
{
"name": "limit",
"in": "query",
"description": "Max entries per response (default and cap 1000)",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Entries after the cursor, oldest first",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LogPage"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/native/clients": {
"get": {
"tags": [
"native"
],
"summary": "List native paired clients",
"operationId": "listNativeClients",
"responses": {
"200": {
"description": "Paired native clients",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NativeClient"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/native/clients/{fingerprint}": {
"delete": {
"tags": [
"native"
],
"summary": "Unpair a native client",
"description": "Removes a punktfunk/1 client from the native trust store by fingerprint.",
"operationId": "unpairNativeClient",
"parameters": [
{
"name": "fingerprint",
"in": "path",
"description": "Hex SHA-256 of the client certificate (case-insensitive)",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Client unpaired"
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No paired native client with that fingerprint",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"503": {
"description": "Native host not enabled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/native/pair": {
"get": {
"tags": [
"native"
],
"summary": "Native pairing status",
"description": "The native (punktfunk/1) pairing window. Poll while armed to show the PIN + countdown.\n`enabled: false` means this host runs GameStream only (no `--native`).",
"operationId": "getNativePairing",
"responses": {
"200": {
"description": "Native pairing status",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NativePairStatus"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
},
"delete": {
"tags": [
"native"
],
"summary": "Disarm native pairing",
"description": "Closes the pairing window immediately (no new ceremonies accepted).",
"operationId": "disarmNativePairing",
"responses": {
"204": {
"description": "Pairing disarmed"
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"503": {
"description": "Native host not enabled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/native/pair/arm": {
"post": {
"tags": [
"native"
],
"summary": "Arm native pairing",
"description": "Opens a pairing window and mints a fresh PIN to display. The user enters it on their device\nwithin `ttl_secs`; the device then appears in the native client list.",
"operationId": "armNativePairing",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ArmNativePairing"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Pairing armed; the response carries the PIN to display",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NativePairStatus"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"503": {
"description": "Native host not available in this process",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/native/pending": {
"get": {
"tags": [
"native"
],
"summary": "List devices awaiting pairing approval",
"description": "Unpaired devices that tried to connect while the host requires pairing. Approve one to pair\nit without a PIN (delegated approval); entries expire after ~10 minutes.",
"operationId": "listPendingDevices",
"responses": {
"200": {
"description": "Devices awaiting approval (empty when none, or when the native host is not enabled)",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PendingDevice"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/native/pending/{id}/approve": {
"post": {
"tags": [
"native"
],
"summary": "Approve a pending device",
"description": "Pairs the device's certificate fingerprint — it can connect immediately (no PIN). Optionally\nrelabel it via the body; send `{}` to keep the name it knocked with.",
"operationId": "approvePendingDevice",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Pending-request id from the pending list",
"required": true,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApprovePending"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Device paired",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NativeClient"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No pending request with that id (expired?)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Could not persist the trust store",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"503": {
"description": "Native host not enabled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/native/pending/{id}/deny": {
"post": {
"tags": [
"native"
],
"summary": "Deny a pending device",
"description": "Drops the request. Not a blocklist — the device's next attempt knocks again.",
"operationId": "denyPendingDevice",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Pending-request id from the pending list",
"required": true,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
],
"responses": {
"204": {
"description": "Request dropped"
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No pending request with that id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"503": {
"description": "Native host not enabled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/pair": {
"get": {
"tags": [
"pairing"
],
"summary": "Pairing-flow status",
"description": "Poll this to know when to prompt the user for the PIN Moonlight displays.",
"operationId": "getPairingStatus",
"responses": {
"200": {
"description": "Whether a pairing handshake is waiting for a PIN",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PairingStatus"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/pair/pin": {
"post": {
"tags": [
"pairing"
],
"summary": "Submit the pairing PIN",
"description": "Delivers the PIN the Moonlight client is displaying, completing the out-of-band half\nof the pairing handshake.",
"operationId": "submitPairingPin",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitPin"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "PIN delivered to the waiting handshake"
},
"400": {
"description": "Malformed PIN or unparseable JSON body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"409": {
"description": "No pairing handshake is waiting for a PIN",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"415": {
"description": "Body is not application/json",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"422": {
"description": "JSON body does not match the schema",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/session": {
"delete": {
"tags": [
"session"
],
"summary": "Stop the active session",
"description": "Kicks the connected client: stops the video/audio stream threads and clears the launch\nstate. Idempotent — succeeds even when nothing is streaming.",
"operationId": "stopSession",
"responses": {
"204": {
"description": "Session stopped (or none was active)"
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/session/idr": {
"post": {
"tags": [
"session"
],
"summary": "Force a keyframe",
"description": "Asks the encoder for an IDR frame on the active video stream (what a client requests\nafter unrecoverable loss — exposed for debugging).",
"operationId": "requestIdr",
"responses": {
"202": {
"description": "Keyframe requested"
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"409": {
"description": "No active video stream",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/stats/capture/live": {
"get": {
"tags": [
"stats"
],
"summary": "Live in-progress capture",
"description": "The full sample time-series of the capture currently recording, for live graphing. `404` when\nnothing is armed.",
"operationId": "statsCaptureLive",
"responses": {
"200": {
"description": "The in-progress capture (meta + samples so far)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Capture"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No capture is currently recording",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/stats/capture/start": {
"post": {
"tags": [
"stats"
],
"summary": "Start a stats capture",
"description": "Arms a new performance-stats capture. Idempotent: if a capture is already running this returns\nthe current status unchanged. While armed, the streaming loops emit aggregated samples (~ every\n1–2 s) into the in-progress capture, readable live via `GET /stats/capture/live`.",
"operationId": "statsCaptureStart",
"responses": {
"200": {
"description": "Capture armed (or already running)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatsStatus"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/stats/capture/status": {
"get": {
"tags": [
"stats"
],
"summary": "Stats capture status",
"description": "Whether a capture is armed, its sample count, and start time. Poll this (e.g. every 2 s) to\ndrive the capture-control UI.",
"operationId": "statsCaptureStatus",
"responses": {
"200": {
"description": "In-progress capture status (idle when not armed)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StatsStatus"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/stats/capture/stop": {
"post": {
"tags": [
"stats"
],
"summary": "Stop the stats capture",
"description": "Disarms the in-progress capture and writes it to disk atomically, returning its summary. If\nnothing was recording, returns `204 No Content`.",
"operationId": "statsCaptureStop",
"responses": {
"200": {
"description": "Capture stopped and saved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CaptureMeta"
}
}
}
},
"204": {
"description": "Nothing was recording"
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Could not write the recording to disk",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/stats/recordings": {
"get": {
"tags": [
"stats"
],
"summary": "List saved recordings",
"description": "Every saved capture's summary (the `meta` head only — not the sample body), newest first.",
"operationId": "statsRecordingsList",
"responses": {
"200": {
"description": "Saved capture summaries, newest first",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CaptureMeta"
}
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/stats/recordings/{id}": {
"get": {
"tags": [
"stats"
],
"summary": "Get a saved recording",
"description": "The full capture (meta + samples) for `id`, for graphing or download.",
"operationId": "statsRecordingGet",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The recording id (its filename stem)",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The full capture",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Capture"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No recording with that id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "The recording file is unreadable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
},
"delete": {
"tags": [
"stats"
],
"summary": "Delete a saved recording",
"description": "Removes the recording `id` from disk. `404` if there is no such recording.",
"operationId": "statsRecordingDelete",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The recording id (its filename stem)",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Recording deleted"
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "No recording with that id",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Could not delete the recording",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/api/v1/status": {
"get": {
"tags": [
"host"
],
"summary": "Live host status",
"operationId": "getStatus",
"responses": {
"200": {
"description": "Streaming/pairing state and the active session, if any",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RuntimeStatus"
}
}
}
},
"401": {
"description": "Missing or invalid bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ApiActiveGpu": {
"type": "object",
"description": "The GPU live sessions are encoding on right now.",
"required": [
"id",
"name",
"vendor",
"backend",
"sessions"
],
"properties": {
"backend": {
"type": "string",
"description": "The encode backend in use (`nvenc` | `amf` | `qsv` | `vaapi` | `software`)."
},
"id": {
"type": "string",
"description": "Stable id matching an entry of `gpus` (empty for the CPU/software encoder)."
},
"name": {
"type": "string"
},
"sessions": {
"type": "integer",
"format": "int32",
"description": "Number of live encode sessions on it.",
"minimum": 0
},
"vendor": {
"type": "string",
"description": "`nvidia` | `amd` | `intel` | `other`."
}
}
},
"ApiCodec": {
"type": "string",
"description": "Video codec identifier. The wire token matches the codec's canonical name used across the\nstack (SDP/GameStream advertisement, the stats-capture `CaptureMeta.codec`, and the encoder's\n[`Codec::label`]) — notably `H.265` serializes as `\"hevc\"`, not `\"h265\"`, so the same codec\nreads identically on every console page.",
"enum": [
"h264",
"hevc",
"av1",
"pyrowave"
]
},
"ApiDisplayInfo": {
"type": "object",
"description": "One live or kept virtual display.",
"required": [
"slot",
"backend",
"mode",
"state",
"sessions",
"group",
"display_index",
"x",
"y",
"topology"
],
"properties": {
"backend": {
"type": "string",
"description": "Backend name (`pf-vdisplay`, `kwin`, …)."
},
"client": {
"type": [
"string",
"null"
],
"description": "Short client label, when the owner tracks it."
},
"display_index": {
"type": "integer",
"format": "int32",
"description": "This display's ordinal within its group, in acquire order (0-based).",
"minimum": 0
},
"expires_in_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Milliseconds until a lingering display is torn down (absent when active/pinned).",
"minimum": 0
},
"group": {
"type": "integer",
"format": "int32",
"description": "Display group (shared desktop) id — several displays with the same group form one desktop (§6A).",
"minimum": 0
},
"identity_slot": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Stable per-client identity slot keying persistent config + manual layout (absent = shared/anonymous).",
"minimum": 0
},
"mode": {
"type": "string",
"description": "`WIDTHxHEIGHT@HZ`."
},
"sessions": {
"type": "integer",
"format": "int32",
"description": "Live sessions holding the display.",
"minimum": 0
},
"slot": {
"type": "integer",
"format": "int64",
"description": "Stable-enough id for the `/display/release` `slot` argument.",
"minimum": 0
},
"state": {
"type": "string",
"description": "`active` | `lingering` | `pinned`."
},
"topology": {
"type": "string",
"description": "Effective topology for this display's group (`extend` | `primary` | `exclusive`)."
},
"x": {
"type": "integer",
"format": "int32",
"description": "Desktop-space top-left `x` (auto-row or the console's manual arrangement, §6.2)."
},
"y": {
"type": "integer",
"format": "int32",
"description": "Desktop-space top-left `y`."
}
}
},
"ApiError": {
"type": "object",
"description": "Error envelope for every non-2xx response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"ApiGpu": {
"type": "object",
"description": "One hardware GPU on the host (software/WARP adapters are never listed).",
"required": [
"id",
"name",
"vendor",
"vram_mb"
],
"properties": {
"id": {
"type": "string",
"description": "Stable identifier (`vendorid-deviceid-occurrence`, hex PCI ids) — pass to `setGpuPreference`.\nStable across reboots and driver updates, unlike an adapter index or LUID.",
"example": "10de-2c05-0"
},
"name": {
"type": "string",
"description": "Adapter/marketing name.",
"example": "NVIDIA GeForce RTX 5070 Ti"
},
"vendor": {
"type": "string",
"description": "`nvidia` | `amd` | `intel` | `other`."
},
"vram_mb": {
"type": "integer",
"format": "int64",
"description": "Dedicated VRAM in MiB (0 where the platform doesn't expose it).",
"minimum": 0
}
}
},
"ApiSelectedGpu": {
"type": "object",
"description": "The GPU the **next** session's pipeline will be created on, and why. (A preference change\napplies to the next session; a running session keeps the GPU it opened on.)",
"required": [
"id",
"name",
"vendor",
"source"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"source": {
"type": "string",
"description": "Why this GPU was selected: `preference` (the manual choice), `env`\n(`PUNKTFUNK_RENDER_ADAPTER`), `auto` (max dedicated VRAM / platform default), or\n`preference_missing` (a manual choice is set but that GPU is absent — auto-selected\ninstead so the host keeps streaming)."
},
"vendor": {
"type": "string",
"description": "`nvidia` | `amd` | `intel` | `other`."
}
}
},
"ApprovePending": {
"type": "object",
"description": "Approve-pending-device request body. Send `{}` to keep the device's own name.",
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "Operator-chosen label for the device (defaults to the name it knocked with).",
"example": "Living Room TV"
}
}
},
"ArmNativePairing": {
"type": "object",
"description": "Arm-native-pairing request body.",
"properties": {
"fingerprint": {
"type": [
"string",
"null"
],
"description": "Optional: bind the window to ONE device fingerprint (hex SHA-256, e.g. from a pending knock).\nWhen set, only a pairing attempt from that fingerprint consumes the window — so an unpaired\nLAN peer can neither pair nor burn a window armed for a specific device (security-review #9).\nOmit for an unbound window (any device may use the PIN — trusted-LAN only).",
"example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
},
"ttl_secs": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Window length in seconds (default 120; clamped to 15–600).",
"example": 120,
"minimum": 0
}
}
},
"Artwork": {
"type": "object",
"description": "Cover art for a title. All fields are URLs (the Steam CDN for Steam titles, user-supplied for\ncustom). The client prefers `portrait` for a grid and falls back to `header` when a title has\nno 600×900 capsule (common for older Steam apps).",
"properties": {
"header": {
"type": [
"string",
"null"
],
"description": "Horizontal header (Steam `header.jpg`) — the universal fallback."
},
"hero": {
"type": [
"string",
"null"
],
"description": "Wide background (Steam `library_hero.jpg`)."
},
"logo": {
"type": [
"string",
"null"
],
"description": "Transparent title logo (Steam `logo.png`)."
},
"portrait": {
"type": [
"string",
"null"
],
"description": "Vertical capsule / poster (Steam `library_600x900.jpg`). Best for a grid."
}
}
},
"AvailableCompositor": {
"type": "object",
"description": "A compositor backend the host can drive a virtual output on, and whether it's usable now.",
"required": [
"id",
"label",
"available",
"default"
],
"properties": {
"available": {
"type": "boolean",
"description": "Usable on this host right now: the live session's own compositor, or gamescope wherever\nits binary is installed."
},
"default": {
"type": "boolean",
"description": "True for the backend an `Auto` (unspecified) request resolves to right now."
},
"id": {
"type": "string",
"description": "Stable identifier (`\"kwin\"` | `\"wlroots\"` | `\"mutter\"` | `\"gamescope\"`) — pass this to a\nclient's `--compositor` flag."
},
"label": {
"type": "string",
"description": "Human-readable label for UIs."
}
}
},
"Capture": {
"type": "object",
"description": "A full capture: summary + the sample time-series. The wire + on-disk shape.",
"required": [
"meta",
"samples"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/CaptureMeta"
},
"samples": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StatsSample"
}
}
}
},
"CaptureMeta": {
"type": "object",
"description": "Capture summary — the filename stem plus the negotiated mode/codec/client. Stored at the head\nof each on-disk recording and listed standalone (without the sample body) by\n[`StatsRecorder::list`].",
"required": [
"id",
"started_unix_ms",
"duration_ms",
"kind",
"width",
"height",
"fps",
"codec",
"client",
"sample_count"
],
"properties": {
"client": {
"type": "string",
"description": "Short label / fingerprint prefix, or `\"\"` if unknown."
},
"codec": {
"type": "string",
"description": "`\"h264\" | \"hevc\" | \"av1\"`."
},
"duration_ms": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"fps": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"height": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"id": {
"type": "string",
"description": "e.g. `\"2026-06-26T20-14-03Z_5120x1440\"` — also the filename stem."
},
"kind": {
"type": "string",
"description": "`\"native\" | \"gamestream\"`."
},
"sample_count": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"started_unix_ms": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"width": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
},
"ClientRef": {
"type": "object",
"description": "The connecting/disconnecting client's identity.",
"required": [
"name",
"plane"
],
"properties": {
"fingerprint": {
"type": [
"string",
"null"
],
"description": "Hex SHA-256 certificate fingerprint, when the client presented one."
},
"name": {
"type": "string",
"description": "Client-supplied device name; may be empty (an anonymous or compat-plane client)."
},
"plane": {
"$ref": "#/components/schemas/Plane"
}
}
},
"CustomEntry": {
"type": "object",
"description": "A user-added title, persisted in `~/.config/punktfunk/library.json`. Same shape the API\nreturns and the web console edits.",
"required": [
"id",
"title"
],
"properties": {
"art": {
"$ref": "#/components/schemas/Artwork"
},
"id": {
"type": "string",
"description": "Host-assigned, stable for the life of the entry (the `{id}` in the CRUD path)."
},
"launch": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/LaunchSpec"
}
]
},
"prep": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PrepCmd"
},
"description": "Per-title prep/undo steps (RFC §6): each `do` runs before this title launches, each\n`undo` at session end in reverse order (see [`crate::hooks::run_prep`])."
},
"title": {
"type": "string"
}
}
},
"CustomInput": {
"type": "object",
"description": "Request body to create or replace a custom entry (no `id` — the host owns it).",
"required": [
"title"
],
"properties": {
"art": {
"$ref": "#/components/schemas/Artwork"
},
"launch": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/LaunchSpec"
}
]
},
"prep": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PrepCmd"
},
"description": "Per-title prep/undo steps — commands run as the host user; operator-privileged config."
},
"title": {
"type": "string"
}
}
},
"CustomPreset": {
"type": "object",
"description": "A user-defined named preset: a saved bundle of the six display-behavior axes (exactly what a\nbuilt-in [`Preset`] expands to) plus the orthogonal game-session axis, that the operator names\nand applies from the console.\n\nUnlike the built-in [`Preset`]s (a closed enum), custom presets are **data** — a catalog stored in\n`<config>/display-presets.json`. Applying one writes a `Custom` [`DisplayPolicy`] carrying these\nfields (the console reuses `PUT /display/settings`), so [`DisplayPolicy::effective`] stays pure and\nthe built-in set is never touched. The catalog is decoupled from the active `display-settings.json`:\nediting or deleting a preset never mutates the running policy (re-apply to adopt a change).",
"required": [
"id",
"name",
"fields"
],
"properties": {
"fields": {
"$ref": "#/components/schemas/EffectivePolicy",
"description": "The six display-behavior axes this preset applies (the same shape a built-in preset expands to)."
},
"game_session": {
"$ref": "#/components/schemas/GameSession",
"description": "The game-session routing this preset applies (orthogonal to the six axes; see [`GameSession`]).\nA custom preset captures the operator's *full* setup, so — unlike a built-in preset — applying\none does set this axis."
},
"id": {
"type": "string",
"description": "Host-assigned, stable for the life of the entry (the `{id}` in the CRUD path)."
},
"name": {
"type": "string",
"description": "User-facing name shown on the preset card; editable."
}
}
},
"CustomPresetInput": {
"type": "object",
"description": "Request body to create or replace a custom preset (no `id` — the host owns it).",
"required": [
"name",
"fields"
],
"properties": {
"fields": {
"$ref": "#/components/schemas/EffectivePolicy"
},
"game_session": {
"$ref": "#/components/schemas/GameSession"
},
"name": {
"type": "string"
}
}
},
"DeviceRef": {
"type": "object",
"description": "A device in the pairing flow.",
"required": [
"name",
"fingerprint",
"plane"
],
"properties": {
"fingerprint": {
"type": "string",
"description": "Hex certificate fingerprint."
},
"name": {
"type": "string",
"description": "Sanitized device name (the pairing store's copy)."
},
"plane": {
"$ref": "#/components/schemas/Plane"
}
}
},
"DisconnectReason": {
"type": "string",
"description": "Why a client went away. `Quit` is a deliberate user \"stop\" (the typed close code);\n`Timeout` is a transport idle timeout (the client vanished); `Error` is everything else.",
"enum": [
"quit",
"timeout",
"error"
]
},
"DisplayLayoutRequest": {
"type": "object",
"description": "Request body for `setDisplayLayout`: per-identity-slot desktop offsets, keyed by the identity-slot\nid as a string (the same id `/display/state` reports as `identity_slot`).",
"properties": {
"positions": {
"type": "object",
"description": "`{\"<identity_slot>\": {\"x\": …, \"y\": …}}` — where each arranged display's top-left sits.",
"additionalProperties": {
"$ref": "#/components/schemas/Position"
},
"propertyNames": {
"type": "string"
}
}
}
},
"DisplayPolicy": {
"type": "object",
"description": "The user-facing display-management policy — what `display-settings.json` holds and what the mgmt\nAPI GETs/PUTs. When [`preset`](Self::preset) is not [`Preset::Custom`] the explicit fields are\nignored (the console writes one or the other); [`effective`](Self::effective) resolves both to a\nsingle [`EffectivePolicy`].",
"properties": {
"ddc_power_off": {
"type": "boolean",
"description": "EXPERIMENTAL (Windows): command physical monitors' panels off over DDC/CI (VCP 0xD6 →\nDPMS off) right before an `Exclusive` isolate deactivates them, and back on at restore.\nTargets the \"connected-but-dark head\" periodic-stutter class (monitor standby\nauto-input-scan / DP link churn while the virtual display is the sole active display) at\nthe monitor-firmware level. Best-effort — monitors without DDC/CI (or with it disabled in\nthe OSD) are skipped. Orthogonal to `preset` (like `game_session`): preserved across\npreset changes; `#[serde(default)]` = off so existing `display-settings.json` files are\nuntouched."
},
"game_session": {
"$ref": "#/components/schemas/GameSession",
"description": "How a game-launching session is served (`design/gamemode-and-dedicated-sessions.md` §5.2).\nOrthogonal to `preset`/lifecycle — preserved across preset changes; `#[serde(default)]` = `Auto`\nso existing `display-settings.json` files are untouched."
},
"identity": {
"$ref": "#/components/schemas/Identity"
},
"keep_alive": {
"$ref": "#/components/schemas/KeepAlive"
},
"layout": {
"$ref": "#/components/schemas/Layout"
},
"max_displays": {
"type": "integer",
"format": "int32",
"description": "Upper bound on simultaneously-live virtual displays (clamped to `1..=16` on write).",
"minimum": 0
},
"mode_conflict": {
"$ref": "#/components/schemas/ModeConflict"
},
"pnp_disable_monitors": {
"type": "boolean",
"description": "EXPERIMENTAL (Windows): DISABLE physical monitors' PnP device nodes for the stream's\nduration (persistently, so a standby monitor/TV whose hot-plug events re-arrive stays\ndisabled) and re-enable them at teardown. Two selectors: the monitors an `Exclusive`\nisolate deactivated, plus — in ANY topology — external monitors that are connected but not\npart of the desktop (the standby TV that was never active, whose input auto-scan /\ninstant-on HPD cycling re-probes the link every few seconds). Targets the same\n\"connected-but-dark head\" periodic-stutter class as [`Self::ddc_power_off`], but at the\nWindows-reaction level: a disabled devnode's wake events trigger no PnP arrival, no CCD\nre-evaluation, no DWM invalidation. A crash-recovery journal re-enables leftovers on host\nstartup. Orthogonal to `preset` (like `game_session`); `#[serde(default)]` = off."
},
"preset": {
"$ref": "#/components/schemas/Preset"
},
"topology": {
"$ref": "#/components/schemas/Topology"
},
"version": {
"type": "integer",
"format": "int32",
"description": "Schema version (currently 1) — lets a future field addition migrate rather than reject.",
"minimum": 0
}
}
},
"DisplaySettingsState": {
"type": "object",
"description": "Full display-management state for the console: the stored policy, every preset's expansion, the\nresolved effective policy, and which options this build actually enforces yet (Stage 0 wires\nkeep-alive linger + topology; the rest are stored but not yet acted on).",
"required": [
"settings",
"configured",
"effective",
"presets",
"custom_presets",
"enforced"
],
"properties": {
"configured": {
"type": "boolean",
"description": "True once a `display-settings.json` exists (the console has configured this host)."
},
"custom_presets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomPreset"
},
"description": "The operator's saved custom presets (`display-presets.json`) — named field-bundles rendered\nalongside the built-ins. Managed via `POST/PUT/DELETE /display/presets`; applied by writing a\n`Custom` policy carrying the preset's fields."
},
"effective": {
"$ref": "#/components/schemas/EffectivePolicy",
"description": "The effective (preset-expanded) policy currently in force."
},
"enforced": {
"type": "array",
"items": {
"type": "string"
},
"description": "Option names this build enforces right now. All five axes are now acted on (keep_alive +\ntopology since Stage 0-2, identity Stage 3, mode_conflict Stage 4, layout Stage 5) — the console\nreads this to know which controls are live vs. \"coming soon\" (per-backend nuance, e.g. layout\nposition apply being KWin-only, is reported per display in `/display/state`)."
},
"presets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PresetInfo"
},
"description": "Every named preset and what it expands to (for the picker's preview)."
},
"settings": {
"$ref": "#/components/schemas/DisplayPolicy",
"description": "The stored policy (preset + custom fields), or the built-in default when unconfigured."
}
}
},
"DisplayStateResponse": {
"type": "object",
"description": "The host's managed virtual displays right now.",
"required": [
"displays"
],
"properties": {
"displays": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiDisplayInfo"
}
}
}
},
"EffectivePolicy": {
"type": "object",
"description": "The six resolved fields after preset expansion — what the lifecycle/registry and the Stage-0 call\nsites read, and what the mgmt API echoes as the \"currently in force\" policy. Pure output of\n[`DisplayPolicy::effective`].",
"required": [
"keep_alive",
"topology",
"mode_conflict",
"identity",
"layout",
"max_displays"
],
"properties": {
"identity": {
"$ref": "#/components/schemas/Identity"
},
"keep_alive": {
"$ref": "#/components/schemas/KeepAlive"
},
"layout": {
"$ref": "#/components/schemas/Layout"
},
"max_displays": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"mode_conflict": {
"$ref": "#/components/schemas/ModeConflict"
},
"topology": {
"$ref": "#/components/schemas/Topology"
}
}
},
"EventKind": {
"oneOf": [
{
"type": "object",
"required": [
"client",
"kind"
],
"properties": {
"client": {
"$ref": "#/components/schemas/ClientRef"
},
"kind": {
"type": "string",
"enum": [
"client.connected"
]
}
}
},
{
"type": "object",
"required": [
"client",
"reason",
"kind"
],
"properties": {
"client": {
"$ref": "#/components/schemas/ClientRef"
},
"kind": {
"type": "string",
"enum": [
"client.disconnected"
]
},
"reason": {
"$ref": "#/components/schemas/DisconnectReason"
}
}
},
{
"type": "object",
"required": [
"session",
"kind"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"session.started"
]
},
"session": {
"$ref": "#/components/schemas/SessionRef"
}
}
},
{
"type": "object",
"required": [
"session",
"kind"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"session.ended"
]
},
"session": {
"$ref": "#/components/schemas/SessionRef"
}
}
},
{
"type": "object",
"required": [
"stream",
"kind"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"stream.started"
]
},
"stream": {
"$ref": "#/components/schemas/StreamRef"
}
}
},
{
"type": "object",
"required": [
"stream",
"kind"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"stream.stopped"
]
},
"stream": {
"$ref": "#/components/schemas/StreamRef"
}
}
},
{
"type": "object",
"required": [
"device",
"kind"
],
"properties": {
"device": {
"$ref": "#/components/schemas/DeviceRef"
},
"kind": {
"type": "string",
"enum": [
"pairing.pending"
]
}
}
},
{
"type": "object",
"required": [
"device",
"kind"
],
"properties": {
"device": {
"$ref": "#/components/schemas/DeviceRef"
},
"kind": {
"type": "string",
"enum": [
"pairing.completed"
]
}
}
},
{
"type": "object",
"required": [
"device",
"kind"
],
"properties": {
"device": {
"$ref": "#/components/schemas/DeviceRef"
},
"kind": {
"type": "string",
"enum": [
"pairing.denied"
]
}
}
},
{
"type": "object",
"required": [
"backend",
"mode",
"kind"
],
"properties": {
"backend": {
"type": "string",
"description": "The virtual-display backend that minted it (`VirtualDisplay::name`)."
},
"kind": {
"type": "string",
"enum": [
"display.created"
]
},
"mode": {
"type": "string",
"description": "`WxH@Hz`."
}
}
},
{
"type": "object",
"required": [
"count",
"kind"
],
"properties": {
"count": {
"type": "integer",
"format": "int32",
"description": "How many kept displays this release retired.",
"minimum": 0
},
"kind": {
"type": "string",
"enum": [
"display.released"
]
}
}
},
{
"type": "object",
"required": [
"source",
"kind"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"library.changed"
]
},
"source": {
"type": "string",
"description": "What mutated the library: `\"manual\"` today; a provider id once the provider\nAPI (RFC §8) lands."
}
}
},
{
"type": "object",
"required": [
"version",
"gamestream",
"kind"
],
"properties": {
"gamestream": {
"type": "boolean",
"description": "Whether the GameStream/Moonlight compat plane is enabled."
},
"kind": {
"type": "string",
"enum": [
"host.started"
]
},
"version": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"kind"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"host.stopping"
]
}
}
}
],
"description": "The event catalog (RFC §4). Serialized internally tagged as `\"kind\": \"<domain>.<verb>\"`,\nflattened into [`HostEvent`]. **Additive-only** within [`SCHEMA_VERSION`]."
},
"GameEntry": {
"type": "object",
"description": "One title in the unified library, regardless of which store it came from.",
"required": [
"id",
"store",
"title",
"art"
],
"properties": {
"art": {
"$ref": "#/components/schemas/Artwork"
},
"id": {
"type": "string",
"description": "Stable, store-qualified id: `steam:<appid>` or `custom:<id>`.",
"example": "steam:570"
},
"launch": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/LaunchSpec",
"description": "How the host would launch it, when known."
}
]
},
"store": {
"type": "string",
"description": "Which store surfaced it: `\"steam\"` or `\"custom\"`.",
"example": "steam"
},
"title": {
"type": "string"
}
}
},
"GameSession": {
"type": "string",
"description": "How a session that **launches a game** (a library id on the Hello / apps.json / Decky pin) is\nserved (`design/gamemode-and-dedicated-sessions.md` §5.2). Orthogonal to the preset/lifecycle axes\n— a top-level [`DisplayPolicy`] field, NOT part of [`EffectivePolicy`], so a preset never clobbers\nit. Linux-only in effect (a launching Windows session opens into the one desktop).",
"enum": [
"auto",
"dedicated"
]
},
"GpuState": {
"type": "object",
"description": "Full GPU-selection state for the console: inventory, the persisted preference, what the next\nsession will use, and what is in use right now.",
"required": [
"gpus",
"mode",
"preferred_available"
],
"properties": {
"active": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ApiActiveGpu",
"description": "The GPU live sessions use right now (absent while nothing is streaming)."
}
]
},
"env_override": {
"type": [
"string",
"null"
],
"description": "`PUNKTFUNK_RENDER_ADAPTER` (the host.env pin), when set — it applies while `mode` is\n`auto`; a manual preference overrides it."
},
"gpus": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiGpu"
},
"description": "The host's hardware GPUs."
},
"mode": {
"type": "string",
"description": "`auto` or `manual`."
},
"preferred_available": {
"type": "boolean",
"description": "Whether the preferred GPU is currently present."
},
"preferred_id": {
"type": [
"string",
"null"
],
"description": "The manually preferred GPU's stable id, when one is stored (kept while `mode` is `auto` so\na console can offer returning to it). May reference a GPU that is currently absent."
},
"preferred_name": {
"type": [
"string",
"null"
],
"description": "The stored name of the preferred GPU (a usable label even when it is absent)."
},
"selected": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/ApiSelectedGpu",
"description": "The GPU the next session will use."
}
]
}
}
},
"Health": {
"type": "object",
"description": "Liveness + version probe.",
"required": [
"status",
"version",
"abi_version"
],
"properties": {
"abi_version": {
"type": "integer",
"format": "int32",
"description": "`punktfunk-core` C ABI version.",
"minimum": 0
},
"status": {
"type": "string",
"description": "Always `\"ok\"` when the host responds.",
"example": "ok"
},
"version": {
"type": "string",
"description": "`punktfunk-host` crate version."
}
}
},
"HookEntry": {
"type": "object",
"description": "One hook: fire `run` and/or `webhook` when an event matching `on` (+ `filter`) occurs.",
"required": [
"on"
],
"properties": {
"debounce_ms": {
"type": "integer",
"format": "int64",
"description": "Minimum interval between firings of this hook, in milliseconds. 0 = fire every time.",
"minimum": 0
},
"filter": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/HookFilter",
"description": "Exact-match constraints on the event's fields; every present field must match."
}
]
},
"hmac_secret_file": {
"type": [
"string",
"null"
],
"description": "File holding the webhook HMAC secret (`X-Punktfunk-Signature: sha256=<hex>`). The file\nshould be operator-owned and private; a world-readable secret is warned about."
},
"on": {
"type": "string",
"description": "Which events fire this hook: an exact kind (`stream.started`) or a `domain.*` prefix\n(`pairing.*`) — the same vocabulary as the SSE `?kinds=` filter."
},
"run": {
"type": [
"string",
"null"
],
"description": "Shell command to execute (detached, event JSON on stdin + `PF_EVENT_*` env)."
},
"timeout_s": {
"type": "integer",
"format": "int32",
"description": "Exec timeout in seconds (1–600, default 30); the process group is killed on expiry.",
"minimum": 0
},
"webhook": {
"type": [
"string",
"null"
],
"description": "URL to POST the event JSON to."
}
}
},
"HookFilter": {
"type": "object",
"description": "Exact-match filters against an event's identity fields (RFC open-question 3: exact match\nonly — anything richer is what the SDK is for). Absent fields don't constrain; a filter\nfield set on an event kind that doesn't carry it (e.g. `client` on `host.started`) never\nmatches.",
"properties": {
"app": {
"type": [
"string",
"null"
],
"description": "Launched app id/title (`stream.*` events)."
},
"client": {
"type": [
"string",
"null"
],
"description": "Client/device name (for `session.*`: the short client label the Dashboard shows)."
},
"fingerprint": {
"type": [
"string",
"null"
],
"description": "Certificate fingerprint (hex, case-insensitive)."
},
"plane": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/Plane",
"description": "Protocol plane (`native` / `gamestream`)."
}
]
}
}
},
"HooksConfig": {
"type": "object",
"description": "The operator's hook configuration — the `hooks.json` document and the `/api/v1/hooks` body.",
"properties": {
"hooks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HookEntry"
}
}
}
},
"HostEvent": {
"allOf": [
{
"$ref": "#/components/schemas/EventKind",
"description": "The event kind + payload, flattened: `\"kind\": \"stream.started\", …payload…`."
},
{
"type": "object",
"required": [
"seq",
"ts_ms",
"schema"
],
"properties": {
"schema": {
"type": "integer",
"format": "int32",
"description": "Wire-shape version ([`SCHEMA_VERSION`]).",
"minimum": 0
},
"seq": {
"type": "integer",
"format": "int64",
"description": "Monotonic sequence number (1-based) — a consumer resumes with `since = last seen`.",
"minimum": 0
},
"ts_ms": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp in milliseconds (the [`crate::log_capture::LogEntry`] convention).",
"minimum": 0
}
}
}
],
"description": "One host lifecycle event, as it will appear on the wire (`data:` of one SSE frame)."
},
"HostInfo": {
"type": "object",
"description": "Host identity and advertised capabilities (static for the life of the process).",
"required": [
"hostname",
"uniqueid",
"local_ip",
"version",
"abi_version",
"app_version",
"gfe_version",
"codecs",
"gamestream",
"ports"
],
"properties": {
"abi_version": {
"type": "integer",
"format": "int32",
"description": "`punktfunk-core` C ABI version.",
"minimum": 0
},
"app_version": {
"type": "string",
"description": "GameStream host version advertised to Moonlight clients."
},
"codecs": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiCodec"
},
"description": "Codecs the host can encode (NVENC)."
},
"gamestream": {
"type": "boolean",
"description": "Whether the GameStream/Moonlight-compat planes are running (`--gamestream`). `false` on the\nsecure default (native punktfunk/1 only) — a console can hide Moonlight-only UI (e.g. the\nMoonlight PIN pairing card, which could never receive a PIN when this is `false`)."
},
"gfe_version": {
"type": "string",
"description": "GFE version advertised to Moonlight clients."
},
"hostname": {
"type": "string"
},
"local_ip": {
"type": "string",
"description": "Best-effort primary LAN IP."
},
"ports": {
"$ref": "#/components/schemas/PortMap"
},
"uniqueid": {
"type": "string",
"description": "Stable per-host id (persisted across restarts), matched on pairing."
},
"version": {
"type": "string",
"description": "`punktfunk-host` crate version."
}
}
},
"Identity": {
"type": "string",
"description": "Stable display identity, so desktop environments persist per-display config (KDE scaling). Stored\nat Stage 0; carriers wired from the identity stage.",
"enum": [
"shared",
"per-client",
"per-client-mode"
]
},
"KeepAlive": {
"oneOf": [
{
"type": "object",
"description": "Tear the display down at session end (today's default on every backend but Windows, which\nlingers 10 s).",
"required": [
"mode"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"off"
]
}
}
},
{
"type": "object",
"description": "Keep the display for `seconds` after the last session leaves, then tear it down; a reconnect\ninside the window reuses it.",
"required": [
"seconds",
"mode"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"duration"
]
},
"seconds": {
"type": "integer",
"format": "int32",
"description": "Linger window in seconds.",
"minimum": 0
}
}
},
{
"type": "object",
"description": "Keep the display until host shutdown or an explicit release (the `Pinned` lifecycle state).\n**Not honored until the display-lifecycle stage** — rejected by the mgmt PUT at Stage 0.",
"required": [
"mode"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"forever"
]
}
}
}
],
"description": "How long a virtual display (and, on gamescope's bare spawn, the nested session + its game)\nsurvives after the last client session detaches. Serialized as an object tagged on `mode`\n(`{\"mode\":\"off\"}` / `{\"mode\":\"duration\",\"seconds\":300}` / `{\"mode\":\"forever\"}`) so the web form\nand the OpenAPI schema stay simple."
},
"LaunchSpec": {
"type": "object",
"description": "How the host would launch a title (consumed by the session launcher in a later step). Kept\nopen-ended so new stores slot in: `steam_appid` → `steam steam://rungameid/<value>`;\n`command` → run `<value>` nested in a gamescope session.",
"required": [
"kind",
"value"
],
"properties": {
"kind": {
"type": "string",
"description": "`\"steam_appid\"` or `\"command\"`.",
"example": "steam_appid"
},
"value": {
"type": "string",
"description": "The appid (for `steam_appid`) or the shell command (for `command`)."
}
}
},
"Layout": {
"type": "object",
"description": "Group layout: the arrangement mode plus, for [`LayoutMode::Manual`], per-slot offsets keyed by\nidentity-slot id (string keys for stable JSON).",
"properties": {
"mode": {
"$ref": "#/components/schemas/LayoutMode"
},
"positions": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Position"
},
"propertyNames": {
"type": "string"
}
}
}
},
"LayoutMode": {
"type": "string",
"description": "How group members are arranged in the desktop coordinate space. Stored at Stage 0; applied from\nthe multi-monitor stage.",
"enum": [
"auto-row",
"manual"
]
},
"LocalSummary": {
"type": "object",
"description": "Non-sensitive host status for the local tray icon: counts and booleans only — no PIN values,\nno fingerprints, no device names. Served unauthenticated to LOOPBACK peers only (see\n`require_auth`): the bearer-token file is SYSTEM/Administrators-DACL'd on Windows, so the\nper-user tray process cannot authenticate — this narrow read-only route is its status source.",
"required": [
"version",
"video_streaming",
"audio_streaming",
"paired_clients",
"native_paired_clients",
"pin_pending",
"pending_approvals",
"kept_displays"
],
"properties": {
"audio_streaming": {
"type": "boolean",
"description": "True while the audio stream thread is running."
},
"conflicts": {
"type": "array",
"items": {
"type": "string"
},
"description": "Other Moonlight-compatible hosts (Sunshine/Apollo/…) detected on this machine at startup —\nrunning one alongside Punktfunk is unsupported. Compact labels (e.g. `Sunshine (running)`);\nthe tray/console surface them so the clash is visible before pairing silently fails."
},
"kept_displays": {
"type": "integer",
"format": "int32",
"description": "Virtual displays being KEPT with no live session — lingering (keep-alive window) or pinned\n(`keep_alive: forever`). Non-zero means a display (and, exclusive, your physical monitors) is\nheld; the tray surfaces it + a one-click release. Active (in-use) displays are not counted.",
"minimum": 0
},
"native_paired_clients": {
"type": "integer",
"format": "int32",
"description": "Number of paired native (punktfunk/1) devices.",
"minimum": 0
},
"paired_clients": {
"type": "integer",
"format": "int32",
"description": "Number of pinned (paired) GameStream client certificates.",
"minimum": 0
},
"pending_approvals": {
"type": "integer",
"format": "int32",
"description": "Native pairing knocks awaiting the operator's approval (count only).",
"minimum": 0
},
"pin_pending": {
"type": "boolean",
"description": "True while a GameStream pairing handshake is parked waiting for the user's PIN."
},
"session": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/SessionInfo",
"description": "The active launch session (set by Moonlight's `/launch`, cleared on cancel/stop)."
}
]
},
"version": {
"type": "string",
"description": "Host version (mirrors `/health`)."
},
"video_streaming": {
"type": "boolean",
"description": "True while the video stream thread is running."
}
}
},
"LogEntry": {
"type": "object",
"description": "One captured log event.",
"required": [
"seq",
"ts_ms",
"level",
"target",
"msg"
],
"properties": {
"level": {
"type": "string",
"description": "`ERROR` | `WARN` | `INFO` | `DEBUG` | `TRACE`."
},
"msg": {
"type": "string",
"description": "The formatted message, structured fields appended as `key=value`."
},
"seq": {
"type": "integer",
"format": "int64",
"description": "Monotonic sequence number (1-based) — pass the last one back as the `after` cursor.",
"minimum": 0
},
"target": {
"type": "string",
"description": "The emitting module path (tracing target)."
},
"ts_ms": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp in milliseconds.",
"minimum": 0
}
}
},
"LogPage": {
"type": "object",
"description": "One poll's worth of log entries.",
"required": [
"entries",
"next",
"dropped"
],
"properties": {
"dropped": {
"type": "boolean",
"description": "True when entries between `after` and the first returned one were already evicted."
},
"entries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LogEntry"
}
},
"next": {
"type": "integer",
"format": "int64",
"description": "Cursor for the next poll (the last returned seq, or the request's `after` when empty).",
"minimum": 0
}
}
},
"ModeConflict": {
"type": "string",
"description": "Admission when a *different* client connects while a display/session is already live and asks for\na different mode. Stored at Stage 0; enforced from the mode-conflict admission stage.",
"enum": [
"separate",
"steal",
"join",
"reject"
]
},
"NativeClient": {
"type": "object",
"description": "A paired native (punktfunk/1) client.",
"required": [
"name",
"fingerprint"
],
"properties": {
"fingerprint": {
"type": "string",
"description": "Hex SHA-256 of the client certificate — its stable id here."
},
"name": {
"type": "string",
"description": "The name the client supplied when pairing.",
"example": "Living Room iPad"
}
}
},
"NativePairStatus": {
"type": "object",
"description": "Native (punktfunk/1) pairing status. Unlike GameStream, the **host** mints the PIN (the SPAKE2\nceremony needs it client-side first), so the console **displays** `pin` for the user to enter on\ntheir device — armed on demand for a short window.",
"required": [
"enabled",
"armed",
"paired_clients"
],
"properties": {
"armed": {
"type": "boolean",
"description": "True while a pairing window is open."
},
"enabled": {
"type": "boolean",
"description": "Whether the native host is running (the unified host started with `--native`)."
},
"expires_in_secs": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Seconds left in the window (null = disarmed, or armed with no expiry via the CLI flag).",
"minimum": 0
},
"paired_clients": {
"type": "integer",
"format": "int32",
"description": "Number of paired native clients.",
"minimum": 0
},
"pin": {
"type": [
"string",
"null"
],
"description": "The PIN to display while armed (null when disarmed).",
"example": "1234"
}
}
},
"PairedClient": {
"type": "object",
"description": "A paired (certificate-pinned) Moonlight client.",
"required": [
"fingerprint"
],
"properties": {
"fingerprint": {
"type": "string",
"description": "Lowercase hex SHA-256 of the client certificate DER — the client's stable id here.",
"example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
},
"not_after_unix": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Certificate validity end (unix seconds)."
},
"not_before_unix": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Certificate validity start (unix seconds)."
},
"subject": {
"type": [
"string",
"null"
],
"description": "Certificate subject (e.g. `CN=NVIDIA GameStream Client`), if the DER parses."
}
}
},
"PairingStatus": {
"type": "object",
"description": "Pairing-flow status.",
"required": [
"pin_pending"
],
"properties": {
"pin_pending": {
"type": "boolean",
"description": "True while a pairing handshake is parked waiting for the user's PIN."
}
}
},
"PendingDevice": {
"type": "object",
"description": "An unpaired device that tried to connect while the host requires pairing — awaiting\n**delegated approval** (approve it here instead of fetching the host PIN out of band).",
"required": [
"id",
"name",
"fingerprint",
"age_secs"
],
"properties": {
"age_secs": {
"type": "integer",
"format": "int64",
"description": "Seconds since the device last knocked.",
"minimum": 0
},
"fingerprint": {
"type": "string",
"description": "Hex SHA-256 of the device's certificate — what approval pins."
},
"id": {
"type": "integer",
"format": "int32",
"description": "Id to address approve/deny (per-process; entries expire after ~10 minutes).",
"minimum": 0
},
"name": {
"type": "string",
"description": "Best-effort device label (the client's own name, else fingerprint-derived).",
"example": "Enrico's MacBook"
}
}
},
"Plane": {
"type": "string",
"description": "Which protocol plane an event originated from. Hooks and scripts filter on it — a hook\nthat fires for native clients but not Moonlight clients is a bug, not a v2 feature.",
"enum": [
"native",
"gamestream"
]
},
"PortMap": {
"type": "object",
"description": "Every port a client integration may need (Moonlight derives the stream ports from the\nHTTP base; a control pane should not have to).",
"required": [
"mgmt",
"http",
"https",
"rtsp",
"video",
"control",
"audio"
],
"properties": {
"audio": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"control": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"http": {
"type": "integer",
"format": "int32",
"description": "nvhttp plain HTTP (serverinfo, pairing).",
"minimum": 0
},
"https": {
"type": "integer",
"format": "int32",
"description": "nvhttp mutual-TLS HTTPS (post-pairing).",
"minimum": 0
},
"mgmt": {
"type": "integer",
"format": "int32",
"description": "This management API.",
"minimum": 0
},
"rtsp": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"video": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
},
"Position": {
"type": "object",
"description": "A desktop-space offset for a display (top-left origin).",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "integer",
"format": "int32"
},
"y": {
"type": "integer",
"format": "int32"
}
}
},
"PrepCmd": {
"type": "object",
"description": "One per-app preparation step (RFC §6 — deliberate Sunshine `prep-cmd` parity): `do` runs\n**synchronously before the app launches** (an HDR toggle or a MangoHud env change must land\nfirst), `undo` runs at session end — reverse order across steps, best-effort, on every exit\npath including a crash-unwind (RAII via [`PrepGuard`]).",
"required": [
"do"
],
"properties": {
"do": {
"type": "string",
"description": "Command run before launch. Same execution recipe and ownership checks as hook `run`\ncommands (event-less: stdin is empty JSON, env carries the `PF_APP_*` context)."
},
"undo": {
"type": [
"string",
"null"
],
"description": "Command run after the session ends. Skipped when its `do` failed (it never took effect)."
}
}
},
"Preset": {
"type": "string",
"description": "A named bundle of the fields below. `Custom` (the default) means the explicit fields rule; any\nother preset ignores the stored fields and expands to its own ([`DisplayPolicy::effective`]).",
"enum": [
"custom",
"default",
"gaming-rig",
"shared-desktop",
"hotdesk",
"workstation"
]
},
"PresetInfo": {
"type": "object",
"description": "One preset's human-facing description + the fields it expands to, so the console can render a\npreset picker with an accurate \"what this does\" preview without hardcoding the expansion.",
"required": [
"id",
"summary",
"fields"
],
"properties": {
"fields": {
"$ref": "#/components/schemas/EffectivePolicy",
"description": "The effective policy this preset expands to (the same fields a `custom` policy carries)."
},
"id": {
"type": "string",
"description": "The preset id (`default` | `gaming-rig` | `shared-desktop` | `hotdesk` | `workstation`)."
},
"summary": {
"type": "string",
"description": "One-line story shown next to the option."
}
}
},
"ReleaseDisplayRequest": {
"type": "object",
"description": "Request body for `releaseDisplay`.",
"properties": {
"slot": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Slot to release (see `state`); omit to release **all** kept displays.",
"minimum": 0
}
}
},
"ReleaseDisplayResult": {
"type": "object",
"description": "Result of a `/display/release`.",
"required": [
"released"
],
"properties": {
"released": {
"type": "integer",
"description": "Number of kept displays torn down.",
"minimum": 0
}
}
},
"RuntimeStatus": {
"type": "object",
"description": "Live host status (changes as clients launch/end sessions).",
"required": [
"video_streaming",
"audio_streaming",
"pin_pending",
"paired_clients",
"active_sessions"
],
"properties": {
"active_sessions": {
"type": "integer",
"format": "int32",
"description": "Number of live streaming sessions across BOTH planes (GameStream + native punktfunk/1). The\nnative server admits concurrent sessions, so this can exceed 1; `session`/`stream` below\ndescribe a single representative session for the detail card.",
"minimum": 0
},
"audio_streaming": {
"type": "boolean",
"description": "True while the audio stream thread is running."
},
"paired_clients": {
"type": "integer",
"format": "int32",
"description": "Number of pinned (paired) client certificates.",
"minimum": 0
},
"pin_pending": {
"type": "boolean",
"description": "True while a pairing handshake is parked waiting for the user's PIN\n(submit it via `POST /api/v1/pair/pin`)."
},
"session": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/SessionInfo",
"description": "A representative active session. GameStream's launch (Moonlight `/launch`) when present, else\nthe first live native session. `null` when nothing is streaming."
}
]
},
"stream": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/StreamInfo",
"description": "The active stream's parameters — RTSP-negotiated for GameStream, or the live native session's\nmode/codec/bitrate. `null` when nothing is streaming."
}
]
},
"video_streaming": {
"type": "boolean",
"description": "True while the video stream thread is running."
}
}
},
"SessionInfo": {
"type": "object",
"description": "Client-requested launch parameters (key material is never exposed here).",
"required": [
"width",
"height",
"fps"
],
"properties": {
"fps": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"height": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"width": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
},
"SessionRef": {
"type": "object",
"description": "A live A/V session (the plane-neutral notion the Dashboard shows).",
"required": [
"id",
"client",
"mode",
"hdr"
],
"properties": {
"client": {
"type": "string",
"description": "Short client label (cert-fingerprint prefix, or peer IP for an anonymous client)."
},
"hdr": {
"type": "boolean"
},
"id": {
"type": "integer",
"format": "int64",
"description": "Host-local session id (unique within this host process).",
"minimum": 0
},
"mode": {
"type": "string",
"description": "Negotiated mode, `WxH@Hz` (e.g. `\"3840x2160@120\"`)."
}
}
},
"SetGpuPreference": {
"type": "object",
"description": "Request body for `setGpuPreference`.",
"required": [
"mode"
],
"properties": {
"gpu_id": {
"type": [
"string",
"null"
],
"description": "Required when `mode` is `manual`: the stable `id` of a currently listed GPU\n(see `listGpus`).",
"example": "10de-2c05-0"
},
"mode": {
"type": "string",
"description": "`auto` (env pin, else max dedicated VRAM — the default) or `manual`.",
"example": "manual"
}
}
},
"StageTiming": {
"type": "object",
"description": "One pipeline stage's latency in an aggregation window (microseconds).",
"required": [
"name",
"p50_us",
"p99_us"
],
"properties": {
"name": {
"type": "string",
"description": "`\"capture\" | \"submit\" | \"encode\" | \"packetize\" | \"send\"` (path-dependent)."
},
"p50_us": {
"type": "number",
"format": "float"
},
"p99_us": {
"type": "number",
"format": "float"
}
}
},
"StatsSample": {
"type": "object",
"description": "One aggregated sample (~ every 2 s native, ~ every 1 s GameStream).",
"required": [
"t_ms",
"session_id",
"stages",
"fps",
"repeat_fps",
"mbps",
"bitrate_kbps",
"frames_dropped",
"packets_dropped",
"send_dropped",
"fec_recovered"
],
"properties": {
"bitrate_kbps": {
"type": "integer",
"format": "int32",
"description": "Configured target bitrate.",
"minimum": 0
},
"fec_recovered": {
"type": "integer",
"format": "int32",
"description": "FEC shards recovered this window (delta).",
"minimum": 0
},
"fps": {
"type": "number",
"format": "float",
"description": "Genuine NEW frames/s from the source."
},
"frames_dropped": {
"type": "integer",
"format": "int32",
"description": "Frames dropped this window (delta).",
"minimum": 0
},
"mbps": {
"type": "number",
"format": "float",
"description": "Transmit goodput (Mb/s)."
},
"packets_dropped": {
"type": "integer",
"format": "int32",
"description": "Packets dropped this window (receiver-side / reassembler, where known).",
"minimum": 0
},
"repeat_fps": {
"type": "number",
"format": "float",
"description": "Re-encoded holds/s (source-starvation indicator)."
},
"send_dropped": {
"type": "integer",
"format": "int32",
"description": "Host send-buffer overflow / EAGAIN this window (delta).",
"minimum": 0
},
"session_id": {
"type": "integer",
"format": "int32",
"description": "Disambiguates concurrent sessions (usually constant).",
"minimum": 0
},
"stages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StageTiming"
},
"description": "Ordered pipeline stages for this path."
},
"t_ms": {
"type": "integer",
"format": "int64",
"description": "Milliseconds since capture start (monotonic; stamped by [`StatsRecorder::push_sample`]).",
"minimum": 0
}
}
},
"StatsStatus": {
"type": "object",
"description": "Snapshot of the in-progress capture for the management API.",
"required": [
"armed",
"sample_count",
"started_unix_ms",
"elapsed_ms",
"kind"
],
"properties": {
"armed": {
"type": "boolean",
"description": "Capture currently running."
},
"elapsed_ms": {
"type": "integer",
"format": "int64",
"description": "Host-measured elapsed time of the in-progress capture, in ms (`0` if idle). Computed from the\nhost's MONOTONIC clock, so a console can show elapsed time without subtracting `started_unix_ms`\nfrom its own (possibly skewed) wall clock.",
"minimum": 0
},
"kind": {
"type": "string",
"description": "Path of the in-progress capture (`\"\"` if idle)."
},
"sample_count": {
"type": "integer",
"format": "int32",
"description": "Samples in the in-progress capture.",
"minimum": 0
},
"started_unix_ms": {
"type": "integer",
"format": "int64",
"description": "Unix start time of the in-progress capture (`0` if idle).",
"minimum": 0
}
}
},
"StreamInfo": {
"type": "object",
"description": "RTSP-negotiated stream parameters.",
"required": [
"width",
"height",
"fps",
"bitrate_kbps",
"packet_size",
"min_fec",
"codec"
],
"properties": {
"bitrate_kbps": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"codec": {
"$ref": "#/components/schemas/ApiCodec"
},
"fps": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"height": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"min_fec": {
"type": "integer",
"format": "int32",
"description": "Client's parity floor per FEC block (`minRequiredFecPackets`).",
"minimum": 0
},
"packet_size": {
"type": "integer",
"format": "int32",
"description": "Video payload size per packet (bytes).",
"minimum": 0
},
"width": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
},
"StreamRef": {
"type": "object",
"description": "A live video stream (what the stream marker file reflects).",
"required": [
"mode",
"hdr",
"client",
"plane"
],
"properties": {
"app": {
"type": [
"string",
"null"
],
"description": "The launched app/title for this stream, when one was requested (store-qualified id on\nthe native plane, app title on the GameStream plane)."
},
"client": {
"type": "string",
"description": "Client-supplied device name; may be empty."
},
"hdr": {
"type": "boolean"
},
"mode": {
"type": "string",
"description": "Negotiated mode, `WxH@Hz`."
},
"plane": {
"$ref": "#/components/schemas/Plane"
}
}
},
"SubmitPin": {
"type": "object",
"description": "The PIN Moonlight displays during pairing.",
"required": [
"pin"
],
"properties": {
"pin": {
"type": "string",
"description": "1–16 ASCII digits (Moonlight shows 4).",
"example": "1234"
}
}
},
"Topology": {
"type": "string",
"description": "What the host does to the box's display topology while managed virtual displays are up.",
"enum": [
"auto",
"extend",
"primary",
"exclusive"
]
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
},
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "host",
"description": "Host identity, capabilities, and liveness"
},
{
"name": "gpu",
"description": "GPU inventory and selection: list the host's GPUs, choose automatic or a preferred GPU, see the one in use"
},
{
"name": "display",
"description": "Virtual-display management policy: lifecycle (keep-alive), topology (primary/exclusive), conflict handling, identity, and layout"
},
{
"name": "clients",
"description": "Paired Moonlight client management"
},
{
"name": "pairing",
"description": "Pairing PIN delivery (the out-of-band half of the GameStream pairing handshake)"
},
{
"name": "native",
"description": "Native punktfunk/1 pairing: arm a window, display the host PIN, manage paired devices"
},
{
"name": "session",
"description": "Active streaming session control"
},
{
"name": "library",
"description": "Game library: installed-store titles (Steam) plus user-curated custom entries"
},
{
"name": "stats",
"description": "Streaming performance-stats capture: arm/stop a recording, read the live + saved time-series for graphing"
},
{
"name": "logs",
"description": "Host log stream: the newest in-memory log entries, cursor-paged for live following"
},
{
"name": "events",
"description": "Host lifecycle events: an SSE stream (client/session/stream lifecycle, pairing, displays, library, host) with Last-Event-ID resume and server-side kind filters"
},
{
"name": "hooks",
"description": "Operator hooks: commands and webhooks fired on lifecycle events (fire-and-forget — hooks observe, never veto)"
}
]
}
Reference in New Issue View Git Blame Copy Permalink