Skip to main content
This is unreleased documentation for the next Zaparoo Core release.
For up-to-date documentation, see the latest version (Stable).
Version: Next

Core API

The Core API is stable and ready for third-party integrations. The published /api/v0.1 contract will receive backward-compatible, additive changes only. Any future breaking changes will use a new versioned endpoint.

The Core API is available on and published by every device running the Zaparoo Core software. This API allows management of all Zaparoo features locally and remotely. The Zaparoo app uses this API for all communication with Zaparoo devices, as do most of the flags when Zaparoo is run via the command line.

This page documents the protocol used to communicate with the API and how to interact with it. It is currently the source of truth when developing applications that work with Zaparoo.

Communication Protocol​

The API uses a standard WebSocket connection to exchange JSON payloads using the JSON-RPC 2.0 protocol.

Communication follows a loose client-server relationship. Clients, by default, are not expected to implement the API beyond what that particular client needs to function.

Connection​

Connections to the API can be established with any standard WebSocket client, using the versioned endpoint of the HTTP server published by the Zaparoo service. By default, the HTTP server is accessible on port 7497. This port is configurable by the user.

These endpoints are currently available:

  • /api/v0.1
  • /api/v0
  • /api/

It's highly recommended to target your application at the specific minor version of the endpoint you're using, which will maintain compatibility during API updates.

An example address for connecting to the API: ws://10.0.0.123:7497/api/v0.1

The connection requires no special configuration or authentication to initiate. When encryption is enabled, remote clients must complete a one-time pairing and encrypt all WebSocket traffic.

HTTP POST​

All API methods can also be called via HTTP POST requests to the same versioned endpoints used for WebSocket connections. This provides an alternative for applications that prefer REST-style communication over persistent WebSocket connections.

These HTTP endpoints are available:

  • /api/v0.1
  • /api/v0
  • /api/

HTTP requests must use the POST method with Content-Type: application/json and send the same JSON-RPC 2.0 formatted payloads as WebSocket connections. The server will respond with a single JSON-RPC 2.0 response object.

An example HTTP request to get the server version:

curl -X POST http://10.0.0.123:7497/api/v0.1 \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": "550e8400-e29b-41d4-a716-446655440000",
"method": "version"
}'

For release 2.16.1, this would return a response like:

{
"jsonrpc": "2.0",
"id": "550e8400-e29b-41d4-a716-446655440000",
"result": {
"version": "2.16.1",
"platform": "linux"
}
}

The reported version is build-dependent. Core returns config.AppVersion, populated from APP_VERSION during release builds.

Unlike WebSocket connections, HTTP requests are stateless and do not support notifications. Each request requires a complete JSON-RPC 2.0 payload and will receive a single response.

Server-Sent Events (SSE)​

The API provides a Server-Sent Events endpoint for receiving notifications over a standard HTTP connection. This is useful for clients that only need to receive notifications without the full bidirectional communication of WebSocket, and works with any HTTP client without additional libraries.

These SSE endpoints are available:

  • /api/v0.1/events
  • /api/v0/events
  • /api/events

An example using curl:

curl -N http://10.0.0.123:7497/api/v0.1/events

Each notification is sent as an SSE data field containing the same JSON-RPC 2.0 notification object used by WebSocket:

data: {"jsonrpc":"2.0","method":"tokens.added","params":{"type":"nfc","uid":"04E1234567890","text":"**launch:game.rom"}}

data: {"jsonrpc":"2.0","method":"media.started","params":{"systemId":"NES","systemName":"NES","name":"game.rom"}}

SSE connections are long-lived and will continue receiving events until the client disconnects. To call methods, use HTTP POST to the standard API endpoint alongside the SSE connection.

Bluetooth LE​

On Linux and Windows machines with a Bluetooth adapter, Core can also serve the API over Bluetooth Low Energy, so the app works with no shared Wi-Fi at all: discovery, pairing and every method run over the one Bluetooth connection. The transport is on by default and does nothing on a device without a usable Bluetooth adapter; turn it off with the bleEnabled setting ([service.ble] enabled = false in the config file). Core is the peripheral and the client is the central.

Provisional: the Bluetooth LE wire format below (characteristics, chunking and framing) may still change before it is declared stable. Clients should check the protocol version in Info and refuse one they do not know.

Core never switches the adapter on: one that is off stays off, and the transport starts once the user turns Bluetooth on. While a user scans for or pairs a Bluetooth controller through the device.bluetooth.* methods, Core stops advertising and keeps any connected client. An adapter that keeps failing is left alone after five attempts in a row, until it is unplugged, switched off and on, or the setting changes. When a simpleserial_ble reader is configured and the adapter cannot scan and advertise at once, the reader takes the adapter and the transport stays off.

Once a client is connected and authenticated, device.endpoints tells it where the network API is, so it can move to a WebSocket when the two share a network and keep Bluetooth LE as the fallback.

Core advertises a primary service and, on Linux, the local name from [service.ble] name, falling back to the mDNS discovery instance name; the name is read when advertising starts, so a rename shows up after the transport restarts. On Windows the advertisement carries the PC's own Bluetooth name and the setting has no effect, so identify a device by the service and the deviceId in Info rather than by name:

CharacteristicUUIDPropertiesPurpose
Service0da70001-b359-443b-836f-477d34b6a638Primary service, also in the advertisement so clients can filter on it.
RX0da70002-b359-443b-836f-477d34b6a638write, write without responseChunks from the client to Core.
TX0da70003-b359-443b-836f-477d34b6a638notifyChunks from Core to the client.
Info0da70004-b359-443b-836f-477d34b6a638readJSON description of the endpoint, readable before authenticating.
Bond0da70005-b359-443b-836f-477d34b6a638read, encrypted link onlyReads empty. Reading it first makes a phone pair with the Bluetooth stack before subscribing to TX.

Info returns {"v": 1, "deviceId": "<device id>", "maxMessage": 4194304, "maxUnauthenticated": 65536, "preferredMtu": 512, "window": 64}. deviceId lets a client pick the stored credentials for this device before it speaks; peer addresses are not stable enough for that. maxMessage and maxUnauthenticated are the largest messages Core accepts from the client after and before it authenticates. Clients should request the largest ATT MTU the platform allows, and should discover the characteristics on every connection rather than reuse cached handles, which change when Core or the Bluetooth daemon restarts.

Framing. A message is one complete WebSocket-equivalent frame: an encrypted frame, or one of the plaintext pairing requests below. It is split into chunks of at most MTU - 3 bytes, and never more than 512 (the longest value an attribute can hold, which a 517-byte MTU would exceed), and written to RX one after another; Core sends replies the same way on TX. Every chunk starts with a header:

byte 0 flags bits 7..4 = protocol version (1), bit 2 = ACK, bit 1 = LAST, bit 0 = FIRST, bit 3 reserved (0)
byte 1-2 seq big-endian, see below
byte 3-4 tag session tag, big-endian
byte 5-8 length total message length, big-endian, FIRST chunk only
payload at least one byte; none on an ACK

seq counts every data chunk the sender has sent on this connection, starting at 0 and wrapping at 65536. It does not restart with each message. Each direction has its own count. Chunks may reach Core out of order, within a message or across two messages, and Core uses seq to put them back, so a client may send its next request without waiting for the previous one to be delivered. A chunk more than 256 places ahead of the one expected, a repeated sequence number, or a length that does not add up ends the connection.

The client picks a random non-zero 16-bit tag for the session and sends it on every chunk. To start over on the same connection, the client picks a new tag and starts at seq 0: Core ends the old session without a closing notice and serves the new one. A tag must not have been used on the connection before: Core drops chunks carrying a tag the connection has already left, and acknowledgements carrying any tag but the current one. A connection may start over 8 times; after that Core ends the session and the client must reconnect. Core stamps the session's tag on every chunk it sends that client, and clients must drop TX chunks carrying any other tag, because on Linux the radio delivers notifications to every subscribed central: every connected central sees every TX chunk, including pairing replies, and only the per-session encryption keeps another client's traffic unreadable. Whether a second client can connect while one is connected depends on the adapter: Core advertises again as soon as a client connects, and an adapter that cannot advertise while connected simply stays hidden until that client leaves.

Writing. Write chunks to RX as writes with a response. RX also takes writes without a response, which are faster, but a Bluetooth stack may drop one when chunks arrive faster than it can hand them on (Windows does), and nothing resends it. Core waits ten seconds for a missing chunk and then ends the session. A client that wants the speed should send only some chunks without a response and should expect to fall back.

Flow control. Core sends at most window data chunks beyond the last one the client acknowledged, then waits. The client acknowledges by writing an ACK chunk to RX: the 5-byte header alone, with the ACK flag set and seq set to the sequence number of the next data chunk it expects from Core. A client must send one at least every window / 2 chunks it receives; more often is fine. ACK chunks carry no sequence number of their own and Core never sends them. Core ignores an ACK behind one it already has, since writes can reach it out of order, but an ACK for a chunk Core has not sent ends the connection. A client that leaves a full window unacknowledged for 30 seconds is disconnected.

Message size. Messages from Core have no size limit: a response is streamed however large it is, so everything the API returns over WebSocket is available over Bluetooth. Throughput is the practical limit: about one chunk per connection interval, which is around 10 kB/s at a 50 ms interval, so ask for the shortest interval the platform allows. One connection carries one message at a time, so a large response delays everything behind it, including pong. Any chunk from Core shows the link is alive. Prefer bounded requests on this transport: thumbnails rather than full-size images, and media.asset which pages a file by offset. Messages from the client may not exceed maxMessage, or maxUnauthenticated until the encrypted first frame has been answered.

Pairing. Pairing runs the same exchange as the HTTP pairing endpoints, carried as two plaintext JSON-RPC requests that exist only on this transport: pair.start with params {"pake": "<base64 PAKE message A>", "name": "<client name>"} returning {"session": "...", "pake": "<base64 PAKE message B>"}, then pair.finish with params {"session": "...", "confirm": "<base64 client HMAC>"} returning {"authToken": "...", "clientId": "...", "confirm": "<base64 server HMAC>"}. The pairing PIN is still generated and shown on the device by clients.pair.start. Failures return error -32005 (pairing failed) whose data carries the HTTP status and message the endpoints would have used, including 429 when a connection sends more than a couple of pairing requests per second.

Sessions. A connection accepts only pairing requests and an encrypted first frame; plaintext method calls end the connection, and there is no localhost or legacy access over Bluetooth. Encrypted frames use the binary envelope, which is the only one accepted here, with the AAD transport label ble (see AAD); a JSON-enveloped frame is treated as plaintext and ends the connection. After pairing, the client sends its encrypted first frame on the same connection. When Core ends a session itself, for a framing error, a failed decryption, a timeout or anything else, the last thing it sends is a plaintext JSON-RPC error with a null id: -32004 (session closed) with the reason in data.reason, or the more specific -32001 for an unsupported encryption version. On Linux Core then drops the link. On Windows it cannot, so a client must treat this notice as the end of the session and disconnect. An unauthenticated connection that stays silent for two minutes is dropped, and an authenticated one that sends nothing for five minutes is dropped too, so send the ping heartbeat at least once a minute; it works unchanged over Bluetooth. Once authenticated, notifications arrive on TX like WebSocket notifications, except that media.indexing and media.scraping are skipped while the link is backed up. A client that requests more than the link can carry is slowed down: Core holds further responses until the queue drains, and answers -32000 (Server busy) once its request queues fill.

Adapters. How well this works depends heavily on the Bluetooth adapter and the host. In testing, a CSR8510 adapter carried several megabytes in one connection at about 21 kB/s of API data, on a MiSTer and on a desktop. A Realtek RTL8761B adapter (TP-Link UB500) on a MiSTer managed about 3 kB/s and stalled within a megabyte. When a link stalls, Core drops the connection after 30 seconds and the client can reconnect; media.asset can resume from the offset it reached.

Readers. The same adapter also serves the simpleserial_ble reader driver, which connects to a configured Nordic UART Service device as a central. A reader the Bluetooth daemon has connected to before is waited for without a full scan and is picked up a few seconds after it starts advertising; only a reader it has never seen is scanned for. Serving the API and a reader from one adapter needs an adapter and host that can advertise while scanning and while connected to the reader. A MiSTer could not do that reliably in testing, with either adapter above, so use one or the other there.

JSON Payloads​

Server and clients communicate back and forth using JSON payloads, following the JSON-RPC 2.0 protocol.

Because a WebSocket connection is asynchronous, request payloads are tagged with a unique ID. The client must keep track of IDs sent to another client and wait for a matching response object. A client can continue sending requests while waiting for responses to previous requests.

Requests​

A request object asks the connected server to run a predefined method, and report back when it's completed with a response object.

An example request:

{
"jsonrpc": "2.0",
"id": "4b5da056-a5d4-436b-b4e6-b96231e99969",
"method": "media.search",
"params": {
"query": "240p"
}
}

This request would query Zaparoo's media database for a filename containing the word "240p" and return a response with the search results.

Request object​
KeyTypeRequiredDescription
jsonrpcstringYesAs per the JSON-RPC 2.0 spec, this key's value must be the string 2.0 for a payload to be accepted.
idstringYes*A UUID generated by the requesting client, used to match requests back to responses. A request missing this key is valid but would be treated as a notification and not receive any response.
methodstringYesA string corresponding to a method to be run by the receiving server.
paramsanyNoArguments supplied for the method. The value of this key depends on the method used and is omitted for some methods.

All available request methods and their parameters are documented below.

Notifications​

Notifications are requests which do not contain an ID. Otherwise, they are identical to a standard request object. Notifications can be sent by either server or client and do not receive a response.

Like standard requests, notifications may or may not have parameters and its value will depend on the method. Types of notifications are documented below.

Responses​

Every request sent must have a matching response. An example response to the media.search request shown above:

{
"jsonrpc": "2.0",
"id": "4b5da056-a5d4-436b-b4e6-b96231e99969",
"result": {
"results": [
{
"system": {
"id": "Gameboy",
"name": "Gameboy"
},
"name": "240p Test Suite (PD) v0.03 tepples",
"path": "Gameboy/240p Test Suite (PD) v0.03 tepples.gb",
"zapScript": "@Gameboy/240p Test Suite (PD) v0.03 tepples",
"tags": []
}
],
"total": 1,
"pagination": {
"hasNextPage": false,
"pageSize": 100
}
}
}
Response object​
KeyTypeRequiredDescription
jsonrpcstringYesSame as a request.
idstringYesSame as a request. The same ID sent by the original request.
resultanyNo*Return value of the method. May be null depending on the method, will be missing if there was an error. See methods for possible values.
errorErrorNo*If a method failed, this key will be populated with the error details and the result key will be empty. See below for details about errors.
Response errors​

If a method fails, it will populate the error key in the response object with details about the failure. An example of a failed request:

{
"jsonrpc": "2.0",
"id": "4b5da056-a5d4-436b-b4e6-b96231e99969",
"error": {
"code": 1,
"message": "invalid cursor: invalid base64"
}
}
Error object​
KeyTypeRequiredDescription
codenumberYesAn integer specifying the general error category. Error codes are not yet formalised.
messagestringYesShort human readable message explaining the error cause, if possible.
dataobjectNoOptional structured detail. Methods that emit it document its shape; run emits { "category": string }, plus reason and params for the categories that document them. Media methods refused while another operation holds the media database emit { "category": "busy" }; see media database busy errors.

Protocol Errors​

If a low-level error occurs before a request context can be established, a protocol error will be sent back. This can happen, for example, if a JSON payload is malformed or a payload could not be decrypted. They're identical to an error response except they will have no ID.

Protocol errors may be sent cleartext if a secure context couldn't be established, but will not contain any sensitive data.

Anonymous Access​

Anonymous cleartext access is, generally, allowed when an API connection is made from a loopback address (i.e. from the same device Zaparoo is running). This access depends on the platform and whether the service is running with elevated privileges. Check the page for the specific platform you're using to make sure it's available to you.

This access is also allowed when a connection is made over a WebSocket Secure (wss) connection.

Permissions​

Core evaluates four public access states:

  • Localhost requests originate from Core's device and have full access.
  • Authenticated admin includes paired admin clients and requests carrying a valid configured static API key. API-key admin is not localhost and cannot invoke localhost-only methods.
  • Authenticated member clients can use day-to-day methods, including input and screenshots, but cannot manage profiles, change protected settings, apply updates, reboot or shut down the device, or list, pair or forget Bluetooth devices.
  • Unauthenticated legacy clients are admitted only on MiSTer, MiSTeX, Batocera, LibreELEC, and ReplayOS. Legacy is a distinct compatibility state, never admin. Every other platform rejects legacy full-API access.

Grandfathered legacy screenshot access exists on MiSTer and ReplayOS. Grandfathered legacy input exists on MiSTer, MiSTeX, Batocera, and ReplayOS. New methods and capabilities do not become legacy-accessible automatically.

Legacy admission does not govern Core's intentionally unauthenticated surface:

  • Client pairing (/api/pair/start, /api/pair/finish) is remotely reachable and strictly rate limited.
  • Online authentication bootstrap (settings.auth.claim, settings.auth.status, settings.auth.link, and redacted settings.auth.link.status) is available before authentication. Remote HTTP POST requires allowed_ips and remains rate limited.
  • /health is unrestricted and returns a small JSON body for liveness checks: {"status":"ok","state":"ready"} once the service is up, with state also reporting starting while it works through startup and failed when it stopped on something a person has to resolve. It always answers 200, carries nothing beyond that state, and status is kept so callers matching the previous "status":"ok" keep working. Builds before v2.18 returned a bare OK.

Call clients.current to inspect current connection's access state, paired role, and capabilities. Every method in API Methods states its access requirements. Some read methods return additional sensitive fields to privileged clients; those fields are identified in their result contracts.

Heartbeat​

If sent the bytes ping, the API will immediately respond with the bytes pong. This feature can be used by heartbeat functions in WebSocket libraries.

Launch Endpoint​

The HTTP server has additional endpoints which allow restricted access to launch ZapScript using a GET request. These endpoints are specifically meant to support uses such as QR codes scanned by a phone's camera app or simple launch testing.

The following endpoints are available:

  • /run/ - Preferred endpoint for launching ZapScript.
  • /r/ - Alias for /run/.
  • /l/ - Deprecated. Use /run/ instead.

An example request: GET http://10.0.0.123:7497/run/**launch.system:snes

This would act as though a token with the text **launch.system:snes had been scanned.

URL-encode media paths used in the endpoint. Core decodes the path once before running it, including encoded spaces and parentheses:

GET http://10.0.0.123:7497/run/_Arcade/Youjyuden%20%28JP%29.mra

This runs _Arcade/Youjyuden (JP).mra.

Requests from the local device are allowed without restriction. Remote requests must be explicitly allowed using the allow_run config setting.

These endpoints respond as soon as the token is accepted and do not report execution failures. Use the JSON-RPC run method to wait for execution and receive its result.

The decoded ZapScript may be at most 8192 bytes. A longer path returns 413 Request Entity Too Large and nothing is run.

Methods​

Methods execute actions and return data from Core. See API Methods for request and response contracts, complete access details, and examples. Local/admin means localhost or authenticated admin, including paired and valid static API-key admins; Tiered means fields or availability vary by client and are detailed in method reference.

IDDescriptionAccess
runRun supplied ZapScript.All clients
stopKill any active launcher, if possible.All clients
confirmConfirm and launch the currently staged token.All clients
uiReturn authoritative global UI event state.All clients
ui.respondRespond to active global UI event.All clients
ui.shownReport that the active global UI event is on screen.Localhost or any authenticated client
tokensList active tokens.All clients
tokens.historyReturn latest token launches.All clients
mediaReturn media database status and active media.All clients
media.generateStart a media database index.All clients
media.generate.cancelCancel active media database indexing.All clients
media.generate.resumeResume paused media database indexing.All clients
media.searchSearch indexed media.All clients
media.versionsList the other versions of a media item's game.All clients
media.similarList media like a media item.All clients
media.recommendedList media the active profile may want to play next.All clients
media.browseBrowse indexed media in a directory hierarchy.All clients
media.browse.indexReturn jump-to-letter buckets and seek cursors for browsing.All clients
media.tagsQuery tags available for media filtering.All clients
media.tags.updateAdd or remove user tags for indexed media.All clients
media.meta.updateUpdate writable metadata for indexed media.All clients
media.activeReturn currently active media.All clients
media.active.updateUpdate currently active media information.All clients
media.active.imageReturn cover art of the audio track playing in a slot.All clients
media.clean.orphansRemove orphaned media database rows.All clients
media.historyReturn paginated media play history.All clients
media.history.latestReturn latest media play history entries.All clients
media.history.topReturn most-played media ranked by play time.All clients
media.lookupResolve game name and system to indexed media.All clients
media.lookup.candidatesReturn up to five ranked canonical titles in one system.All clients
media.metaReturn metadata for indexed media.All clients
media.imageReturn best matching image for indexed media.All clients
media.artwork.randomReturn random indexed media that have artwork.Localhost or any authenticated client
scrapersList available metadata scrapers.All clients
media.scrapeStart metadata scraping.All clients
media.scrape.statusReturn latest metadata scraping status.All clients
media.scrape.cancelCancel active metadata scraping.All clients
media.scrape.resumeResume paused metadata scraping.All clients
media.controlSend control action to active media launcher.All clients
playlists.updateChange shuffle and repeat of the playlist open in a slot.All clients
media.title.parsePreview media title and slug parsing.All clients
settingsList current configuration settings.Tiered
settings.updateUpdate and save configuration settings.settings.write
settings.zapscript.holdDisable ZapScript until this WebSocket connection closes.settings.write
settings.reloadReload settings from disk.All clients
settings.logs.downloadDownload current log file.All clients
settings.backupCreate local device backup.Local/admin
settings.backup.listList local device backups.Local/admin
settings.backup.inspectInspect local device backup.Local/admin
settings.backup.deleteDelete local device backup.Local/admin
settings.backup.restoreRestore local device backup.Local/admin
settings.backup.statusReturn local and remote backup status.All clients
settings.backup.remote.runCreate remote device backup.Local/admin
settings.backup.remote.listList remote device backups.Local/admin
settings.backup.remote.restoreRestore remote device backup.Local/admin
settings.playtime.limitsReturn playtime limit configuration.All clients
settings.playtime.limits.updateUpdate playtime limits.settings.write
playtimeReturn playtime session status and usage.All clients
playtime.extendGrant extra time to the session currently being limited.playtime.extend
systemsList indexed or supported systems.All clients
launchersList launchers known to running service.All clients
launchers.refreshRefresh launcher cache.All clients
mappingsList mappings.All clients
mappings.newCreate mapping.All clients
mappings.deleteDelete mapping.All clients
mappings.updateUpdate mapping.All clients
mappings.reloadReload mappings from disk.All clients
readersList connected readers and capabilities.All clients
readers.writeWrite text using available write-capable reader.All clients
readers.write.cancelCancel active reader write.All clients
input.keyboardSend keyboard input sequence.input
input.gamepadSend gamepad input sequence.input
screenshotCapture platform display.screenshot
versionReturn Core version and platform.All clients
healthCheck whether Core is responding.All clients
inboxList inbox messages.All clients
inbox.deleteDelete inbox message.All clients
inbox.clearDelete all inbox messages.All clients
clientsList paired clients.Localhost
clients.currentReturn current connection role and capabilities.All clients
clients.deleteRevoke paired client.Localhost
clients.pair.startStart pairing flow.Localhost
clients.pair.cancelCancel pairing flow.Localhost
profilesList profiles.Tiered
profiles.newCreate profile.profiles.manage
profiles.updateUpdate profile.profiles.manage
profiles.deleteDelete profile.profiles.manage
profiles.activeReturn active profile.All clients
profiles.switchSwitch active profile.All clients
profiles.verifyVerify profile PIN.All clients
profiles.contentReturn a profile's kiosk content rule.Admin
profiles.content.updateReplace a profile's kiosk content rule.Admin
kioskReturn kiosk lock state, settings and seal status.Authenticated
kiosk.enableTurn kiosk mode on from a preset.Localhost or admin
kiosk.updateChange kiosk settings.Admin
kiosk.disableTurn kiosk mode off.Admin
kiosk.unlockTemporarily unlock a locked device.Admin, or local PIN
kiosk.lockEnd a temporary unlock.Authenticated
kiosk.allowApprove one launch the content rule would refuse.Admin
decksList decks.All clients
decks.getReturn one deck with its items.All clients
decks.newCreate a deck.All clients
decks.updateEdit a deck's name, description or items.All clients
decks.deleteDelete a deck.All clients
decks.openOpen a deck as the active playlist.All clients
settings.auth.claimClaim API credentials from remote server.All clients
settings.auth.statusReturn credential link status.All clients
settings.auth.unlinkRemove online account credentials.Local/admin
settings.auth.linkStart online account link, or a RomM, Plex or Jellyfin server link (local/admin only).All clients
settings.auth.link.statusReturn online account link flow status.Tiered
settings.auth.link.cancelCancel online account link flow.Local/admin
online.statusReturn online account link state and reported account features.All clients
update.statusReport the last known update state without contacting the release server.Localhost or any paired client
update.checkCheck for newer Core version.Localhost or any paired client
update.applyApply latest update and restart gracefully.update.apply
device.statusQuery the state of the device Core runs on.Localhost or any paired client
device.endpointsQuery where else the API can be reached: LAN addresses, port and Bluetooth LE.Localhost or any paired client
device.power.rebootRestart the device.device.power
device.power.shutdownPower the device off.device.power
device.power.suspendPut the device to sleep.device.power
device.bluetooth.devicesList paired Bluetooth devices and the ones a scan found.device.bluetooth
device.bluetooth.scan.startStart looking for Bluetooth devices.device.bluetooth
device.bluetooth.scan.stopStop looking for Bluetooth devices.device.bluetooth
device.bluetooth.pairPair with a Bluetooth device, trust it and connect it.device.bluetooth
device.bluetooth.forgetUnpair a Bluetooth device and remove it.device.bluetooth

Notifications​

Notifications let a server or client know an event has occurred. See the API Notifications page for detailed definitions and examples of each notification.

IDDescription
readers.addedA new reader was connected to the server.
readers.removedA connected reader was disconnected from the server.
tokens.addedA new token detected by a reader.
tokens.removedA token was removed.
tokens.stagedA token was staged by launch guard and is awaiting confirmation.
tokens.staged.readyA staged token's delay period has expired and is ready for confirmation.
ui.changedAuthoritative global UI event state changed.
media.startedNew media was started on server.
media.stoppedMedia has stopped on server.
media.playbackNative audio in a slot started, paused, resumed, seeked or had its tags read.
media.history.changedPlay history was recorded outside the media started and stopped lifecycle.
media.tags.changedAn item's user flags (favorite, liked, disliked, play later, hidden) changed.
playlists.changedAn open playlist changed; carries every open playlist.
media.indexingThe state of the indexing or optimization process has changed.
media.scrapingProgress updates emitted during media scraping (includes progress/status details).
playtime.limit.reachedA playtime limit (session or daily) has been reached and enforced.
playtime.limit.warningA playtime warning notification sent at configured intervals before limit reached.
playtime.extendedExtra playtime was granted to the session currently being limited.
kiosk.stateThe kiosk lock was turned on or off, locked, unlocked, or reconfigured.
kiosk.launch.refusedThe kiosk lock refused a launch.
inbox.addedA new inbox message was added to the server.
decks.changedA deck was created, edited, deleted or refreshed from its source.
update.stateProgress of an update being applied.
device.changedThe state of the device Core runs on changed.
device.bluetooth.changedBluetooth devices, a scan or a pairing attempt changed.