# Methods Methods are used to execute actions and request data back from the API. ## Access Each method below identifies which clients may call it: - **Unauthenticated bootstrap:** JSON-RPC methods `settings.auth.claim`, `settings.auth.status`, `settings.auth.link`, and redacted `settings.auth.link.status` are available before authentication. Remote HTTP POST requires `allowed_ips` and remains rate limited. Separate client-pairing endpoints `/api/pair/start` and `/api/pair/finish` are remotely reachable and strictly rate limited. `/health` is unrestricted and returns a small JSON body carrying the service's coarse lifecycle state (`starting`, `ready` or `failed`) and nothing else. - **All accepted clients:** localhost, authenticated admin, authenticated member, and legacy clients admitted by platform compatibility policy. - **Localhost or any authenticated client:** localhost, paired clients, and API-key admin. Legacy clients are rejected. - **`profiles.manage`:** localhost and clients with the capability. Admin has it; member does not. Legacy retains it only on approved appliance platforms. - **`settings.write`:** localhost and clients with the capability. Admin has it; member does not. Legacy retains it only on approved appliance platforms. - **`input`:** localhost, member, and admin. Legacy input is grandfathered only on MiSTer, MiSTeX, Batocera, and ReplayOS. - **`screenshot`:** localhost, member, and admin. Legacy screenshot capture is grandfathered only on MiSTer and ReplayOS. - **`update.apply`:** localhost and authenticated admin. Member and legacy do not receive it. - **`device.power`:** localhost and authenticated admin. Member and legacy do not receive it. - **`device.bluetooth`:** localhost and authenticated admin. Member and legacy do not receive it. - **Localhost or admin:** localhost, paired admin, and API-key admin. Member and legacy are rejected. - **Localhost only:** requests originating from Core's device. All remote clients are rejected. Use [`clients.current`](#clientscurrent) to inspect current connection's access state, paired role, and effective capabilities. A method may also require a resource-specific credential, such as a profile PIN; those requirements are documented separately from connection access. ## Launching ### run **Access:** All clients. Emulate the scanning of a token. Access is decided when the API accepts `run`; mapped and expanded ZapScript commands do not re-evaluate connection capabilities during internal execution. Legacy `run` access therefore remains limited to explicitly grandfathered platforms. #### Parameters Accepts two types of parameters: - A string, in which case the string will be treated as the token text with all other options set as default. - An object: | Key | Type | Required | Description | | :----- | :------ | :------- | :------------------------------------------------------------------------------------------------------------- | | type | string | No | An internal category of the type of token being scanned. _Not currently in use outside of logging._ | | uid | string | No\* | The UID of the token being scanned. For example, the UID of an NFC tag. Used for matching mappings. | | text | string | No\* | The main text to be processed from a scan, should contain [ZapScript](../../zapscript/index.md). At most 8192 bytes. | | data | string | No\* | The raw data read from a token, converted to a hexadecimal string. Used in mappings and detection of NFC toys. | | unsafe | boolean | No | Allow unsafe operations. Default is false. | These parameters allow emulating a token exactly as it would be read directly from an attached reader on the server. A request's parameters must contain at least a populated `uid`, `text` or `data` value. #### Result Returns `null` once the ZapScript has finished executing without error. The method waits for execution to complete: mapping, parsing, launch policy (profiles, playtime limits, blocked commands, hooks), media lookup and every command in the script. Success means the script ran to completion; it does not prove the launched software is still running afterwards. If execution fails, the response carries an [error](index.md#response-errors) whose `data.category` is one of: | Category | Meaning | | :----------------- | :-------------------------------------------------------------------------------------------- | | `busy` | Another launch is already in progress. | | `media_not_found` | The requested media could not be found or matched. | | `disabled` | ZapScript execution is disabled in settings. | | `invalid_script` | The script could not be parsed, names an unknown command or system, or exceeds 8192 bytes. | | `blocked` | Execution was refused by configuration, a profile requirement or a hook. | | `playtime_limit` | A playtime limit prevented the launch. | | `timeout` | Core stopped waiting after the request timeout (30 seconds). Anything already started continues. | | `cancelled` | The request was cancelled, for example because the connection closed. Anything already started continues. | | `unavailable` | The service is shutting down. | | `launch_repair` | The launch needs the user to fix something first. See [launch repair errors](#launch-repair-errors). | | `execution_failed` | Any other execution failure. | Error messages are fixed per category and never include filesystem paths or token contents; the details are in the Core log. `timeout` and `cancelled` only mean Core stopped waiting: nothing that already started is rolled back. During shutdown the connection often closes before the `unavailable` response can be written, so treat a dropped connection with a request in flight the same way. ##### Launch repair errors A `launch_repair` error means the launch stopped for something the user can act on, such as an uninstalled launcher or a missing permission. Its `data` carries two extra keys that let a client write and localize its own wording: | Key | Type | Required | Description | | :------- | :----- | :------- | :----------------------------------------------------------------------------------- | | `reason` | string | Yes | A machine readable reason from the closed set below. | | `params` | object | No | Display names for the reason's wording. Present only when the reason carries one. | The reasons and the parameters each one can carry: | Reason | Meaning | Parameters | | :------------------------------ | :-------------------------------------------------------------------------------- | :------------------- | | `launcher_not_installed` | The launcher application is not installed. | `launcher`, `plugin` | | `launcher_component_missing` | The launcher is installed, but the entry point it declares is gone or disabled. | `launcher`, `plugin` | | `launcher_plugin_missing` | The launcher is installed but its plugin or core for this system is absent. | `launcher`, `plugin` | | `launcher_version_unsupported` | The installed build of the launcher cannot be used for this media, for example because its storage model is unsupported. The user needs a different build of that launcher. | `launcher`, `plugin` | | `launcher_ambiguous` | Several usable launchers and no reviewed default; the user must choose one. Reserved: see below. | `launcher`, `plugin` | | `launcher_unsupported_media` | This launcher cannot play the selected media entry. | `launcher`, `plugin` | | `launcher_options_unsupported` | The launch options requested are not supported by this launcher. | `launcher`, `plugin` | | `storage_permission_required` | The launcher lacks the storage permission it needs. | `launcher`, `plugin` | | `storage_provider_unsupported` | The media lives on a provider this launcher cannot read. | `launcher`, `plugin` | | `storage_unavailable` | The storage holding the media is not present. | `launcher`, `plugin` | | `media_unavailable` | The media file cannot be resolved or opened. | `launcher`, `plugin` | | `media_access_revoked` | The host's own access to this media's source was revoked or withdrawn, distinct from `media_unavailable`'s unspecified cause: the user can act on this one by re-granting access. | `launcher`, `plugin` | | `host_unavailable` | The host's launch service is not answering. | `launcher`, `plugin` | | `host_foreground_required` | The launch needs the user to return to the app first. | `launcher`, `plugin` | | `cancelled` | The launch was cancelled before it started. | `launcher`, `plugin` | | `outcome_unknown` | The launch was dispatched, but the result could not be confirmed. | `launcher`, `plugin` | | `refused` | The operating system refused the request. This is not a catch-all. | `launcher`, `plugin` | | `unspecified` | Core sent no structured reason. Show `message` verbatim. | `launcher`, `plugin` | `refused` means specifically that the operating system refused the launch. A failure Core cannot classify that far reports `unspecified` instead, so do not treat `refused` as "something else went wrong". `launcher_ambiguous` is reserved. No Core version emits it yet, because launcher selection resolves by catalog precedence rather than asking the user. It is published so that clients can handle it when a version does; do not wait for it. `params` has a closed key set: `launcher` is the launcher application's display name, such as `RetroArch` or `DuckStation`, and `plugin` is the name of its plugin or core for this system, such as `Mesen`. Both are short display names only, never identifiers, paths, URIs or text from the host. A key is absent when Core has no name for it, so treat both as optional for every reason. Clients must tolerate an unknown `reason`, and an absent one from an older Core, by falling back to the error's `message`, exactly as they do for `unspecified`. The message is a fixed English string that reads sensibly on its own, so it is always a usable last resort, but it is not a stable contract: branch on `reason` wherever the wording matters. Physical reader scans, playlists and the [launch endpoint](index.md#launch-endpoint) are not affected. They remain asynchronous and do not report execution failures. For ZapScript `launch.random`, Core selects uniformly from matching non-missing media rows after applying systems, tags, and path scope. Filesystem and virtual path targets recursively include subfolders. Tagged requests never use filesystem fallback because unindexed files have no tag metadata. ##### Compatibility Earlier Core versions returned `null` as soon as the token was accepted, before execution started, and never reported execution failures. Clients that treated an immediate `null` as "launched" should now expect the response to arrive when execution finishes, or when Core stops waiting for it. A `timeout` or `cancelled` error means Core stopped waiting, not that execution ended: work already started continues, so poll for the effect rather than treating either as proof of failure. Any other error response is authoritative. ##### Aliases `launch` is a deprecated alias for `run` with identical parameters and result. `run.script` is reserved and currently returns a method-not-found error. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "52f6242e-7a5a-11ef-bf93-020304050607", "method": "run", "params": { "text": "**launch.system:snes" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "52f6242e-7a5a-11ef-bf93-020304050607", "result": null } ``` ##### Error response ```json { "jsonrpc": "2.0", "id": "52f6242e-7a5a-11ef-bf93-020304050607", "error": { "code": 1, "message": "media not found", "data": { "category": "media_not_found" } } } ``` ##### Launch repair error response ```json { "jsonrpc": "2.0", "id": "52f6242e-7a5a-11ef-bf93-020304050607", "error": { "code": 1, "message": "this launcher's plugin for this system is not installed", "data": { "category": "launch_repair", "reason": "launcher_plugin_missing", "params": { "launcher": "RetroArch", "plugin": "Mesen" } } } } ``` ### stop **Access:** All clients. Kill any active launcher, if possible. This method is highly dependant on the platform and specific launcher used. It's not guaranteed that a launcher is capable of killing the playing process. #### Parameters None. #### Result Returns `null` on success, meaning nothing was running or the media was confirmed stopped. Active media is only cleared when the stop succeeded. Returns an error when the media is known to still be running, such as a launcher process that ignored both a close request and a forced kill. Launchers that never expose a process at all, like an opened browser tab, still report success because there is nothing to stop. Whether a failure can be detected at all is platform-dependent. Windows reports one when it can confirm the media is still running; platforms that cannot confirm it continue to report success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "176b4558-7a5b-11ef-b318-020304050607", "method": "stop" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "176b4558-7a5b-11ef-b318-020304050607", "result": null } ``` ### confirm **Access:** All clients. Confirm and launch a staged token from the launch guard. When launch guard is enabled and media is playing, scanned tokens are staged instead of launched immediately. This method confirms the currently staged token and launches it. #### Parameters None. #### Result Returns `null` on success. Returns an error if no token is currently staged. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5b-11ef-b318-020304050607", "method": "confirm" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5b-11ef-b318-020304050607", "result": null } ``` ## UI Core exposes transient UI requests so connected clients—and host platform when appropriate—can render same notice, loader, picker, or confirmation in parallel. Core initially keeps at most one active request, but API uses arrays for future expansion. First valid response for event ID wins; stale responses fail. UI events are intended for small, non-sensitive interactions. They are broadcast to every permitted connected client. Never use them for PINs, passwords, recovery codes, or other secrets. ### ui **Access:** All clients. Returns authoritative UI event state. Clients should call this after connecting or reconnecting. #### Parameters None. #### Result | Key | Type | Required | Description | | :------- | :------------------- | :------- | :---------- | | revision | number | Yes | Monotonic revision of global UI state shared across clients. Ignore older snapshots. | | events | [UI event](#ui-event-object)[] | Yes | Active events. Initial implementation contains zero or one event. | | resolved | [UI resolution](#ui-resolution-object)[] | Yes | Always empty in query response; terminal resolutions are delivered by `ui.changed`. | ##### UI event object | Key | Type | Required | Description | | :-------------- | :-------- | :------- | :---------- | | id | string | Yes | Opaque event ID required by `ui.respond`. | | kind | string | Yes | `notice`, `loader`, `picker`, or `confirm`. | | title | string | No | Optional heading. | | message | string | No | Optional body text. | | choices | [UI choice](#ui-choice-object)[] | No | Picker choices. | | selectedChoiceId | string | No | Initially selected picker choice. | | dismissible | boolean | Yes | Whether `dismiss` is accepted. | | createdAt | string | Yes | RFC3339 creation timestamp. | | expiresAt | string | No | Authoritative RFC3339 expiry. Omitted for producer-controlled events such as loaders. | ##### UI choice object | Key | Type | Required | Description | | :---- | :----- | :------- | :---------- | | id | string | Yes | Opaque choice ID used by `ui.respond`. | | label | string | Yes | Display label. | | media | object | No | The local game the choice launches: `system` (system ID), `path` and `name`. Pass `system` and `path` to [`media.image`](#mediaimage) for its art. Present for playlist and deck items that resolve to an indexed game on this device when the lookup finishes in time, and for any other choice that is a game. | Choice IDs are presentation-safe. Executable ZapScript and private choice values remain inside Core. On MiSTer, Main_MiSTer records in `/tmp/zaparoo/frontend_status.json` whether the Zaparoo frontend runs in place of the stock menu. While it does, Core shows no UI event through its own menu widgets and leaves every event to API clients, including at the menu before the frontend has started, as when a game has just exited and Main is still loading the menu: such an event stays open for at least 60 seconds for the frontend to start and show it, or for its own timeout when that is longer. An event raised while a game runs, which the widgets would have ended the game to show, instead returns to the menu so Main starts the frontend, and stays open for at least 60 seconds from then, or for its own timeout when that is longer. Events the widgets never show over a running game, such as the auto-advance switch countdown, are unchanged. Main starts a new process on every core load and names it in the file shortly after, so when the file names a Main process that is no longer running, Core rereads it for up to 5 seconds before deciding. If it still names that process (a stock Main started in its place), Core shows events as before, without waiting again until the file changes. When the file is missing, unreadable or reports the frontend inactive, Core shows events as before. #### Example ```json { "jsonrpc": "2.0", "id": "ui-state-1", "method": "ui" } ``` ```json { "jsonrpc": "2.0", "id": "ui-state-1", "result": { "revision": 8, "events": [ { "id": "56969e9c-f863-4cc8-9c2c-d7512bf10d4d", "kind": "confirm", "title": "Change game?", "message": "**launch.system:snes", "dismissible": true, "createdAt": "2026-07-16T12:00:00Z", "expiresAt": "2026-07-16T12:00:15Z" } ], "resolved": [] } } ``` ### ui.respond **Access:** All clients. Responds to active UI event. First valid response wins globally and closes host/client renderers. #### Parameters | Key | Type | Required | Description | | :------- | :----- | :------- | :---------- | | id | string | Yes | Active event ID. | | action | string | Yes | `dismiss`, `select`, or `confirm`. | | choiceId | string | No | Required for picker `select`; must identify one published choice. | Allowed actions: - `notice`: `dismiss` when dismissible - `loader`: `dismiss` only when explicitly dismissible - `picker`: `select` with `choiceId`, or `dismiss` - `confirm`: `confirm`, or `dismiss` when dismissible Returns `null` when accepted. Returns client error for stale event ID, invalid action, missing/unknown choice, expired event, or non-dismissible event. #### Example ```json { "jsonrpc": "2.0", "id": "ui-response-1", "method": "ui.respond", "params": { "id": "56969e9c-f863-4cc8-9c2c-d7512bf10d4d", "action": "confirm" } } ``` ```json { "jsonrpc": "2.0", "id": "ui-response-1", "result": null } ``` Top-level `confirm` remains launch-guard-specific for compatibility. It cannot confirm unrelated generic UI event. ##### UI resolution object | Key | Type | Required | Description | | :------ | :----- | :------- | :---------- | | id | string | Yes | Resolved event ID. | | outcome | string | Yes | `confirmed`, `selected`, `dismissed`, `timed_out`, `completed`, `superseded`, or `cancelled`. | | choiceId | string | No | Selected opaque choice ID for `selected`. | ### ui.shown **Access:** Localhost or any authenticated client. Reports that a client has put the active UI event on screen. The first report for an event restarts its expiry at the event's full timeout from now, so time spent waiting for the client to start does not count against the person answering it, and publishes the new `expiresAt` through `ui.changed`. A first report within a second of the event opening keeps the current expiry. Repeated reports for the same event are accepted and change nothing. An event the host renderer presents counts as shown without a report. Clients should send it once per event, when the event first becomes visible. #### Parameters | Key | Type | Required | Description | | :-- | :----- | :------- | :---------- | | id | string | Yes | Active event ID. | Returns `null` when accepted. Returns client error for stale event ID or expired event. #### Example ```json { "jsonrpc": "2.0", "id": "ui-shown-1", "method": "ui.shown", "params": { "id": "56969e9c-f863-4cc8-9c2c-d7512bf10d4d" } } ``` ```json { "jsonrpc": "2.0", "id": "ui-shown-1", "result": null } ``` ## Tokens ### tokens **Access:** All clients. Returns information about active and last scanned tokens. #### Parameters None. #### Result | Key | Type | Required | Description | | :----- | :------------------------------ | :------- | :------------------------------------------------------------- | | active | [TokenResponse](#token-object)[] | Yes | A list of currently active tokens. | | last | [TokenResponse](#token-object) | No | The last scanned token. Null if no token has been scanned yet. | ##### Token object | Key | Type | Required | Description | | :------- | :------ | :------- | :----------------------------------------------- | | type | string | Yes | Type of token. | | uid | string | Yes | UID of the token. | | text | string | Yes | Text content of the token. | | data | string | Yes | Raw data of the token as hexadecimal string. | | scanTime | string | Yes | Timestamp of when the token was scanned in RFC3339 format. | | readerId | string | No | ID of the reader that scanned the token. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "5e9f3a0e-7a5b-11ef-8084-020304050607", "method": "tokens" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "5e9f3a0e-7a5b-11ef-8084-020304050607", "result": { "active": [], "last": { "type": "", "uid": "", "text": "**launch.system:snes", "data": "", "scanTime": "2024-09-24T17:49:42.938167429+08:00" } } } ``` ### tokens.history **Access:** All clients. Returns a list of the last recorded token launches. #### Parameters None. #### Result | Key | Type | Required | Description | | :------ | :------------------------------------ | :------- | :--------------------------------- | | entries | [LaunchEntry](#launch-entry-object)[] | Yes | A list of recorded token launches. | ##### Launch entry object | Key | Type | Required | Description | | :------ | :------ | :------- | :---------------------------------------------- | | data | string | Yes | Raw data of the token as hexadecimal string. | | success | boolean | Yes | True if the launch was successful. | | text | string | Yes | Text content of the token. | | time | string | Yes | Timestamp of the launch time in RFC3339 format. | | type | string | Yes | Type of token. | | uid | string | Yes | UID of the token. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "5e9f3a0e-7a5b-11ef-8084-020304050607", "method": "tokens.history" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "5e9f3a0e-7a5b-11ef-8084-020304050607", "result": { "entries": [ { "data": "", "success": true, "text": "**launch.system:snes", "time": "2024-09-24T17:49:42.938167429+08:00", "type": "", "uid": "" } ] } } ``` ## Media ### media **Access:** All clients. Returns the current media database status and active media. The database status includes both indexing and optimization information: - **Indexing** takes priority over optimization in the response (if both are running, only indexing status is shown) - **Optimization** status and progress are shown when no indexing is in progress #### Parameters None. #### Result | Key | Type | Required | Description | | :-------- | :---------------------------------------- | :------- | :------------------------------------- | | database | [IndexingStatus](#indexing-status-object) | Yes | Status of the media database. | | active | [ActiveMedia](#active-media-object)[] | Yes | List of currently active media. | | playlists | [PlaylistState](#playlist-state-object)[] | No | Currently active playlist slots. | ##### Indexing status object | Key | Type | Required | Description | | :----------------- | :----- | :------- | :----------------------------------------------- | | exists | boolean| Yes | True if the database exists. | | indexing | boolean| Yes | True if indexing is currently in progress. | | optimizing | boolean| Yes | True if database optimization is currently in progress. | | totalSteps | number | No | Total number of indexing steps. | | currentStep | number | No | Current indexing step. | | currentStepDisplay | string | No | Display name of the current indexing step or optimization step. | | totalFiles | number | No | Total number of files to index. | | totalMedia | number | No | Total number of media entries in the database. Only included when database exists and is not indexing. | | scan | object | No | The current system's folder scan, only included while a scan is running: `path` is the folder being read and `entries` the files and folders read so far. | ##### Active media object | Key | Type | Required | Description | | :--------------- | :------- | :------- | :----------------------------------------- | | mediaId | number | No | Opaque media database row ID for efficient follow-up `media.meta` and `media.image` requests. Omitted when the active path cannot be resolved in the current media database. | | launcherId | string | Yes | ID of the launcher. | | systemId | string | Yes | ID of the system. | | systemName | string | Yes | Display name of the system. | | mediaPath | string | Yes | Path to the media file. | | relativePath | string | No | Launcher-relative convenience path, when it can be derived. Not a stable media identity. | | positionMs | number | No | Current playback position in milliseconds when reported by the launcher. Currently available for native audio. | | durationMs | number | No | Total playback duration in milliseconds when reported by the launcher. Currently available for native audio. | | playbackState | string | No | Launcher-reported playback state: `playing`, `paused`, or `stopped`. Currently available for native audio; omitted when unavailable. | | mediaName | string | Yes | Display name of the media. | | slot | string | No | Media slot for the item. Omitted or `primary` is foreground media; `background` is background audio. | | started | string | Yes | Timestamp when media started in RFC3339 format. | | zapScript | string | Yes | ZapScript command to launch this media item. For a track in the `background` slot this is the track's path, since track titles are not unique across albums. | | launcherControls | string[] | No | List of control action names supported by the active launcher. Only present if the launcher supports controls. See [media.control](#mediacontrol). | | track | [TrackInfo](#track-info-object) | No | Tags of an audio track played by native audio, in either slot. Omitted when the track has no tags or they have not been read yet, which takes a moment after the track starts. `mediaName` is unchanged by the tags. | ##### Track info object Every field is omitted when the track does not have it. | Key | Type | Required | Description | | :---------- | :------ | :------- | :---------- | | title | string | No | Track title. | | artist | string | No | Track artist. | | album | string | No | Album title. | | albumArtist | string | No | Album artist. | | genre | string | No | Genre. | | year | number | No | Release year. | | trackNumber | number | No | Track number on its disc. | | trackTotal | number | No | Number of tracks on the disc. | | discNumber | number | No | Disc number. | | discTotal | number | No | Number of discs. | | hasArt | boolean | No | True when [media.active.image](#mediaactiveimage) has cover art for the track, embedded in it or beside it. Omitted when false. | ##### Playlist state object | Key | Type | Required | Description | | :------ | :----- | :------- | :---------- | | id | string | Yes | Playlist ID. | | name | string | Yes | Playlist display name. | | slot | string | Yes | Playlist slot, `primary` or `background`. | | repeat | string | Yes | Repeat mode: `none`, `all`, or `one`. | | shuffle | boolean | Yes | True when the items are in a random order. `items` lists them in the order they play. See [playlists.update](#playlistsupdate). | | items | object[] | Yes | Playlist items. | | index | number | Yes | Zero-based current item index. | | total | number | Yes | Total item count. | | playing | boolean | Yes | Whether playlist slot is playing. | | advanceMs | number | No | Milliseconds of playing time before the playlist moves to the next item by itself. Omitted when the playlist does not advance on a timer. | | idleMs | number | No | Milliseconds with no user input before the playlist moves to the next item, or starts when it was loaded waiting. Never present together with `advanceMs`. | | countdownMs | number | No | Milliseconds the notice before an automatic switch stays up. `0` switches with no notice. Omitted when the playlist does not say, which uses the default of 10 seconds. | | armed | boolean | No | True while an idle playlist is loaded and waiting for the device to go idle before it starts. Omitted when false. | | unsafe | boolean | Yes | Read-only. True when the playlist's items came from a source this device does not trust, such as a fetched ZapLink or a deck shared by someone else, and also when an untrusted script opened it, which even the user's own deck inherits. Commands in those items that drive input or run programs will not run. Core versions that do not report this field do not restrict playlist items, so treat a missing value as `false`. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "47f80537-7a5d-11ef-9c7b-020304050607", "method": "media" } ``` ##### Response (database ready) ```json { "jsonrpc": "2.0", "id": "47f80537-7a5d-11ef-9c7b-020304050607", "result": { "database": { "exists": true, "indexing": false, "optimizing": false, "totalMedia": 1337 }, "active": [] } } ``` ##### Response (optimization in progress) ```json { "jsonrpc": "2.0", "id": "47f80537-7a5d-11ef-9c7b-020304050607", "result": { "database": { "exists": true, "indexing": false, "optimizing": true, "currentStepDisplay": "vacuum", "totalMedia": 1337 }, "active": [] } } ``` ### media.search **Access:** All clients. Query the media database and return matching indexed media. Hidden entries, and everything under a hidden folder, are excluded before pagination unless `includeHidden` is true. A search whose `pathPrefix` is a hidden folder, or a path inside one, addresses that folder directly and still searches it. Explicit required user tag filters (`user:favorite`, `user:liked`, `user:hidden` and the other user tags) and `~` groups of user tags (`~user:favorite ~user:liked`) also include hidden entries; `-` user tag filters do not enable this exception. **Note:** This API uses cursor-based pagination for all requests. The `total` field is deprecated and returns only the current response-page count; it is not the full match count. Use the `pagination` object to navigate through results. For subsequent pages, include the `nextCursor` value and repeat the same systems, pathPrefix, query, tags, letter, and sort scope. Changing `includeHidden` or editing media preferences invalidates existing search cursors; restart without a cursor when Core reports `library visibility changed`. #### Parameters An object: | Key | Type | Required | Description | | :--------- | :------- | :------- | :----------------------------------------------------------------------------------------------------------------------------- | | query | string | No | Case-insensitive search by filename. By default, query is split by white space and results are found which contain every word. If omitted, all media is returned. | | systems | string[] | No | Case-sensitive list of system IDs to restrict search to. A missing key or empty list will search all systems. | | includeHidden | boolean | No | Include hidden entries for recovery/management. Defaults to `false`; available to all clients. Repeat on subsequent pages. | | pathPrefix | string | No | Recursively restrict results beneath a filesystem directory or virtual route. Matching respects path boundaries, so `/roms/SNES` does not include `/roms/SNES2`; `%` and `_` are literal path characters. | | maxResults | number | No | Max number of results to return. Default is 100. | | cursor | string | No | Cursor for pagination. Omit for first page, use `nextCursor` from previous response for subsequent pages with the same scope and sort. | | tags | string[] | No | Filter results by case-sensitive tags. Maximum 50 tags, each up to 128 characters. Default and `+` filters require matches, `-` excludes matches, and `~` joins alternatives of the same tag type: a result must match at least one `~` filter of every type given, so `~genre:rpg ~genre:platformer ~region:us ~region:jp` means (rpg or platformer) and (us or jp). Can be used without query or systems for tag-only searches. | | letter | string | No | Filter results by first character of game name. Supports: A-Z (single letters), "0-9" (numbers), "#" (symbols). Case-insensitive. | | sort | string | No | Explicit order: `name-asc`, `name-desc`, `filename-asc`, `filename-desc` or `added-desc`. Name uses the returned display name with SQLite's case-insensitive collation; filename uses full indexed path. `added-desc` orders by when each game got a flag; see [Sorting by date added](#sorting-by-date-added). Omitted preserves legacy database order. | | fuzzySystem | boolean | No | Enable fuzzy matching for system IDs in the `systems` array (e.g., `"snes"` matches `"SNES"`). | | groupBy | string | No | `title` returns one result per title and system instead of one per media file. See [Grouped search](#grouped-search). Only `name-asc` and `name-desc` sorts apply. Cannot be combined with `titleId`. | | titleId | number | No | List the versions of one title: its media matching `tags`, `pathPrefix` and visibility, folded the same way as a grouped search's `versionCount`. `query`, `systems` and `letter` are ignored. Use the `titleId` of a search result. | #### Sorting by date added `added-desc` lists the games of one user flag list by when each got the flag, newest first. It needs a positive `user:favorite`, `user:liked`, `user:disliked` or `user:playlater` filter in `tags` (no `-` or `~` operator); when several are given, the first one names the order. Games flagged before Core recorded when flags are set have no date: they come after every dated game, ordered by name ascending. Setting a flag that is already set keeps its date, and clearing a flag clears it. Cursors work as for the other sorts. Any other use of `added-desc`, including with `groupBy` or `titleId`, is a client error. #### Grouped search With `groupBy: "title"`, each result stands for one title on one system. Regional releases, revisions and copies in other folders are one title. The same name on two systems gives two results. `maxResults`, `hasNextPage` and cursors count titles rather than files. A title's media that launch through one container (a `.cue` and its `.bin` tracks, or a folder of discs) count as one version, the file the container launches. Each result carries the fields of the version Core prefers for the title, chosen the same way a title launch chooses: main releases before variants, then your preferred regions and languages, then the launcher's file type order. Its `zapScript` launches that version. `versionCount` is the number of versions matching the search's tags, `pathPrefix` and visibility, across the whole search rather than the page. A search with the result's `titleId` lists the same versions. #### Result | Key | Type | Required | Description | | :--------- | :--------------------------------- | :------- | :------------------------------------------------------------------------------ | | results | Media[] | Yes | A list of all search results from the given query. | | total | number | Yes | **Deprecated:** Returns the count of results in the current response page. Use pagination info for navigation. | | pagination | [Pagination](#pagination-object) | Yes | Pagination information for cursor-based navigation. | ##### Media object | Key | Type | Required | Description | | :-------- | :----------------------- | :------- | :---------------------------------------------------------------------------------------------------------- | | mediaId | number | No | Opaque media database row ID for efficient follow-up `media.meta` and `media.image` requests. | | titleId | number | No | Opaque title ID for a `titleId` search listing this title's versions. Changes when media is re-indexed. | | versionCount | number | No | Grouped searches only. Number of versions of this title that match the search. | | system | [System](#system-object) | Yes | System which the media has been indexed under. | | name | string | Yes | A human-readable version of the result's filename without a file extension. | | path | string | Yes | Canonical indexed media path. Use with `system.id` for `media.meta` and `media.image`. | | relativePath | string | No | Launcher-relative convenience path, when it can be derived. Not a stable media identity. | | hasCover | boolean | Yes | Whether media-level or title-level image properties are available. | | coverColor | string | No | Average colour of the cover thumbnail as `#rrggbb`, for a placeholder while the image loads. Omitted until Core has built a thumbnail for the media through `media.image` with a `maxSize`. | | zapScript | string | Yes | ZapScript command to launch this media item. Includes the disambiguating tags inline (e.g. `@Arcade/X-Men Vs. Street Fighter (region:eu) (builddate:1996-10-04)`) so the written command resolves back to this specific variant. | | tags | [TagInfo](#taginfo-object)[] | Yes | Array of tags associated with this media item. | | disambiguatingTags | [TagInfo](#taginfo-object)[] | No | Subset of `tags` whose values differ across same-named siblings of this title, plus any tag that makes the file a distinct game (a ROM hack, homebrew or public-domain work) even when it has no sibling, ordered by display importance. Omitted when there is nothing to disambiguate. Clients can render these to tell variants apart. | ##### System object | Key | Type | Required | Description | | :----------- | :----- | :------- | :----------------------------------------------------------------------- | | id | string | No | Internal system ID for this system. | | name | string | No | Display name of the system. | | category | string | No | Deprecated: use `categories`. Primary category of system (e.g., "Console", "Computer"), kept for clients that support one category. Always equal to the first entry of `categories`. | | categories | string[] | No | Complete ordered category membership. The primary category is first, followed by configured additional memberships. | | releaseDate | string | No | Release date of the system in ISO 8601 format (YYYY-MM-DD). | | manufacturer | string | No | Manufacturer of the system (e.g., "Nintendo", "Sega"). | | mediaCount | number | No | Populated only in `systems` responses; not included on System objects nested in `media.search` results. Exact non-missing indexed media-row count for this system, or exact matching count when `systems.tags` is set. Zero means the system is supported but empty. Omitted by older Core versions or when counts are unavailable. | Clients should use `categories` and fall back to `[category]` only when connected to older Core versions that do not send it. Custom category strings are literal display values configured in Core TOML. Core matches configured references case-insensitively but returns canonical built-in spelling or custom declaration spelling. References to undeclared categories are ignored, and a virtual system whose primary category is undeclared reports `Other`. Clients display unknown custom values as received. Available categories remain dynamic: derive them from `categories` on systems returned by the current request. Core does not return a separate fixed category catalog. Filters such as `systems.tags` may therefore change which categories are represented. ##### Pagination object | Key | Type | Required | Description | | :---------- | :------ | :------- | :-------------------------------------------------------------------------- | | nextCursor | string | No | Cursor for the next page of results. Omitted if no more pages available. | | hasNextPage | boolean | Yes | Whether there are more results available after the current page. | | pageSize | number | Yes | Number of results requested for this page (matches `maxResults` parameter). | ##### TagInfo object | Key | Type | Required | Description | | :--- | :----- | :------- | :---------------------------------------------------- | | tag | string | Yes | The tag name. | | type | string | Yes | The type/category of the tag (e.g., "genre", "year"). | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "47f80537-7a5d-11ef-9c7b-020304050607", "method": "media.search", "params": { "query": "240p" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "47f80537-7a5d-11ef-9c7b-020304050607", "result": { "results": [ { "mediaId": 123, "name": "240p Test Suite (PD) v0.03 tepples", "path": "/media/fat/games/Gameboy/240p Test Suite (PD) v0.03 tepples.gb", "relativePath": "Gameboy/240p Test Suite (PD) v0.03 tepples.gb", "hasCover": false, "zapScript": "@Gameboy/240p Test Suite (PD) v0.03 tepples", "system": { "category": "Handheld", "categories": ["Handheld"], "id": "Gameboy", "name": "Gameboy" }, "tags": [ { "tag": "homebrew", "type": "release" } ] } ], "total": 1, "pagination": { "hasNextPage": false, "pageSize": 100 } } } ``` ##### Example with tag filtering ###### Request ```json { "jsonrpc": "2.0", "id": "b2c3d4e5-7a5d-11ef-9c7b-020304050607", "method": "media.search", "params": { "query": "mario", "tags": ["genre:action:platformer", "publisher:nintendo"], "maxResults": 10 } } ``` ###### Response ```json { "jsonrpc": "2.0", "id": "b2c3d4e5-7a5d-11ef-9c7b-020304050607", "result": { "results": [ { "mediaId": 456, "name": "Super Mario Bros.", "path": "/media/fat/games/NES/Super Mario Bros.nes", "relativePath": "NES/Super Mario Bros.nes", "hasCover": true, "zapScript": "@NES/Super Mario Bros. (year:1985)", "system": { "category": "Console", "categories": ["Console"], "id": "NES", "name": "Nintendo Entertainment System" }, "tags": [ { "tag": "action:platformer", "type": "genre" }, { "tag": "nintendo", "type": "publisher" }, { "tag": "1985", "type": "year" } ] } ], "total": 1, "pagination": { "hasNextPage": false, "pageSize": 10 } } } ``` ### media.browse **Access:** All clients. Browse indexed media content by directory, similar to navigating a file manager. Supports filesystem paths, virtual URI schemes (e.g. `mame-arcade://`), and paginated results. When called without a `path` parameter (or with an empty path), returns top-level root entries including filesystem roots and virtual scheme roots. When `systems` is provided without `path`, returns populated launcher routes for those systems only. Pass the same `systems` filter when browsing a returned route to keep shared paths scoped to the selected systems. `path` also accepts the launcher-relative form reported as `relativePath`: a system ID, optionally followed by a path below that system's launcher folder (for example `SNES` or `SNES/USA`). Core browses the first matching folder, in platform root order, that holds indexed content, and the result's `path` is that folder's absolute path. A relative path that matches no indexed folder is an error. This lets a client keep a folder reference that survives the media moving to another root. Set `rootView` to `contents` with exactly one system to replace its filesystem routes with a one-level view of their immediate contents. This is display-only: entries retain physical paths, and browsing a returned directory uses ordinary single-path behavior. Root priority follows platform order (first root wins); exact, case-sensitive filesystem basenames define collisions. Virtual URI routes remain separate, except platform-defined `zaparoo://` media, which are listed among the files. A directory whose direct contents collapse to a single logical launch target is returned with that target's `mediaId`, display name, `zapScript`, `tags`, and `hasCover`, so a per-game disc folder appears as one launchable game. Display names leave out set markers such as `(Disc 1)`; the disc number is reported in `tags` instead. A directory qualifies when it has no nested media and holds one media file, one `.m3u` plus its discs, one `.cue` plus its companion tracks, or at least two supported disc-image files that all share one positive title identity. Shared-title disc sets support `.cue`, `.chd`, `.iso`, `.bin`, `.img`, and `.pbp`; mixed title identities or other extensions remain ambiguous. The selected target is deterministic by path then media ID. Existing single-file, playlist, and cue precedence remains unchanged. Its `type` stays `directory` and it keeps its own `path` and `fileCount`, so clients can still navigate into it. Directories that hold nested media or an ambiguous file set stay plain directories. A folder played as a playlist (`**playlist.play:`, and `playlist.load` and `playlist.open`) holds the folder's media as a `filename-asc` browse of it lists it: the same entries, in the same order, without hidden media, under the same names. Its `system` argument filters it as the browse's `systems` does (`?system=Audio` keeps the folder's tracks), so a client that browsed a folder with one system can play it with the same one and start it at the entry it shows as item *n* with `start=n`. The media index is preferred but not required: a folder it does not cover is read from disk instead, keeping to the files the system's launchers take. A directory that collapsed because it holds several disc images of one game is marked `multiDisc: true`. Its launch fields point at the disc most recently played from that folder, or at the first disc when none of them appears in the system's recent play history, and its `tags` carry that disc's number. Its `disambiguatingTags` omit the disc number, since the entry stands for the whole set. To offer the other discs, browse the entry's `path`. Only `media.browse` reads play history: `media.meta` and `media.image` given the folder's path alone resolve it to the first disc. Request a collapsed `directory` entry's image and metadata with its `mediaId`, `system`, and `path` together, so they describe the disc the entry launches. `media.image` then returns the folder's own artwork first, then the launch target's, then the first disc's; `media.meta` returns the launch target's metadata and also lists the folder's own image types. A plain directory has no `mediaId`; request its image with `(system, path)`. The `mediaId` form alone only ever returns the launch target's artwork. Plain directories may also have artwork imported by the `media-folder` scraper. This does not make them launchable or hide their children; it only sets `hasCover` and lets clients request the image with the directory's `(system, path)`. A directory holding media for more than one system also stays plain, because its `fileCount` is the sum across those systems and the rule is applied one system at a time. A page spanning several systems is resolved per system when `systems` names them; without a `systems` filter such a page is left unresolved, since browsing a media root lists one directory per installed system and resolving all of them is disproportionate to that page's cost. Tags filter direct media files in the current path. Directories remain visible for navigation with tag-unfiltered `fileCount` values, while `totalFiles`, file pagination, and cursors reflect only matching files. Tagged directory entries remain plain directories rather than being promoted to logical single-game aliases. Visibility is separate from ordinary tag filtering: hidden media is excluded from files, directory/root counts, and letter indexes before pagination. Hidden-only directories/routes disappear. A hidden folder is left out of its parent's listing and its media are subtracted from every count above it, but the folder still lists normally when its own `path`, or a path inside it, is browsed. Set `includeHidden: true` to show hidden entries with their `user:hidden` tag; a hidden folder's `directory` entry carries the tag in `tags`, and the entries inside it do not. Required user tag filters, such as `user:favorite`, `user:liked` or `user:hidden`, also include hidden entries. Changing visibility mode or editing media preferences invalidates existing browse cursors. A request with a cursor must restart without one when Core reports `library visibility changed`. A request with no cursor is retried once inside Core automatically and only returns an error if preferences change again during that retry. Set `live: true` to list a filesystem `path` straight from disk instead of from the media index. This reaches folders the index does not cover, such as MiSTer menu folders of `.mgl` files (`/media/fat/_Chronological`) or Arcade Organizer folders. The path must sit under the same allowed roots as an indexed browse, and with symlinks resolved it must stay under them. Folders are listed first, then files that a launcher accepts; dot files, broken symlinks and symlinks that resolve outside the roots are left out. Each file's `zapScript` launches its own path, so writing it to a tag keeps the entry the user picked. A file whose path, or whose symlink target, is an indexed media file gets that media's `mediaId`, `systemId` and cover fields. Other files carry the system of the launcher that accepts them, or no system for a generic launcher. Live browse ignores visibility settings, and `fileCount`, `relativePath` on the result, and single-game folder collapsing are not provided. It cannot be combined with `systems`, `tags` or `rootView`. `letter` and `sort` work as for indexed browse. Cursors from a live browse are only valid for a live browse with the same `path`, `letter` and `sort`. One directory read is capped at 10,000 entries. #### Parameters All parameters are optional. When called with no parameters, returns root entries. | Key | Type | Required | Description | | :--------- | :----- | :------- | :--------------------------------------------------------------------------------------------------------- | | live | boolean | No | List `path` from disk instead of the media index. Requires a filesystem `path`. Defaults to `false`. Repeat with cursor requests. | | path | string | No | Directory path to browse. Omit or set empty to list root entries. Supports filesystem paths, launcher-relative paths (e.g. `SNES/USA`), and virtual URI schemes (e.g. `mame-arcade://`). | | systems | string[] | No | Case-sensitive list of system IDs to restrict route discovery and browse results to. A missing key or empty list preserves unfiltered behavior. | | fuzzySystem | boolean | No | Enable fuzzy matching for system IDs in the `systems` array (e.g., `"snes"` matches `"SNES"`). | | includeHidden | boolean | No | Include hidden media and its contribution to directory/root counts. Defaults to `false`. Repeat with cursor requests. | | rootView | string | No | Pathless system-root presentation: `routes` (default) returns separate populated routes; `contents` returns one-level immediate contents and requires exactly one system. Ignored when `path` is non-empty. Repeat with cursor requests. | | maxResults | number | No | Maximum results per page. Default is 100, maximum is 1000. | | cursor | string | No | Opaque pagination cursor from a previous response's `nextCursor`. Omit for first page. Cursors are valid only with the same path, systems, tags, letter, and sort parameters. | | tags | string[] | No | Filter direct media files by tags. Syntax and AND/NOT/OR operators match `media.search`. Directories remain unfiltered. | | letter | string | No | Filter results to entries starting with this letter. | | sort | string | No | Sort order. One of: `name-asc` (default), `name-desc`, `filename-asc`, `filename-desc`. Name sorting is prefix-aware for detected ranked/date collection folders. The `filename` variants sort by full file path. | | offset | number | No | Start the page at this absolute position in the listing, directories first, then files. Must be 0 or greater. An offset at or past the end returns no entries with correct totals. Root `virtualEntries` of a `rootView: "contents"` listing are not counted and appear only on the cursorless first page. See [Positioned pages](#positioned-pages). | | anchorPath | string | No | Non-empty absolute path to locate in the listing, in the form entries report as `path`. The launcher-relative form accepted by `path` is not resolved here. Returns the page starting at the largest multiple of `maxResults` not after its position. A path below a listed folder, at any depth, finds that folder, whether or not the path itself is still indexed or visible. See [Positioned pages](#positioned-pages). | #### Result | Key | Type | Required | Description | | :--------- | :------------------------------------ | :------- | :----------------------------------------------------------------------- | | path | string | Yes | The browsed directory path. Empty string when listing roots. | | relativePath | string | No | Launcher-relative path of the browsed directory itself (for example `SNES/USA`). Present only when `systems` names exactly one system and the directory sits under that system's launcher folders. | | entries | [BrowseEntry](#browse-entry-object)[] | Yes | Array of entries in the current path. | | totalFiles | number | Yes | Total count of media files in the current directory (respects `tags` and `letter` filters). | | totalDirs | number | Yes | Total count of immediate child directories in the current directory. | | pagination | [Pagination](#browse-pagination-object) | No | Pagination info. Always present on a cursorless page without `letter` of a `path` or `rootView: "contents"` listing. Never present on a route listing (no `path`, default `rootView`). Elsewhere, omitted when the page has no entries. | ##### Browse entry object | Key | Type | Required | Description | | :----------- | :------- | :------- | :----------------------------------------------------------------------------------------------- | | mediaId | number | No | Opaque media database row ID. Present on `media` entries, and on `directory` entries whose direct contents collapse to one logical launch target, where it identifies that target. Use it for follow-up `media.meta` requests and for `media.image` on `media` entries; request a `directory` entry's image by `(system, path)` so folder artwork is used. | | name | string | Yes | Display name of the entry. Set markers such as `(Disc 1)` are left out of media names and reported in `tags`. | | path | string | Yes | Full path to the entry. | | type | string | Yes | Entry type: `root`, `directory`, or `media`. | | fileCount | number | No | Number of files in this directory. Present on `root` and `directory` entries, except a `root` entry whose exact count could not be computed in time (known non-empty, count omitted). | | group | string | No | Launcher group name. Present on virtual scheme `root` entries. | | systemId | string | No | System ID for the media or single-system filtered route (e.g. `SNES`). Present on `media` entries and filtered `root` entries when exactly one system applies. | | systemIds | string[] | No | System IDs represented by a filtered `root` or `directory` entry. | | zapScript | string | No | ZapScript command to launch this media. Present on `media` entries and logical single-game container `directory` entries. | | relativePath | string | No | Launcher-relative convenience path (for example `SNES/Game.sfc`) when portable conversion succeeds. Present on media and logical single-game container entries, and on `directory` and `root` entries that belong to exactly one system, where it names the folder itself (`SNES/USA`, or `SNES` for the system's launcher folder) and can be sent back as `path`. Omitted for unmatched absolute paths, virtual URIs, and folders shared by several systems. Not a stable media identity. | | tags | object[] | No | Tags attached to the media. Each object has `tag` (string) and `type` (string). Present on `media` entries and logical single-game container `directory` entries. | | disambiguatingTags | object[] | No | Subset of `tags` whose values differ across same-named siblings of this title, plus any tag that makes the file a distinct game (a ROM hack, homebrew or public-domain work) even when it has no sibling, ordered by display importance. Same object shape as `tags`. Omitted when there is nothing to disambiguate. | | multiDisc | boolean | No | `true` on a `directory` entry that stands for several disc images of one game. Its launch fields point at the disc last played from it, or the first disc; browse its `path` to list the others. Omitted otherwise. | | hasCover | boolean | Yes | Whether image properties are available. For directories this includes path-keyed folder artwork and, when collapsed, media/title artwork. Clients can skip image requests when false. | | coverColor | string | No | Average colour of the cover thumbnail as `#rrggbb`, for a placeholder while the image loads. Present on `media` entries and logical single-game container `directory` entries once Core has built a thumbnail for the media through `media.image` with a `maxSize`. Omitted on a container `directory` entry that has folder artwork of its own, because the colour describes the launch target's cover. | ##### Browse pagination object | Key | Type | Required | Description | | :---------- | :----- | :------- | :------------------------------------------------------- | | hasNextPage | bool | Yes | Whether more results exist beyond the current page. | | pageSize | number | Yes | The requested page size. | | nextCursor | string | No | Opaque cursor for the next page. Absent on the last page. | | offset | number | No | Absolute position of the first returned row, not counting root `virtualEntries`. Present on every cursorless page without `letter`, including 0, so a client can detect support from a normal first page. Absent on cursor and letter-filtered pages and on `live` listings. | | anchorIndex | number | No | Absolute position of `anchorPath`, or of the listed folder it sits below. Absent when neither is listed. | ##### Positioned pages `offset` and `anchorPath` read a listing by position instead of walking it with cursors. An offset page holds the same rows as the cursor page at that depth, for every `sort`, and its `nextCursor`, `totalDirs` and `totalFiles` work as on any other page. When `anchorPath` is not listed and is not below a listed folder, the response is the cursorless first page without `anchorIndex`, and no error is returned. That covers a path that does not exist, lies outside the listing, or is hidden or removed by the request's `tags`, `systems` or `includeHidden`. Both return an invalid parameter error when: - combined with each other, `cursor`, `letter` or `live` - used on a listing with no position: no `path` and no `rootView: "contents"` - `offset` is negative or `anchorPath` is empty #### System route example ##### Request ```json { "jsonrpc": "2.0", "id": 1, "method": "media.browse", "params": { "systems": ["SNES"] } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "path": "", "entries": [ { "name": "SNES", "path": "/roms/SNES", "type": "root", "fileCount": 150, "hasCover": false, "systemId": "SNES", "systemIds": ["SNES"], "relativePath": "SNES" } ], "totalFiles": 0 } } ``` #### Root contents example With SNES media under `/configured/SNES` and `/roms/SNES`, this view displays their immediate children together. If both roots contain the same basename, `/configured/SNES` wins because it appears first in platform root order. ##### Request ```json { "jsonrpc": "2.0", "id": 1, "method": "media.browse", "params": { "systems": ["SNES"], "rootView": "contents" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "path": "", "entries": [ { "name": "RPGs", "path": "/configured/SNES/RPGs", "type": "directory", "fileCount": 42, "systemIds": ["SNES"], "hasCover": false }, { "mediaId": 42, "name": "Super Mario World", "path": "/roms/SNES/Super Mario World.sfc", "type": "media", "systemId": "SNES", "zapScript": "@SNES/Super Mario World", "relativePath": "SNES/Super Mario World.sfc", "hasCover": true } ], "pagination": { "hasNextPage": false, "pageSize": 100 }, "totalDirs": 1, "totalFiles": 1 } } ``` Selecting `RPGs` browses only `/configured/SNES/RPGs`; `rootView` does not merge lower levels. #### Browse path example ##### Request ```json { "jsonrpc": "2.0", "id": 1, "method": "media.browse", "params": { "path": "/roms/SNES", "maxResults": 3 } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "path": "/roms/SNES", "entries": [ { "name": "RPGs", "path": "/roms/SNES/RPGs", "type": "directory", "fileCount": 42, "hasCover": false }, { "mediaId": 42, "name": "Super Mario World", "path": "/roms/SNES/Super Mario World.sfc", "type": "media", "systemId": "SNES", "hasCover": true, "zapScript": "@SNES/Super Mario World", "relativePath": "SNES/Super Mario World.sfc", "tags": [ {"tag": "1990", "type": "year"}, {"tag": "2", "type": "players"} ] }, { "mediaId": 43, "name": "The Legend of Zelda - A Link to the Past", "path": "/roms/SNES/The Legend of Zelda - A Link to the Past.sfc", "type": "media", "systemId": "SNES", "hasCover": false, "zapScript": "@SNES/The Legend of Zelda - A Link to the Past", "relativePath": "SNES/The Legend of Zelda - A Link to the Past.sfc", "tags": [ {"tag": "1991", "type": "year"}, {"tag": "1", "type": "players"} ] } ], "totalFiles": 150, "pagination": { "hasNextPage": true, "pageSize": 3, "nextCursor": "eyJzb3J0VmFsdWUiOiJUaGUgTGVnZW5kIG9mIFplbGRhIC0gQSBMaW5rIHRvIHRoZSBQYXN0IiwibGFzdElkIjo0Mn0=" } } } ``` ### media.browse.index **Access:** All clients. Return the ordered first-character "jump to letter" buckets for a browse scope. Each bucket carries a count and a ready-to-use cursor that seeks `media.browse` to the start of that bucket, so a single round trip gives a client everything it needs to draw a section rail _and_ jump into the full ordered list. This avoids paging from the top to reach a distant section, which matters on constrained clients (e.g. MiSTer). The scope parameters mirror `media.browse` so the index describes the exact media-file list `media.browse` would return for the same scope. The per-bucket `cursor` is an ordinary browse cursor: pass it to `media.browse` with the same `path`/`systems`/`tags`/`sort` to get a normal page that begins at the bucket and continues into the next bucket as the user scrolls. A scope can have no media files of its own and still be a list of games: on most CD systems each game is a folder, which `media.browse` returns as a `directory` entry carrying the game's `mediaId`. When the scope has no media files but does have directory entries, the buckets are computed over those directory entries instead and `entryType` is `directory`. See [Directory buckets](#directory-buckets). A scope with at least one media file of its own is always bucketed by its media files. #### Parameters All parameters are optional. | Key | Type | Required | Description | | :---------- | :------- | :------- | :------------------------------------------------------------------------------------------------ | | path | string | No | Directory or virtual scheme to index, same as `media.browse`. Omit or set empty for a root listing (no rail applies). | | systems | string[] | No | Case-sensitive system IDs to scope the index to, same as `media.browse`. | | fuzzySystem | boolean | No | Enable fuzzy matching for system IDs in `systems`. | | includeHidden | boolean | No | Match the visibility mode of `media.browse`. Defaults to `false`. | | tags | string[] | No | Filter indexed media by tags, using the same syntax and operators as `media.browse`. | | sort | string | No | Sort order, must match the `media.browse` sort the rail is for. One of `name-asc` (default), `name-desc`, `filename-asc`, `filename-desc`. | #### Result | Key | Type | Required | Description | | :--------- | :-------------------------------------------- | :------- | :-------------------------------------------------------------------------- | | scheme | string | Yes | Collation used to derive the buckets. `latin` for first-character bucketing; `none` when no rail applies (a root listing, or a directory whose effective sort is not alphabetical, e.g. a ranked/date-prefixed collection folder), in which case `groups` is empty. | | entryType | string | Yes | What the groups count: `media` for the scope's media files, or `directory` when the scope has no media files and the groups describe its directory entries. Always `media` when `scheme` is `none` for a root listing. A Core that predates this field omits it; treat a missing value as `media`. | | totalFiles | number | Yes | Total media files matching the complete systems/path/tags scope. `0` when `entryType` is `directory`. | | groups | [BrowseIndexGroup](#browse-index-group-object)[] | Yes | Only non-empty buckets, ordered to match `sort`. | ##### Browse index group object | Key | Type | Required | Description | | :----- | :----- | :------- | :------------------------------------------------------------------------------------------------ | | key | string | Yes | Stable bucket identifier (`A`–`Z`, `0-9`, `#`). Treat as opaque. | | label | string | Yes | Display text for the bucket. Equal to `key` for the `latin` scheme. | | count | number | Yes | Number of media files in the bucket, or the number of directory entries when `entryType` is `directory`. | | cursor | string | Yes | Opaque `media.browse` cursor positioned just before the bucket's first row (its first directory entry when `entryType` is `directory`). Empty string for the bucket that begins the list (call `media.browse` with no cursor for the first page). | | offset | number | Yes | 0-based position of the bucket's first item among the scope's media files, taken from its row number in the same ordered listing `media.browse` pages through (so it cannot drift from the browse order). Excludes any directory entries the listing shows before files; a client that jumps to a position in the full list adds its own leading-directory count. Use this to jump to the bucket's position rather than reloading from `cursor`. When `entryType` is `directory` this is instead the position among the scope's directory entries, and nothing is added to it: see [Directory buckets](#directory-buckets). | Clients should render `groups` exactly as received, in order, without assuming a particular alphabet: `scheme` and `key` are opaque so a future locale-aware scheme (e.g. pinyin/kana/hangul buckets) requires no client change. ##### Directory buckets When `entryType` is `directory`, every group describes directory entries of the scope rather than media files: - `count` is the number of directory entries in the bucket. - `offset` is the 0-based position of the bucket's first directory among the scope's `directory` entries, in the order `media.browse` returns them. It already counts directories, so a client must not add a leading-directory count to it. In the root `contents` view, any `root` entries `media.browse` lists ahead of the directories are not counted. - `cursor` is the cursor `media.browse` itself returns after the directory that precedes the bucket. Passing it to `media.browse` with the same scope returns a page that begins at the bucket's first directory and continues through the remaining directories. - Buckets follow the order `media.browse` lists directories in, which ascends by name whatever `sort` is: `sort` orders media files only. The bucket is taken from the directory name as it is ordered, which ignores bracketed metadata such as `(USA)` or `[T-En]`. A directory entry that stands for a single game displays that game's name, which can begin with a different character than the directory name it is ordered by. - The same `systems` and `includeHidden` scoping `media.browse` applies to its directory listing applies here. `tags` filters media files only, in both methods: a `tags` filter that leaves the scope with no matching media files yields directory buckets over the unfiltered directory entries, which is what `media.browse` lists for that request. A flat virtual scheme (for example `steam://`) has no directory entries and is always `media`. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": 1, "method": "media.browse.index", "params": { "path": "/roms/SNES", "sort": "name-asc" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": 1, "result": { "scheme": "latin", "entryType": "media", "totalFiles": 150, "groups": [ { "key": "#", "label": "#", "count": 3, "cursor": "", "offset": 0 }, { "key": "0-9", "label": "0-9", "count": 7, "cursor": "eyJzb3J0VmFsdWUiOiIjV29sZiIsImxhc3RJZCI6MTAyfQ==", "offset": 3 }, { "key": "A", "label": "A", "count": 12, "cursor": "eyJzb3J0VmFsdWUiOiI5IExpdmVzIiwibGFzdElkIjoxMTV9", "offset": 10 } ] } } ``` To jump to "A", the client calls `media.browse` with that group's `cursor` and the same `path`/`sort`; the returned page begins at the first "A" title and continues into "B" as the user keeps scrolling. ### media.tags **Access:** All clients. Query the media database and return available tags for filtering. This method returns all available tags (with their types) for the specified systems. Use this to build dynamic filter UIs showing available tag options. #### Parameters | Key | Type | Required | Description | | :------ | :------- | :------- | :-------------------------------------------------------------------------------------------------- | | systems | string[] | No | Case-sensitive list of system IDs to restrict tags to. A missing key or empty list will get all systems. | | fuzzySystem | boolean | No | Enable fuzzy matching for system IDs in the `systems` array (e.g., `"snes"` matches `"SNES"`). | #### Result | Key | Type | Required | Description | | :--- | :----------------------- | :------- | :----------------------------- | | tags | [TagInfo](#taginfo-object)[] | Yes | Array of available tags. | **Tag Capping:** To prevent large responses, long-tail tag types are capped at 100 entries per type. Tags within each type are sorted by usage count (most popular first), then alphabetically. Every tag type is either a closed list of canonical values, a strict format, or one of the three free-text company types (`developer`, `publisher`, `credit`). Closed types such as `genre`, `region`, `lang` and `arcadeboard` have finite vocabularies and are returned in full, as are `year` and `rating`. The free-text types, the other format types (for example `extension`, `track`, `mameparent`, `compilation`, `gamedatabase`, `builddate`) and `search`, whose franchise and feature values run long, are capped. ##### TagInfo object | Key | Type | Required | Description | | :--- | :----- | :------- | :------------------------------------ | | tag | string | Yes | The tag value. | | type | string | Yes | The tag type (e.g., "genre", "year"). | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5d-11ef-9c7b-020304050607", "method": "media.tags", "params": { "systems": ["NES", "SNES"] } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5d-11ef-9c7b-020304050607", "result": { "tags": [ { "type": "genre", "tag": "action" }, { "type": "genre", "tag": "action:platformer" }, { "type": "search", "tag": "franchise:castlevania" } ] } } ``` ### media.tags.update **Access:** All clients. Add or remove user tags for an indexed media item, or hide a folder. Mutable tags are `user:favorite`, `user:hidden`, `user:liked`, `user:disliked` and `user:playlater`. All are installation-wide preferences available to all clients, not security restrictions. Add `user:hidden` to hide an entry; remove it to unhide. When the same tag appears in both lists, addition wins. Editing one flag preserves the others, except for the pairs the model forbids: adding `user:disliked` clears `user:liked` and `user:favorite`, and adding `user:liked` or `user:favorite` clears `user:disliked`. A request that adds both sides of such a pair at once is rejected. Deck membership tags (`user:deck:`) are read-only here and managed through the decks methods. Hidden entries disappear from normal discovery and random selection, but remain launchable through direct NFC, ZapScript, playlists, and explicit API launches. Favorites, the other user tag lists and history retain hidden entries and include the `user:hidden` tag when their current media tags are available. `includeHidden: true` on browse/search enables recovery. A folder is hidden by sending its `system` and `path` with `user:hidden` as the only tag. The path must name no indexed file and hold indexed media for that system. The hide is one preference stored against the folder's path, not a tag on each file under it, so it also covers files indexed later and its cost does not grow with the folder. The folder leaves its parent's `media.browse` listing and `media.browse.index`, and its media leave `media.search`, system counts and random selection, until `includeHidden` is set. Browsing or searching the folder's own path still works, so a client can keep a shortcut to a hidden folder. The result's `tags` holds `user:hidden` while the folder is hidden and is empty otherwise. Any other tag sent with a folder's path keeps its earlier meaning: it applies to the folder's single launch target when it has one. All flags persist in UserDB and are restored to MediaDB on reindex/rebuild by canonical system/path, like existing favorites. Moving a file does not transfer any preference; the old path's preferences remain stored. Automatic reassociation is deferred. Successful hide/unhide emits [`media.visibility`](notifications.md#mediavisibility), prompting connected clients to refresh their lists and discard old cursors. Every update that changes a flag emits [`media.tags.changed`](notifications.md#mediatagschanged) with the item's flags afterwards. #### Parameters | Key | Type | Required | Description | | :------ | :------- | :------- | :-------------------------------------------------------- | | mediaId | number | No | Media DBID to update. Cannot be mixed with system/path. | | system | string | No | System ID for path-based lookup. Required when using path. | | path | string | No | Media path for path-based lookup. Required with system. | | add | string[] | No | Tags to add, from the mutable user tags above. | | remove | string[] | No | Tags to remove, from the mutable user tags above. | Either `mediaId` or `system` plus `path` is required. At least one of `add` or `remove` is required. Search operators (`+`, `-`, `~`) are not valid in mutation requests. #### Result | Key | Type | Required | Description | | :--- | :--------------------------- | :------- | :----------------------------------- | | tags | [TagInfo](#taginfo-object)[] | Yes | Effective tags for the media item. | #### Media database busy errors While indexing, database optimization, maintenance or recovery owns the media database, the update is refused at once and nothing is stored. The response is an [error](index.md#response-errors) whose `data.category` is `busy`, the same category [`run`](#run) uses for a launch already in progress. Branch on the category, not on the message, and retry once the operation has finished ([`media`](#media) and the [`media.indexing`](notifications.md) notification report it). A running scrape does not refuse the update. | Message | Operation holding the media database | | :--------------------------------------- | :------------------------------------------ | | `media indexing is in progress` | Indexing. | | `database optimization in progress` | Optimization. | | `media database maintenance in progress` | Maintenance or recovery. | ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5d-11ef-9c7b-020304050607", "error": { "code": 1, "message": "media indexing is in progress", "data": { "category": "busy" } } } ``` [`media.meta.update`](#mediametaupdate) is refused the same way. [`media.generate`](#mediagenerate) and [`media.scrape`](#mediascrape) report `busy` too when they cannot start because one of these operations, or another index or scrape, is running; their messages also include `indexing already in progress`, `scraping already in progress` and `scraping is in progress`. A Core that predates the category sends the same messages with no `data`. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5d-11ef-9c7b-020304050607", "method": "media.tags.update", "params": { "mediaId": 42, "add": ["user:favorite"] } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5d-11ef-9c7b-020304050607", "result": { "tags": [ { "type": "user", "tag": "favorite" } ] } } ``` ### media.generate **Access:** All clients. Create a new media database index. During indexing, the server will emit [media.indexing](./notifications.md) notifications showing progress of the index. #### Parameters Optionally, an object: | Key | Type | Required | Description | | :------ | :------- | :------- | :---------------------------------------------------------------------------------- | | systems | string[] | No | List of system IDs to restrict indexing to. Other system indexes will remain as is. | | fuzzySystem | boolean | No | Enable fuzzy matching for system IDs in the `systems` array (e.g., `"snes"` matches `"SNES"`). | | rebuild | boolean | No | Discard the media database entirely and index from scratch ("fresh start"). Scraped metadata is lost and must be re-scraped; favourites and launcher overrides are preserved (they live in the user database and are re-applied after indexing). Cannot be combined with `systems`. | An omitted or `null` value parameters key is also valid and will index every system. **Selective Indexing Behavior:** - When `systems` is provided with specific system IDs, only those systems will be reindexed - The server will validate all provided system IDs and return an error if any are invalid - If all systems are specified (equivalent to no restriction), a full database rebuild will be performed for optimal performance - Selective indexing cannot be performed while database optimization is running - A request refused because indexing, scraping, optimization, maintenance or recovery is already running returns an error whose `data.category` is `busy`. See [media database busy errors](#media-database-busy-errors). - Resume functionality will validate that the system configuration hasn't changed between indexing sessions #### Result Returns `null` on success. Indexing runs in the background after the response is sent. Track progress using [media.indexing](./notifications.md) notifications. #### Examples ##### Full index request ```json { "jsonrpc": "2.0", "id": "6f20e07c-7a5e-11ef-84bb-020304050607", "method": "media.generate" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "6f20e07c-7a5e-11ef-84bb-020304050607", "result": null } ``` ##### Selective index request ```json { "jsonrpc": "2.0", "id": "7f30e17d-7a5e-11ef-85cc-020304050607", "method": "media.generate", "params": { "systems": ["NES", "SNES", "Genesis"] } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "7f30e17d-7a5e-11ef-85cc-020304050607", "result": null } ``` ### media.generate.cancel **Access:** All clients. Cancel any currently running media database indexing operation. #### Parameters None. #### Result | Key | Type | Required | Description | | :------ | :----- | :------- | :------------------------------------ | | message | string | Yes | Status message about the cancellation. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "8f40e28e-7a5e-11ef-86dd-020304050607", "method": "media.generate.cancel" } ``` ##### Response (indexing was running) ```json { "jsonrpc": "2.0", "id": "8f40e28e-7a5e-11ef-86dd-020304050607", "result": { "message": "Media indexing cancelled successfully" } } ``` ##### Response (no indexing running) ```json { "jsonrpc": "2.0", "id": "8f40e28e-7a5e-11ef-86dd-020304050607", "result": { "message": "No media indexing operation is currently running" } } ``` ### media.generate.resume **Access:** All clients. Resume media database indexing paused by Core while media is active. #### Parameters None. #### Result | Key | Type | Required | Description | | :------ | :----- | :------- | :---------- | | message | string | Yes | `Media indexing resumed` when a paused index resumes, or `Media indexing is not paused` when there is nothing to resume. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "9a51f39f-7a5e-11ef-87ee-020304050607", "method": "media.generate.resume" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "9a51f39f-7a5e-11ef-87ee-020304050607", "result": { "message": "Media indexing resumed" } } ``` ### media.active **Access:** All clients. Returns the currently active media. #### Parameters | Key | Type | Required | Description | | :--- | :----- | :------- | :---------- | | slot | string | No | Media slot to query. Use `primary` or `background`. Defaults to `primary`. | #### Result Returns an [ActiveMedia](#active-media-object) object if media is currently active, or `null` if no media is active. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "47f80537-7a5d-11ef-9c7b-020304050607", "method": "media.active" } ``` ##### Response (no active media) ```json { "jsonrpc": "2.0", "id": "47f80537-7a5d-11ef-9c7b-020304050607", "result": null } ``` ##### Response (media active) ```json { "jsonrpc": "2.0", "id": "47f80537-7a5d-11ef-9c7b-020304050607", "result": { "mediaId": 42, "started": "2024-09-24T17:49:42.938167429+08:00", "launcherId": "SNES", "systemId": "SNES", "systemName": "Super Nintendo Entertainment System", "mediaPath": "/roms/snes/Super Mario World (USA).sfc", "relativePath": "snes/Super Mario World (USA).sfc", "mediaName": "Super Mario World", "zapScript": "@SNES/Super Mario World", "launcherControls": ["load_state", "save_state", "toggle_menu"] } } ``` ##### Response (background track) ```json { "jsonrpc": "2.0", "id": "47f80537-7a5d-11ef-9c7b-020304050607", "result": { "started": "2024-09-24T17:49:42.938167429+08:00", "launcherId": "native-audio", "systemId": "Audio", "systemName": "Audio", "mediaPath": "/media/fat/Music/Album/01 Intro.mp3", "mediaName": "01 Intro", "slot": "background", "zapScript": "/media/fat/Music/Album/01 Intro.mp3", "positionMs": 20000, "durationMs": 180000, "playbackState": "playing", "launcherControls": ["fast_forward", "pause", "resume", "rewind", "stop", "toggle_pause"], "track": { "title": "Intro", "artist": "Some Artist", "album": "Some Album", "trackNumber": 1, "trackTotal": 12, "hasArt": true } } } ``` ### media.active.image **Access:** All clients. Returns the cover art of the audio track native audio is playing in a slot: the picture embedded in the track's tags, else a `cover`, `folder` or `front` image (`.jpg`, `.jpeg` or `.png`, any case) in the track's folder. The track is always the one the slot is playing; the request never names a path. Requests share the image concurrency limit and low-priority lane of [media.image](#mediaimage). #### Parameters | Key | Type | Required | Description | | :------- | :----- | :------- | :---------- | | slot | string | No | `primary`, `background` or `bg`. Defaults to `primary`. | | maxSize | number | No | Longest edge in pixels, 1 to 8192, as for `media.image`: the image is resized to fit and snapped to a standard size, so it may come back larger than asked. Omit it for the full-size image. | | delivery | string | No | `inline` (default) or `localPath`, as for `media.image`. `localPath` requires `maxSize`. | #### Result The same object as [media.image](#mediaimage), with `typeTag` `audio:embedded` for art from the track's tags or `audio:folder` for an image beside it. Errors: - `no active audio track`: nothing is playing through native audio in the slot. - `no cover art`: the track has no embedded picture and no image beside it. - `cover art is too large`: the art is larger than the platform's image limit. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "47f80537-7a5d-11ef-9c7b-020304050607", "method": "media.active.image", "params": { "slot": "background", "maxSize": 256 } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "47f80537-7a5d-11ef-9c7b-020304050607", "result": { "extension": "webp", "contentType": "image/webp", "data": "UklGRh4AAABXRUJQVlA4...", "delivery": "inline", "typeTag": "audio:embedded" } } ``` ### media.active.update **Access:** All clients. Update the currently active media information. #### Parameters An object: | Key | Type | Required | Description | | :-------- | :----- | :------- | :-------------------------- | | systemId | string | Yes | ID of the system. | | mediaPath | string | Yes | Path to the media file. | | mediaName | string | Yes | Display name of the media. | #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "47f80537-7a5d-11ef-9c7b-020304050607", "method": "media.active.update", "params": { "systemId": "SNES", "mediaPath": "/roms/snes/game.sfc", "mediaName": "Game" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "47f80537-7a5d-11ef-9c7b-020304050607", "result": null } ``` ### media.history.latest **Access:** All clients. Return the most recent played media entry from the user database only. This is intended for startup paths that need the last played game as quickly as possible, without media database enrichment. This method does not return tags, metadata, media IDs, ZapScript, pagination, end time, or play time. #### Parameters None. Empty params may be omitted or sent as `{}`. #### Result | Key | Type | Required | Description | | :---- | :----------------------------------------------------------- | :------- | :------------------------------------------------------------ | | entry | [MediaHistoryLatestEntry](#media-history-latest-entry-object) | Yes | Most recent media play history entry, or `null` when none exists. | ##### Media history latest entry object | Key | Type | Required | Description | | :--------- | :----- | :------- | :---------------------------------------------- | | systemId | string | Yes | ID of the system. | | systemName | string | Yes | Display name of the system from the history row. | | mediaName | string | Yes | Display name of the media from the history row. | | mediaPath | string | Yes | Path to the media file from the history row. | | relativePath | string | No | Launcher-relative convenience path, when it can be derived. Not a stable media identity. | | launcherId | string | Yes | ID of the launcher used. | | startedAt | string | Yes | Timestamp when media started in RFC3339 format. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "9f2c6a52-7a5d-11ef-9c7b-020304050607", "method": "media.history.latest" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "9f2c6a52-7a5d-11ef-9c7b-020304050607", "result": { "entry": { "systemId": "SNES", "systemName": "Super Nintendo Entertainment System", "mediaName": "Super Mario World", "mediaPath": "/roms/snes/Super Mario World (USA).sfc", "relativePath": "SNES/Super Mario World (USA).sfc", "launcherId": "SNES", "startedAt": "2025-01-22T14:30:00Z" } } } ``` ### media.history **Access:** All clients. Return paginated media play history. Set `distinctMedia` to return only the newest session for each `(systemId, mediaPath)` identity, which is useful for recents grids. #### Parameters Optionally, an object: | Key | Type | Required | Description | | :------------ | :------- | :------- | :---------------------------------------------------------------------------------------------- | | limit | number | No | Maximum number of entries to return. Default is 25, maximum is 100. | | cursor | string | No | Cursor for pagination. Omit for first page, use `nextCursor` from previous response for subsequent pages with the same filters and `distinctMedia` value. | | systems | string[] | No | Filter to one or more system IDs (e.g., `["SNES", "NES"]`). | | fuzzySystem | boolean | No | Enable fuzzy matching for system IDs. | | distinctMedia | boolean | No | Return the newest session for each unique `(systemId, mediaPath)` pair. Each page contains up to `limit` unique media entries. Default is `false`. | #### Result | Key | Type | Required | Description | | :--------- | :--------------------------------------------------- | :------- | :--------------------------------------- | | entries | [MediaHistoryEntry](#media-history-entry-object)[] | Yes | A list of media play history entries. | | pagination | [Pagination](#pagination-object) | No | Pagination information for cursor-based navigation. Only present when entries are returned. | ##### Media history entry object | Key | Type | Required | Description | | :--------- | :----- | :------- | :----------------------------------------------------- | | mediaId | number | No | Opaque media database row ID for efficient follow-up `media.meta` and `media.image` requests. Omitted when the history path cannot be resolved in the current media database. | | systemId | string | Yes | ID of the system. | | systemName | string | Yes | Display name of the system. | | mediaName | string | Yes | Display name of the media. | | mediaPath | string | Yes | Path to the media file. | | relativePath | string | No | Launcher-relative convenience path, when it can be derived. Not a stable media identity. | | zapScript | string | No | ZapScript command to launch this media item, in the same form `media.search` reports. Omitted when the history path cannot be resolved in the current media database. | | hasCover | boolean | Yes | Whether media-level or title-level image properties are available. | | coverColor | string | No | Average colour of the cover thumbnail as `#rrggbb`, for a placeholder while the image loads. Omitted until Core has built a thumbnail for the media through `media.image` with a `maxSize`. | | launcherId | string | Yes | ID of the launcher used. | | startedAt | string | Yes | Timestamp when media started in RFC3339 format. | | endedAt | string | No | Timestamp when media stopped in RFC3339 format. Omitted if media is still active. | | playTime | number | Yes | Duration of the play session in seconds. | | sessionSource | string | Yes | How the session was timed: `active_media` (Core's own launch lifecycle), `foreground_events` (host foreground evidence, with user-granted permission) or `host_return` (until the launcher came back, without that permission). | | sessionConfidence | string | Yes | `unspecified` for a row predating this distinction, `exact` for measured foreground time, `approximate` for a `host_return` estimate that never proves the game was played, or `provisional` for a `foreground_events` launch not yet confirmed (no `endedAt`, `playTime` 0; it becomes `exact` or is withdrawn). | | tags | [TagInfo](#taginfo-object)[] | No | Tags for the resolved media, merged from file-level and title-level tags exactly as `media.search` returns them. An empty array means the media is indexed but has no tags. Omitted when `mediaId` is omitted or when media database enrichment fails or times out. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5d-11ef-9c7b-020304050607", "method": "media.history", "params": { "limit": 10, "distinctMedia": true } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5d-11ef-9c7b-020304050607", "result": { "entries": [ { "mediaId": 42, "systemId": "SNES", "systemName": "Super Nintendo Entertainment System", "mediaName": "Super Mario World", "mediaPath": "/roms/snes/Super Mario World (USA).sfc", "relativePath": "snes/Super Mario World (USA).sfc", "zapScript": "@SNES/Super Mario World", "hasCover": true, "launcherId": "SNES", "startedAt": "2025-01-22T14:30:00Z", "endedAt": "2025-01-22T15:15:30Z", "playTime": 2730, "sessionSource": "foreground_events", "sessionConfidence": "exact", "tags": [ { "tag": "favorite", "type": "user" }, { "tag": "action:platformer", "type": "genre" } ] } ], "pagination": { "hasNextPage": false, "pageSize": 10 } } } ``` ### media.history.top **Access:** All clients. Return aggregated media play history grouped by game, sorted by total play time descending. Useful for "most played" displays. #### Parameters Optionally, an object: | Key | Type | Required | Description | | :---------- | :------- | :------- | :---------------------------------------------------------------------------------------------- | | limit | number | No | Maximum number of entries to return. Default is 25, maximum is 100. | | systems | string[] | No | Filter to one or more system IDs (e.g., `["SNES", "NES"]`). | | fuzzySystem | boolean | No | Enable fuzzy matching for system IDs. | | since | string | No | Only count sessions starting after this RFC3339 timestamp. | #### Result | Key | Type | Required | Description | | :------ | :----------------------------------------------------------- | :------- | :--------------------------------------- | | entries | [MediaHistoryTopEntry](#media-history-top-entry-object)[] | Yes | A ranked list of games by total play time. | ##### Media history top entry object | Key | Type | Required | Description | | :------------ | :----- | :------- | :----------------------------------------------------- | | mediaId | number | No | Opaque media database row ID for efficient follow-up `media.meta` and `media.image` requests. Omitted when the history path cannot be resolved in the current media database. | | systemId | string | Yes | ID of the system. | | systemName | string | Yes | Display name of the system. | | mediaName | string | Yes | Display name of the media. | | mediaPath | string | Yes | Path to the media file (from most recent session). | | relativePath | string | No | Launcher-relative convenience path, when it can be derived. Not a stable media identity. | | zapScript | string | No | ZapScript command to launch this media item, in the same form `media.search` reports. Omitted when the history path cannot be resolved in the current media database. | | totalPlayTime | number | Yes | Total play time across all sessions in seconds. | | sessionCount | number | Yes | Number of play sessions. | | lastPlayedAt | string | Yes | Timestamp of the most recent session in RFC3339 format. | | tags | [TagInfo](#taginfo-object)[] | No | Tags for the resolved media, merged from file-level and title-level tags exactly as `media.search` returns them. An empty array means the media is indexed but has no tags. Omitted when `mediaId` is omitted or when media database enrichment fails or times out. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "b2c3d4e5-8b6e-12f0-ad8c-030405060708", "method": "media.history.top", "params": { "limit": 5, "systems": ["SNES"] } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "b2c3d4e5-8b6e-12f0-ad8c-030405060708", "result": { "entries": [ { "mediaId": 42, "systemId": "SNES", "systemName": "Super Nintendo Entertainment System", "mediaName": "Super Mario World", "mediaPath": "/roms/snes/Super Mario World (USA).sfc", "relativePath": "snes/Super Mario World (USA).sfc", "zapScript": "@SNES/Super Mario World", "totalPlayTime": 7200, "sessionCount": 12, "lastPlayedAt": "2026-02-14T20:30:00Z", "tags": [ { "tag": "favorite", "type": "user" }, { "tag": "action:platformer", "type": "genre" } ] } ] } } ``` ### media.lookup.candidates Returns up to five ranked canonical title candidates for an approximate name in **one system**. This is title discovery, not media selection: pass a selected candidate's `systemId` and `name` to `media.lookup` for file selection and enrichment. **Parameters** | Key | Type | Required | Description | | --- | --- | --- | --- | | system | string | Yes | One canonical system ID; never a list or an all-systems search. | | name | string | Yes | Approximate title, 1–256 Unicode characters. Whitespace-only names and names that normalize to an empty slug are rejected. | | fuzzySystem | boolean | No | Resolve system names/aliases instead of requiring a canonical ID. Default `false`, matching `media.lookup`. | | maxResults | integer | No | Maximum number of candidates, 1–5. Default `5`; out-of-range values are rejected. | **Result** `{"candidates": [...]}`; an empty array means no eligible title met the match threshold. Database failures and canceled requests remain errors, not empty results. Each candidate contains only: | Key | Type | Description | | --- | --- | --- | | systemId | string | Canonical system ID. | | name | string | Canonical indexed title, deduplicated within the system. | | rank | integer | One-based rank; results are ordered by rank. | | matchType | string | Stable coarse enum: `exact`, `secondary`, or `fuzzy`. | | confidence | number | Advisory ranking evidence, not a probability or a stable client threshold contract. | Exact normalized primary-title evidence ranks before exact secondary-title evidence. If any eligible primary or secondary exact matches exist, only those matches are returned: results are never padded with fuzzy matches to reach `maxResults`. Fuzzy matching runs only when neither exact class produces an eligible result, and reuses title normalization and the existing length/word-count prefilter, token-order matching, and typo threshold. Within an evidence class, ranking uses confidence, edit-distance tie-breaking for fuzzy matches, then canonical name and an internal identity tie-breaker. Internal algorithm names are not API enums. These candidates need not reproduce the launch resolver's prefix, progressive-trimming, tag preference, or media-selection fallbacks. A title is eligible only if at least one indexed media entry is present and not user-hidden. Hidden/missing variants do not suppress another eligible variant. Hidden state is always excluded; there is no `includeHidden` override. Authorization matches ordinary media discovery; this method grants no launch or profile-management authority. Results never contain paths, media IDs, tags, artwork, or ZapScript, and requests neither launch nor update history or lookup/resolution caches. Results describe the **current MediaDB incarnation**, not a durable catalog snapshot. A request pins one database connection and fails with a retryable error if a fresh-start rebuild replaces that database before the final generation check. Cached IDs from a discarded database are not used against its replacement. Ordinary indexing and hide/unhide changes may become visible between read statements; exact matches are read directly from indexed SQL without waiting for a shared slug cache refresh, while fuzzy discovery can lag behind ordinary indexing until that refresh. The later `media.lookup` resolves against its own then-current state, so candidates do not reserve a file or guarantee later availability. ```json { "jsonrpc": "2.0", "id": 1, "method": "media.lookup.candidates", "params": {"system": "NES", "name": "Metriod"} } ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "candidates": [ {"systemId": "NES", "name": "Metroid", "rank": 1, "matchType": "fuzzy", "confidence": 0.96} ] } } ``` The example confidence is illustrative; clients should present ordered candidates, not hard-code score cutoffs. ### media.lookup **Access:** All clients. Resolve a game name and system to a media database match. Given a system ID and game name, searches the media database for the best matching title. Uses fuzzy matching to handle minor differences in naming. Returns `null` for the match when no title is found or confidence is too low. #### Parameters An object: | Key | Type | Required | Description | | :---------- | :------ | :------- | :------------------------------------------------------------------------------------- | | system | string | Yes | System ID to search within (e.g., `"SNES"`, `"Genesis"`). | | name | string | Yes | Game name to look up. | | fuzzySystem | boolean | No | Enable fuzzy matching for the system ID (e.g., `"snes"` matches `"SNES"`). | #### Result | Key | Type | Required | Description | | :---- | :------------------------------------------- | :------- | :----------------------------------------------------- | | match | [MediaLookupMatch](#media-lookup-match-object) | No | The best matching media entry, or `null` if no match found. | ##### Media lookup match object | Key | Type | Required | Description | | :--------- | :--------------------------- | :------- | :------------------------------------------------------------------------------------------ | | mediaId | number | No | Opaque media database row ID for efficient follow-up `media.meta` and `media.image` requests. | | system | [System](#system-object) | Yes | System the media was found in. | | name | string | Yes | Display name of the matched media. | | path | string | Yes | Path to the media file. | | relativePath | string | No | Launcher-relative convenience path, when it can be derived. Not a stable media identity. | | zapScript | string | Yes | ZapScript command to launch this media item. | | tags | [TagInfo](#taginfo-object)[] | Yes | Array of tags associated with this media item. | | confidence | number | Yes | Match confidence score from 0.0 to 1.0. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "b2c3d4e5-7a5d-11ef-9c7b-020304050607", "method": "media.lookup", "params": { "system": "SNES", "name": "Super Mario World" } } ``` ##### Response (match found) ```json { "jsonrpc": "2.0", "id": "b2c3d4e5-7a5d-11ef-9c7b-020304050607", "result": { "match": { "mediaId": 42, "system": { "id": "SNES", "name": "Super Nintendo Entertainment System", "category": "Console", "categories": ["Console"], "releaseDate": "1990-11-21", "manufacturer": "Nintendo" }, "name": "Super Mario World", "path": "/roms/snes/Super Mario World (USA).sfc", "relativePath": "SNES/Super Mario World (USA).sfc", "zapScript": "@SNES/Super Mario World", "tags": [ { "tag": "action:platformer", "type": "genre" }, { "tag": "1990", "type": "year" } ], "confidence": 0.95 } } } ``` ##### Response (no match) ```json { "jsonrpc": "2.0", "id": "b2c3d4e5-7a5d-11ef-9c7b-020304050607", "result": { "match": null } } ``` ### media.meta **Access:** All clients. Return the full metadata graph for one indexed media row, including its title, system, tags, and scraped properties. Use this when a client has a search, browse, or lookup result and needs all metadata attached to that row. Identify media by the result's `mediaId` when available, or by `system.id` and canonical `path`. Launcher-relative paths in the `system/path` shape are accepted as a compatibility fallback when they resolve to exactly one indexed media row. Properties are separated by scope: `media.properties` applies to the specific ROM/file row, and `media.title.properties` applies to the shared title. #### Parameters An object: | Key | Type | Required | Description | | :----- | :----- | :------- | :---------------------------------- | | mediaId | number | No | Opaque media database row ID from search, browse, or lookup. With `system` and `path`, the media a directory entry launches; see below. | | system | string | No | System ID for the media row. Required when `mediaId` is omitted. | | path | string | No | Canonical indexed media path, or a directory path. Required when `mediaId` is omitted. | | items | object[] | No | Batch request items. Each item uses `mediaId`, `system`/`path`, or all three. Maximum 100 items. Cannot be mixed with top-level media ref fields. | A collapsed `directory` entry from `media.browse` is requested with its `mediaId`, `system`, and `path` together. The result describes that `mediaId`, which must be the path itself or a file directly inside it; otherwise the request fails with `media not in path`. Given a directory path alone, Core resolves it to the media it collapses to, which for a multi-disc folder is the first disc. When `path` names a directory, `media.availableImageTypes` also lists the image types of the directory's own artwork, which `media.image` serves for the same request ahead of the media's. That artwork is not included in `media.properties`. Single requests return the existing single `media` response shape. Batch requests return `{ "items": [...] }` in input order. Each batch item contains either `media` or `error`, so one missing media row does not fail the whole batch. #### Result | Key | Type | Required | Description | | :---- | :------------------------------------ | :------- | :--------------------------- | | media | [MediaMeta](#media-meta-object) | Yes | Metadata for the media row. | ##### Media meta object | Key | Type | Required | Description | | :--------- | :-------------------------------------- | :------- | :---------------------------------------------------- | | path | string | Yes | Media file path. | | relativePath | string | No | Launcher-relative convenience path, when it can be derived. Not a stable media identity. | | zapScript | string | No | ZapScript command to launch this media item, in the same form `media.search` reports. Omitted for a missing media row. | | parentDir | string | Yes | Parent directory stored for the media row. | | isMissing | boolean | Yes | Whether the indexed file is currently missing. | | tags | [TagInfo](#taginfo-object)[] | Yes | ROM-level tags for this media row. | | properties | object | Yes | ROM-level properties keyed by canonical type tag. | | launcherOverride | string | No | Launcher ID stored for this media row, mirrored from `property:launcher-override` in `properties`. When present, Core uses it for title, search, path, random, and history launches unless ZapScript includes an explicit `launcher` argument. | | availableImageTypes | string[] | No | Image types `media.image` can return from this media row, plus the requested directory's own artwork types. Omitted when there are none. | | userEdited | string[] | No | Images of this media row the user set by hand with [`media.meta.update`](#mediametaupdate), as `images.`. Omitted when there are none. | | title | [MediaMetaTitle](#media-meta-title-object) | Yes | Shared title metadata for this media row. | ##### Media meta title object | Key | Type | Required | Description | | :------------ | :--------------------------- | :------- | :----------------------------------------------- | | slug | string | Yes | Primary normalized title slug. | | secondarySlug | string | No | Secondary title slug, when available. | | name | string | Yes | Display title. | | slugLength | number | Yes | Character length of the primary slug. | | slugWordCount | number | Yes | Word count of the primary slug. | | system | object | Yes | Stored system object with `id` and `name`. | | tags | [TagInfo](#taginfo-object)[] | Yes | Title-level tags shared by matching media rows. | | properties | object | Yes | Title-level properties keyed by canonical type tag. | | availableImageTypes | string[] | No | Image types `media.image` can return from title-level properties. Omitted when there are none. | | userEdited | string[] | No | Title fields the user set by hand with [`media.meta.update`](#mediametaupdate): `name`, `description` and `tags.`. Omitted when there are none. | ##### Media meta property object | Key | Type | Required | Description | | :---------- | :----- | :------- | :--------------------------------------------------------------------- | | text | string | Yes | Text value or source path for the property. Images Core downloaded are given relative to Core's image folder as `images://`, for example `images://libretro//Named_Boxarts/.png`; fetch them with `media.image`. | | contentType | string | Yes | MIME type for binary-backed properties, empty for text-only values. | | extension | string | No | File extension without a dot, derived from MIME type or source path. | | blobSize | number | No | Size in bytes for binary-backed properties. | Binary property data is not returned by `media.meta`. Use `media.image` to fetch image bytes and `media.asset` to fetch supported file-backed assets. Property keys are canonical type tags such as `property:description`, `property:image-image`, or `property:manual`. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "d4e5f6a7-7a5d-11ef-9c7b-020304050607", "method": "media.meta", "params": { "system": "SNES", "path": "/roms/snes/Super Mario World.sfc" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "d4e5f6a7-7a5d-11ef-9c7b-020304050607", "result": { "media": { "path": "/roms/snes/Super Mario World.sfc", "relativePath": "SNES/Super Mario World.sfc", "zapScript": "@SNES/Super Mario World", "parentDir": "/roms/snes", "isMissing": false, "tags": [ {"type": "region", "tag": "us"} ], "properties": { "property:launcher-override": { "text": "RetroArch", "contentType": "" } }, "launcherOverride": "RetroArch", "title": { "slug": "super mario world", "name": "Super Mario World", "slugLength": 17, "slugWordCount": 3, "system": { "id": "SNES", "name": "Super Nintendo Entertainment System" }, "tags": [ {"type": "developer", "tag": "nintendo"}, {"type": "genre", "tag": "action:platformer"} ], "properties": { "property:description": { "text": "Mario's dinosaur friend Yoshi makes his debut.", "contentType": "" } } } } } } ``` ##### Batch Request ```json { "jsonrpc": "2.0", "id": "d4e5f6a7-7a5d-11ef-9c7b-020304050608", "method": "media.meta", "params": { "items": [ {"mediaId": 42}, {"system": "SNES", "path": "/roms/snes/Super Metroid.sfc"} ] } } ``` ### media.meta.update **Access:** All clients. An image named by an absolute path on the Core host needs localhost or admin; one picked with [`files.browse`](#filesbrowse) needs localhost or any authenticated client. Update writable metadata fields for one indexed media row, then return the same response shape as [`media.meta`](#mediameta). A patch can set a per-media launcher override and edit the game's metadata by hand: its name, description, common tags and images. Every field is optional; a field left out is untouched, and `null` resets a field. Edited metadata is the user's own. Core keeps it in the user database and copies it into the media database, so it survives a reindex, a media database rebuild and a scrape, including a forced one. [`media.meta`](#mediameta) lists the fields that hold a user value in `userEdited`. - **Name, description and tags belong to the title**, so every version of the game shows them. The name is what browse and search show and sort by; the slug, and so launching by title, still follows the filename. - **Images belong to the one file.** Other versions of the game keep their own art. - **Resetting a field** removes the user's value. A name goes back to the one read from the filename. Any other field is left for the scrapers, and Core starts a scrape of that one file with every scraper that fills missing fields. - **Images are stored as files** in Core's data directory, never in the user database and never in a backup. A restore onto another device brings back the text and tags; a game whose image file is not there shows its scraped art. Launcher selection order is: 1. Explicit `launcher` advanced argument in ZapScript. 2. Per-media `launcherOverride` stored with `media.meta.update`. 3. System default launcher from configuration. 4. Normal launcher matching. #### Parameters An object identifying the media row by `mediaId` or by `system` and canonical `path`. | Key | Type | Required | Description | | :------ | :----- | :------- | :---------- | | mediaId | number | No | Opaque media database row ID from search, browse, or lookup. Cannot be mixed with `system`/`path`. | | system | string | No | System ID for the media row. Required when `mediaId` is omitted. | | path | string | No | Canonical indexed media path. Required when `mediaId` is omitted. | | media | object | Yes | Patch object with at least one field. Unknown fields are rejected. | ##### Media patch object | Key | Type | Required | Description | | :--------------- | :----------- | :------- | :---------- | | launcherOverride | string\|null | No | Launcher ID to use for this media row, matched case-insensitively and stored with canonical casing. Core validates the launcher exists and supports the row's system. Use `null` to clear it. Empty strings are rejected. | | name | string\|null | No | The title's display name, 1 to 255 characters after trimming, with no control characters. `null` puts back the name read from the filename. | | description | string\|null | No | The title's description, up to 10,000 characters. `null` resets it. | | tags | object | No | Tag type to a list of values, or `null` to reset that type. The types are `developer`, `publisher`, `year`, `genre` and `players`. A list is the full set the title carries for the type and replaces whatever was there; an empty list is a title with none. `year` and other single-value types take one value. `genre`, `players` and `year` values must be ones Core knows; `developer` and `publisher` take any name. | | images | object | No | Image kind to an [image source](#media-image-source-object), or `null` to reset that image. The kinds are `image`, `boxart`, `boxart3d`, `boxartside`, `boxartback`, `screenshot`, `thumbnail`, `marquee`, `wheel`, `fanart`, `titleshot` and `map`, each the `property:image-` property of the file. | ##### Media image source object An image must be a JPEG, PNG, GIF or WebP of at most 10 MiB. Core copies it into its own folder. | Key | Type | Required | Description | | :------- | :----- | :------- | :---------- | | kind | string | Yes | `file` for an image on the Core host by absolute path, `browse` for one picked with [`files.browse`](#filesbrowse), `upload` for a finished [upload](#uploads). | | path | string | No | For `file`, the absolute path of the image on the Core host; `file` needs localhost or admin. For `browse`, the entry's `path` under its root. | | root | string | No | ID of the browse root the image is under. Required for `browse`. | | uploadId | string | No | ID of a finished upload of purpose `media-image`. Required for `upload`. The upload is used up. | #### Result | Key | Type | Required | Description | | :---- | :------------------------------ | :------- | :-------------------------- | | media | [MediaMeta](#media-meta-object) | Yes | Updated metadata for row. | While indexing, database optimization, maintenance or recovery owns the media database, the update is refused with an error whose `data.category` is `busy`. See [media database busy errors](#media-database-busy-errors). #### Example ##### Set override ```json { "jsonrpc": "2.0", "id": 1, "method": "media.meta.update", "params": { "mediaId": 42, "media": { "launcherOverride": "RetroArch" } } } ``` ##### Clear override ```json { "jsonrpc": "2.0", "id": 2, "method": "media.meta.update", "params": { "system": "SNES", "path": "/roms/snes/Super Mario World.sfc", "media": { "launcherOverride": null } } } ``` ##### Edit metadata ```json { "jsonrpc": "2.0", "id": 3, "method": "media.meta.update", "params": { "mediaId": 42, "media": { "name": "Chrono Trigger", "description": "A group of adventurers travels through time.", "tags": { "genre": ["rpg"], "year": ["1995"], "developer": ["Square"] }, "images": { "boxart": { "kind": "file", "path": "/media/usb0/covers/chrono-trigger.png" } } } } } ``` ##### Reset fields ```json { "jsonrpc": "2.0", "id": 4, "method": "media.meta.update", "params": { "mediaId": 42, "media": { "name": null, "tags": { "genre": null }, "images": { "boxart": null } } } } ``` ### media.asset **Access:** All clients. Return one bounded base64 chunk from an allowlisted file-backed property associated with indexed media. Initial support is `assetType: "manual"`, which resolves `property:manual` and accepts only regular PDF files within trusted media or scraper roots. `video` and other assets are not currently supported. Source paths and basenames are never returned. Each request is independent. Start with `offset: 0`, then request `nextOffset` with the exact `etag` from the preceding response until `complete` is `true`. Assets no larger than one requested chunk return with `complete: true` in first response; clients must stop when `complete` is true. This pull model keeps memory and WebSocket messages bounded and gives clients natural backpressure. If an asset changes between chunks, Core rejects the continuation; restart from offset zero. Asset resolution follows media metadata precedence: primary media property, equivalent media aliases, then title property. #### Parameters An object identifying a media row by `mediaId` or by `(system, path)`. | Key | Type | Required | Description | | :-------- | :----- | :------- | :---------- | | mediaId | number | No | Opaque media database row ID from search, browse, or lookup. Cannot be mixed with `system`/`path`. | | system | string | No | System ID. Required when `mediaId` is omitted. | | path | string | No | Canonical indexed media path. Required when `mediaId` is omitted. | | assetType | string | Yes | Allowlisted asset type. Currently only `manual`. Raw property tags are not accepted. | | offset | number | No | Zero-based raw byte offset. Defaults to `0`. Nonzero offsets require `etag`. An offset equal to `size` returns an empty complete chunk; larger offsets are rejected. | | length | number | No | Requested raw bytes. Defaults to and cannot exceed 131072 (128 KiB). | | etag | string | No | Opaque asset version from a prior response. Required when `offset` is nonzero. | #### Result | Key | Type | Required | Description | | :---------- | :------ | :------- | :---------- | | assetType | string | Yes | Resolved allowlisted asset type. | | typeTag | string | Yes | Canonical matched property tag; `property:manual` for manuals. | | contentType | string | Yes | Validated MIME type; `application/pdf` for manuals. | | extension | string | Yes | Validated extension without a dot; `pdf` for manuals. | | size | number | Yes | Total raw asset size in bytes. | | etag | string | Yes | Opaque asset version. Send unchanged on continuation requests. | | offset | number | Yes | Raw byte offset returned by this response. | | length | number | Yes | Actual raw bytes in `data`. May be smaller than requested at EOF. | | data | string | Yes | Base64-encoded chunk bytes. Empty at exact EOF. | | nextOffset | number | No | Offset for next request. Omitted when `complete` is true. | | complete | boolean | Yes | Whether this response reaches asset EOF. | #### Example ##### Initial request ```json { "jsonrpc": "2.0", "id": 1, "method": "media.asset", "params": { "mediaId": 123, "assetType": "manual", "length": 131072 } } ``` ##### Partial response ```json { "jsonrpc": "2.0", "id": 1, "result": { "assetType": "manual", "typeTag": "property:manual", "contentType": "application/pdf", "extension": "pdf", "size": 7340032, "etag": "43e47c399d35d8be...", "offset": 0, "length": 131072, "data": "JVBERi0xLjcK...", "nextOffset": 131072, "complete": false } } ``` ##### Continuation request ```json { "jsonrpc": "2.0", "id": 2, "method": "media.asset", "params": { "mediaId": 123, "assetType": "manual", "offset": 131072, "length": 131072, "etag": "43e47c399d35d8be..." } } ``` ### media.image **Access:** All clients. Return the best matching image for one indexed media row or indexed directory. Inline base64 delivery remains default. Clients can explicitly request a transient path to a Core-owned cached thumbnail. For path requests, `media.image` preserves exact-media behavior first, then checks path-keyed directory properties, then tries existing launcher-relative and singleton media fallbacks. A request with `mediaId`, `system`, and `path` together names a collapsed directory entry and the media it launches: Core checks the directory's own properties, then that media's and its title's, then the media the path alone resolves to, such as a multi-disc folder's first disc. The `mediaId` must be the path itself or a file directly inside it; otherwise the request fails with `media not in path`. Within media results it checks each requested image type against media-level properties before title-level properties. Directory properties follow the same requested type order. If a stored media file path no longer exists, the stale property is removed and lookup continues; stale directory paths remain until the next completed `media-folder` snapshot. #### Parameters An object identifying a media row by `mediaId`, media/directory content by `(system, path)`, or a directory entry and its launch target by all three. Canonical indexed paths are preferred. Directory artwork requires the directory's exact indexed path. Launcher-relative paths in the `system/path` shape are accepted as a compatibility fallback when they resolve to exactly one indexed media row. | Key | Type | Required | Description | | :--------- | :------- | :------- | :-------------------------------------------------------------------------- | | mediaId | number | No | Opaque media database row ID from search, browse, or lookup. With `system` and `path`, the media a directory entry launches. | | system | string | No | System ID. Required when `mediaId` is omitted. | | path | string | No | Canonical indexed media or directory path. Required when `mediaId` is omitted. | | imageTypes | string[] | No | Image type preference order. Defaults to `image`, `thumbnail`, `boxart`, `boxart3d`, `screenshot`, `wheel`, `titleshot`, `map`, `marquee`, `fanart`. | | maxSize | number | No | Longest-edge size hint in pixels. When set, the server resizes the image to fit a `maxSize`×`maxSize` box and caches the result; omit it for the full-size image. Required for `localPath` delivery. | | delivery | string | No | `inline` (default) or `localPath`. `localPath` requires a positive `maxSize` and returns a path on the Core host. | Supported image type values are `image`, `thumbnail`, `boxart`, `boxart3d`, `boxartside`, `boxartback`, `screenshot`, `wheel`, `titleshot`, `map`, `marquee`, and `fanart`. They resolve to canonical property tags such as `property:image-image` and `property:image-boxart`. Resizing is intended for grid and preview views where transferring and holding full-size art is expensive. `maxSize` is snapped up to the nearest of a small set of standard tiers (`32`, `64`, `128`, `256`, `512`, `768`) server-side. The returned image is **never larger than the snapped tier and never larger than the source**: when the source already fits the tier it is returned at its native dimensions, so the result may still be larger than the exact `maxSize` you asked for. Request your true display size (logical size × pixel ratio) and downscale to the final size on the client. The snapped tiers bound how many resized variants are cached per image. Output that had to be scaled down is re-encoded as WebP (lossy, alpha preserved) regardless of source format, and cached on disk so repeat requests are cheap. A source that already fits the box is re-encoded as WebP too when it is larger than 64 KiB, so a near-native request for large art still gets the smaller WebP. The original bytes and content type are returned instead when the source already fits the box and is at most 64 KiB (the encode costs far more than the few kilobytes it would save on constrained devices), when WebP would not shrink them (already-compact sources), when `maxSize` is omitted/non-positive (full size), or when the source cannot be decoded. A resized request can therefore return `image/jpeg` or `image/png` as well as `image/webp`: read `contentType` rather than assuming WebP. The same applies to `localPath` delivery, where the cached file keeps the original's extension. When a resized thumbnail is built for a request whose image type preference list has more than one entry, Core records the image type it resolved to and the thumbnail's average colour. Later requests, including after a restart, are then served from the thumbnail cache without reading the original artwork, and list results (`media.browse`, `media.search`, `media.history`) report the colour as `coverColor`. A request for a single image type does not change the recorded cover. The records are cleared together with the thumbnail cache after indexing or scraping changes artwork. `localPath` never returns an original scraper or media path. Core resolves image semantics, materializes its own bounded thumbnail cache artifact, and returns that path. Path delivery is available to any client that explicitly requests it, regardless of peer locality or Core platform; remote callers are responsible for having an appropriate shared-filesystem view of the Core host path. Treat the path as opaque, transient, and nonportable: read it immediately, never persist it or derive neighboring paths, and retry once with `delivery: "inline"` if the file is inaccessible or disappears before it is opened. If cache materialization fails, Core can safely return `delivery: "inline"` in the same response. #### Result | Key | Type | Required | Description | | :---------- | :----- | :------- | :------------------------------------------- | | delivery | string | Yes | Actual delivery used: `inline` or `localPath`. Clients must inspect this field because a requested local path can fall back inline. | | contentType | string | Yes | MIME type of the returned image data. | | extension | string | No | File extension without a dot, derived from MIME type or source path. | | data | string | No | Base64-encoded image bytes. Present for `inline` delivery. | | localPath | string | No | Absolute, opaque Core-host path to a cached thumbnail. Present for `localPath` delivery. | | typeTag | string | Yes | Canonical property tag that matched. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "e5f6a7b8-7a5d-11ef-9c7b-020304050607", "method": "media.image", "params": { "system": "SNES", "path": "/roms/snes/Super Mario World.sfc", "imageTypes": ["boxart", "image"], "maxSize": 512 } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "e5f6a7b8-7a5d-11ef-9c7b-020304050607", "result": { "delivery": "inline", "contentType": "image/webp", "extension": "webp", "data": "UklGRiQAAABXRUJQVlA4...", "typeTag": "property:image-boxart" } } ``` ##### Local-path request ```json { "jsonrpc": "2.0", "id": "e5f6a7b8-7a5d-11ef-9c7b-020304050607", "method": "media.image", "params": { "mediaId": 123, "imageTypes": ["boxart"], "maxSize": 256, "delivery": "localPath" } } ``` ##### Local-path response ```json { "jsonrpc": "2.0", "id": "e5f6a7b8-7a5d-11ef-9c7b-020304050607", "result": { "delivery": "localPath", "contentType": "image/webp", "extension": "webp", "localPath": "/media/fat/zaparoo/images/thumbs/v3/4f/4f2a9c1e0b7d.webp", "typeTag": "property:image-boxart" } } ``` ### scrapers **Access:** All clients. List all registered metadata scrapers. #### Parameters None. #### Result | Key | Type | Required | Description | | :------- | :----------------------------------- | :------- | :---------------------------------- | | scrapers | [ScraperInfo](#scraper-info-object)[] | Yes | Registered scraper implementations. | ##### Scraper info object | Key | Type | Required | Description | | :--------------- | :------- | :------- | :----------------------------------------------------------------------- | | id | string | Yes | Stable scraper ID used by `media.scrape`. | | name | string | Yes | Human-readable scraper name. | | supportedSystems | string[] | Yes | Supported system IDs. Empty means the scraper can run against all systems. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "f6a7b8c9-7a5d-11ef-9c7b-020304050607", "method": "scrapers" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "f6a7b8c9-7a5d-11ef-9c7b-020304050607", "result": { "scrapers": [ { "id": "gamelist.xml", "name": "ES gamelist.xml", "supportedSystems": [] }, { "id": "media-folder", "name": "ES media folders", "supportedSystems": [] }, { "id": "mister-docs", "name": "MiSTer docs databases", "supportedSystems": [] } ] } } ``` ### media.scrape **Access:** All clients. Start a metadata scraper run in the background. Scraping enriches existing MediaDB records only. It does not create media rows; run `media.generate` first so the filesystem scanner has indexed the library. Scraping and media indexing are mutually exclusive, and only one scraper can run at a time. Progress is reported with [media.scraping](./notifications.md#mediascraping) notifications and can be queried with `media.scrape.status`. Scraping pauses while media is running and resumes automatically when playback stops. #### Parameters An object: | Key | Type | Required | Description | | :-------- | :------- | :------- | :-------------------------------------------------------------------------- | | scraperId | string | Yes | Scraper ID from the `scrapers` method, for example `gamelist.xml`. | | systems | string[] | No | System IDs to scrape. Omit or pass an empty array to scrape all eligible systems. Cannot be combined with `scope`. | | scope | object | No | Select one indexed media item or one directory subtree; see below. | | force | boolean | No | Re-scrape records that already have this scraper's sentinel tag, within the selected scope. Default is false. | #### Scope Without `scope` (or with `scope: null`), existing `systems` behavior is unchanged. Otherwise, supply exactly one of these forms: ```json {"scope": {"mediaId": 42}} ``` ```json {"scope": {"file": {"system": "SNES", "path": "/games/SNES/Game.sfc"}}} ``` ```json {"scope": {"subtree": {"system": "SNES", "path": "/games/SNES/RPG"}}} ``` These are parameter fragments; `scraperId` is still required. - `mediaId` must be a positive indexed media ID, available from `media.search` or `media.browse` **before scraping**. Use it when available; clients that only have a file path can use `file` instead. - `file` matches one indexed file or virtual URI exactly. It does not resolve a directory to its launch target. `subtree` selects indexed files below a directory recursively, within the specified system. `/games/foo` does not select `/games/foobar`. A filesystem or volume root is valid. - `system` accepts canonical IDs and existing system aliases, case-insensitively, and must identify an indexed system. Path spelling is **case-sensitive on all platforms**, including Windows; use the indexed spelling. Windows native separators and forward slashes are accepted. On Unix, backslashes are literal filename characters. - Filesystem paths must be absolute. Relative paths, `..` components, control characters, invalid UTF-8, and paths longer than 4096 bytes are rejected. Repeated native separators, `.` components, and trailing separators are normalized. Paths are matched lexically against the index; symlinks are not resolved and directories are not scanned. - Virtual URIs such as `steam://123` are opaque, exact identities supported by `mediaId` or `file`; they are not valid subtree paths. Whether metadata exists depends on the selected scraper's sources. - Missing or index-marked-missing IDs/files are client errors. A valid subtree with no present indexed matches succeeds with zero work, even if that directory no longer exists. Unindexed media must be indexed first. - Empty scope objects, unknown scope fields, multiple scope forms, and combining `scope` with `systems` (including `[]`) are client errors. Selector arrays are not supported. Duplicate source matches do not scrape a selected media row more than once per run. - Scoped progress counts selected media rows: `total` is selection size; unmatched, already-scraped, and already-completed-on-resume rows count as skipped. `totalScraped` retains its existing scraper/library-wide meaning. Source files may still need parsing even when only one media row is selected. - Metadata and cleanup writes stay within selected media and their shared titles. Title-level metadata is shared with other ROMs of that title, so those ROMs may display updated title metadata too. - Interrupted operations persist normalized scope and force-run markers. Restart recovery restores that scope, never a whole-system fallback. Single-item scopes also pin system and path alongside the ID; an identity that disappeared or changed fails recovery. Subtrees are re-queried within the same stored boundary, not snapshotted as an ID list. - Status, cancellation, and playback pause/resume remain operation-wide. Cancellation discards resumable operation state; `media.scrape.resume` resumes a playback-paused run, not a cancelled run. IDs are local to the current media database and are not portable across rebuilds. #### Result Returns `null` on success. The scraper continues after the response is sent. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "a7b8c9d0-7a5d-11ef-9c7b-020304050607", "method": "media.scrape", "params": { "scraperId": "gamelist.xml", "systems": ["SNES", "NES"], "force": false } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "a7b8c9d0-7a5d-11ef-9c7b-020304050607", "result": null } ``` ### media.scrape.status **Access:** All clients. Return the latest known metadata scraper status. This method behaves like `media` does for indexing status: clients can query the current scrape snapshot after opening a UI, then continue listening for `media.scraping` notifications. If no scrape has run since startup, the result is idle with `scraping: false`, `done: false`, and `state: "idle"`. Existing flat counter fields remain for compatibility; new UIs should prefer `currentSystem` for per-system progress and `totalSteps`/`currentStep`/`currentStepDisplay` for whole-run progress. #### Parameters None. #### Result | Key | Type | Required | Description | | :-------- | :------ | :------- | :--------------------------------------------------------- | | scraperId | string | No | Scraper ID for the latest or active run. | | systemId | string | No | System currently being processed, when known. | | processed | integer | Yes | Number of records processed. | | total | integer | Yes | Total records expected for the current scrape, when known. | | matched | integer | Yes | Number of records matched and enriched. | | skipped | integer | Yes | Number of records skipped. | | totalScraped | integer | Yes | Number of media records already marked scraped. | | scraping | boolean | Yes | Whether a scrape is currently running. | | done | boolean | Yes | Whether the latest scrape reached a terminal state. | | paused | boolean | Yes | Whether the active scrape is paused because media is running or until resumed. | | state | string | No | Explicit lifecycle state: `idle`, `running`, `paused`, `completed`, `cancelled`, or `failed`. | | error | string | No | Fatal scrape error on failed terminal updates. | | totalSteps | integer | No | Total systems in the scrape run, when known. | | currentStep | integer | No | 1-based current system step, when known. | | currentStepDisplay | string | No | Display name for the current system step, falling back to system ID. | | currentSystem | object | No | Per-system progress object with `systemId`, `systemName`, `processed`, `total`, `matched`, and `skipped`. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "b8c9d0e1-7a5d-11ef-9c7b-020304050607", "method": "media.scrape.status" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "b8c9d0e1-7a5d-11ef-9c7b-020304050607", "result": { "scraperId": "gamelist.xml", "systemId": "snes", "processed": 42, "total": 100, "matched": 38, "skipped": 4, "totalScraped": 1200, "scraping": true, "done": false, "paused": false, "state": "running", "totalSteps": 2, "currentStep": 1, "currentStepDisplay": "Super Nintendo Entertainment System", "currentSystem": { "systemId": "snes", "systemName": "Super Nintendo Entertainment System", "processed": 42, "total": 100, "matched": 38, "skipped": 4 } } } ``` ### media.scrape.cancel **Access:** All clients. Cancel the currently running metadata scraper operation. #### Parameters None. #### Result | Key | Type | Required | Description | | :------ | :----- | :------- | :------------------------------------ | | message | string | Yes | Status message about the cancellation. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "b8c9d0e1-7a5d-11ef-9c7b-020304050607", "method": "media.scrape.cancel" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "b8c9d0e1-7a5d-11ef-9c7b-020304050607", "result": { "message": "scraping cancelled" } } ``` ### media.scrape.resume **Access:** All clients. Resume a paused metadata scraper operation. Scraping normally resumes automatically when playback stops. This method mirrors `media.generate.resume` and lets a local client force the active scrape to continue while the pauser is currently paused. #### Parameters None. #### Result | Key | Type | Required | Description | | :------ | :----- | :------- | :----------------------------- | | message | string | Yes | Status message about resuming. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "c9d0e1f2-7a5d-11ef-9c7b-020304050607", "method": "media.scrape.resume" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "c9d0e1f2-7a5d-11ef-9c7b-020304050607", "result": { "message": "Media scraping resumed" } } ``` ### media.clean.orphans **Access:** All clients. Delete media rows marked missing and remove orphaned related data. This is intended for cleanup after files have been removed from disk and the media database has been refreshed. It removes missing `Media` rows, their tags and properties, and any titles that no longer have media rows. It does not run `VACUUM`; SQLite will reuse freed pages. #### Parameters None. #### Result | Key | Type | Required | Description | | :------ | :----- | :------- | :-------------------------------- | | deleted | number | Yes | Number of missing media rows removed. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "c9d0e1f2-7a5d-11ef-9c7b-020304050607", "method": "media.clean.orphans" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "c9d0e1f2-7a5d-11ef-9c7b-020304050607", "result": { "deleted": 12 } } ``` ### media.control **Access:** All clients. Send a control action to the active media's launcher. Requires active media with a launcher that supports control capabilities. The available control actions depend on the launcher. Use the `launcherControls` field from `media.active` or `media` to discover supported actions. Control actions run in a restricted runtime that blocks media-launching and playlist commands. Utility commands like `input.keyboard`, `execute`, `delay` and `echo` are allowed. The `execute` command bypasses the `allow_execute` allowlist for control scripts defined in launcher configuration. #### Parameters An object: | Key | Type | Required | Description | | :----- | :----- | :------- | :---------------------------------------------------------------- | | action | string | Yes | The control action to execute (e.g., `"save_state"`, `"toggle_pause"`). | | slot | string | No | Target media slot. Omit for primary media; use `"background"` to control background audio. | | args | object | No | Optional key-value arguments for the control action. Values are strings. | `pause`, `resume` and `toggle_pause` on the `background` slot also pause or play the background playlist, so its `playing` field matches the track. #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "c3d4e5f6-7a5d-11ef-9c7b-020304050607", "method": "media.control", "params": { "action": "save_state" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "c3d4e5f6-7a5d-11ef-9c7b-020304050607", "result": null } ``` ##### Slot and arguments example This request targets the background slot and supplies an action argument. Discover supported actions through `launcherControls`. ```json { "jsonrpc": "2.0", "id": "d4e5f6a7-7a5d-11ef-9c7b-020304050607", "method": "media.control", "params": { "action": "fast_forward", "slot": "background", "args": { "seconds": "30" } } } ``` ##### Save state slot example `save_state` and `load_state` take an optional `slot` argument naming the state slot. The default is slot 1. MiSTer cores accept slots 1-4 and RePlayOS accepts 1-18. Batocera chooses the slot itself and rejects the argument, and RetroArch ignores it. On Batocera, `fast_forward` holds the emulator's fast-forward key for `seconds` seconds (default 5, maximum 30), because its RetroArch binds fast forward as a held key. On Batocera, `fast_forward` holds the emulator's fast-forward key for `seconds` seconds (default 5, maximum 30), because its RetroArch binds fast forward as a held key. An action that a launcher defines but the running core or emulator cannot perform, such as `save_state` on a MiSTer core without save states, fails with an error. On MiSTer with the Zaparoo Main fork, cores also offer `cheat` and `save_ram`. `cheat` takes `name`, the cheat's file name in the game's cheat zip (the extension can be left off), and `mode`: `on` (default), `off`, `toggle`, or `clear` to turn every cheat off, which takes no name. Main resets cheats on every game load, and blocks them in RetroAchievements hardcore mode. A name Main cannot match, or a game with no cheats, does not return an error. `save_ram` writes the core's save, such as battery RAM or a memory card, to the SD card. ```json { "jsonrpc": "2.0", "id": "e5f6a7b8-7a5d-11ef-9c7b-020304050607", "method": "media.control", "params": { "action": "save_state", "args": { "slot": "2" } } } ``` ### media.title.parse **Access:** All clients. Preview title and slug generation for a media path without reading the filesystem or media database. This uses the same path parsing rules as media indexing. #### Parameters An object: | Key | Type | Required | Description | | :------- | :----- | :------- | :---------- | | systemId | string | Yes | System ID used to select game or media title-parsing rules. | | path | string | Yes | Media path to parse. | #### Result | Key | Type | Required | Description | | :----------- | :--------------- | :------- | :---------- | | name | string | Yes | Parsed display title. | | slug | string | Yes | Primary normalized title slug. | | secondarySlug | string | No | Secondary slug generated for a subtitle when present. | | slugLength | number | Yes | Primary slug length in Unicode characters. | | slugWordCount | number | Yes | Number of words represented by primary slug. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "c4e5f607-7a5d-11ef-9c7b-020304050607", "method": "media.title.parse", "params": { "systemId": "NES", "path": "roms/nes/Tetris.nes" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "c4e5f607-7a5d-11ef-9c7b-020304050607", "result": { "name": "Tetris", "slug": "tetris", "slugLength": 6, "slugWordCount": 1 } } ``` ### systems **Access:** All clients. List systems currently indexed or supported by an available launcher on the running platform. Virtual systems are also included. Set `all` to include every system represented by the running platform's launcher definitions, even when its runtime dependency is currently unavailable. This is useful when selecting a specific system for its first media index. On MiSTer, a launcher whose FPGA core isn't installed on the SD card counts as unavailable, so without `all` the system list reflects only systems you can currently launch. See [launchers](#launchers) to check which core a launcher needs. Responses include each system's complete `categories` membership, primary category first, and the deprecated `category` field. Additional custom memberships come from manual Core TOML configuration; this API does not provide category mutation or UI behavior. Clients derive available categories from systems in the response. Responses include an exact non-missing `mediaCount` for each system when the media database count query succeeds. Supported systems with no indexed media have `mediaCount: 0`. The field is omitted if counts are unavailable, preserving compatibility with older clients and database-error fallback behavior. Set `tags` to return only systems containing matching non-missing media. Tagged responses use `mediaCount` for the exact matching count and omit zero-match systems. Tag syntax and AND/NOT/OR operators match `media.search`. Tags remain the final filter when combined with `all`, so launcher-only systems with no matching media are omitted. #### Parameters | Key | Type | Required | Description | | :--- | :------- | :------- | :---------------------------------------------------------------------------------------------- | | includeHidden | boolean | No | Include hidden media in system counts. Defaults to `false`; required user tag filters and `~` groups of user tags also include hidden entries. | | all | boolean | No | Include systems with unavailable launchers. Defaults to `false`. Indexed systems remain listed. | | tags | string[] | No | Return systems with matching media. Uses the same tag syntax and operators as `media.search`. | #### Result | Key | Type | Required | Description | | :------ | :------------------------- | :------- | :----------------------------------------------------------------- | | systems | [System](#system-object)[] | Yes | Indexed, available, and optionally unavailable platform systems. Tagged requests include only positive-count systems. | See [System object](#system-object). #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "dbd312f3-7a5f-11ef-8f29-020304050607", "method": "systems", "params": { "all": true } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "dbd312f3-7a5f-11ef-8f29-020304050607", "result": { "systems": [ { "id": "GameboyColor", "name": "Gameboy Color", "category": "Handheld", "categories": ["Handheld"], "releaseDate": "1998-10-21", "manufacturer": "Nintendo", "mediaCount": 842 }, { "id": "EDSAC", "name": "EDSAC", "category": "Computer", "categories": ["Computer", "Favorite Systems"], "releaseDate": "1949-05-06", "manufacturer": "University of Cambridge", "mediaCount": 0 } ] } } ``` ## Uploads A client that cannot name a file on the Core host sends one in chunks, then hands the finished upload to the method that wants it. Uploads run over the same connection as every other method. 1. [`uploads.begin`](#uploadsbegin) with the file's purpose, size and SHA-256 returns an `uploadId` and the chunk size. 2. [`uploads.chunk`](#uploadschunk) sends the bytes in order, each chunk at the offset the last response returned in `received`. 3. [`uploads.finish`](#uploadsfinish) checks the size, the SHA-256 and the content. 4. The finished upload is named by its `uploadId` in the method it was made for, which uses it up. A purpose sets what may be uploaded. The one purpose today: | Purpose | Largest file | Content | Used by | | :------------ | :----------- | :------------------------- | :------ | | `media-image` | 10 MiB | JPEG, PNG, GIF or WebP | [`media.meta.update`](#mediametaupdate) `images` | A session belongs to the client that began it and lives in Core's memory: it ends after 10 minutes without a request, and when Core restarts. A client that lost its connection asks [`uploads.status`](#uploadsstatus) where the upload is and carries on from there. Core holds at most four uploads at once. ### Upload object | Key | Type | Required | Description | | :-------- | :------ | :------- | :---------- | | uploadId | string | Yes | ID of the upload session. | | purpose | string | Yes | Purpose the upload was begun for. | | size | number | Yes | Declared size of the file in bytes. | | received | number | Yes | Bytes received so far: the offset of the next chunk. | | chunkSize | number | Yes | Largest chunk accepted, in raw bytes (131072). | | finished | boolean | Yes | True once `uploads.finish` accepted the upload. | ### uploads.begin **Access:** Localhost or any authenticated client. Open an upload session. #### Parameters | Key | Type | Required | Description | | :------ | :----- | :------- | :---------- | | purpose | string | Yes | What the file is for. See the purposes above. | | size | number | Yes | Size of the file in bytes. Greater than zero and no larger than the purpose allows. | | sha256 | string | Yes | SHA-256 of the whole file, 64 hex characters. | #### Result An [upload object](#upload-object). #### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "uploads.begin", "params": { "purpose": "media-image", "size": 204800, "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" } } ``` ### uploads.chunk **Access:** Localhost or any authenticated client. Append one chunk to an upload. Chunks arrive in order: `offset` must equal the `received` of the previous response. A chunk at any other offset is refused and changes nothing. #### Parameters | Key | Type | Required | Description | | :------- | :----- | :------- | :---------- | | uploadId | string | Yes | ID from `uploads.begin`. | | offset | number | Yes | Zero-based byte offset of this chunk in the file. | | data | string | Yes | The chunk's bytes, base64 encoded. At most `chunkSize` raw bytes, and never past the declared size. | #### Result An [upload object](#upload-object). ### uploads.status **Access:** Localhost or any authenticated client. Report an upload session, so a client can resume from `received`. #### Parameters | Key | Type | Required | Description | | :------- | :----- | :------- | :---------- | | uploadId | string | Yes | ID from `uploads.begin`. | #### Result An [upload object](#upload-object). ### uploads.finish **Access:** Localhost or any authenticated client. Check a fully received upload against its declared size, its SHA-256 and its purpose's content rule. An upload that fails the SHA-256 or the content rule is discarded. An upload that is not complete is refused and kept. #### Parameters | Key | Type | Required | Description | | :------- | :----- | :------- | :---------- | | uploadId | string | Yes | ID from `uploads.begin`. | #### Result An [upload object](#upload-object) with `finished` true. ### uploads.cancel **Access:** Localhost or any authenticated client. Discard an upload session and its bytes. #### Parameters | Key | Type | Required | Description | | :------- | :----- | :------- | :---------- | | uploadId | string | Yes | ID from `uploads.begin`. | #### Result Returns `null` on success. ## Files A client picks an image that is already on the Core host by browsing to it. It never names an absolute path: Core offers a set of roots, and a client names a root by its ID and a path under it. The roots are the folders Core indexes media from, including any media folder set in the configuration, and Core's image folder. A folder that does not exist is not offered. Every path is resolved against its root again on each request. A path that leaves its root, by `..` or through a symbolic link, is refused, and a link that leads out of a root is not listed. ### files.browse **Access:** Localhost or any authenticated client. List the browse roots, or the folders and images of one folder under a root. Without `root`, the result holds `roots` and no entries. A listing holds folders and files with an image extension (`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`), folders first and each group by name. Hidden entries, whose names start with a dot, are left out. #### Parameters | Key | Type | Required | Description | | :------ | :----- | :------- | :---------- | | purpose | string | Yes | What is being picked. `image` is the one purpose. | | root | string | No | ID of a root from a request without `root`. Omit to list the roots. | | path | string | No | Folder under the root, with forward slashes. Omit for the root itself. Needs `root`. | | offset | number | No | Zero-based index of the first entry to return. Defaults to `0`. | | limit | number | No | Entries to return, 1 to 500. Defaults to `100`. | #### Result | Key | Type | Required | Description | | :-------- | :-------------------------------- | :------- | :---------- | | roots | [FilesRoot](#files-root-object)[] | No | The browse roots. Present only when the request named no root. | | root | string | No | ID of the root that was listed. | | path | string | Yes | Folder that was listed, as requested. | | entries | [FilesEntry](#files-entry-object)[] | Yes | This page of the folder's entries. | | total | number | Yes | Entries in the folder across every page. | | truncated | boolean | Yes | True when the folder holds more than 10,000 entries and was read in part. | ##### Files root object | Key | Type | Required | Description | | :--- | :----- | :------- | :---------- | | id | string | Yes | Opaque ID to pass as `root`. Stable for a folder between requests. | | name | string | Yes | The folder's path on the Core host, for display. | ##### Files entry object | Key | Type | Required | Description | | :------- | :------ | :------- | :---------- | | name | string | Yes | Name of the folder or file. | | path | string | Yes | Path under the root, with forward slashes. Pass it as `path` to browse a folder, fetch an image or set one. | | isDir | boolean | Yes | True for a folder. | | size | number | Yes | Size of a file in bytes. `0` for a folder. | | modified | string | Yes | Modification time, RFC 3339. | A folder that does not answer within five seconds is refused, as is a request made while four other folders are still being read. #### Example ```json { "jsonrpc": "2.0", "id": 1, "method": "files.browse", "params": { "purpose": "image", "root": "r3f9a1c0b2e", "path": "covers" } } ``` ### files.image **Access:** Localhost or any authenticated client. Return one image found with `files.browse`, to preview it. The response is the one [`media.image`](#mediaimage) gives, with `typeTag` `file:image`. #### Parameters | Key | Type | Required | Description | | :------- | :----- | :------- | :---------- | | root | string | Yes | ID of the root the image is under. | | path | string | Yes | The entry's `path`. | | maxSize | number | No | Longest edge in pixels to resize down to, as in `media.image`. Omit for the full image. | | delivery | string | No | `inline` (default) or `localPath`, as in `media.image`. `localPath` needs `maxSize`. | ## Playlists ### playlists.update **Access:** All clients. Changes the shuffle and repeat of the playlist open in a slot. The current item stays current and playback is not interrupted; nothing is launched. The change applies to whatever playlist is open in the slot when Core gets to it, and every change is reported by the [playlists.changed](notifications.md#playlistschanged) notification. Turning shuffle on moves the current item to the front and shuffles the rest behind it. Turning it off puts the items back in the order they loaded in, keeping the current item. A playlist restored from a Core version that did not keep the load order stays in its shuffled order when shuffle is turned off. #### Parameters At least one of `shuffle` and `repeat` is required. | Key | Type | Required | Description | | :------ | :------ | :------- | :---------- | | slot | string | No | `primary`, `background` or `bg`. Defaults to `primary`. | | shuffle | boolean | No | Turn shuffle on or off. | | repeat | string | No | `none`, `all` or `one`. `off` is accepted as `none`. | #### Result Returns `null` on success. Asking for a slot with no playlist open is an error. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5d-11ef-9c7b-020304050607", "method": "playlists.update", "params": { "slot": "background", "shuffle": true, "repeat": "all" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5d-11ef-9c7b-020304050607", "result": null } ``` ## Settings ### settings **Access:** All accepted clients. Online backup, play-history sync, remote-control and image folder fields are returned only to localhost or authenticated admin. List currently set configuration settings. This method will list values set in the [Config File](../../core/config.md). Some config file options may be omitted which are not appropriate to be read or written remotely. #### Parameters None. #### Result | Key | Type | Required | Description | | :------------------------ | :---------------------------------------- | :------- | :-------------------------------------------------------------- | | runZapScript | boolean | Yes | The user's ZapScript setting. Holds do not change it. | | debugLogging | boolean | Yes | Whether debug logging is enabled. | | audioScanFeedback | boolean | Yes | Whether audio feedback on scan is enabled. | | audioVolume | number | Yes | Volume of scan and other feedback sounds, 0 to 200 (100 is unchanged, 0 is silent). Music follows it while `audioMusicVolume` has not been set. | | audioMusicVolume | number | Yes | Volume of music and other audio played by native audio in either slot, 0 to 200 (`[audio] music_volume`). Reports `audioVolume` while it has not been set. | | audioMusicAutoplay | boolean | Yes | Whether the background playlist open when Core last stopped starts playing on the first Core start of each boot (`[audio] music_autoplay`). Defaults to true. | | audioMusicPauseOnLaunch | boolean | Yes | Whether background music pauses while a game runs in the primary slot and resumes when it exits. Stored as `pause_on_launch` on the `Audio` entry of `[[systems.default]]`. Defaults to true. | | audioNormalize | boolean | Yes | Whether music, radio, chiptune and MIDI playback is levelled to a common loudness, using ReplayGain tags where a file has them (`[audio] normalize`). Defaults to true. | | audioMidiSoundFont | string | Yes | SoundFont (.sf2) that MIDI files play through (`[audio] midi_soundfont`). Relative paths resolve under the data directory's `assets` folder. Empty means MIDI plays through the built-in FM synthesizer. | | readersAutoDetect | boolean | Yes | Whether automatic reader detection is enabled. | | readersScanMode | string | Yes | Current scan mode setting. | | readersScanExitDelay | number | Yes | Delay before exiting scan mode in seconds. | | readersScanIgnoreSystems | string[] | Yes | List of system IDs to ignore during scanning. | | errorReporting | boolean | Yes | Whether error reporting is enabled. | | encryption | boolean | Yes | Whether paired encryption is required for remote WebSocket connections. Localhost remains exempt. | | bleEnabled | boolean | Yes | Whether the API is also served over [Bluetooth LE](./#bluetooth-le). Defaults to true. | | readersConnect | [ReaderConnection](#reader-connection-object)[] | Yes | List of manually configured reader connections. | | systemDefaults | [SystemDefault](#system-default-object)[] | Yes | Per-system overrides for default launcher and exit ZapScript. | | launcherPreference | string[] | Yes | Global launcher preference (`[launchers] preference`), in order. Each entry is a launcher ID or group name. When a launch names no launcher and the system has no `systemDefaults` launcher, the first entry with an available launcher for the media's system is used. Empty when unset. | | profilesRequireForLaunch | boolean | Yes | Whether media launches are blocked while no personal profile is active. | | profilesSwapData | boolean | Yes | Whether profile switches also swap profile-scoped data (saves, save states) on supported platforms. Defaults to true. | | mediaThumbCacheMaxMb | number | Yes | Size cap of the generated thumbnail cache in MiB (`[media] thumb_cache_max_mb`). Defaults to 1024. It covers only the resized covers Core generates, never scraped images. | | updateChannel | string | Yes | Release channel used for update checks: `stable` or `beta`. Defaults to `stable`. | | updateCheck | boolean | Yes | Whether the service looks for new releases on its own. Defaults to true on every platform, including installs a package manager owns. | | updateInstall | boolean | Yes | Whether the device downloads and installs updates on its own, rather than only telling the user one exists. Defaults to false, and is always false while `updateCheck` is off. | | backupRemoteEnabled | boolean | No | Whether automatic remote backup scheduling is enabled. Only returned to localhost and authenticated admin clients. | | playtimeSyncEnabled | boolean | No | Whether the user explicitly enabled play history sync. Defaults to false. Only returned to localhost and authenticated admin clients. | | librarySyncEnabled | boolean | No | Whether the user explicitly enabled Library sync. Defaults to false, and is reset to false whenever the account is linked or unlinked. Only returned to localhost and authenticated admin clients. | | backupRemoteSchedule | string | No | Remote backup schedule: `daily`, `weekly`, or `manual`. Only returned to localhost and authenticated admin clients. | | remoteControlEnabled | boolean | No | Whether the device owner explicitly allowed a linked Zaparoo Online account to send remote commands to this device. Defaults to false, and is reset to false whenever the account is linked or unlinked. Only returned to localhost and authenticated admin clients. | | mediaImageDir | string | No | Absolute path of the image folder (`[media] image_dir`), where scraped images (`libretro/`) and the generated thumbnail cache (`thumbs/`) are stored. Defaults to `images` under Core's data directory. Only returned to localhost and authenticated admin clients. | | onlineBaseUrl | string | No | Base URL of the Zaparoo Online service every online feature uses: account linking, cloud backup, play history sync, Library sync and remote control (read-only, set as `online_base_url` under `[service]` in the config file). Only returned to localhost and authenticated admin clients. | ##### Reader connection object | Key | Type | Required | Description | | :------- | :----- | :------- | :----------------------------------------------- | | driver | string | Yes | Reader driver type (e.g., "pn532uart", "ccid"). | | path | string | Yes | Path or address for the reader connection. | | idSource | string | No | Source for the reader ID. | | enabled | bool | No | Whether the connection is enabled. Defaults to true if omitted. | | scanMode | string | No | Scan mode for this reader (`"tap"` or `"hold"`), overriding the driver's and the global `readers.scan.mode`. Empty means inherit. Case and surrounding space are ignored and the canonical spelling is stored; any other value is rejected. | ##### System default object | Key | Type | Required | Description | | :--------- | :----- | :------- | :------------------------------------------------------------------------------------------------ | | system | string | Yes | System ID this default applies to. Accepts canonical IDs and aliases. | | launcher | string | No | Launcher ID or group name to use for this system. Empty means no override. | | beforeExit | string | No | ZapScript to run just before media for this system stops or is replaced: tapping another card, `**stop`, `**playlist.stop`, `**mister.mgl`, the `stop` method, a playtime limit, or a hold-mode card removal. Does not run when media exits on its own, and applies to primary media only. Failures are logged and never block the exit, the script is bounded to 30 seconds, and only one runs at a time. A `before_exit` can also be written per launcher or launcher group as `[[launchers.default]] before_exit`, or globally as `[launchers] before_exit`; neither is exposed through this API, and this per-system script beats a group entry and the global but loses to an entry naming the launcher that started the media. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "f208d996-7ae6-11ef-960e-020304050607", "method": "settings" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "f208d996-7ae6-11ef-960e-020304050607", "result": { "runZapScript": true, "debugLogging": false, "audioScanFeedback": true, "readersAutoDetect": true, "readersScanMode": "tap", "readersScanExitDelay": 0.0, "readersScanIgnoreSystems": ["DOS"], "errorReporting": true, "encryption": false, "bleEnabled": true, "readersConnect": [], "systemDefaults": [ { "system": "Genesis", "launcher": "retroarch" } ], "launcherPreference": ["retroarch", "libretro"] } } ``` ### settings.update **Access:** Requires `settings.write`. Changing `encryption` is localhost only. Online backup, play-history sync, remote-control and image folder settings require localhost or authenticated admin, so legacy clients cannot change them. Update one or more settings in-memory and save changes to disk. This method will only write values which are supplied. Existing values will not be modified. #### Parameters An object containing any of the following optional keys: | Key | Type | Required | Description | | :------------------------ | :---------------------------------------- | :------- | :-------------------------------------------------------------- | | runZapScript | boolean | No | Whether ZapScript execution is enabled. | | debugLogging | boolean | No | Whether debug logging is enabled. | | audioScanFeedback | boolean | No | Whether audio feedback on scan is enabled. | | audioVolume | number | No | Volume of scan and other feedback sounds, 0 to 200. While `audioMusicVolume` has not been set, music follows it and the change is heard at once. | | audioMusicVolume | number | No | Volume of music played by native audio in either slot, 0 to 200. `0` is silent. Applies at once to what is playing. | | audioMusicAutoplay | boolean | No | Whether the restored background playlist starts playing on the first Core start of each boot. | | audioMusicPauseOnLaunch | boolean | No | Whether background music pauses while a game runs. Applied after `systemDefaults` when both are sent, and kept when `systemDefaults` leaves the `Audio` entry out. | | audioNormalize | boolean | No | Whether music, radio, chiptune and MIDI playback is levelled to a common loudness. Applies to what is playing within a few seconds. | | audioMidiSoundFont | string | No | SoundFont (.sf2) that MIDI files play through. Empty goes back to the built-in FM synthesizer. Applies to the next MIDI file played. | | readersAutoDetect | boolean | No | Whether automatic reader detection is enabled. | | readersScanMode | string | No | Current scan mode setting. | | readersScanExitDelay | number | No | Delay before exiting scan mode in seconds. | | readersScanIgnoreSystems | string[] | No | List of system IDs to ignore during scanning. | | errorReporting | boolean | No | Whether error reporting is enabled. | | encryption | boolean | No | Require paired encryption for remote WebSocket connections. This setting can only be changed from localhost. | | bleEnabled | boolean | No | Serve the API over [Bluetooth LE](./#bluetooth-le) as well. Takes effect within about fifteen seconds without a restart. | | readersConnect | [ReaderConnection](#reader-connection-object)[] | No | List of manually configured reader connections. | | systemDefaults | [SystemDefault](#system-default-object)[] | No | Replace the full list of per-system launcher/exit-script overrides. Each `launcher` value, if non-empty, must match a known launcher ID or group (case-insensitive). Fields the API does not carry, such as `pause_on_launch`, are kept, including on an `Audio` entry the list leaves out. | | launcherPreference | string[] | No | Replace the global launcher preference list, keeping its order. `[]` clears it. Each entry must match a known launcher ID or group (case-insensitive), unless it is already in the current list. | | profilesRequireForLaunch | boolean | No | Whether media launches are blocked while no personal profile is active. | | profilesSwapData | boolean | No | Whether profile switches also swap profile-scoped data. Turning it off converges data back to the shared state immediately. | | updateChannel | string | No | Release channel used for update checks: `stable` or `beta`. | | updateCheck | boolean | No | Whether the service looks for new releases on its own. | | updateInstall | boolean | No | Whether the device installs updates on its own. Setting it to true while update checking is off is refused; send `updateCheck: true` in the same call to turn both on. | | mediaImageDir | string | No | Image folder for scraped images and the generated thumbnail cache. `""` restores the default. A relative path resolves against the folder holding the Core executable, like `[launchers] media_dir`. A filesystem root or an existing file is refused. Core never moves or copies images to a new folder; covers already scraped stay where they are until copied by hand or downloaded again by a fill-missing run, and the thumbnail cache starts empty there. Takes effect at once. Refused with category `busy` while the `libretro-thumbnails` scraper runs. Requires localhost or an authenticated admin client. | | mediaThumbCacheMaxMb | number | No | Size cap of the generated thumbnail cache in MiB, up to 1048576. `0` restores the default of 1024. Takes effect at once; a lower cap is trimmed in the background, keeping thumbnails used within the last day. | | backupRemoteEnabled | boolean | No | Enable automatic remote backup scheduling. Requires localhost or an authenticated admin client. | | playtimeSyncEnabled | boolean | No | Explicitly enable or disable play history sync. The first enabled sync uploads retained local history. Disabling stops future uploads. Requires localhost or an authenticated admin client. | | librarySyncEnabled | boolean | No | Explicitly enable or disable Library sync, which uploads the list of games this device holds and keeps favorites, play-later, likes, dislikes and decks in step with the linked Zaparoo Online account. Disabling removes this device's game list from the account; local favorites and decks are kept. The linked account is told within a minute. Requires localhost or an authenticated admin client. | | backupRemoteSchedule | string | No | Remote backup schedule: `daily`, `weekly`, or `manual`. Requires localhost or an authenticated admin client. | | remoteControlEnabled | boolean | No | Allow or stop allowing the linked Zaparoo Online account to send remote commands to this device. Takes effect within a few seconds; the device advertises or withdraws the capability itself. Requires localhost or an authenticated admin client. | #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "method": "settings.update", "params": { "debugLogging": false } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "result": null } ``` ### settings.zapscript.hold **Access:** Localhost or `settings.write`. WebSocket only. Disable ZapScript execution for as long as this WebSocket connection stays open. The hold is released when the connection closes for any reason, including a client that is killed, so it cannot leave ZapScript disabled the way `settings.update` with `runZapScript: false` can. Holds do not change the `runZapScript` setting. A connection holds at most once; repeat calls succeed without stacking. #### Parameters None. #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "method": "settings.zapscript.hold" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "result": null } ``` ### settings.reload **Access:** All clients. Reload settings and mappings from disk. #### Parameters None. #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "method": "settings.reload" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "result": null } ``` ### settings.auth.claim **Access:** Unauthenticated bootstrap. Redeem a claim token against a remote auth server and store the resulting credentials in `auth.toml`. This method performs trust discovery using the `.well-known/zaparoo` protocol. It first verifies that the claim URL's root domain supports auth (`auth: 1` in the well-known response), then redeems the claim token to obtain a bearer credential. If the root domain's well-known response includes a `trusted` list, each related domain is checked for bidirectional trust confirmation before extending the credential. Production claim URLs must use HTTPS. Plain HTTP is accepted only for loopback, private-network, or link-local development endpoints; public HTTP endpoints are rejected. #### Parameters An object: | Key | Type | Required | Description | | :------- | :----- | :------- | :------------------------------------------------------------- | | claimUrl | string | Yes | HTTPS claim URL. HTTP is allowed only for loopback, private, or link-local development endpoints. | | token | string | Yes | The one-time claim token to redeem. | #### Result | Key | Type | Required | Description | | :------ | :------- | :------- | :----------------------------------------------------------------- | | domains | string[] | Yes | List of domains the credential was stored for (root + any trusted). | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-auth-claim-example", "method": "settings.auth.claim", "params": { "claimUrl": "https://api.example.com/auth/claim", "token": "claim-token-abc123" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-auth-claim-example", "result": { "domains": [ "https://api.example.com", "https://cdn.example.com" ] } } ``` ### settings.auth.status **Access:** Unauthenticated bootstrap. Report whether Core holds a stored bearer credential for an auth server URL. The check is local only: the token is never validated against the server and no token material is returned. Status probes are only answered for official Zaparoo API hosts over HTTPS and for the configured online base URL. Any other URL returns `linked: false` without revealing whether a credential exists. #### Parameters An object: | Key | Type | Required | Description | | :-- | :----- | :------- | :------------------------------------- | | url | string | Yes | Auth server URL to check link state for. | #### Result | Key | Type | Required | Description | | :----- | :------ | :------- | :------------------------------------------------------- | | linked | boolean | Yes | Whether a stored bearer credential exists for the URL. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "b2c3d4e5-auth-status-example", "method": "settings.auth.status", "params": { "url": "https://api.zaparoo.com" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "b2c3d4e5-auth-status-example", "result": { "linked": true } } ``` ### settings.auth.unlink **Access:** Localhost or admin. Remove the device's online account credentials — the inverse of `settings.auth.link`. The claim/link flow tags every credential it stores with the root domain that created it (`linked_via` in `auth.toml`), so unlink removes the configured remote backup server's entry plus every entry tagged with it, whatever domains the server's trusted list contained at link time. Credentials for other domains, hand-written basic-auth entries, and API keys are untouched. Remote backup state is marked unlinked so the status UI prompts a re-link and the scheduler stops attempting remote backups. Requires a localhost client or an authenticated admin client, including a valid static API-key admin. #### Parameters None. #### Result | Key | Type | Required | Description | | :------ | :------- | :------- | :---------------------------------------------- | | domains | string[] | Yes | Domains whose stored credentials were removed. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "c3d4e5f6-auth-unlink-example", "method": "settings.auth.unlink" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "c3d4e5f6-auth-unlink-example", "result": { "domains": ["https://api.zaparoo.com", "https://zpr.au"] } } ``` ### settings.auth.link **Access:** Unauthenticated bootstrap. Start a reverse device link flow (device-authorization style): Core requests a link from the auth server, returns a user code and verification URLs to display, then polls in the background until the user approves the link in their account. On approval the resulting claim token is redeemed through the same pipeline as `settings.auth.claim` and the credential is stored in `auth.toml`. This method is deliberately available before client authentication. Remote HTTP POST still requires an address allowed by `allowed_ips`. Only one link flow can be pending at a time; starting another while one is pending returns an error. Progress is pushed via the [`auth.link.status`](./notifications.md#authlinkstatus) notification (with user code and verification URLs omitted) and can be polled with `settings.auth.link.status`. #### Parameters An object (optional): | Key | Type | Required | Description | | :-- | :----- | :------- | :--------------------------------------------------------------------------------------------------- | | url | string | No | Auth server base URL. Defaults to the configured online base URL, which is the official Zaparoo API unless changed. HTTP is allowed only for loopback, private, or link-local development endpoints. | #### Result A link status object: | Key | Type | Required | Description | | :---------------------- | :----- | :------- | :---------------------------------------------------------------- | | status | string | Yes | One of `none`, `pending`, `approved`, `failed`, or `cancelled`. | | userCode | string | No | Short code the user enters at the verification URL. | | verificationUrl | string | No | URL where the user approves the link. | | verificationUrlComplete | string | No | Verification URL with the user code included, for QR display. | | expiresAt | string | No | RFC 3339 time when the link request expires. | | error | string | No | Human-readable reason when `status` is `failed`. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "c3d4e5f6-auth-link-example", "method": "settings.auth.link" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "c3d4e5f6-auth-link-example", "result": { "status": "pending", "userCode": "ABCD-1234", "verificationUrl": "https://online.zaparoo.com/link", "verificationUrlComplete": "https://online.zaparoo.com/link?code=ABCD1234", "expiresAt": "2026-06-24T15:14:05Z" } } ``` ### settings.auth.link.status **Access:** Unauthenticated bootstrap with redacted output; localhost and admin receive full output. Members are rejected. Return the state of the active link flow as a link status object (see `settings.auth.link`). When no flow has been started, `status` is `none`. Access is tiered: localhost, paired admin, and API-key admin receive the full object including `userCode` and verification URLs. Unauthenticated callers receive only flow state; `userCode`, `verificationUrl`, and `verificationUrlComplete` are omitted. Paired member clients are forbidden. #### Parameters None. #### Result A link status object (see `settings.auth.link`). #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "d4e5f6a7-auth-link-status-example", "method": "settings.auth.link.status" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "d4e5f6a7-auth-link-status-example", "result": { "status": "approved" } } ``` ### settings.auth.link.cancel **Access:** Localhost or admin. Cancel the pending link flow. Requires a localhost client or an authenticated admin client, including a valid static API-key admin. Returns the terminal `cancelled` status object with user code and verification URLs omitted. When no flow is pending, returns an error (`no active link request`). #### Parameters None. #### Result A link status object (see `settings.auth.link`) with `status` set to `cancelled`. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "e5f6a7b8-auth-link-cancel-example", "method": "settings.auth.link.cancel" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "e5f6a7b8-auth-link-cancel-example", "result": { "status": "cancelled" } } ``` ### settings.logs.download **Access:** All clients. Download the current log file as base64-encoded content. #### Parameters None. #### Result | Key | Type | Required | Description | | :------- | :----- | :------- | :----------------------------------------------- | | filename | string | Yes | Name of the log file. | | size | number | Yes | Size of the log file in bytes. | | content | string | Yes | Base64-encoded content of the log file. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "9f50e39f-7a5e-11ef-87ee-020304050607", "method": "settings.logs.download" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "9f50e39f-7a5e-11ef-87ee-020304050607", "result": { "filename": "zaparoo.log", "size": 1024, "content": "MjAyNC0wOS0yNFQxNzowMDowMC4wMDBaIElORk8gU3RhcnRpbmcgWmFwYXJvby4uLg==" } } ``` ### Device backup response objects Backup methods use the following shared response objects. Authentication credentials are excluded from every backup. Restoring preserves the destination device's identity, encryption setting, paired clients, and stored credentials. #### Local backup object | Key | Type | Required | Description | | :--------- | :-------------------------------------- | :------- | :---------- | | name | string | Yes | Backup ZIP filename. | | path | string | No | Backup ZIP path on the device. | | createdAt | string | Yes | Creation time in RFC 3339 format. | | size | number | Yes | ZIP size in bytes. | | status | string | Yes | `success` or `partial`. `partial` means one or more files were skipped. | | integrity | string | Yes | `valid` after creation or restore validation; `unchecked` after metadata-only inspection. | | categories | object | No | Map from category name to [backup category status](#backup-category-status-object). | | warnings | [BackupWarning](#backup-warning-object)[] | No | Files omitted from backup. | | error | string | No | Safe error summary when available. | ##### Backup category status object | Key | Type | Required | Description | | :------ | :------ | :------- | :---------- | | files | number | Yes | Number of included files. | | bytes | number | Yes | Total uncompressed bytes. | | enabled | boolean | Yes | Whether category is enabled in backup scope. | ##### Backup warning object | Key | Type | Required | Description | | :------- | :----- | :------- | :---------- | | category | string | Yes | Backup category. | | path | string | Yes | Affected source path. | | reason | string | Yes | Why file was skipped. | #### Remote backup object | Key | Type | Required | Description | | :----------- | :----- | :------- | :---------- | | id | string | Yes | Opaque remote backup ID. | | backupType | string | Yes | Backup type, such as `manual` or `scheduled`. | | schemaVersion | number | Yes | Remote backup schema version. | | createdAt | string | Yes | Creation time in RFC 3339 format. | | sizeBytes | number | Yes | Stored backup size in bytes. | | manifestHash | string | Yes | Hash identifying snapshot contents. | | categories | object | Yes | Map from category name to `{ "files": number, "bytes": number }`. | | coreVersion | string | No | Core version that created backup. | | platform | string | No | Source platform ID. | | verifiedAt | string | No | Latest verification time in RFC 3339 format. | | restoredAt | string | No | Latest restore time in RFC 3339 format. | | sourceDevice | object | No | Source device: `id`, `name`, `linked`, `current`, and optional `platform`. IDs are opaque. | | incompatible | boolean | No | Whether backup uses a newer schema and cannot be restored by this Core version. | | manifest | object | No | Remote manifest when endpoint includes it. | Local backups are ZIP archives using known categories (`zaparoo`, `settings`, `inputs`, `saves`, and `savestates`), exact platform matching, SHA-256 payload verification, and fixed entry, path, and manifest limits. Restores stage and verify every payload before device mutation. Remote files larger than a 64 MiB transfer pack are skipped and reported, and server quota is checked before upload. ### settings.backup **Access:** Localhost or admin. Create a local full-device ZIP backup. #### Parameters None. #### Result A [local backup object](#local-backup-object). Newly created backups report `integrity: "valid"`. #### Example ```json { "jsonrpc": "2.0", "id": "backup-create-1", "method": "settings.backup" } ``` ```json { "jsonrpc": "2.0", "id": "backup-create-1", "result": { "name": "backup-20260710-120000-manual.zip", "path": "/data/backups/backup-20260710-120000-manual.zip", "createdAt": "2026-07-10T12:00:00Z", "size": 1048576, "status": "success", "integrity": "valid", "categories": { "settings": {"files": 4, "bytes": 8192, "enabled": true} } } } ``` ### settings.backup.list **Access:** Localhost or admin. List local backup ZIP metadata without reading archive manifests. #### Parameters None. #### Result An array of objects with `name`, `createdAt`, `size`, and optional device-local `path`. #### Example ```json { "jsonrpc": "2.0", "id": "backup-list-1", "method": "settings.backup.list" } ``` ```json { "jsonrpc": "2.0", "id": "backup-list-1", "result": [ { "name": "backup-20260710-120000-manual.zip", "path": "/data/backups/backup-20260710-120000-manual.zip", "createdAt": "2026-07-10T12:00:00Z", "size": 1048576 } ] } ``` ### settings.backup.inspect **Access:** Localhost or admin. Read and validate local backup manifest metadata without hashing every payload. #### Parameters | Key | Type | Required | Description | | :--- | :----- | :------- | :---------- | | name | string | Yes | Local backup filename from `settings.backup.list`. | #### Result A [local backup object](#local-backup-object). Successful inspection reports `integrity: "unchecked"`; restore performs full payload verification before mutation. #### Example ```json { "jsonrpc": "2.0", "id": "backup-inspect-1", "method": "settings.backup.inspect", "params": {"name": "backup-20260710-120000-manual.zip"} } ``` ```json { "jsonrpc": "2.0", "id": "backup-inspect-1", "result": { "name": "backup-20260710-120000-manual.zip", "createdAt": "2026-07-10T12:00:00Z", "size": 1048576, "status": "success", "integrity": "unchecked" } } ``` ### settings.backup.delete **Access:** Localhost or admin. Delete a local backup ZIP. #### Parameters | Key | Type | Required | Description | | :--- | :----- | :------- | :---------- | | name | string | Yes | Local backup filename from `settings.backup.list`. | #### Result Returns `null` on success. #### Example ```json { "jsonrpc": "2.0", "id": "backup-delete-1", "method": "settings.backup.delete", "params": {"name": "backup-20260710-120000-manual.zip"} } ``` ```json { "jsonrpc": "2.0", "id": "backup-delete-1", "result": null } ``` ### settings.backup.restore **Access:** Localhost or admin. Transactionally restore a local backup. Restore is rejected while media is active or launching. Core creates a pre-restore safety backup, writes the response, then restarts. #### Parameters | Key | Type | Required | Description | | :--- | :----- | :------- | :---------- | | name | string | Yes | Local backup filename from `settings.backup.list`. | #### Result | Key | Type | Required | Description | | :-------------- | :---------------------------------------- | :------- | :---------- | | restoredFrom | [LocalBackup](#local-backup-object) | Yes | Backup restored after full validation. | | preRestoreBackup | [LocalBackup](#local-backup-object) | No | Safety backup created before mutation. | #### Example ```json { "jsonrpc": "2.0", "id": "backup-restore-1", "method": "settings.backup.restore", "params": {"name": "backup-20260710-120000-manual.zip"} } ``` ```json { "jsonrpc": "2.0", "id": "backup-restore-1", "result": { "restoredFrom": { "name": "backup-20260710-120000-manual.zip", "createdAt": "2026-07-10T12:00:00Z", "size": 1048576, "status": "success", "integrity": "valid" } } } ``` ### settings.backup.status **Access:** All clients. Localhost and paired admin requests may trigger a background refresh of stale remote availability; response never waits for that network request. Return current local and remote backup state. #### Parameters None. #### Result | Key | Type | Required | Description | | :-------------- | :----- | :------- | :---------- | | activeOperation | string | No | Active operation, such as `local-create`, `remote-upload`, or `remote-restore`. | | activeSince | string | No | Operation start time in RFC 3339 format. | | local | object | Yes | Local [backup status entry](#backup-status-entry-object). | | remote | object | Yes | Remote [backup status entry](#backup-status-entry-object). | ##### Backup status entry object | Key | Type | Required | Description | | :-------------------- | :------ | :------- | :---------- | | enabled | boolean | Yes | Whether backup mode is enabled. | | lastStatus | string | Yes | `never`, `running`, `success`, `partial`, or `failed`. | | lastBackupSize | number | Yes | Latest backup size in bytes. | | lastRunAt | string | No | Latest attempt time. | | lastSuccessAt | string | No | Latest successful run time, including unchanged remote runs. | | lastSnapshotCreatedAt | string | No | Time remote stored content last changed. | | lastRunNoChanges | boolean | No | Latest remote run succeeded without creating new snapshot. | | lastError | string | No | Safe latest failure summary. | | categories | object | No | Category status map. | | warnings | [BackupWarning](#backup-warning-object)[] | No | Files skipped by latest run. | | skippedFiles | number | No | Number of skipped files. | | schedule | string | No | Remote schedule: `daily`, `weekly`, or `manual`. | | linked | boolean | No | Whether device has usable remote credentials. | | deviceName | string | No | Linked remote device name. | | linkedAt | string | No | Device link time. | | availability | string | No | Cached remote service availability: `available` when the account has the `cloud_backup` feature, `unavailable` when it does not, `unknown` before a check succeeds or after one fails. | | availabilityCheckedAt | string | No | Latest availability check time. | #### Example ```json { "jsonrpc": "2.0", "id": "backup-status-1", "method": "settings.backup.status" } ``` ```json { "jsonrpc": "2.0", "id": "backup-status-1", "result": { "local": {"enabled": true, "lastStatus": "success", "lastBackupSize": 1048576}, "remote": {"enabled": true, "linked": true, "schedule": "daily", "lastStatus": "success", "lastBackupSize": 1048576} } } ``` ### settings.backup.remote.run **Access:** Localhost or admin. Create a manual remote backup. Manual backups remain available when automatic scheduling is disabled. Upload and scheduling require remote service availability. #### Parameters None. #### Result | Key | Type | Required | Description | | :---------------- | :---------------------------------------------- | :------- | :---------- | | backup | [RemoteBackup](#remote-backup-object) | Yes | Stored remote snapshot metadata. | | categories | object | Yes | Uploaded category summaries. | | uploadedFiles | number | Yes | Files uploaded in this run. | | dedupedFiles | number | Yes | Files already stored remotely. | | uploadedPacks | number | Yes | Transfer packs uploaded. | | uploadedBytes | number | Yes | Bytes uploaded. | | skippedFiles | number | No | Unsafe, unavailable, or oversized files skipped. | | warnings | [BackupWarning](#backup-warning-object)[] | No | Structured skipped-file details. | | storageUsedBytes | number | No | Remote account storage used. | | storageQuotaBytes | number | No | Remote account storage quota. | | noChanges | boolean | No | Server already held identical snapshot; run succeeded without new stored content. | #### Example ```json { "jsonrpc": "2.0", "id": "backup-remote-run-1", "method": "settings.backup.remote.run" } ``` ```json { "jsonrpc": "2.0", "id": "backup-remote-run-1", "result": { "backup": { "id": "01J2BACKUP", "backupType": "manual", "schemaVersion": 1, "createdAt": "2026-07-10T12:00:00Z", "sizeBytes": 1048576, "manifestHash": "sha256:example", "categories": {} }, "categories": {}, "uploadedFiles": 4, "dedupedFiles": 20, "uploadedPacks": 1, "uploadedBytes": 8192 } } ``` ### settings.backup.remote.list **Access:** Localhost or admin. List remote backups and account quota. Listing existing backups remains available when uploads are unavailable. #### Parameters None. #### Result | Key | Type | Required | Description | | :---------------- | :---------------------------------------- | :------- | :---------- | | items | [RemoteBackup](#remote-backup-object)[] | Yes | Remote backups. IDs are opaque. | | storageUsedBytes | number | Yes | Remote account storage used. | | storageQuotaBytes | number | Yes | Remote account storage quota. | #### Example ```json { "jsonrpc": "2.0", "id": "backup-remote-list-1", "method": "settings.backup.remote.list" } ``` ```json { "jsonrpc": "2.0", "id": "backup-remote-list-1", "result": { "items": [], "storageUsedBytes": 0, "storageQuotaBytes": 1073741824 } } ``` ### settings.backup.remote.restore **Access:** Localhost or admin. Transactionally restore an opaque remote backup ID. Listing and restoring existing backups remain available when uploads are unavailable. Restore is rejected while media is active or launching. Core writes response, then restarts. #### Parameters | Key | Type | Required | Description | | :-- | :----- | :------- | :---------- | | id | string | Yes | Opaque backup ID from `settings.backup.remote.list`. | #### Result | Key | Type | Required | Description | | :-------------- | :---------------------------------------- | :------- | :---------- | | restoredFrom | [RemoteBackup](#remote-backup-object) | Yes | Remote backup restored after full validation. | | preRestoreBackup | [LocalBackup](#local-backup-object) | No | Local safety backup created before mutation. | #### Example ```json { "jsonrpc": "2.0", "id": "backup-remote-restore-1", "method": "settings.backup.remote.restore", "params": {"id": "01J2BACKUP"} } ``` ```json { "jsonrpc": "2.0", "id": "backup-remote-restore-1", "result": { "restoredFrom": { "id": "01J2BACKUP", "backupType": "manual", "schemaVersion": 1, "createdAt": "2026-07-10T12:00:00Z", "sizeBytes": 1048576, "manifestHash": "sha256:example", "categories": {} } } } ``` A remote API `401` marks device unlinked until a fresh link succeeds. Archives that fail ZIP header, manifest, hash, schema, or platform-policy validation return an RPC error without backup metadata. ## Playtime ### playtime **Access:** All clients. Query current playtime session status and usage statistics. This method returns comprehensive information about the current playtime session, including active game time, cumulative session time, cooldown state, daily usage, and remaining time before limits are reached. **Session States:** - `reset` - No active session, ready to start new session - `active` - Game currently running, time being tracked - `cooldown` - Game stopped but session persists (within session reset timeout) #### Parameters None. #### Result | Key | Type | Required | Description | | :-------------------- | :------ | :------- | :---------------------------------------------------------------------------------------------------- | | state | string | Yes | Current session state: `"reset"`, `"active"`, or `"cooldown"`. | | sessionActive | boolean | Yes | Whether a game is currently running. | | limitsEnabled | boolean | Yes | Whether playtime limits are currently enabled for enforcement. | | sessionStarted | string | No | ISO 8601 timestamp when current game started. Only present during `"active"` state. | | sessionDuration | string | No | Total time in current session (Go duration format). Present during `"active"` and `"cooldown"` states. | | sessionCumulativeTime | string | No | Cumulative time from previous games in session. Present during `"active"` and `"cooldown"` states. | | sessionRemaining | string | No | Time remaining before session limit reached. Only present if session limit is configured. | | cooldownRemaining | string | No | Time until session auto-resets. Only present during `"cooldown"` state. | | dailyUsageToday | string | No | Total playtime accumulated today. Available in all states when data is available. | | dailyRemaining | string | No | Time remaining before daily limit reached. Available in all states if daily limit is configured. | | sessionExtension | string | No | Extra time granted to the current session on top of the configured session limit. Omitted when nothing was granted. | | sessionExtendedUntil | string | No | RFC 3339 timestamp when a session-limit waiver lapses. While set, the session limit is not enforced and `sessionRemaining` is omitted; the daily limit still applies. | **Note:** All duration fields use Go's duration format (e.g., `"1h30m45s"`, `"45m"`, `"2h"`). `sessionRemaining` already accounts for any granted extension, so a client showing time left needs no extra arithmetic. `sessionExtension` is reported separately so a client can show that time was granted rather than silently displaying a larger allowance. See [`playtime.extend`](#playtimeextend). #### Examples ##### Request ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5e-11ef-9c7b-020304050607", "method": "playtime" } ``` ##### Response (reset state) ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5e-11ef-9c7b-020304050607", "result": { "state": "reset", "sessionActive": false, "limitsEnabled": true, "dailyUsageToday": "1h30m0s", "dailyRemaining": "2h30m0s" } } ``` ##### Response (active game with limits) ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5e-11ef-9c7b-020304050607", "result": { "state": "active", "sessionActive": true, "limitsEnabled": true, "sessionStarted": "2025-01-22T14:30:00Z", "sessionDuration": "45m30s", "sessionCumulativeTime": "15m", "sessionRemaining": "14m30s", "dailyUsageToday": "2h15m30s", "dailyRemaining": "1h44m30s" } } ``` ##### Response (cooldown state) ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5e-11ef-9c7b-020304050607", "result": { "state": "cooldown", "sessionActive": false, "limitsEnabled": true, "sessionDuration": "45m30s", "sessionCumulativeTime": "45m30s", "sessionRemaining": "14m30s", "cooldownRemaining": "12m30s", "dailyUsageToday": "2h15m30s", "dailyRemaining": "1h44m30s" } } ``` ### playtime.extend **Access:** `playtime.extend` capability (localhost, or an authenticated admin client). Grant extra time to the playtime session currently being limited, without stopping what is playing and without changing any configured limit. The recipient is never named by the caller: a grant always applies to the profile playtime is being enforced against at that moment, so it cannot be aimed at someone else's session. A `duration` grant is held against the current session only and is cleared when that session resets — when a different profile becomes active, when the cooldown window expires, or when limits are disabled. A `today` waiver survives all three because it is day-scoped: it lapses at the next local midnight and nowhere else. **The daily limit is never affected.** It remains the hard ceiling in both modes; raising it is a settings change, not a grant. **Modes:** - `duration` adds time to the current session's allowance. It requires a session to extend, so it is accepted during `active` and `cooldown` states but rejected during `reset`. Cooldown is the common case: the limit stopped the game and the player is about to relaunch. - `today` waives the session limit for the recipient profile until the next local midnight. It is day-scoped rather than session-scoped, so it is accepted in any state, and it is rejected when the system clock is unreliable. A single duration grant must be between 1 minute and 24 hours, and the total accumulated across one session is capped at 24 hours. A grant that would exceed the cap is rejected rather than reduced, so a caller is never told less time was added than it asked for. The same grant can also be made by scanning a physical card holding `**playtime.extend`, authorized by an administrator profile's switch ID rather than by a paired client. #### Parameters | Key | Type | Required | Description | | :-------- | :----- | :------- | :---------------------------------------------------------------------------------------------------------------- | | mode | string | Yes | `"duration"` or `"today"`. | | duration | string | No | Time to add, in Go duration format (e.g. `"15m"`, `"1h30m"`). Required for `"duration"` mode, ignored for `"today"`. | | requestId | string | No | Idempotency key. Repeating a request ID reports the original grant instead of adding more time. | #### Result | Key | Type | Required | Description | | :--------------- | :------ | :------- | :----------------------------------------------------------------------------------- | | mode | string | Yes | The mode that was applied. | | replayed | boolean | Yes | True when a repeated `requestId` matched an earlier grant and no time was added. | | duration | string | No | Time this grant added. Omitted for `"today"`. | | expires | string | No | RFC 3339 timestamp when a `"today"` waiver lapses. Omitted for `"duration"`. | | sessionExtension | string | No | The session's accumulated extension after this grant. | | profileId | string | No | Recipient profile. Omitted for the shared profile. | A successful grant emits [`playtime.extended`](./notifications.md#playtimeextended). A replayed request granted nothing, so it emits no notification. #### Examples ##### Request ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5e-11ef-9c7b-020304050607", "method": "playtime.extend", "params": { "mode": "duration", "duration": "15m", "requestId": "5f2c9a10-1d44-4f8e-9f0b-6d1c2a3b4c5d" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5e-11ef-9c7b-020304050607", "result": { "mode": "duration", "duration": "15m0s", "sessionExtension": "15m0s", "profileId": "0194e2a1-6c3f-7b21-9d4e-8a5b6c7d8e9f", "replayed": false } } ``` ##### Response (waiving the session limit for the rest of the day) ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-7a5e-11ef-9c7b-020304050607", "result": { "mode": "today", "expires": "2025-01-23T00:00:00-05:00", "profileId": "0194e2a1-6c3f-7b21-9d4e-8a5b6c7d8e9f", "replayed": false } } ``` ### settings.playtime.limits **Access:** All clients. Get current playtime limit configuration. Returns all configured playtime limits including daily limits, session limits, session reset timeout, warning intervals, and retention settings. #### Parameters None. #### Result | Key | Type | Required | Description | | :----------- | :------- | :------- | :--------------------------------------------------------------------------------------------------------------------- | | enabled | boolean | Yes | Whether playtime limits are enabled for enforcement. | | daily | string | No | Daily playtime limit in Go duration format (e.g., `"4h"`). Omitted if not configured. | | session | string | No | Per-session playtime limit in Go duration format (e.g., `"1h"`). Omitted if not configured. | | sessionReset | string | No | Idle timeout before session auto-resets in Go duration format (e.g., `"20m"`). `"0s"` means session never resets. | | warnings | string[] | Yes | List of time intervals when warnings are sent before limits reached (e.g., `["5m", "2m", "1m"]`). Empty array if none. | | retention | number | No | Number of days to retain playtime history. Omitted if not configured. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "b2c3d4e5-7a5e-11ef-9c7b-020304050607", "method": "settings.playtime.limits" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "b2c3d4e5-7a5e-11ef-9c7b-020304050607", "result": { "enabled": true, "daily": "4h", "session": "1h", "sessionReset": "20m", "warnings": ["5m", "2m", "1m"], "retention": 30 } } ``` ### settings.playtime.limits.update **Access:** Requires `settings.write`. Update playtime limit settings. This method updates one or more playtime limit configuration values in-memory and saves changes to disk. Only provided fields will be updated; omitted fields remain unchanged. #### Parameters An object containing any of the following optional keys: | Key | Type | Required | Description | | :----------- | :------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------- | | enabled | boolean | No | Enable or disable playtime limit enforcement. | | daily | string | No | Daily playtime limit in Go duration format (e.g., `"4h"`, `"2h30m"`). Use `"0"` or `"0s"` to disable daily limit. | | session | string | No | Per-session playtime limit in Go duration format (e.g., `"1h"`, `"45m"`). Use `"0"` or `"0s"` to disable session limit. | | sessionReset | string | No | Idle timeout before session auto-resets in Go duration format (e.g., `"20m"`). Use `"0"` or `"0s"` for sessions that never reset. | | warnings | string[] | No | List of time intervals for warnings in Go duration format (e.g., `["10m", "5m", "1m"]`). Empty array disables warnings. | | retention | number | No | Number of days to retain playtime history. Use `0` for no retention limit. | **Important:** Duration strings must use Go duration format: combinations of hours (`h`), minutes (`m`), and seconds (`s`). Examples: `"1h"`, `"30m"`, `"1h30m"`, `"2h15m30s"`. #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "c3d4e5f6-7a5e-11ef-9c7b-020304050607", "method": "settings.playtime.limits.update", "params": { "enabled": true, "session": "1h", "warnings": ["10m", "5m", "2m"] } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "c3d4e5f6-7a5e-11ef-9c7b-020304050607", "result": null } ``` ## Decks A deck is a persistent, ordered list of games and cards the user keeps on the device. It is the one list type Zaparoo syncs with a linked online account, and everything about it works with no account: the ID is minted on the device, and a deck reached through a ZapLink is cached in the same list as a read-only copy. Every deck has a twelve-character ID drawn from the Crockford base32 alphabet (digits and letters without I, L, O and U). Core stores and shows it lower-case and matches it without regard to case; IDs of eight characters from older decks are also accepted, and may use any digit or letter. The same ID names the deck on the device, in its `user:deck:` tag, on a card and on the account. A deck opens as a playlist from ZapScript with `**playlist.open:deck://` (and `playlist.load` and `playlist.play` accept the same argument), from the API with `decks.open`, or by tapping a ZapLink that serves it. Any ZapLink, on any host, whose ZapScript is a single `playlist.open`, `playlist.play` or `playlist.load` command carrying a JSON playlist is kept on the device as a read-only deck, so it opens offline next time, shows in the deck list and has its games tagged. The copy is known by the link it was fetched from and gets a deck ID minted on this device; nothing in the link or the playlist is used as its ID, so it can never replace or stand in for a deck the user owns. At most 200 decks are kept from links; past that the one fetched longest ago is removed. A deck made on the device opens as the playlist ID `deck://`, and a deck kept from a link opens as the `id` its playlist was served with, so reopening the deck that is playing recognises it as the deck already open whichever way it was opened: `playlist.open` keeps its position, and `playlist.play` moves it on to the next item. A link the linked account vouches for as the user's own runs as served and is not kept as a copy. A deck item is either a `script` (a name and the ZapScript it runs) or a `card` (an online card by ID, with its scripts and display metadata as pulled). A game added from the local library is stored as a script item: Core composes `**launch.title:/` with the file's disambiguating tags, so the item names the same game on any device, and keeps the file it was added from as the item's `media` so this device launches exactly that file. Card and deck `metadata` are stored as received and returned verbatim. Every indexed file a deck's game items resolve to carries the tag `user:deck:<id>`, so a deck can be browsed, searched and picked from with the ordinary tag filters, for example `**launch.random:SNES?tags=user:deck:0k3v9x2rq7bm`. An item resolves by the file it is linked to, or by its title when it has no linked file on this device or that file is no longer indexed, in which case it is linked to the file it matched. A title match only counts when it is a confident one. When the linked file is still indexed but was not found by the last scan, such as a file on a drive that was unplugged, the item keeps its link and its title match carries the tag until the file is found again. Tags are updated in the background shortly after a deck is created, edited or deleted, so `decks.new` and `decks.update` return before they are in place, and a title item is linked once its title has been matched; Core sends `decks.changed` with `updated` when it links items. The tags are also rebuilt after every reindex, after `media.clean.orphans` removes files and after a backup is restored. Deck tags cannot be set through `media.tags.update`. A deck can have a cover image. Set one with `decks.update` `cover`, from a game's art or an image file on the Core host; Core stores it with the user's data, not in the thumbnail cache. A deck synced with the account, or a card in a deck, may also have an image held online. Clients ask Core for any of these with [`decks.image`](#decksimage) and never fetch them themselves: Core fetches online images (https only, at most 10 MiB) and keeps them in its thumbnail cache. Decks work with no account. With Library sync on, the decks this device owns sync with the linked Zaparoo Online account: a deck made on either side appears on the other, an edit on one side is taken by the other, and when both sides edited a deck the changes are merged, with a name or description changed on the device kept. A deck deleted on the account is deleted here. Decks the account saved from other accounts are kept on the device as read-only copies of their links, marked `saved`, and are not counted toward the 200 decks kept from links; a saved deck is removed when the account no longer lists it. A cover set or removed on the device is sent to the account with the deck; a deck created on the device sends its cover once the account has created the deck. An image the account sends for a deck replaces the cover stored here, unless a cover change made here is still waiting to be sent. A deck the account locked keeps the account's image, and a cover change made here before the lock is dropped. Creating, editing and deleting decks is open to every accepted client, like favorites. ### Deck object | Key | Type | Required | Description | | :---------- | :------------------------------- | :------- | :------------------------------------------------------------------- | | deckId | string | Yes | The deck's ID, lower-case. | | name | string | Yes | Display name, at most 100 characters. | | description | string | Yes | Description, at most 1000 characters. Empty when unset. | | owned | boolean | Yes | True for decks made on this device or its account; false for a cached copy of somebody else's deck, which cannot be edited. | | locked | boolean | Yes | True when the linked Zaparoo Online account locked the deck. A locked deck cannot be edited or deleted on the device. | | saved | boolean | Yes | True for a copy of a deck the linked account saved from another account. It follows the account's saved list: it is kept while the account lists it and removed when it stops. | | ownedBy | string | No | The owner's name as the account gave it, for a saved deck. Omitted when the account gave none. | | sourceUrl | string | No | The link a deck that is not owned was fetched from. Omitted for owned decks. | | itemCount | number | Yes | Number of items in the deck. | | hasImage | boolean | Yes | True when the deck has a cover [`decks.image`](#decksimage) can serve: one stored on the device, or the account's image. | | containsItemIds | number[] | No | Only from `decks` given a game's `system` and `path`: the IDs of the items linked to exactly that file, `[]` when none. | | items | [DeckItem](#deck-item-object)[] | No | The deck's members in order, `[]` when empty. Omitted by `decks`. | | metadata | object | No | Display metadata as received from the account, verbatim. | | createdAt | number | Yes | Unix timestamp of creation. | | updatedAt | number | Yes | Unix timestamp of the last change. | ### Deck item object | Key | Type | Required | Description | | :-------- | :------- | :------- | :------------------------------------------------------------------------------------------ | | id | number | Yes | Item ID, kept while the item stays in the deck, including when other items are added, removed or moved. Used by `removeItemIds`. | | position | number | Yes | 1-based position in the deck. | | kind | string | Yes | `script` or `card`. | | name | string | Yes | Display name. | | zapscript | string | No | The ZapScript a `script` item runs. | | cardId | string | No | The online card a `card` item names. | | scripts | object[] | No | A `card` item's scripts, each `{name, zapscript}`. | | metadata | object | No | A `card` item's display metadata, verbatim. | | hasImage | boolean | Yes | True when a `card` item has art [`decks.image`](#decksimage) can serve (an https `rendered_url` or `image_url` in its metadata). Always false for other items; for a game item, ask [`media.image`](#mediaimage) with its `media.system` and `media.path`. | | media | object | No | The local file a game item is linked to: `system`, `path`, `name`, `tags`, `available` (whether the path is currently indexed) and `userTags`, the file's current user flags as [TagInfo](#taginfo-object)[] (any of `user:favorite`, `user:hidden`, `user:liked`, `user:disliked` and `user:playlater`, `[]` when none is set, always present with `media`). Absent for cards and for items added elsewhere that have not been resolved on this device. | ### Deck item input Items are supplied to `decks.new` and `decks.update` in this shape. A deck holds at most 120 items. In the `items` of `decks.update` only, an entry may instead be just `{"id": <item id>}`, which keeps that existing item unchanged at its place in the new list. | Key | Type | Required | Description | | :-------- | :------- | :------- | :------------------------------------------------------------------------------------------- | | kind | string | No | `media`, `script` or `card`. Required for every entry except an `id` entry. | | id | number | No | In `decks.update` `items` only: an item already in the deck to keep. Takes no other fields. | | mediaId | number | No | For `media`: the indexed media to add. Cannot be mixed with system/path. | | system | string | No | For `media`: system ID for path-based lookup. Required with `path`. | | path | string | No | For `media`: media path. Required with `system`. | | name | string | No | Display name. Required for `script`; overrides the indexed title for `media`. | | zapscript | string | No | Required for `script`. At most 5000 characters. | | cardId | string | No | Required for `card`. | | scripts | object[] | No | For `card`: the card's scripts, each `{name, zapscript}`. | | metadata | object | No | For `card`: display metadata to keep with the item. | ### decks **Access:** All clients. List every deck without its items. Given a game, every deck also says which of its items are linked to it, so a client can show which decks hold the game. #### Parameters Optional. An object: | Key | Type | Required | Description | | :----- | :----- | :------- | :------------------------------------------------------------------ | | system | string | No | System ID of a game. Required with `path`. | | path | string | No | Path of the game's file. Required with `system`. | With `system` and `path`, every deck in the result carries `containsItemIds`: the items whose linked file is exactly that system and path. One without the other is an error. #### Result | Key | Type | Required | Description | | :---- | :----------------------- | :------- | :------------- | | decks | [Deck](#deck-object)[] | Yes | List of decks, most recently changed first. | ### decks.get **Access:** All clients. Return one deck with its items. #### Parameters | Key | Type | Required | Description | | :----- | :----- | :------- | :----------- | | deckId | string | Yes | The deck ID. | #### Result A [Deck](#deck-object) with `items`. ### decks.new **Access:** All clients. Create a deck owned by this device. Core mints the ID. A deck holds at most 120 items; how many decks a device holds is not limited. #### Parameters | Key | Type | Required | Description | | :---------- | :----------------------------------- | :------- | :------------------------------------- | | name | string | Yes | Display name, at most 100 characters. | | description | string | No | At most 1000 characters. | | items | [DeckItemInput](#deck-item-input)[] | No | Members in order, at most 120. | #### Result The created [Deck](#deck-object) with `items`. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "5d8f1b6e-7a5d-11ef-9c7b-020304050607", "method": "decks.new", "params": { "name": "Weekend", "items": [ {"kind": "media", "mediaId": 42}, {"kind": "script", "name": "Something random", "zapscript": "**launch.random:SNES"} ] } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "5d8f1b6e-7a5d-11ef-9c7b-020304050607", "result": { "deckId": "0k3v9x2rq7bm", "name": "Weekend", "description": "", "owned": true, "locked": false, "itemCount": 2, "items": [ { "id": 1, "position": 1, "kind": "script", "name": "Super Metroid", "zapscript": "**launch.title:SNES/Super Metroid (region:us)", "media": { "system": "SNES", "path": "/media/fat/games/SNES/Super Metroid (USA).sfc", "name": "Super Metroid", "tags": ["region:us"], "available": true } }, { "id": 2, "position": 2, "kind": "script", "name": "Something random", "zapscript": "**launch.random:SNES" } ], "createdAt": 1726300000, "updatedAt": 1726300000 } } ``` ### decks.update **Access:** All clients. Edit an owned deck. A cached copy of somebody else's deck, and a deck the account locked, are read-only. Item edits are applied in the order remove, replace, append, and the result must hold at most 120 items. The whole edit is applied at once, to the deck as it is at that moment: if any part fails, nothing changes. A request with no changes returns the deck as it is and sends no notification. #### Parameters | Key | Type | Required | Description | | :------------ | :----------------------------------- | :------- | :------------------------------------------------------------- | | deckId | string | Yes | The deck ID. | | name | string | No | New display name. | | description | string | No | New description. | | items | [DeckItemInput](#deck-item-input)[] | No | Replaces the whole item list, in order. Entries given as `{"id": …}` keep that existing item and its ID, so a reorder is `items` listing the current IDs in the new order; any other entry is a new item. An ID the deck does not hold, or one listed twice, is an error. | | addItems | [DeckItemInput](#deck-item-input)[] | No | Items to append. | | removeItemIds | number[] | No | Item IDs to remove. An ID not in the deck is ignored. | | cover | object | No | Sets or removes the deck's cover; see below. | `cover` is one of: | Value | Effect | | :------------------------------------------------- | :------------------------------------------------------------------------------------------- | | `{"kind": "media", "system": "…", "path": "…"}` | The game's art, chosen the way `media.image` chooses it by default. | | `{"kind": "file", "path": "…"}` | An image file on the Core host, by absolute path. It must be a JPEG, PNG, GIF or WebP image of at most 10 MiB that decodes. | | `{"kind": "none"}` | Removes the cover. | A cover change works with no account and updates `updatedAt`. With Library sync on it is sent to the account; `none` removes the account's image. #### Result The updated [Deck](#deck-object) with `items`. ### decks.image **Access:** All clients. Return a deck's cover, or the art of one of its `card` items. A game item's art comes from [`media.image`](#mediaimage) with the item's `media.system` and `media.path`. The cover is the one stored on the device, or else the account's image for the deck. A card's art is its `rendered_url`, or else its `image_url`. Online images are fetched by Core over https only, at most 10 MiB, and kept in Core's thumbnail cache by URL, so a second request does not fetch again. #### Parameters | Key | Type | Required | Description | | :------- | :----- | :------- | :-------------------------------------------------------------------------- | | deckId | string | Yes | The deck ID. | | itemId | number | No | A `card` item of the deck. Omit for the deck's cover. | | maxSize | number | No | As in [`media.image`](#mediaimage): snapped to the same size tiers and resized the same way. Omit for the full image. | | delivery | string | No | `inline` (default) or `localPath`, as in [`media.image`](#mediaimage); `localPath` needs a positive `maxSize`. | #### Result The [`media.image`](#mediaimage) result: `delivery`, `contentType`, `extension`, `data` or `localPath`, and `typeTag`, which is `deck:cover` for a cover and `deck:card` for card art. When there is no image, the request fails with the client error `image not found`. An `itemId` the deck does not hold fails with `deck item not found`. ### decks.delete **Access:** All clients. Delete a deck, owned or cached. A deck the account locked cannot be deleted. #### Parameters | Key | Type | Required | Description | | :----- | :----- | :------- | :----------- | | deckId | string | Yes | The deck ID. | #### Result None. ### decks.open **Access:** All clients. Open a deck as the active playlist. This runs `**playlist.open:deck://<id>`, the same command a card can carry, and returns once it has run, like [`run`](#run). Before a deck opens it is brought up to date when that is quick: a cached copy of somebody else's deck is fetched again from its link, and a deck that syncs with an online account is pulled. Either way a slow or offline service never delays the open for more than a few seconds, and the local copy opens when the refresh fails. A fetch that brings nothing new costs no write, and an item a fetch leaves unchanged keeps the file it is linked to on this device, so a refreshed deck goes on launching the files the user picked. A game item whose linked file is still indexed launches that exact file; any other game item runs its title launch. A card item runs its script, or opens its scripts as a nested playlist when it has several, the way the card's own link does. #### Parameters | Key | Type | Required | Description | | :----- | :----- | :------- | :------------------------------------------------------- | | deckId | string | Yes | The deck ID. | | slot | string | No | Media slot to open the playlist in, as the playlist commands' `slot` argument. | #### Result None. ## Profiles Profiles are lightweight runtime identities: named buckets of preferences, limits, and profile-owned data. One profile is active per device at a time, switched via the API or by scanning an NFC card containing the profile's switch ID (`**profile:<switchId>`). Profile roles (`admin` or `member`) are separate from paired-client roles: profile roles identify who may authorize local household management, while client roles describe which remote device may call privileged APIs. When no personal profile is active the device is on the implicit **shared profile** — the device as it behaves when nobody is signed in. The shared profile's playtime limits are the global config limits, its history is unattributed, and it owns everything the device did before profiles existed. Deactivating means switching to the shared profile. To stop the shared profile launching media (parking the device until someone identifies themselves), enable the `profilesRequireForLaunch` setting (see [settings](#settings)). A profile's **switch ID is a bearer credential**: presenting it — by scanning the card it is written on, or by sending it over the API — authorizes switching to that profile with no PIN, on every path. Switch IDs are therefore only returned to clients with `profiles.manage` for card-writing. This includes localhost, paired admins, and legacy unpaired remote clients when encryption is disabled; paired members never see them. The optional 4-8 digit **PIN** protects the remaining path: switching by `profileId` picked from the visible profile list. Leaving a profile is always free — PINs gate entry only. **Data swapping.** On supported platforms (currently MiSTer), profile-owned platform data follows the active profile. This includes saved progress and supported account-specific settings; exact items depend on the platform and installed integrations. The shared profile continues to use the platform's existing data, and creating profiles does not move that data. Device-owned settings remain shared across profiles. A swap requested while media is running is deferred until it stops, so the running session keeps the data it launched with. Progress and failures are reported by the [`profiles.data`](notifications.md#profilesdata) notification; the `profilesSwapData` setting turns swapping off. Deleting a profile does not delete its profile-owned platform data. **Administration and trust model.** The first profile is created as `admin` and must have a PIN; later profiles default `member`. The first paired client is `admin`; later pairings default `member`. Sensitive local UIs call `profiles.verify`, confirm the returned profile has the `admin` role, then send the ordinary management request. This is a client-side nuisance gate for parental and kiosk controls, not cryptographic request authorization; no unlock session is retained. Admin paired clients use their client capability directly. The last admin profile/client cannot be removed or demoted. Profiles remain a household convenience boundary, comparable to TV parental controls — not OS account security. Anyone with OS access still owns the device, and while `service.encryption` is off an unpaired remote client retains legacy admin API capability, apart from the capabilities that require an authenticated connection — currently `update.apply`. Enabling encryption makes paired-client restrictions enforceable. ### Profile object | Key | Type | Required | Description | | :------------ | :------ | :------- | :------------------------------------------------------------------------------------------------------- | | profileId | string | Yes | Unique identifier of the profile. | | name | string | Yes | Display name, e.g. "Dad" or "Kid A". | | role | string | Yes | `admin` or `member`. Admin profiles may authorize local management and must have a PIN. | | switchId | string | No | Word phrase written to profile switch cards, e.g. `corn-arm-truck`. A bearer credential: presenting it switches to profile with no PIN. Returned only to clients with `profiles.manage`. | | hasPin | boolean | Yes | True when the profile has a PIN set. The PIN itself is never returned. | | limitsEnabled | boolean | No | Playtime limits enabled override. Omitted = inherit the global setting. | | dailyLimit | string | No | Daily playtime limit override as a duration string (e.g. `2h30m`). Omitted = inherit; `0` = unlimited. | | sessionLimit | string | No | Session playtime limit override as a duration string. Omitted = inherit; `0` = unlimited. | | lastUsedAt | number | No | Unix timestamp of most recent successful profile activation. Omitted if never activated. | | createdAt | number | Yes | Unix timestamp of profile creation. | | lastUpdatedAt | number | Yes | Unix timestamp of last modification. | ### profiles **Access:** All clients. `switchId` is returned only to clients with `profiles.manage`. List all profiles. #### Parameters None. #### Result | Key | Type | Required | Description | | :------- | :--------------------------- | :------- | :---------------- | | profiles | [Profile](#profile-object)[] | Yes | List of profiles. | ### profiles.new **Access:** Requires `profiles.manage`. Create a new profile. Local UIs may use `profiles.verify` as a nuisance gate. The switch ID is generated automatically; write it to a card as `**profile:<switchId>`. #### Parameters | Key | Type | Required | Description | | :------------ | :------ | :------- | :---------------------------------------------------------------- | | name | string | Yes | Display name. | | role | string | No | `admin` or `member`; later profiles default member. First profile is always admin. | | pin | string | No | Optional 4-8 digit PIN required to switch by `profileId`; mandatory for admin profiles. | | limitsEnabled | boolean | No | Playtime limits enabled override. | | dailyLimit | string | No | Daily limit duration override. | | sessionLimit | string | No | Session limit duration override. | #### Result The created [profile object](#profile-object). ### profiles.update **Access:** Requires `profiles.manage`. Update a profile. Local UIs may gate this action with `profiles.verify`. Migrated profiles without an administrator may still be recovered locally. Omitted fields are unchanged. If the updated profile is currently active, its limit changes apply immediately (without resetting the running session). #### Parameters | Key | Type | Required | Description | | :----------------- | :------ | :------- | :---------------------------------------------------------------------- | | profileId | string | Yes | Profile to update. | | name | string | No | New display name. | | role | string | No | Change between `admin` and `member`; final admin cannot be demoted. | | pin | string | No | Set or replace the PIN; admin profiles must retain one. | | clearPin | boolean | No | Remove the PIN. | | limitsEnabled | boolean | No | Playtime limits enabled override. | | dailyLimit | string | No | Daily limit duration override. | | sessionLimit | string | No | Session limit duration override. | | clearLimits | boolean | No | Reset all limit overrides back to inheriting the global config, before any limit fields in the same request are applied. | | regenerateSwitchId | boolean | No | Issue a new switch ID (lost-card replacement). Old cards stop working. | #### Result The updated [profile object](#profile-object). ### profiles.delete **Access:** Requires `profiles.manage`. Delete a profile. Local UIs may gate this action with `profiles.verify`. The final admin profile cannot be deleted. If it is active, the device switches to the shared profile. Past play history keeps its attribution. #### Parameters | Key | Type | Required | Description | | :-------- | :----- | :------- | :----------------- | | profileId | string | Yes | Profile to delete. | #### Result Returns `null` on success. ### profiles.active **Access:** All clients. Get the device's currently active profile. #### Parameters None. #### Result The active profile (a subset of the [profile object](#profile-object) without `switchId` and timestamps), or null when no profile is active. ### profiles.switch **Access:** All clients. Profile PIN or switch ID may still be required. Switch the device's active profile. Switching by `profileId` requires the profile's PIN when one is set. Switching by `switchId` never requires a PIN: the switch ID is a bearer credential, and presenting it is equivalent to scanning the profile's card. Calling with neither `profileId` nor `switchId` switches to the shared profile (deactivates), which never requires a PIN. Providing both is an error. If a game is running when the profile changes, its playtime keeps counting against the profile that launched it: switching to another profile starts a fresh limit session for the new person, while deactivating leaves the launch profile's limits in force until the media stops. #### Parameters | Key | Type | Required | Description | | :-------- | :----- | :------- | :------------------------------------------------------ | | profileId | string | No | Profile to activate, by ID. Requires `pin` when the profile has one. | | switchId | string | No | Profile to activate, by switch ID (bearer credential; no PIN needed). | | pin | string | No | The profile's PIN, for `profileId` switching. | #### Result The new active profile, or null when deactivated (shared profile). ### profiles.verify **Access:** All clients. Requires valid profile PIN or switch ID. Verify a profile credential **without switching**: either a profile ID plus its PIN, or a switch ID (a bearer credential — resolving it is the verification, same as scanning the card). Success returns the profile's identity and changes nothing on the device: no session, no active-profile change, no server-side grant of any kind. Clients use this to gate their own ad-hoc UI items behind a credential — e.g. a kiosk frontend requiring a parent's PIN before opening its settings screen. The security of whatever the client unlocks is entirely the client's responsibility. PIN attempts share the same per-profile rate limiter as `profiles.switch`, so this method cannot be used to brute-force a PIN any faster than switching attempts could. #### Parameters | Key | Type | Required | Description | | :-------- | :----- | :------- | :-------------------------------------------------------- | | profileId | string | No | Profile to verify against. Requires `pin` when the profile has one. | | switchId | string | No | Verify by switch ID (bearer credential; no PIN needed). | | pin | string | No | The profile's PIN, for `profileId` verification. | Exactly one of `profileId` or `switchId` is required. #### Result | Key | Type | Required | Description | | :-------- | :------ | :------- | :---------------------------------------- | | profileId | string | Yes | ID of the verified profile. | | name | string | Yes | Display name of the verified profile. | | role | string | Yes | Profile role (`admin` or `member`). | | hasPin | boolean | Yes | Whether the profile has a PIN set. | Verification failure (wrong PIN, unknown profile or switch ID, rate limited) returns an error, using the same errors as `profiles.switch`. ## Mappings Mappings are used to modify the contents of tokens before they're launched, based on different types of matching parameters. Stored mappings are queried before every launch and applied to the token if there's a match. This allows, for example, adding ZapScript to a read-only NFC tag based on its UID. ### mappings **Access:** All clients. List all mappings. Returns a list of all active and inactive mappings entries stored on server. #### Parameters None. #### Result | Key | Type | Required | Description | | :------- | :--------------------------- | :------- | :------------------------------------------------------------------ | | mappings | [Mapping](#mapping-object)[] | Yes | List of all stored mappings. See [mapping object](#mapping-object). | ##### Mapping object | Key | Type | Required | Description | | :------- | :------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | Yes | Internal database ID of mapping entry. Used to reference mapping for updates and deletions. | | added | string | Yes | Timestamp of the time mapping was created in RFC3339 format. | | label | string | Yes | An optional display name shown to the user. | | enabled | boolean | Yes | True if the mapping will be used when looking up matching mappings. | | type | string | Yes | The field which will be matched against:<br/>_ `uid`: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.<br/>_ `text`: match on the stored text on token.<br/>\* `data`: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this. | | match | string | Yes | The method used to match a mapping pattern:<br/>_ `exact`: match the entire string exactly to the field.<br/>_ `partial`: match part of the string to the field.<br/>\* `regex`: use a regular expression to match the field. | | pattern | string | Yes | Pattern that will be matched against the token, using the above settings. | | override | string | Yes | Final text that will completely replace the existing token text if a match was successful. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "1a8bee28-7aef-11ef-8427-020304050607", "method": "mappings" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "1a8bee28-7aef-11ef-8427-020304050607", "result": { "mappings": [ { "id": "1", "added": "1970-01-21T06:08:18+08:00", "label": "barcode pokemon", "enabled": true, "type": "text", "match": "partial", "pattern": "9780307468031", "override": "**launch.search:gbc/*pokemon*gold*" } ] } } ``` ### mappings.new **Access:** All clients. Create a new mapping. #### Parameters An object: | Key | Type | Required | Description | | :------- | :------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | label | string | Yes | An optional display name shown to the user. | | enabled | boolean | Yes | True if the mapping will be used when looking up matching mappings. | | type | string | Yes | The field which will be matched against:<br/>_ `uid`: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.<br/>_ `text`: match on the stored text on token.<br/>\* `data`: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this. | | match | string | Yes | The method used to match a mapping pattern:<br/>_ `exact`: match the entire string exactly to the field.<br/>_ `partial`: match part of the string to the field.<br/>\* `regex`: use a regular expression to match the field. | | pattern | string | Yes | Pattern that will be matched against the token, using the above settings. | | override | string | Yes | Final text that will completely replace the existing token text if a match was successful. At most 8192 bytes. | #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "method": "mappings.new", "params": { "label": "Test Mapping", "enabled": true, "type": "text", "match": "exact", "pattern": "test", "override": "**launch.system:snes" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "result": null } ``` ### mappings.delete **Access:** All clients. Delete an existing mapping. #### Parameters An object: | Key | Type | Required | Description | | :-- | :----- | :------- | :---------------------- | | id | number | Yes | Database ID of mapping. | #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "method": "mappings.delete", "params": { "id": 1 } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "result": null } ``` ### mappings.update **Access:** All clients. Change an existing mapping. #### Parameters An object: | Key | Type | Required | Description | | :------- | :------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | number | Yes | Internal database ID of mapping entry. | | label | string | No | An optional display name shown to the user. | | enabled | boolean | No | True if the mapping will be used when looking up matching mappings. | | type | string | No | The field which will be matched against:<br/>_ `uid`: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.<br/>_ `text`: match on the stored text on token.<br/>\* `data`: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this. | | match | string | No | The method used to match a mapping pattern:<br/>_ `exact`: match the entire string exactly to the field.<br/>_ `partial`: match part of the string to the field.<br/>\* `regex`: use a regular expression to match the field. | | pattern | string | No | Pattern that will be matched against the token, using the above settings. | | override | string | No | Final text that will completely replace the existing token text if a match was successful. At most 8192 bytes. | Only keys which are provided in the object will be updated in the database. #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "e98fd686-7e62-11ef-8f8c-020304050607", "method": "mappings.update", "params": { "id": 1, "enabled": false } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "e98fd686-7e62-11ef-8f8c-020304050607", "result": null } ``` ### mappings.reload **Access:** All clients. Reload mappings from the configuration file. #### Parameters None. #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "method": "mappings.reload" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "result": null } ``` ## Readers ### readers **Access:** All clients. List all currently connected readers and their capabilities. #### Parameters None. #### Result | Key | Type | Required | Description | | :---------------- | :------------------------- | :------- | :---------------------------------- | | readers | [ReaderInfo](#reader-info-object)[] | Yes | A list of all connected readers. | | holdOwnerReaderId | string | No | ID of the reader whose token is currently tracked as the owner of the running media. Omitted when no token is tracked. | | holdScanMode | string | No | Effective scan mode of that token, including a `#tap` or `#hold` override on the token itself. A tracked owner can be `tap`: the token still owns the running media, its removal just does not exit. This is resolved exactly as the removal will resolve it, so an owner whose reader has since disconnected reports `hold` — the decision made while that reader was present still stands. | ##### Reader info object | Key | Type | Required | Description | | :----------- | :------- | :------- | :-------------------------------------------- | | id | string | Yes | Device path or system identifier of the reader. Legacy field, prefer `readerId` for stable identification. | | readerId | string | Yes | Stable reader ID, deterministic across restarts. Format: `{driver}-{hash}`. | | driver | string | Yes | Driver type for the reader (e.g., `"pn532"`, `"ccid"`, `"file"`). | | info | string | Yes | Human-readable information about the reader. | | scanMode | string | Yes | Effective scan mode for this reader (`"tap"` or `"hold"`), resolving its `[[readers.connect]]` entry, then its `[readers.drivers.<id>]` entry, then the global `readers.scan.mode`. | | connected | boolean | Yes | Whether the reader is currently connected. | | capabilities | string[] | Yes | List of capabilities supported by the reader. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "method": "readers" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "result": { "readers": [ { "id": "/dev/ttyUSB0", "readerId": "pn532-ujqixjv6", "driver": "pn532", "info": "PN532 (1-2.3.1)", "scanMode": "tap", "capabilities": ["read", "write"], "connected": true } ], "holdOwnerReaderId": "pn532-ujqixjv6", "holdScanMode": "tap" } } ``` ### readers.write **Access:** All clients. Attempt to write given text to the first available write-capable reader, if possible. #### Parameters An object: | Key | Type | Required | Description | | :------- | :----- | :------- | :--------------------------------------------------------------------------- | | text | string | Yes | ZapScript to be written to the token. | | readerId | string | No | ID of a specific reader to write to. If omitted, uses the first available write-capable reader. | #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "method": "readers.write", "params": { "text": "**launch.system:snes" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "result": null } ``` ### readers.write.cancel **Access:** All clients. Cancel any ongoing write operation. #### Parameters Optionally, an object: | Key | Type | Required | Description | | :------- | :----- | :------- | :----------------------------------------------------------------------------- | | readerId | string | No | ID of a specific reader to cancel write on. If omitted, cancels on all readers. | #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "method": "readers.write.cancel" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "562c0b60-7ae8-11ef-87d7-020304050607", "result": null } ``` ## Launchers ### launchers **Access:** All clients. List all launchers known to the running service. Suitable for populating a UI launcher picker (for example, when assigning a per-system default via [settings.update](#settingsupdate)). Core's internal launchers for virtual systems and virtual media (`zaparoo://` URIs) are not listed, since each can only launch its own entry. #### Parameters | Key | Type | Required | Description | | :---------- | :------- | :------- | :-------------------------------------------------------------------------------------------------- | | systems | string[] | No | Case-insensitive list of system IDs to restrict results to. A missing key or empty list returns every launcher. Values not matching any launcher's system return no launchers for that value, rather than an error, since launcher system IDs can be launchable or virtual systems outside the standard system list. | | fuzzySystem | boolean | No | Also resolve a system-ID alias to its canonical ID before matching (e.g., `"megadrive"` matches `"Genesis"`). Matching is always case-insensitive regardless of this flag. | The unfiltered response can be large on platforms with many launchers (250+ on MiSTer). Pass `systems` to scope the request when looking up a specific system's launchers. #### Result | Key | Type | Required | Description | | :-------- | :------------------------------------ | :------- | :--------------------------- | | launchers | [Launcher](#launcher-object)[] | Yes | Matching cached launchers, sorted by `systemId` then `id`. | ##### Launcher object | Key | Type | Required | Description | | :------------------ | :------- | :------- | :----------------------------------------------------------------------------------------------------- | | id | string | Yes | Unique launcher identifier. | | systemId | string | No | The system this launcher targets. Omitted for generic launchers without a fixed system. | | systemName | string | No | Human-readable system name resolved from system metadata. Omitted when no metadata is available. | | groups | string[] | No | Group names this launcher belongs to. Group names are valid values for `systemDefaults.launcher`. | | available | boolean | Yes | Whether this launcher's runtime dependencies are currently satisfied. | | availabilityReason | string | No | Why the launcher is unavailable. Omitted when `available` is `true`. | | detected | boolean | No | Whether the platform looked for this launcher and found it installed. Omitted when the platform does not check its launchers, which is every platform that reports nothing here; an omitted value means unknown, not missing. Distinct from `available`, which is about the launcher's runtime dependencies. | | default | boolean | No | Whether this launcher is the configured default for its system (`systemDefaults.launcher`, matched by launcher ID or by any of `groups`). Omitted (implicitly `false`) otherwise. | | backend | string | No | What kind of thing this launcher runs. Currently only `mister_core` is emitted. Omitted when the platform has nothing to say about this launcher. Clients must ignore backend values they don't recognize. | | misterCore | [MisterCoreInfo](#mistercoreinfo-object) | No | Present when `backend` is `mister_core` and the core is installed. Absent when the core isn't installed; `available` and `availabilityReason` say why. | ##### MisterCoreInfo object | Key | Type | Required | Description | | :------ | :----- | :------- | :------------------------------------------------------------------------------------------------ | | name | string | Yes | RBF short name, e.g. `"3DO"`. | | file | string | Yes | Installed RBF filename, e.g. `"3DO_20250101.rbf"`. Identifies the installed core version. | | mglPath | string | Yes | SD-relative core identity used to launch it, e.g. `"_Console (Dual SDRAM)/3DO"`. Never an absolute filesystem path. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "5b8c3a40-7a5e-11ef-88ff-020304050607", "method": "launchers", "params": { "systems": ["3DO"] } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "5b8c3a40-7a5e-11ef-88ff-020304050607", "result": { "launchers": [ { "id": "3DO", "systemId": "3DO", "systemName": "3DO", "available": true, "default": true, "backend": "mister_core", "misterCore": { "name": "3DO", "file": "3DO_20250101.rbf", "mglPath": "_Console/3DO" } }, { "id": "DualRAM3DO", "systemId": "3DO", "systemName": "3DO", "available": false, "availabilityReason": "core not installed: _Console (Dual SDRAM)/3DO", "backend": "mister_core" } ] } } ``` ### launchers.refresh **Access:** All clients. Refresh internal launcher cache, forcing reload of launcher configurations and supported platform launcher dependencies. On MiSTer, this forces an RBF filesystem rescan and rewrites the persisted RBF cache. #### Parameters None. #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "af60e4a0-7a5e-11ef-88ff-020304050607", "method": "launchers.refresh" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "af60e4a0-7a5e-11ef-88ff-020304050607", "result": null } ``` ## Service ### version **Access:** All clients. Return server's current version and platform. #### Parameters None. #### Result | Key | Type | Required | Description | | :------- | :----- | :------- | :-------------------------------------------------- | | platform | string | Yes | ID of platform the service is currently running on. | | version | string | Yes | Current version of the running Zaparoo service. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "ca47f646-7e47-11ef-971a-020304050607", "method": "version" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "ca47f646-7e47-11ef-971a-020304050607", "result": { "platform": "mister", "version": "2.0.0-dev" } } ``` ### health **Access:** All clients. Simple health check to verify the server is running and responding. #### Parameters None. #### Result | Key | Type | Required | Description | | :----- | :----- | :------- | :----------------------------------------------- | | status | string | Yes | Health status. Returns `"ok"` when server is healthy. | | state | string | Yes | Lifecycle state. Always `"ready"` here, because this method only answers once the service is fully started. The HTTP `/health` route reports `"starting"` and `"failed"` as well. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "db58f757-7e47-11ef-982b-020304050607", "method": "health" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "db58f757-7e47-11ef-982b-020304050607", "result": { "status": "ok", "state": "ready" } } ``` ## Inbox Inbox messages are system notifications stored on the server, typically used to inform the user of events like update availability, errors, or other important information. ### inbox **Access:** All clients. List all inbox messages. #### Parameters None. #### Result | Key | Type | Required | Description | | :------- | :--------------------------------- | :------- | :------------------------ | | messages | [InboxMessage](#inbox-message-object)[] | Yes | List of inbox messages. | ##### Inbox message object | Key | Type | Required | Description | | :-------- | :----- | :------- | :----------------------------------------------- | | id | number | Yes | Unique identifier of the message. | | title | string | Yes | Title of the message. | | body | string | No | Body text of the message. | | severity | number | Yes | Severity level (0=info, 1=warning, 2=error). | | category | string | No | Category of the message. | | profileId | number | No | Associated profile ID, if applicable. | | createdAt | string | Yes | Timestamp when message was created in RFC3339 format. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "ec69f868-7e47-11ef-993c-020304050607", "method": "inbox" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "ec69f868-7e47-11ef-993c-020304050607", "result": { "messages": [ { "id": 1, "title": "Update Available", "body": "A new version of Zaparoo is available.", "severity": 0, "category": "update", "createdAt": "2024-09-24T17:49:42.938167429+08:00" } ] } } ``` ### inbox.delete **Access:** All clients. Delete a specific inbox message by ID. #### Parameters An object: | Key | Type | Required | Description | | :-- | :----- | :------- | :---------------------------- | | id | number | Yes | ID of the message to delete. | #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "fd7a0979-7e47-11ef-9a4d-020304050607", "method": "inbox.delete", "params": { "id": 1 } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "fd7a0979-7e47-11ef-9a4d-020304050607", "result": null } ``` ### inbox.clear **Access:** All clients. Delete all inbox messages. #### Parameters None. #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "0e8b1a8a-7e48-11ef-9b5e-020304050607", "method": "inbox.clear" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "0e8b1a8a-7e48-11ef-9b5e-020304050607", "result": null } ``` ## Clients ### clients **Access:** Localhost only. List paired API clients. Pairing secrets and authentication tokens are never returned. #### Parameters None. #### Result | Key | Type | Required | Description | | :----- | :---------------------------------------- | :------- | :---------- | | clients | [PairedClient](#paired-client-object)[] | Yes | Paired client metadata. | ##### Paired client object | Key | Type | Required | Description | | :-------- | :----- | :------- | :---------- | | clientId | string | Yes | Opaque client ID. | | clientName | string | Yes | Name supplied by client during pairing. | | role | string | Yes | Paired role: `admin` or `member`. | | createdAt | number | Yes | Pairing time as Unix seconds. | | lastSeenAt | number | Yes | Latest recorded activity as Unix seconds. | #### Example ```json { "jsonrpc": "2.0", "id": "clients-list-1", "method": "clients" } ``` ```json { "jsonrpc": "2.0", "id": "clients-list-1", "result": { "clients": [ { "clientId": "client-01J2", "clientName": "Zaparoo App", "role": "admin", "createdAt": 1783684800, "lastSeenAt": 1783688400 } ] } } ``` ### clients.current **Access:** All clients. Return effective access, pairing status, paired role, and named capabilities for current connection. This method is available to every connection accepted by API transport. `access` is one of `localhost`, `member`, `admin`, or `legacy`. A valid static API key reports `access: "admin"` with `paired: false` and `role: null`. `role` remains the stored paired role for authenticated paired connections, including paired localhost connections, and is `null` for unpaired localhost, API-key admin, and legacy. Clients should use capability presence for corresponding UI gates and treat role as display-only. Capability names currently include `profiles.manage`, `settings.write`, `input`, `screenshot`, and `update.apply`; the array does not enumerate every callable RPC method. #### Parameters None. #### Result | Key | Type | Description | | :----------- | :----------------- | :----------------------------------------------------------- | | access | string | Effective public authority: `localhost`, `member`, `admin`, or `legacy`. | | paired | boolean | Whether connection carries an authenticated paired identity. | | role | string or `null` | Paired client role, otherwise `null`. | | capabilities | array of strings | Effective named capabilities granted to current connection. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "1f9a258e-2f86-4bc9-a31b-ec842eb79a42", "method": "clients.current" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "1f9a258e-2f86-4bc9-a31b-ec842eb79a42", "result": { "access": "member", "paired": true, "role": "member", "capabilities": ["input", "screenshot"] } } ``` ### clients.delete **Access:** Localhost only. Revoke a paired client. Existing encrypted sessions remain active until they disconnect; future sessions cannot authenticate. #### Parameters | Key | Type | Required | Description | | :------- | :----- | :------- | :---------- | | clientId | string | Yes | Opaque client ID from `clients`. | #### Result Returns `null` on success. #### Example ```json { "jsonrpc": "2.0", "id": "clients-delete-1", "method": "clients.delete", "params": {"clientId": "client-01J2"} } ``` ```json { "jsonrpc": "2.0", "id": "clients-delete-1", "result": null } ``` ### clients.pair.start **Access:** Localhost only. Start a pairing approval window and return PIN for remote client. First paired client is always assigned `admin`; later clients default to `member` when `role` is omitted. #### Parameters An optional object: | Key | Type | Required | Description | | :--- | :----- | :------- | :---------- | | role | string | No | Role granted after pairing: `admin` or `member`. Defaults to `member` after first client. | #### Result | Key | Type | Required | Description | | :------- | :----- | :------- | :---------- | | pin | string | Yes | Temporary pairing PIN for remote client. | | expiresAt | number | Yes | PIN expiration time as Unix seconds. | See [encryption and pairing](./encryption) for remote pairing exchange. #### Example ```json { "jsonrpc": "2.0", "id": "clients-pair-start-1", "method": "clients.pair.start", "params": {"role": "member"} } ``` ```json { "jsonrpc": "2.0", "id": "clients-pair-start-1", "result": { "pin": "123456", "expiresAt": 1783685100 } } ``` ### clients.pair.cancel **Access:** Localhost only. Cancel active pairing approval window. #### Parameters None. #### Result Returns `null` on success. #### Example ```json { "jsonrpc": "2.0", "id": "clients-pair-cancel-1", "method": "clients.pair.cancel" } ``` ```json { "jsonrpc": "2.0", "id": "clients-pair-cancel-1", "result": null } ``` ## Online account ### online.status **Access:** All clients. Localhost and paired admin requests may trigger a background refresh of stale remote availability, the same as `settings.backup.status`; the response never waits for that network request. Report whether the device is linked to a Zaparoo Online account and which account features the Online service last reported for it. Core answers from stored state. Feature names are strings such as `cloud_backup` or `custom_branding`, passed through as the service lists them (deduplicated and sorted). Core itself reads only `cloud_backup`, which decides remote backup availability; other names are for clients. Core records them each time it checks the device with the Online service, which happens at startup, on link, before remote backups, on a daily heartbeat, and in the background refresh above. A failed check keeps the last reported features. Linking or unlinking the account clears them. #### Parameters None. #### Result | Key | Type | Required | Description | | :---------------- | :------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | | linked | boolean | Yes | Whether the device holds an online account credential that the server has not rejected. Matches `remote.linked` from `settings.backup.status`. | | deviceName | string | No | Name of this device on the Online account. Omitted when unlinked or unknown. | | linkedAt | string | No | RFC 3339 time the device was linked. Omitted when unlinked or unknown. | | features | string[] | Yes | Account features the Online service reported in its last successful check. Always an array; empty when unlinked or before the first check. | | featuresCheckedAt | string | Yes | RFC 3339 time of the last successful check, or `null` when no check has succeeded since the account was linked. An empty `features` list with a non-null time means the service reported no features. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "online-status-1", "method": "online.status" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "online-status-1", "result": { "linked": true, "deviceName": "Living Room MiSTer", "linkedAt": "2026-11-01T09:30:00Z", "features": ["cloud_backup", "custom_branding"], "featuresCheckedAt": "2026-11-06T12:00:00Z" } } ``` ## Remote control Remote control lets the Zaparoo Online account a device is linked to send a fixed set of commands to it (search and browse the media library, list systems and launchers, launch, stop, run a MiSTer script) through the Zaparoo Online API. It is off until the device owner turns on `remoteControlEnabled` in [settings.update](#settingsupdate), and is turned off again automatically whenever the account is linked or unlinked. Every command that reaches the device is recorded in a local ledger. ### remote.activity **Access:** Localhost and authenticated admin clients only. Return the current remote control status and the most recent entries from the remote command ledger, as an owner-facing record of what the linked account's remote commands have done on this device. #### Parameters | Key | Type | Required | Description | | :---- | :----- | :------- | :-------------------------------------------------------------- | | limit | number | No | Number of entries to return, between 1 and 100. Defaults to 20. | #### Result | Key | Type | Required | Description | | :------ | :----------------------------------------------------- | :------- | :------------------------------------------------ | | status | [RemoteStatus](#remote-status-object) | Yes | Why the device is or isn't reachable right now. | | entries | [RemoteActivityEntry](#remote-activity-entry-object)[] | Yes | Ledger entries, newest first. | ##### Remote status object | Key | Type | Required | Description | | :------------ | :----- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | state | string | Yes | `unknown` (nothing reported yet), `disabled` (remote control is off), `unlinked` (no linked account), `connecting`, `waiting` (polling for commands normally), `not_remote_device` (the server refused the poll because this device is not the account's designated remote device; choose it on Zaparoo Online), `unavailable` (the server reports the feature as off), `credential_rejected` (the server rejected the device credential; link the account again), or `error` (the last capability heartbeat or poll failed for another reason). | | lastContactAt | string | No | RFC 3339 time the remote service last answered normally, whether that was a capability heartbeat or a poll. Omitted until the first successful contact. | | lastErrorCode | string | No | The server's error code for the last failure (for example `remote_slot_required`), or a short local code such as `unreachable`. Omitted while the state carries no error. | ##### Remote activity entry object | Key | Type | Required | Description | | :------------ | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | | createdAt | string | Yes | RFC 3339 time the command was first received. | | operationType | string | Yes | The command type, for example `launch` or `media.search`. | | originKind | string | Yes | `first_party` when the account issued the command directly, or `api_key` when a User API key did. | | originKeyName | string | No | Name of the User API key that issued the command. Only present for `api_key` origins. | | state | string | Yes | Ledger state: `recorded`, `accepted`, `executing`, `terminal` (a result was produced), `void` (the server no longer knew the command), or `expired`. | | status | string | No | Outcome reported for a terminal entry: `succeeded`, `failed`, or `busy`. | | errorCode | string | No | Failure code for a failed entry, for example `bad_params`, `media_not_found`, or `unsupported`. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "remote-activity-1", "method": "remote.activity", "params": { "limit": 2 } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "remote-activity-1", "result": { "status": { "state": "waiting", "lastContactAt": "2026-08-30T01:02:03Z" }, "entries": [ { "createdAt": "2026-08-30T01:01:40Z", "operationType": "launch", "originKind": "api_key", "originKeyName": "misterzine", "state": "terminal", "status": "succeeded" }, { "createdAt": "2026-08-30T01:00:12Z", "operationType": "media.search", "originKind": "first_party", "state": "terminal", "status": "failed", "errorCode": "bad_params" } ] } } ``` ## Input Direct platform input control for remote control use cases. These methods bypass the token pipeline entirely: no hooks, history, or sound effects are triggered. The input macro format is identical to what goes after the `:` in a ZapScript `input.keyboard` or `input.gamepad` command on a token. Each character is a separate keypress, `{...}` groups are special keys/combos, and `\` is the escape character. Macros also support `{delay:duration}`, `{hold:key:duration}`, `{press:key}`, and `{release:key}`. Press and release have short forms `{_key}` and `{^key}`. Delay and explicit hold durations are limited to 30 seconds. Persistent `{press:key}` and `{release:key}` input is available only over supported WebSocket input sessions. A press remains held across requests from that WebSocket until its matching release. Press, release and hold accept a shifted character (`{press:M}`, `{press:!}`), which holds Shift together with the key, and a modifier combo (`{press:ctrl+c}`, `{press:shift+a}`). A release matches the press that names the same keys in any order, so `{release:shift+m}` releases `{press:M}` and `{release:shift+ctrl+a}` releases `{press:ctrl+shift+a}`. Keys are reference counted per WebSocket: a modifier stays down until the last held key that needs it is released. A WebSocket can hold at most 128 distinct key combinations at once. Each WebSocket owns its held keys and buttons; one connection cannot release another connection's input. Core releases all owned input when the WebSocket disconnects, input execution fails, or Core shuts down. HTTP JSON-RPC requests reject persistent press and release tokens because HTTP has no durable session lifecycle. Keys sent by a client that is neither localhost nor an admin are checked against the `allow` and `block` lists in the `[zapscript.input]` config section, the same lists the ZapScript input commands use. On desktop platforms a default block list rejects keys such as `{alt+f4}`, `{ctrl+alt+delete}` and the Linux TTY switches. Wrapping a key in a `{press:...}`, `{release:...}` or `{hold:...}` macro does not evade the lists. Setting `block = []` clears the defaults. Unlike the ZapScript path, the API does not apply the `mode` setting, so plain characters can always be typed by a client that holds `input`. On Windows, Core runs unelevated in the user's desktop session, so two limits apply that Core cannot detect or work around: keys sent to a window belonging to an elevated program are silently discarded by Windows, and nothing reaches the secure desktop, meaning UAC prompts, the lock screen and Ctrl+Alt+Del. Keys are injected as scancodes, so which character a key produces still depends on the active keyboard layout. The virtual gamepad needs a driver on Windows. `input.gamepad` emulates an Xbox 360 controller through ViGEmBus, a kernel-mode driver the Zaparoo installer offers as an optional task; Core never installs it on its own, and installing it is the only step that needs administrator rights. Gamepad support is also off by default on Windows, because an unexpected virtual pad changes controller numbering in games: set `gamepad_enabled = true` under `[input]` to turn it on. With the setting on and the driver absent, `input.gamepad` reports that the driver is missing instead of reporting success. Uninstalling Zaparoo leaves the driver in place, because other software may be using it; remove it separately through Apps & Features, where it is listed as "ViGEm Bus Driver". The driver is published for x86 and x64 only, so the ARM64 build of Zaparoo does not offer the task and has no virtual gamepad: `gamepad_enabled` there reports the driver as missing whatever the setting says. Keyboard input is unaffected on every architecture. ### input.keyboard **Access:** Requires `input`. Press keyboard keys using the ZapScript input macro format. #### Parameters An object: | Key | Type | Required | Description | | :--- | :----- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | | keys | string | Yes | Input macro string. Each character is a keypress, `{...}` for special keys (e.g. `{enter}`, `{f9}`, `{ctrl+q}`). WebSocket requests may use `{press:key}` and `{release:key}` to hold a key, shifted character or modifier combo across requests. | #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-1234-5678-9abc-def012345678", "method": "input.keyboard", "params": { "keys": "abc{enter}" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-1234-5678-9abc-def012345678", "result": null } ``` ### input.gamepad **Access:** Requires `input`. Press gamepad buttons using the ZapScript input macro format. #### Parameters An object: | Key | Type | Required | Description | | :------ | :----- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | | buttons | string | Yes | Input macro string. Each character is a button press, `{...}` for named buttons (e.g. `{up}`, `{start}`, `{l1}`). WebSocket requests may use `{press:button}` and `{release:button}` to hold a button across requests. | #### Result Returns `null` on success. #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "b2c3d4e5-2345-6789-abcd-ef0123456789", "method": "input.gamepad", "params": { "buttons": "^^vv<><>BA{start}" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "b2c3d4e5-2345-6789-abcd-ef0123456789", "result": null } ``` ## Screenshot ### screenshot **Access:** Requires `screenshot`. Capture a screenshot of the current platform display. Returns the image as base64-encoded data and the path where it was saved on disk. Currently supported on MiSTer and ReplayOS. Other platforms return an error. ReplayOS requires active storage and a loaded libretro core. #### Parameters None. #### Result | Key | Type | Required | Description | | :--- | :----- | :------- | :------------------------------------------- | | path | string | Yes | Path where the screenshot was saved on disk. | | data | string | Yes | Base64-encoded image data. | | size | number | Yes | Size of the image data in bytes. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-1234-5678-9abc-def012345678", "method": "screenshot" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-1234-5678-9abc-def012345678", "result": { "path": "/media/fat/screenshots/MiSTer_20260329_181500.png", "data": "iVBORw0KGgo...", "size": 245760 } } ``` ## Updates ### update.check **Access:** Localhost or any paired client. Check if a newer version of Zaparoo Core is available. Returns version information, release notes, and everything a client needs to decide what to offer: whether the device is eligible for updates at all, whether the release has reached this device yet, and what is currently stopping one being installed. A check makes the device fetch and verify signed release metadata and write the result to its data directory, which is why it is not open to unpaired remote clients. On development builds, `updateAvailable` is always `false` and `eligibility` is `development`. #### Parameters None. #### Result | Key | Type | Required | Description | | :-------------- | :------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | currentVersion | string | Yes | The currently running version. | | updateAvailable | boolean | Yes | Whether a newer version is available. | | autoInstall | boolean | Yes | Whether the device installs updates on its own. Mirrors the `updateInstall` setting. | | latestVersion | string | No | The latest available version (if the check succeeded). | | releaseNotes | string | No | Release notes for the latest version. | | channel | string | No | The update channel the check used: `stable` or `beta`. | | eligibility | string | No | Whether this install can take OTA updates: `eligible`, `development`, `unsupported` (this install cannot be replaced in place, such as a Windows install under a directory Zaparoo cannot write to), or `managed` (a package manager owns the install, so it should do the installing). An install that cannot be replaced reports `unsupported` even when a package manager owns it, because that is the one an install is actually refused for. The exception is a Core embedded in a host application, which reports `managed` regardless: it never replaces its own executable, so replaceability does not apply. | | checkedAt | string | No | RFC3339 timestamp of when the release metadata was last fetched. | | rolloutHeld | boolean | No | The release is newer but has not reached this device's share of the fleet yet. Applying it by hand still works; automatic installs wait. | | blockedBy | object | No | What is stopping an update being applied right now. Absent when nothing is. | | deferredReason | string | No | Why an automatic install has been putting this version off. Same values as `blockedBy.reason`. | | deferredSince | string | No | RFC3339 timestamp of when this version was first put off. After 24 hours an automatic install goes ahead through the signals that expire. | | lastResult | object | No | How the previous update finished. Present until a newer result replaces it. | ##### blockedBy | Key | Type | Required | Description | | :-------- | :------ | :------- | :------------------------------------------------------------------------------------------------------------- | | reason | string | Yes | Machine-readable reason, from the table below. | | message | string | Yes | Human-readable explanation, suitable for showing as-is. | | forceable | boolean | Yes | Whether `update.apply` with `force: true` goes ahead anyway. False means the refusal stands whatever is passed. | Reasons: | Reason | Forceable | Meaning | | :---------------- | :-------- | :--------------------------------------------------------------- | | mediaIndexing | No | The media database is being generated. | | mediaOptimizing | No | The media database is being optimised. | | mediaScraping | No | Media metadata is being scraped. | | backupActive | No | A backup, restore or upload is running. | | readerWriting | No | A reader is part-way through writing a token. | | restoreActive | No | A restore is holding the databases. | | activeMedia | Yes | Media is playing and a restart would close it. | | backgroundMedia | Yes | Media is playing in the background. | | activePlaylist | Yes | A playlist is running. | | powerLow | No | The battery is below the level an install needs. | | powerUnknown | Yes | The battery level could not be read. | | apiBusy | Yes | The API has not been idle long enough. Automatic installs only. | `blockedBy` is what a client should read before offering an update: hide or disable the button when `forceable` is false, and offer to go ahead when it is true. ##### lastResult | Key | Type | Required | Description | | :---------- | :----- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | at | string | Yes | RFC3339 timestamp of when the update finished. | | outcome | string | Yes | `succeeded`, `rolledBack` (the new build would not start and the old one was put back), `rollbackBlocked` (the rollback could not be completed), or `recoveryRequired`. | | fromVersion | string | No | The version before the update. | | toVersion | string | No | The version the update was to. | | detail | string | No | What went wrong, when something did. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-1234-5678-9abc-def012345678", "method": "update.check" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-1234-5678-9abc-def012345678", "result": { "currentVersion": "2.9.1", "latestVersion": "2.10.0", "updateAvailable": true, "autoInstall": false, "releaseNotes": "...", "channel": "stable", "eligibility": "eligible", "checkedAt": "2026-08-18T09:30:00Z", "blockedBy": { "reason": "activeMedia", "message": "media is playing", "forceable": true } } } ``` ### update.apply **Access:** Requires `update.apply`. Download and apply the latest available update, then gracefully restart the service. The response is sent to the client before the restart occurs. A Core embedded in a host application refuses `update.apply`: the host updates Core as part of its own package. Before anything is downloaded the device checks that it is safe to install: nothing writing to the databases, no backup or token write in progress, nothing playing, and enough battery. A refusal comes back as an error whose message is the same text `update.check` reports in `blockedBy.message`. Call `update.check` first to know in advance, and whether `force` would get past it. The battery is checked twice — once before the download and again immediately before the install begins — because a download long enough to matter is also long enough to outlive a charger being unplugged. This method has no request timeout: the download and install run to completion or unwind on their own. Applying an update is treated as low priority, so it does not delay reader scans or playback control. While it runs, the device sends [`update.state`](notifications.md#updatestate) notifications. #### Parameters | Key | Type | Required | Description | | :---- | :------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | force | boolean | No | Go ahead through the signals `update.check` reports as `forceable`, such as media playing that the restart will close. It does not get past anything that risks data or a device without the power to finish. Defaults to false. | Parameters may be omitted entirely, which is the same as `force: false`. #### Result | Key | Type | Required | Description | | :-------------- | :----- | :------- | :----------------------------- | | previousVersion | string | Yes | The version before the update. | | newVersion | string | Yes | The version after the update. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-1234-5678-9abc-def012345678", "method": "update.apply", "params": { "force": true } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "a1b2c3d4-1234-5678-9abc-def012345678", "result": { "previousVersion": "2.9.1", "newVersion": "2.10.0" } } ``` ## Device These methods describe and control the machine Core is running on. They are the same on every platform. A platform that cannot report or do something says so in `capabilities` instead of offering a different method. None of these methods is available to legacy clients or to Zaparoo Online remote operations. ### device.status **Access:** Localhost or any authenticated client. Query the state of the device: its battery, network links, Bluetooth adapter, storage, displays, connected controllers, clock and identity. Core keeps this state current while at least one client holds a WebSocket or SSE connection, and sends [`device.changed`](notifications.md#devicechanged) when the part of it a status display needs has changed. Call this method once after connecting, then follow the notification. Do not poll it. A caller with no open connection, such as a one-off HTTP request, gets a fresh reading taken for that request. Every section key is always present. A section that is `null` is either unsupported on this device or has no reading yet; `capabilities.sections` says which. Within a section, a value that is not known is `null`. #### Parameters None. #### Result | Key | Type | Required | Description | | :----------- | :-------------------------------- | :------- | :----------------------------------------------------------- | | capabilities | [Capabilities](#capabilities-object) | Yes | What this device can report and do. | | power | [Power](#power-object) \| null | Yes | The battery the device runs on. | | network | [Network](#network-object) \| null | Yes | Network links and internet reachability. | | bluetooth | [Bluetooth](#bluetooth-object) \| null | Yes | The Bluetooth adapter. | | storage | [Storage](#storage-object) \| null | Yes | The filesystems holding media and Core's data. | | display | [Display](#display-object) \| null | Yes | What the device is showing its picture on. | | controllers | [Controllers](#controllers-object) \| null | Yes | Connected game controllers. | | time | [Time](#time-object) | Yes | The device clock. | | system | [System](#system-object) \| null | Yes | What the device is. | ##### Capabilities object | Key | Type | Required | Description | | :------- | :----- | :------- | :-------------------------------------------------------------------------------------------------- | | sections | object | Yes | Section name to `supported` or `unsupported`. | | actions | object | Yes | Method name to `supported` or `notPermitted`. An action the device cannot perform is left out. | A key that is absent from either object means unsupported. Later versions of Core add sections and actions; a client must ignore keys it does not know. `actions` is worked out for the calling client. `notPermitted` means either the client lacks the capability the method requires, or the device's operating system refuses Core. `device.bluetooth.scan.start`, `device.bluetooth.pair` and `device.bluetooth.forget` are listed only where Core can manage Bluetooth devices and an adapter is present: on Linux, through BlueZ. They stay `supported` while the adapter is switched off; `bluetooth.powered` says whether it is on. ##### Power object | Key | Type | Required | Description | | :------------ | :-------------- | :------- | :------------------------------------------------------------------------------------------------------ | | present | boolean | Yes | Whether the device has a battery of its own. | | percent | number \| null | Yes | Charge of the lowest battery, 0-100. Reported whether or not the device is charging. | | source | string \| null | Yes | `battery` or `external`. | | chargeState | string \| null | Yes | `charging`, `discharging`, `full` or `notCharging`. | | timeRemaining | number | No | Estimated seconds until empty. Only present while discharging and when an estimate exists. | | batteries | Battery[] | Yes | Each battery: `id`, `percent`, `chargeState` and optional `timeRemaining`, with the meanings above. | Batteries that belong to a peripheral, such as a wireless controller, are not reported here. A controller's battery is on its entry in `controllers`. Some hardware reports only a charge level. `source` and `chargeState` are then `null`. ##### Network object | Key | Type | Required | Description | | :--------- | :-------------- | :------- | :------------------------------------------------------------------------------------------------ | | type | string | Yes | Kind of link carrying the default route: `wifi`, `wired`, `other`, or `none` when there is none. | | interface | string \| null | Yes | Name of that interface. | | internet | string \| null | Yes | `full`, `portal` (something such as a sign-in page is answering in place of the internet) or `none`. | | interfaces | Interface[] | Yes | Each Wi-Fi and wired link: `name`, `type`, `up`, and `addresses` (loopback and link-local excluded). | `internet` comes from the operating system where it already checks reachability. Otherwise Core requests a small known page over plain HTTP, on a link change and then every five minutes while a client is connected. It is `null` until the first answer, and stays `null` when `internet_check = false` is set under `[service]` in the config and the operating system has no answer of its own. ##### Bluetooth object | Key | Type | Required | Description | | :------ | :--------------- | :------- | :----------------------------------------------------------------- | | present | boolean | Yes | Whether the device has a Bluetooth adapter. | | powered | boolean \| null | Yes | Whether the adapter is switched on, where that can be read. | Core never switches the adapter on or off. Scanning, pairing and forgetting devices go through the [`device.bluetooth`](#devicebluetoothdevices) methods. ##### Storage object | Key | Type | Required | Description | | :------ | :------- | :------- | :-------------------------- | | volumes | Volume[] | Yes | One entry per filesystem. | Each volume has `path` (where it is mounted, or a directory on it when that is not known), `roles` (`media`, `data`, or both), `totalBytes`, `freeBytes` (the space Core may use) and `usedBytes`. ##### Display object | Key | Type | Required | Description | | :---------------- | :--------------- | :------- | :--------------------------------------------------------------------------------------- | | internalPanel | boolean | Yes | Whether the device has a built-in screen. | | internalActive | boolean | Yes | Whether the built-in screen is being driven. | | externalConnected | boolean | Yes | Whether an external display is plugged in. | | externalActive | boolean | Yes | Whether an external display is being driven. | | docked | boolean \| null | Yes | Whether a device with a built-in screen is driving an external one. `null` without one. | ##### Controllers object | Key | Type | Required | Description | | :---- | :----------- | :------- | :---------------------------------- | | count | number | Yes | Number of connected controllers. | | items | Controller[] | Yes | The controllers. | | Controller key | Type | Required | Description | | :------------- | :-------------- | :------- | :------------------------------------------------------------------------------------------- | | id | string | Yes | Identifies the controller only while it stays connected. | | name | string \| null | Yes | The name the controller reports. | | displayName | string \| null | Yes | The controller's model name, such as `DualShock 4`, from Core's table of well-known controllers by vendor and product ID. `null` when the model is not known; show `name` then. Never includes an address or index, so two of the same model share it. | | vendorId | string \| null | Yes | USB vendor ID, four lowercase hex digits. | | productId | string \| null | Yes | USB product ID, four lowercase hex digits. | | connection | string | Yes | `usb`, `bluetooth` or `unknown`. | | battery | object \| null | Yes | `percent` (number or `null`), `level` (`empty`, `low`, `medium` or `full`) and `chargeState` (`charging`, `discharging`, `full`, `notCharging` or `null` when not known). | Virtual controllers, including the one Core creates for [`input.gamepad`](#inputgamepad), are not listed. On Windows, controllers are read through XInput: at most four, with no name or IDs, and a battery `level` without a `percent` or `chargeState`. XInput cannot tell a virtual gamepad made by another program, such as one from ViGEm, from a real one, so Core lists it as a wired controller. ##### Time object | Key | Type | Required | Description | | :------------ | :-------------- | :------- | :-------------------------------------------------------------------------------------------- | | clockReliable | boolean | Yes | `false` when the clock is clearly unset, as on a device with no clock battery before it syncs. | | timezone | string \| null | Yes | IANA time zone name. | | utcOffset | number | Yes | Current offset from UTC in seconds. | `timezone` is `null` when the name cannot be worked out: on Windows before 10 version 1903, and where the device keeps a copy of a zone file that matches several zones, such as MiSTer's `/media/fat/linux/timezone`. When Core names a zone from a copied file, the zone has the same rules as the one that was chosen but may carry another name that shares them. ##### System object | Key | Type | Required | Description | | :------- | :-------------- | :------- | :------------------------------------------- | | hostname | string | Yes | The device's hostname. | | platform | string | Yes | Core's platform ID, as in [`version`](#version). | | os | string | Yes | Operating system family, such as `linux`. | | arch | string | Yes | CPU architecture, such as `arm64`. | | model | string \| null | Yes | Hardware model, where the device reports one. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "5e9f3a0e-7a5d-4d5c-9b6e-2f3d4c5b6a79", "method": "device.status" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "5e9f3a0e-7a5d-4d5c-9b6e-2f3d4c5b6a79", "result": { "capabilities": { "sections": { "power": "supported", "network": "supported", "bluetooth": "supported", "storage": "supported", "display": "supported", "controllers": "supported", "time": "supported", "system": "supported" }, "actions": { "device.power.reboot": "supported", "device.power.shutdown": "supported", "device.power.suspend": "supported", "device.bluetooth.scan.start": "supported", "device.bluetooth.pair": "supported", "device.bluetooth.forget": "supported" } }, "power": { "present": true, "percent": 96, "source": "external", "chargeState": "charging", "batteries": [{ "id": "BAT1", "percent": 96, "chargeState": "charging" }] }, "network": { "type": "wifi", "interface": "wlan0", "internet": "full", "interfaces": [{ "name": "wlan0", "type": "wifi", "up": true, "addresses": ["192.168.1.20"] }] }, "bluetooth": { "present": true, "powered": true }, "storage": { "volumes": [ { "path": "/home", "roles": ["media", "data"], "totalBytes": 494384795648, "freeBytes": 201863462912, "usedBytes": 292521332736 } ] }, "display": { "internalPanel": true, "internalActive": false, "externalConnected": true, "externalActive": true, "docked": true }, "controllers": { "count": 1, "items": [ { "id": "input17", "name": "DualSense Wireless Controller", "displayName": "DualSense", "vendorId": "054c", "productId": "0ce6", "connection": "bluetooth", "battery": { "percent": 80, "level": "full", "chargeState": "charging" } } ] }, "time": { "clockReliable": true, "timezone": "Australia/Perth", "utcOffset": 28800 }, "system": { "hostname": "steamdeck", "platform": "steamos", "os": "linux", "arch": "amd64", "model": "Jupiter" } } } ``` ### device.endpoints **Access:** Localhost or any authenticated client. Query where else the API can be reached. A client connected over [Bluetooth LE](index.md#bluetooth-le) calls this after authenticating to find the network API, and moves to it when it can open an encrypted WebSocket session there, which also proves it reached the same device. A client connected over the network uses `ble` to learn whether it can fall back to Bluetooth LE. #### Parameters None. #### Result | Key | Type | Required | Description | | :-------- | :------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------- | | deviceId | string | Yes | Core's device ID, the same one network discovery publishes. Match records of one device found over different transports with it. | | name | string | Yes | The name the device goes by, the same one network discovery publishes. | | scheme | string | Yes | WebSocket scheme of the network API. Always `ws`. | | addresses | string[] | Yes | LAN addresses the network API answers on. Empty when it only listens on loopback or on a socket the host supplied. | | port | number | Yes | Port of the network API. | | ble | boolean | Yes | Whether the API is currently served over Bluetooth LE. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "7d1b2c3e-2f90-4b8e-9a52-1e0f6c4d8a21", "method": "device.endpoints" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "7d1b2c3e-2f90-4b8e-9a52-1e0f6c4d8a21", "result": { "deviceId": "3f6c1e2a-9b4d-4c8e-a1f2-5d7e9b0c4a36", "name": "MiSTer", "scheme": "ws", "addresses": ["192.168.1.40"], "port": 7497, "ble": true } } ``` ### device.power.reboot **Access:** Requires `device.power`. Restart the device. The response is sent before the device goes down. Check `capabilities.actions` in [`device.status`](#devicestatus) before offering this to a user: it lists the action only where the device can perform it, and marks it `notPermitted` where it cannot be used. The request is refused while a backup or restore is running. #### Parameters None. #### Result Returns `null` once the request has been accepted. #### Errors A refusal carries a `category` in the error's `data`: | Category | Meaning | | :-------------- | :------------------------------------------------------------------- | | `unsupported` | This device cannot perform the action. | | `not_permitted` | The device's operating system does not allow Core to perform it. | | `busy` | A backup or restore is running. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "0c1b2a39-4857-4a6b-8c9d-0e1f2a3b4c5d", "method": "device.power.reboot" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "0c1b2a39-4857-4a6b-8c9d-0e1f2a3b4c5d", "result": null } ``` ### device.power.shutdown **Access:** Requires `device.power`. Power the device off. Access, parameters, result and errors are the same as [`device.power.reboot`](#devicepowerreboot). ### device.power.suspend **Access:** Requires `device.power`. Put the device to sleep. Access, parameters, result and errors are the same as [`device.power.reboot`](#devicepowerreboot). ### device.bluetooth.devices **Access:** Requires `device.bluetooth`. List paired Bluetooth devices and the devices the current or last scan found. Offer pairing only when `capabilities.actions["device.bluetooth.pair"]` in [`device.status`](#devicestatus) is `supported` and `bluetooth.present` is `true`. While a client holds a WebSocket or SSE connection, Core sends [`device.bluetooth.changed`](notifications.md#devicebluetoothchanged) whenever this state changes. Call this method once, then follow the notification. Both carry the names and addresses of nearby devices, so both need the `device.bluetooth` capability. #### Parameters None. #### Result A [Bluetooth state](#bluetooth-state-object). ##### Bluetooth state object | Key | Type | Required | Description | | :------- | :-------------------------------------- | :------- | :------------------------------------------------------------------ | | powered | boolean | Yes | Whether the adapter is switched on. | | scanning | boolean | Yes | Whether the adapter is searching for devices. | | devices | [BluetoothDevice](#bluetooth-device-object)[] | Yes | Paired devices first, then devices found by the current or last scan. | | pairing | [Pairing](#pairing-object) \| null | Yes | The latest pairing attempt, or `null` before the first one. | A scan lists only gamepads and joysticks besides paired devices, unless it was started with `all: true`. Starting a scan while none is running forgets what the last one found; extending a running scan keeps it. ##### Bluetooth device object | Key | Type | Required | Description | | :----------- | :-------------- | :------- | :-------------------------------------------------------------------------------------------------- | | id | string | Yes | The device's Bluetooth address, upper case, such as `AA:BB:CC:DD:EE:FF`. | | name | string \| null | Yes | The device's name, or `null` when it has not given one. | | displayName | string \| null | Yes | The device's model name, as for a [controller](#controllers-object). `null` when the model is not known; show `name` then. | | vendorId | string \| null | Yes | Vendor ID from the device's modalias, four lowercase hex digits, or `null` when it has not given one. | | productId | string \| null | Yes | Product ID from the device's modalias, four lowercase hex digits, or `null` when it has not given one. | | paired | boolean | Yes | Whether the device is paired. | | connected | boolean | Yes | Whether the device is connected. | | trusted | boolean | Yes | Whether the device may reconnect by itself. | | gamepad | boolean | Yes | Whether the device identifies itself as a gamepad or joystick. | | controllerId | string \| null | Yes | The `id` of the matching entry in `device.status` `controllers` while connected, otherwise `null`. | ##### Pairing object | Key | Type | Required | Description | | :------ | :------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | Yes | Address of the device being paired. | | state | string | Yes | `pairing`, `paired` or `failed`. | | error | string \| null | Yes | Why the attempt failed. `null` unless `state` is `failed`. | | attempt | number | Yes | Counts pair requests since Core started. A later attempt has a higher number, so a repeat outcome, and a reply that arrives after a notification, can be told apart. | `error` is one of: | Error | Meaning | | :------------ | :---------------------------------------------------------------------------------------- | | `pinRequired` | The device asked for a PIN or passkey. Core cannot show or enter one. | | `notPowered` | The adapter is switched off. | | `timeout` | The device did not answer, or the attempt took longer than 30 seconds. | | `rejected` | The device or the Bluetooth stack refused the pairing. | | `notFound` | The device is no longer known, usually because it stopped advertising. | | `failed` | Any other failure. | The pairing object keeps the result of the last attempt until the next one starts. #### Errors | Category | Meaning | | :------------ | :------------------------------------------------------------------- | | `unsupported` | Core cannot manage Bluetooth devices here, or there is no adapter. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "8d2c6b1e-1f0a-4c3e-9b7d-5a6e4f3c2b1a", "method": "device.bluetooth.devices" } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "8d2c6b1e-1f0a-4c3e-9b7d-5a6e4f3c2b1a", "result": { "powered": true, "scanning": true, "devices": [ { "id": "A4:AE:12:00:11:22", "name": "DualSense Wireless Controller", "displayName": "DualSense", "vendorId": "054c", "productId": "0ce6", "paired": true, "connected": true, "trusted": true, "gamepad": true, "controllerId": "input17" }, { "id": "E4:17:D8:33:44:55", "name": "8BitDo Pro 2", "displayName": "8BitDo Pro 2", "vendorId": "2dc8", "productId": "6006", "paired": false, "connected": false, "trusted": false, "gamepad": true, "controllerId": null } ], "pairing": null } } ``` ### device.bluetooth.scan.start **Access:** Requires `device.bluetooth`. Start looking for Bluetooth devices, or extend the scan already running. Devices appear through [`device.bluetooth.changed`](notifications.md#devicebluetoothchanged) as they are found. Calling it while a scan is running sets that scan to end `timeoutSeconds` from now and keeps the devices it has found. To keep a search going, call it again before the scan ends. The found list starts empty only when a scan starts while none is running. A scan stops by itself when its timeout passes, when the last client holding a WebSocket or SSE connection goes, and when pairing starts. Stop it with [`device.bluetooth.scan.stop`](#devicebluetoothscanstop) as soon as the user leaves the screen showing it. Core never switches the adapter on to scan. #### Parameters | Key | Type | Required | Description | | :------------- | :------ | :------- | :--------------------------------------------------------------------------- | | all | boolean | No | List every device found, not only gamepads and joysticks. Default `false`. | | timeoutSeconds | number | No | How long the scan runs, 1 to 120. Default 60. | #### Result The [Bluetooth state](#bluetooth-state-object), with `scanning` set. #### Errors | Category | Meaning | | :------------ | :------------------------------------------------------------------- | | `unsupported` | Core cannot manage Bluetooth devices here, or there is no adapter. | | `unavailable` | The adapter is switched off. The message is `bluetooth adapter is powered off`. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "3f9a1c7e-2b4d-4e6f-8a0b-1c2d3e4f5a6b", "method": "device.bluetooth.scan.start", "params": { "timeoutSeconds": 60 } } ``` ##### Response The result is a [Bluetooth state](#bluetooth-state-object), as in the [`device.bluetooth.devices`](#devicebluetoothdevices) example. ### device.bluetooth.scan.stop **Access:** Requires `device.bluetooth`. Stop the scan Core started. Scans started by other programs on the device are not affected. Stopping when no scan is running is not an error. #### Parameters None. #### Result The [Bluetooth state](#bluetooth-state-object). The devices the scan found stay listed until a new scan starts. #### Errors | Category | Meaning | | :----------------- | :---------------------------------------------------------------------- | | `unsupported` | Core cannot manage Bluetooth devices here, or there is no adapter. | | `execution_failed` | The Bluetooth stack refused to stop. The scan keeps running, and Core tries to stop it again 30 seconds later. | ### device.bluetooth.pair **Access:** Requires `device.bluetooth`. Pair with a device, then mark it trusted so it reconnects by itself, and connect it. The method returns at once with `pairing.state` set to `pairing`; the outcome arrives through [`device.bluetooth.changed`](notifications.md#devicebluetoothchanged). A running scan is stopped first. Core answers the pairing itself without user input ("Just Works"). That covers most game controllers. A device that asks for a PIN or passkey, such as a keyboard or an original Wii Remote, fails with `pinRequired`. A whole attempt is limited to 30 seconds. Only one attempt runs at a time. #### Parameters | Key | Type | Required | Description | | :-- | :----- | :------- | :----------------------------------------------- | | id | string | Yes | The device's address, such as `AA:BB:CC:DD:EE:FF`. | #### Result The [Bluetooth state](#bluetooth-state-object), with `pairing` set to the new attempt. #### Errors | Category | Meaning | | :------------ | :------------------------------------------------------------------- | | `unsupported` | Core cannot manage Bluetooth devices here, or there is no adapter. | | `unavailable` | The adapter is switched off. The message is `bluetooth adapter is powered off`. | | `busy` | Another pairing attempt is running. | #### Example ##### Request ```json { "jsonrpc": "2.0", "id": "7b6a5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "method": "device.bluetooth.pair", "params": { "id": "E4:17:D8:33:44:55" } } ``` ##### Response ```json { "jsonrpc": "2.0", "id": "7b6a5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d", "result": { "powered": true, "scanning": false, "devices": [ { "id": "E4:17:D8:33:44:55", "name": "8BitDo Pro 2", "displayName": "8BitDo Pro 2", "vendorId": "2dc8", "productId": "6006", "paired": false, "connected": false, "trusted": false, "gamepad": true, "controllerId": null } ], "pairing": { "id": "E4:17:D8:33:44:55", "state": "pairing", "error": null, "attempt": 1 } } } ``` ### device.bluetooth.forget **Access:** Requires `device.bluetooth`. Unpair a device and remove it from the device's Bluetooth stack. It has to be paired again before it can reconnect. #### Parameters | Key | Type | Required | Description | | :-- | :----- | :------- | :----------------------------------------------- | | id | string | Yes | The device's address, such as `AA:BB:CC:DD:EE:FF`. | #### Result The [Bluetooth state](#bluetooth-state-object), without the device. #### Errors | Category | Meaning | | :------------ | :------------------------------------------------------------------- | | `unsupported` | Core cannot manage Bluetooth devices here, or there is no adapter. | | `busy` | Core is pairing with this device. Wait for the attempt to end. | An `id` the Bluetooth stack does not know is refused with the message `bluetooth device not found`.