Skip to main content

Methods

Methods are used to execute actions and request data back from the API.

Launching

run

Emulate the scanning of a token.

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:
KeyTypeRequiredDescription
typestringNoAn internal category of the type of token being scanned. Not currently in use outside of logging.
uidstringNo*The UID of the token being scanned. For example, the UID of an NFC tag. Used for matching mappings.
textstringNo*The main text to be processed from a scan, should contain ZapScript.
datastringNo*The raw data read from a token, converted to a hexadecimal string. Used in mappings and detection of NFC toys.
unsafebooleanNoAllow 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 on success.

Currently, it is not reported if the launched ZapScript encountered an error during launching, and the method will return before execution of ZapScript is complete.

Example

Request
{
"jsonrpc": "2.0",
"id": "52f6242e-7a5a-11ef-bf93-020304050607",
"method": "run",
"params": {
"text": "**launch.system:snes"
}
}
Response
{
"jsonrpc": "2.0",
"id": "52f6242e-7a5a-11ef-bf93-020304050607",
"result": null
}

stop

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.

Currently, it is not reported if a process was killed or not.

Example

Request
{
"jsonrpc": "2.0",
"id": "176b4558-7a5b-11ef-b318-020304050607",
"method": "stop"
}
Response
{
"jsonrpc": "2.0",
"id": "176b4558-7a5b-11ef-b318-020304050607",
"result": null
}

Tokens

tokens

Returns information about active and last scanned tokens.

Parameters

None.

Result

KeyTypeRequiredDescription
activeTokenResponse[]YesA list of currently active tokens.
lastTokenResponseNoThe last scanned token. Null if no token has been scanned yet.
Token object
KeyTypeRequiredDescription
typestringYesType of token.
uidstringYesUID of the token.
textstringYesText content of the token.
datastringYesRaw data of the token as hexadecimal string.
scanTimestringYesTimestamp of when the token was scanned in RFC3339 format.

Example

Request
{
"jsonrpc": "2.0",
"id": "5e9f3a0e-7a5b-11ef-8084-020304050607",
"method": "tokens"
}
Response
{
"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

Returns a list of the last recorded token launches.

Parameters

None.

Result

KeyTypeRequiredDescription
entriesLaunchEntry[]YesA list of recorded token launches.
Launch entry object
KeyTypeRequiredDescription
datastringYesRaw data of the token as hexadecimal string.
successbooleanYesTrue if the launch was successful.
textstringYesText content of the token.
timestringYesTimestamp of the launch time in RFC3339 format.
typestringYesType of token.
uidstringYesUID of the token.

Example

Request
{
"jsonrpc": "2.0",
"id": "5e9f3a0e-7a5b-11ef-8084-020304050607",
"method": "tokens.history"
}
Response
{
"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

Returns the current media database status and active media.

Parameters

None.

Result

KeyTypeRequiredDescription
databaseIndexingStatusYesStatus of the media database.
activeActiveMedia[]YesList of currently active media.
Indexing status object
KeyTypeRequiredDescription
existsbooleanYesTrue if the database exists.
indexingbooleanYesTrue if indexing is currently in progress.
totalStepsnumberNoTotal number of indexing steps.
currentStepnumberNoCurrent indexing step.
currentStepDisplaystringNoDisplay name of the current indexing step.
totalFilesnumberNoTotal number of files to index.
Active media object
KeyTypeRequiredDescription
launcherIdstringYesID of the launcher.
systemIdstringYesID of the system.
systemNamestringYesDisplay name of the system.
mediaPathstringYesPath to the media file.
mediaNamestringYesDisplay name of the media.
startedstringYesTimestamp when media started in RFC3339 format.

Example

Request
{
"jsonrpc": "2.0",
"id": "47f80537-7a5d-11ef-9c7b-020304050607",
"method": "media"
}
Response
{
"jsonrpc": "2.0",
"id": "47f80537-7a5d-11ef-9c7b-020304050607",
"result": {
"database": {
"exists": true,
"indexing": false
},
"active": []
}
}

media.search

Query the media database and return all matching indexed media.

Parameters

An object:

KeyTypeRequiredDescription
querystringYesCase-insensitive search by filename. By default, query is split by white space and results are found which contain every word.
systemsstring[]NoCase-sensitive list of system IDs to restrict search to. A missing key or empty list will search all systems.
maxResultsnumberNoMax number of results to return. Default is 250.

Result

KeyTypeRequiredDescription
resultsMedia[]YesA list of all search results from the given query.
totalnumberYesTotal number of search results.
Media object
KeyTypeRequiredDescription
systemSystemYesSystem which the media has been indexed under.
namestringYesA human-readable version of the result's filename without a file extension.
pathstringYesPath to the media file. If possible, this path will be compressed into the <system>/<path> launch format.
System object
KeyTypeRequiredDescription
idstringYesInternal system ID for this system.
namestringYesDisplay name of the system.
categorystringYesCategory of system. This field is not yet formalised.

Example

Request
{
"jsonrpc": "2.0",
"id": "47f80537-7a5d-11ef-9c7b-020304050607",
"method": "media.search",
"params": {
"query": "240p"
}
}
Response
{
"jsonrpc": "2.0",
"id": "47f80537-7a5d-11ef-9c7b-020304050607",
"result": {
"results": [
{
"name": "240p Test Suite (PD) v0.03 tepples",
"path": "Gameboy/240p Test Suite (PD) v0.03 tepples.gb",
"system": {
"category": "Handheld",
"id": "Gameboy",
"name": "Gameboy"
}
}
],
"total": 1
}
}

media.generate

Create a new media database index.

During indexing, the server will emit media.indexing notifications showing progress of the index.

Parameters

Optionally, an object:

KeyTypeRequiredDescription
systemsstring[]NoList of system IDs to restrict indexing to. Other system indexes will remain as is.

An omitted or null value parameters key is also valid and will index every system.

Result

Returns null on success once indexing is complete.

Example

Request
{
"jsonrpc": "2.0",
"id": "6f20e07c-7a5e-11ef-84bb-020304050607",
"method": "media.generate"
}
Response
{
"jsonrpc": "2.0",
"id": "6f20e07c-7a5e-11ef-84bb-020304050607",
"result": null
}

media.active

Returns the currently active media.

Parameters

None.

Result

Returns a list of ActiveMedia objects or an empty array if no media is active.

Example

Request
{
"jsonrpc": "2.0",
"id": "47f80537-7a5d-11ef-9c7b-020304050607",
"method": "media.active"
}
Response
{
"jsonrpc": "2.0",
"id": "47f80537-7a5d-11ef-9c7b-020304050607",
"result": []
}

media.active.update

Update the currently active media information.

Parameters

An object:

KeyTypeRequiredDescription
systemIdstringYesID of the system.
mediaPathstringYesPath to the media file.
mediaNamestringYesDisplay name of the media.

Result

Returns null on success.

Example

Request
{
"jsonrpc": "2.0",
"id": "47f80537-7a5d-11ef-9c7b-020304050607",
"method": "media.active.update",
"params": {
"systemId": "SNES",
"mediaPath": "/roms/snes/game.sfc",
"mediaName": "Game"
}
}
Response
{
"jsonrpc": "2.0",
"id": "47f80537-7a5d-11ef-9c7b-020304050607",
"result": null
}

systems

List all currently indexed systems.

Parameters

None.

Result

KeyTypeRequiredDescription
systemsSystem[]YesA list of all indexed systems.

See System object.

Example

Request
{
"jsonrpc": "2.0",
"id": "dbd312f3-7a5f-11ef-8f29-020304050607",
"method": "systems"
}
Response
{
"jsonrpc": "2.0",
"id": "dbd312f3-7a5f-11ef-8f29-020304050607",
"result": {
"systems": [
{
"category": "Handheld",
"id": "GameboyColor",
"name": "Gameboy Color"
},
{
"category": "Computer",
"id": "EDSAC",
"name": "EDSAC"
}
]
}
}

Settings

settings

List currently set configuration settings.

This method will list values set in the Config File. Some config file options may be omitted which are not appropriate to be read or written remotely.

Parameters

None.

Result

KeyTypeRequiredDescription
runZapScriptbooleanYesWhether ZapScript execution is enabled.
debugLoggingbooleanYesWhether debug logging is enabled.
audioScanFeedbackbooleanYesWhether audio feedback on scan is enabled.
readersAutoDetectbooleanYesWhether automatic reader detection is enabled.
readersScanModestringYesCurrent scan mode setting.
readersScanExitDelaynumberYesDelay before exiting scan mode in seconds.
readersScanIgnoreSystemsstring[]YesList of system IDs to ignore during scanning.

Example

Request
{
"jsonrpc": "2.0",
"id": "f208d996-7ae6-11ef-960e-020304050607",
"method": "settings"
}
Response
{
"jsonrpc": "2.0",
"id": "f208d996-7ae6-11ef-960e-020304050607",
"result": {
"runZapScript": true,
"debugLogging": false,
"audioScanFeedback": true,
"readersAutoDetect": true,
"readersScanMode": "insert",
"readersScanExitDelay": 0.0,
"readersScanIgnoreSystems": ["DOS"]
}
}

settings.update

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:

KeyTypeRequiredDescription
runZapScriptbooleanNoWhether ZapScript execution is enabled.
debugLoggingbooleanNoWhether debug logging is enabled.
audioScanFeedbackbooleanNoWhether audio feedback on scan is enabled.
readersAutoDetectbooleanNoWhether automatic reader detection is enabled.
readersScanModestringNoCurrent scan mode setting.
readersScanExitDelaynumberNoDelay before exiting scan mode in seconds.
readersScanIgnoreSystemsstring[]NoList of system IDs to ignore during scanning.

Result

Returns null on success.

Example

Request
{
"jsonrpc": "2.0",
"id": "562c0b60-7ae8-11ef-87d7-020304050607",
"method": "settings.update",
"params": {
"debugLogging": false
}
}
Response
{
"jsonrpc": "2.0",
"id": "562c0b60-7ae8-11ef-87d7-020304050607",
"result": null
}

settings.reload

Reload settings from the configuration file.

Parameters

None.

Result

Returns null on success.

Example

Request
{
"jsonrpc": "2.0",
"id": "562c0b60-7ae8-11ef-87d7-020304050607",
"method": "settings.reload"
}
Response
{
"jsonrpc": "2.0",
"id": "562c0b60-7ae8-11ef-87d7-020304050607",
"result": null
}

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

List all mappings.

Returns a list of all active and inactive mappings entries stored on server.

Parameters

None.

Result

KeyTypeRequiredDescription
mappingsMapping[]YesList of all stored mappings. See mapping object.
Mapping object
KeyTypeRequiredDescription
idstringYesInternal database ID of mapping entry. Used to reference mapping for updates and deletions.
addedstringYesTimestamp of the time mapping was created in RFC3339 format.
labelstringYesAn optional display name shown to the user.
enabledbooleanYesTrue if the mapping will be used when looking up matching mappings.
typestringYesThe field which will be matched against:
_ uid: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
_ text: match on the stored text on token.
* data: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this.
matchstringYesThe method used to match a mapping pattern:
_ exact: match the entire string exactly to the field.
_ partial: match part of the string to the field.
* regex: use a regular expression to match the field.
patternstringYesPattern that will be matched against the token, using the above settings.
overridestringYesFinal text that will completely replace the existing token text if a match was successful.

Example

Request
{
"jsonrpc": "2.0",
"id": "1a8bee28-7aef-11ef-8427-020304050607",
"method": "mappings"
}
Response
{
"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

Create a new mapping.

Parameters

An object:

KeyTypeRequiredDescription
labelstringYesAn optional display name shown to the user.
enabledbooleanYesTrue if the mapping will be used when looking up matching mappings.
typestringYesThe field which will be matched against:
_ uid: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
_ text: match on the stored text on token.
* data: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this.
matchstringYesThe method used to match a mapping pattern:
_ exact: match the entire string exactly to the field.
_ partial: match part of the string to the field.
* regex: use a regular expression to match the field.
patternstringYesPattern that will be matched against the token, using the above settings.
overridestringYesFinal text that will completely replace the existing token text if a match was successful.

Result

KeyTypeRequiredDescription
idstringYesDatabase ID of new mapping entry.

Example

Request
{
"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
{
"jsonrpc": "2.0",
"id": "562c0b60-7ae8-11ef-87d7-020304050607",
"result": {
"id": "2"
}
}

mappings.delete

Delete an existing mapping.

Parameters

An object:

KeyTypeRequiredDescription
idnumberYesDatabase ID of mapping.

Result

Returns null on success.

Example

Request
{
"jsonrpc": "2.0",
"id": "562c0b60-7ae8-11ef-87d7-020304050607",
"method": "mappings.delete",
"params": {
"id": 1
}
}
Response
{
"jsonrpc": "2.0",
"id": "562c0b60-7ae8-11ef-87d7-020304050607",
"result": null
}

mappings.update

Change an existing mapping.

Parameters

An object:

KeyTypeRequiredDescription
idnumberYesInternal database ID of mapping entry.
labelstringNoAn optional display name shown to the user.
enabledbooleanNoTrue if the mapping will be used when looking up matching mappings.
typestringNoThe field which will be matched against:
_ uid: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
_ text: match on the stored text on token.
* data: match on the raw token data, if available. This is converted from bytes to a hexadecimal string and should be matched as this.
matchstringNoThe method used to match a mapping pattern:
_ exact: match the entire string exactly to the field.
_ partial: match part of the string to the field.
* regex: use a regular expression to match the field.
patternstringNoPattern that will be matched against the token, using the above settings.
overridestringNoFinal text that will completely replace the existing token text if a match was successful.

Only keys which are provided in the object will be updated in the database.

Result

Returns null on success.

Example

Request
{
"jsonrpc": "2.0",
"id": "e98fd686-7e62-11ef-8f8c-020304050607",
"method": "mappings.update",
"params": {
"id": 1,
"enabled": false
}
}
Response
{
"jsonrpc": "2.0",
"id": "e98fd686-7e62-11ef-8f8c-020304050607",
"result": null
}

mappings.reload

Reload mappings from the configuration file.

Parameters

None.

Result

Returns null on success.

Example

Request
{
"jsonrpc": "2.0",
"id": "562c0b60-7ae8-11ef-87d7-020304050607",
"method": "mappings.reload"
}
Response
{
"jsonrpc": "2.0",
"id": "562c0b60-7ae8-11ef-87d7-020304050607",
"result": null
}

Readers

readers.write

Attempt to write given text to the first available write-capable reader, if possible.

Parameters

An object:

KeyTypeRequiredDescription
textstringYesZapScript to be written to the token.

Result

Returns null on success.

Example

Request
{
"jsonrpc": "2.0",
"id": "562c0b60-7ae8-11ef-87d7-020304050607",
"method": "readers.write",
"params": {
"text": "**launch.system:snes"
}
}
Response
{
"jsonrpc": "2.0",
"id": "562c0b60-7ae8-11ef-87d7-020304050607",
"result": null
}

readers.write.cancel

Cancel any ongoing write operation.

Parameters

None.

Result

Returns null on success.

Example

Request
{
"jsonrpc": "2.0",
"id": "562c0b60-7ae8-11ef-87d7-020304050607",
"method": "readers.write.cancel"
}
Response
{
"jsonrpc": "2.0",
"id": "562c0b60-7ae8-11ef-87d7-020304050607",
"result": null
}

Service

version

Return server's current version and platform.

Parameters

None.

Result

KeyTypeRequiredDescription
platformstringYesID of platform the service is currently running on.
versionstringYesCurrent version of the running Zaparoo service.

Example

Request
{
"jsonrpc": "2.0",
"id": "ca47f646-7e47-11ef-971a-020304050607",
"method": "version"
}
Response
{
"jsonrpc": "2.0",
"id": "ca47f646-7e47-11ef-971a-020304050607",
"result": {
"platform": "mister",
"version": "2.0.0-dev"
}
}