enricobuehler
8af1a15aa6
Remote debugging without shell access: a tracing layer tees every event at DEBUG-and-up — independent of the RUST_LOG filter gating stderr/host.log, so console-side debugging never needs a restart — into a bounded in-memory ring (log_capture.rs, 4096 newest entries, OnceLock singleton like config()), installed at both init sites (stderr path in main, the Windows service file path). The mgmt API serves it cursor-paged at GET /api/v1/logs?after=&limit= — bearer-only and deliberately NOT on the mTLS cert allowlist (log lines can name client identities and host paths). The web console grows a Logs page (follow/pause · min-level filter · text search · eviction-gap badge); polling self-paces: a non-empty page advances the after-cursor (new query key → immediate refetch, drains backlogs), an empty page idles at the 2s interval. OpenAPI regenerated; ring pagination/eviction, layer wiring, and the authed route are unit-tested; Storybook story included. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2701 lines
80 KiB
JSON
2701 lines
80 KiB
JSON
{
|
||
"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.4.2"
|
||
},
|
||
"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/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/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/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.",
|
||
"enum": [
|
||
"h264",
|
||
"h265",
|
||
"av1"
|
||
]
|
||
},
|
||
"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
|
||
}
|
||
}
|
||
},
|
||
"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"
|
||
}
|
||
]
|
||
},
|
||
"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"
|
||
}
|
||
]
|
||
},
|
||
"title": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"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"
|
||
}
|
||
}
|
||
},
|
||
"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."
|
||
}
|
||
}
|
||
},
|
||
"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",
|
||
"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)."
|
||
},
|
||
"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."
|
||
}
|
||
}
|
||
},
|
||
"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`)."
|
||
}
|
||
}
|
||
},
|
||
"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
|
||
}
|
||
}
|
||
},
|
||
"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"
|
||
}
|
||
}
|
||
},
|
||
"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
|
||
}
|
||
}
|
||
},
|
||
"RuntimeStatus": {
|
||
"type": "object",
|
||
"description": "Live host status (changes as clients launch/end sessions).",
|
||
"required": [
|
||
"video_streaming",
|
||
"audio_streaming",
|
||
"pin_pending",
|
||
"paired_clients"
|
||
],
|
||
"properties": {
|
||
"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": "The active launch session (set by Moonlight's `/launch`, cleared on cancel/stop)."
|
||
}
|
||
]
|
||
},
|
||
"stream": {
|
||
"oneOf": [
|
||
{
|
||
"type": "null"
|
||
},
|
||
{
|
||
"$ref": "#/components/schemas/StreamInfo",
|
||
"description": "The RTSP-negotiated stream parameters (present once a client has completed ANNOUNCE)."
|
||
}
|
||
]
|
||
},
|
||
"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
|
||
}
|
||
}
|
||
},
|
||
"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",
|
||
"kind"
|
||
],
|
||
"properties": {
|
||
"armed": {
|
||
"type": "boolean",
|
||
"description": "Capture currently running."
|
||
},
|
||
"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
|
||
}
|
||
}
|
||
},
|
||
"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"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"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": "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"
|
||
}
|
||
]
|
||
}
|