Core API/Methods: Difference between revisions

VisualWikitext

Latest revision as of 06:14, 24 December 2024

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

Launching

launch

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:

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.
data	string	No*	The raw data read from a token, converted to a hexadecimal string. Used in mappings and detection of NFC toys.

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": "launch",
    "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.history

Returns a list of the last recorded token launches.

Parameters

None.

Result

Key	Type	Required	Description
entries	LaunchEntry[]	Yes	A list of recorded token launches.

Launch entry object

Key	Type	Required	Description
data	string	No	Same as launch parameter.
success	boolean	Yes	True if the launch was successful.
text	string	No	Same as launch parameter.
time	string	Yes	Timestamp of the launch time in RFC3339 format.
type	string	No	Same as launch parameter.
uid	string	No	Same as launch parameter.

Example

Request

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

Query the media database and return all matching indexed media.

Parameters

An object:

Key	Type	Required	Description
query	string	Yes	Case-insensitive search by filename. By default, query is split by white space and results are found which contain every word.
systems	string[]	No	Case-sensitive list of system IDs to restrict search to. A missing key or empty list will search all systems.
maxResults	number	No	Max number of results to return. Default is 250.

Result

Key	Type	Required	Description
results	Media[]	Yes	A list of all search results from the given query.
total	number	Yes	Total number of search results.

Media object

Key	Type	Required	Description
system	System	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	Path to the media file. If possible, this path will be compressed into the `<system>/<path>` launch format.

System object

Key	Type	Required	Description
id	string	Yes	Internal system ID for this system.
name	string	Yes	Display name of the system.
category	string	Yes	Category 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.index

Create a new media database index.

During an index, the server will emit media.indexing 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.

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.index"
}

Response

{
    "jsonrpc": "2.0",
    "id": "6f20e07c-7a5e-11ef-84bb-020304050607",
    "result": null
}

systems

List all currently indexed systems.

Parameters

None.

Result

Key	Type	Required	Description
systems	System[]	Yes	A 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

Key	Type	Required	Description
reader	string[]	Yes	A list of manually configured reader driver connection strings. See reader.
audioFeedback	boolean	Yes
detectReaders	boolean	Yes
insertMode	boolean	Yes
insertModeBlocklist	string[]	Yes
insertModeExitDelay	number	Yes
consoleLogging	boolean	Yes
debug	boolean	Yes	See debug.
systems	Systems config	Yes	The systems section of the config file.

Systems config

Key	Type	Required	Description
rootFolder	string[]	Yes

Example

Request

{
    "jsonrpc": "2.0",
    "id": "f208d996-7ae6-11ef-960e-020304050607",
    "method": "settings"
}

Response

{
    "jsonrpc": "2.0",
    "id": "f208d996-7ae6-11ef-960e-020304050607",
    "result": {
        "readers": ["pn532_uart:/dev/ttyUSB0"],
        "detectReaders": true,
        "audioFeedback": true,
        "insertMode": false,
        "insertModeBlocklist": ["DOS"],
        "insertModeExitDelay": 0,
        "consoleLogging": false,
        "debug": false,
        "systems": {
            "rootFolders": []
        }
    }
}

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:

Key	Type	Required	Description
reader	string[]	Yes	A list of manually configured reader driver connection strings. See reader.
audioFeedback	boolean	Yes
detectReaders	boolean	Yes
insertMode	boolean	Yes
insertModeBlocklist	string[]	Yes
insertModeExitDelay	number	Yes
consoleLogging	boolean	Yes
debug	boolean	Yes	See debug.
systems	Systems config	Yes	The systems section of the config file.

Systems config

Key	Type	Required	Description
rootFolder	string[]	Yes

Result

Returns null on success.

Example

Request

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

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

Key	Type	Required	Description
mappings	Mapping[]	Yes	List of all stored mappings. See mapping object.

Mapping object

Key	Type	Required	Description
added	string	Yes	Timestamp of the time mapping was created in RFC3339 format.
enabled	boolean	Yes	True if the mapping will be used when looking up matching mappings.
id	number	Yes	Internal database ID of mapping entry. Used to reference mapping for updates and deletions.
label	string	No	An optional display name shown to the user.
type	string	Yes	The 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.
match	string	Yes	The 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.
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

{
    "jsonrpc": "2.0",
    "id": "1a8bee28-7aef-11ef-8427-020304050607",
    "method": "mappings"
}

Response

{
    "jsonrpc": "2.0",
    "id": "1a8bee28-7aef-11ef-8427-020304050607",
    "result": {
        "mappings": [
            {
                "added": "1970-01-21T06:08:18+08:00",
                "enabled": true,
                "id": "1",
                "label": "barcode pokemon",
                "match": "partial",
                "override": "**launch.search:gbc/*pokemon*gold*",
                "pattern": "9780307468031",
                "type": "text"
            }
        ]
    }
}

mappings.new

Create a new mapping.

Parameters

An object:

Key	Type	Required	Description
enabled	boolean	Yes	True if the mapping will be used when looking up matching mappings.
label	string	No	An optional display name shown to the user.
type	string	Yes	The 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.
match	string	Yes	The 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.
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.

Result

Key	Type	Required	Description
id	number	Yes	Database ID of new mapping entry.

Example

mappings.delete

Delete an existing mapping.

Parameters

Key	Type	Required	Description
id	number	Yes	Database ID of mapping.

Result

Returns null on success.

Example

mappings.update

Change an existing mapping.

Parameters

An object:

Key	Type	Required	Description
id	number	Yes	Internal database ID of mapping entry.
enabled	boolean	No	True if the mapping will be used when looking up matching mappings.
label	string	No	An optional display name shown to the user.
type	string	No	The 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.
match	string	No	The 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.
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.

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": {
        "enabled": false,
        "id": 1
    }
}

Result

Readers

readers

List all currently connected readers.

Parameters

Result

Example

readers.write

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.

Result

Returns null on success.

Example

Clients

Clients can only be managed through the API via a device-local connection.

clients

List all registered clients and associated data.

Parameters

None.

Result

Key	Type	Required	Description
clients	Client[]	Yes	List of all registered clients.

Client object

Key	Type	Required	Description
id	string	Yes	Unique ID of client.
name	string	No	Display name of client.
secret	string	Yes	Secret key of client.
address	string	No	Last connected address of client.

Example

Request

{
    "jsonrpc": "2.0",
    "id": "aae4aaa4-7e48-11ef-9e36-020304050607",
    "method": "clients"
}

Response

{
    "jsonrpc": "2.0",
    "id": "aae4aaa4-7e48-11ef-9e36-020304050607",
    "result": {
        "clients": [
            {
                "address": "",
                "id": "0b150eae-0f1b-4ede-9d7c-09c0ae0509ea",
                "name": "Test",
                "secret": "d3edfd14ce20e64f01c06932dcb5553560d0995a8871b7398c9a7b7fcc42e670"
            }
        ]
    }
}

clients.new

Create a new client with a newly generated ID and secret.

Parameters

Optionally, an object:

Key	Type	Required	Description
name	string	No	Display name of client.

Result

Example

clients.delete

Delete an existing client.

Parameters

Result

Example

Service

version

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

{
    "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"
    }
}

@@ Line 1: / Line 1: @@
-=== Launching ===
+Methods are used to execute actions and request data back from the API.
-==== launch ====
+== Launching ==
+=== launch ===
 Emulate the scanning of a token.
-This method accepts two types of parameters:
+==== Parameters ====
+Accepts two types of parameters:
-* A single string, in which case the string will be treated as the token text with default launch options. Similar to the [[TapTo API#Launch Endpoint|Launch Endpoint]].
+* A string, in which case the string will be treated as the token text with all other options set as default.
-* Or a parameters object with the following keys:
+* An object:
 {| class="wikitable"
@@ Line 18: / Line 21: @@
 |string
 |No
-|An internal category of the type of token being scanned. Not currently in use outside of logging.
+|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 scanner. For example, the UID of an NFC tag. Used for matching mappings.
+|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 [[TapScript]].
+|The main text to be processed from a scan, should contain [[ZapScript]].
 |-
 |data
 |string
 |No*
-|The raw data read from a token, converted to a hexadecimal string. Used in mappings and detection of NFC toys such as Amiibos and Lego Dimensions.
+|The raw data read from a token, converted to a hexadecimal string. Used in mappings and detection of NFC toys.
 |}
 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 <code>uid</code>, <code>text</code> or <code>data</code> value.
-This method does not have any response results. Currently, it is not reported if the launched TapScript encounters an error during launching.
+==== Result ====
+Returns <code>null</code> 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 ====
-==== stop ====
+===== Request =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "52f6242e-7a5a-11ef-bf93-020304050607",
+    "method": "launch",
+    "params": {
+        "text": "**launch.system:snes"
+    }
+}
+</syntaxhighlight>
+===== Response =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "52f6242e-7a5a-11ef-bf93-020304050607",
+    "result": null
+}
+</syntaxhighlight>
+=== stop ===
 Kill any active launcher, if possible.
-This methods takes no parameters and does not currently report whether it was successful or not.
+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.
-==== history ====
+==== Parameters ====
+None.
-=== Media ===
+==== Result ====
+Returns <code>null</code> on success.
-==== media.search ====
+Currently, it is not reported if a process was killed or not.
+==== Example ====
+===== Request =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "176b4558-7a5b-11ef-b318-020304050607",
+    "method": "stop"
+}
+</syntaxhighlight>
+===== Response =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "176b4558-7a5b-11ef-b318-020304050607",
+    "result": null
+}
+</syntaxhighlight>
+== Tokens ==
+=== tokens.history ===
+Returns a list of the last recorded token launches.
+==== Parameters ====
+None.
+==== Result ====
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|entries
+|[[API/Methods#Launch entry object|LaunchEntry]][]
+|Yes
+|A list of recorded token launches.
+|}
+===== Launch entry object =====
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|data
+|string
+|No
+|Same as [[API/Methods#launch|launch parameter]].
+|-
+|success
+|boolean
+|Yes
+|True if the launch was successful.
+|-
+|text
+|string
+|No
+|Same as [[API/Methods#launch|launch parameter]].
+|-
+|time
+|string
+|Yes
+|Timestamp of the launch time in RFC3339 format.
+|-
+|type
+|string
+|No
+|Same as [[API/Methods#launch|launch parameter]].
+|-
+|uid
+|string
+|No
+|Same as [[API/Methods#launch|launch parameter]].
+|}
+==== Example ====
+===== Request =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "5e9f3a0e-7a5b-11ef-8084-020304050607",
+    "method": "history"
+}
+</syntaxhighlight>
+===== Response =====
+<syntaxhighlight lang="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": ""
+            }
+        ]
+    }
+}
+</syntaxhighlight>
+== Media ==
+=== media.search ===
 Query the media database and return all matching indexed media.
-This request accepts the following parameters object:
+==== Parameters ====
+An object:
 {| class="wikitable"
 !Key
@@ Line 63: / Line 214: @@
 |Case-insensitive search by filename. By default, query is split by white space and results are found which contain every word.
 |-
-|system
+|systems
 |string[]
 |No
@@ Line 73: / Line 224: @@
 |Max number of results to return. Default is 250.
 |}
-And a response with the following results object:
+==== Result ====
 {| class="wikitable"
 !Key
@@ Line 136: / Line 288: @@
 |Category of system. This field is not yet formalised.
 |}
-==== media.index ====
-Start a new media database index.
-This method can, optionally, take a list of strings of system IDs to restrict the index to just those systems.
+==== Example ====
+===== Request =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "47f80537-7a5d-11ef-9c7b-020304050607",
+    "method": "media.search",
+    "params": {
+        "query": "240p"
+    }
+}
+</syntaxhighlight>
+===== Response =====
+<syntaxhighlight lang="json">
+{
+    "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
+    }
+}
+</syntaxhighlight>
+=== media.index ===
+Create a new media database index.
+During an index, the server will emit [[API/Notifications#media.indexing|media.indexing]] notifications showing progress of the index.
+==== Parameters ====
+Optionally, an object:
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|systems
+|string[]
+|No
+|List of system IDs to restrict indexing to. Other system indexes will remain as is.
+|}
+An omitted or <code>null</code> value parameters key is also valid and will index every system.
+==== Result ====
+Returns <code>null</code> on success once indexing is complete.
+==== Example ====
+===== Request =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "6f20e07c-7a5e-11ef-84bb-020304050607",
+    "method": "media.index"
+}
+</syntaxhighlight>
-This method does not block and wait for the index to complete. It will return a response immediately and start in the background. <code>media.indexing</code> notifications will be sent to show progress of current indexing process.
+===== Response =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "6f20e07c-7a5e-11ef-84bb-020304050607",
+    "result": null
+}
-==== systems ====
+</syntaxhighlight>
+=== systems ===
 List all currently indexed systems.
-This method has no parameters and returns a response results object of a list of [[TapTo API#System object|System objects]].
+==== Parameters ====
+None.
+==== Result ====
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|systems
+|System[]
+|Yes
+|A list of all indexed systems.
+|}
+See [[API/Methods#System object|system]] object.
+==== Example ====
-=== Settings ===
+===== Request =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "dbd312f3-7a5f-11ef-8f29-020304050607",
+    "method": "systems"
+}
-==== settings ====
+</syntaxhighlight>
+===== Response =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "dbd312f3-7a5f-11ef-8f29-020304050607",
+    "result": {
+        "systems": [
+            {
+                "category": "Handheld",
+                "id": "GameboyColor",
+                "name": "Gameboy Color"
+            },
+            {
+                "category": "Computer",
+                "id": "EDSAC",
+                "name": "EDSAC"
+            }
+        ]
+    }
+}
+</syntaxhighlight>
+== Settings ==
+=== settings ===
 List currently set configuration settings.
-This method will list values set in the [[Config File (tapto.ini)|Config File]]. Values may be hidden which are not appropriate to be read remotely.
+This method will list values set in the [[Config File (tapto.ini)|Config File]]. Some config file options may be omitted which are not appropriate to be read or written remotely.
-===== Parameters =====
+==== Parameters ====
-This method has no parameters.
+None.
-===== Results =====
+==== Result ====
 {| class="wikitable"
 !Key
@@ Line 224: / Line 502: @@
 |}
-====== API config ======
+==== Example ====
+===== Request =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "f208d996-7ae6-11ef-960e-020304050607",
+    "method": "settings"
+}
+</syntaxhighlight>
+===== Response =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "f208d996-7ae6-11ef-960e-020304050607",
+    "result": {
+        "readers": ["pn532_uart:/dev/ttyUSB0"],
+        "detectReaders": true,
+        "audioFeedback": true,
+        "insertMode": false,
+        "insertModeBlocklist": ["DOS"],
+        "insertModeExitDelay": 0,
+        "consoleLogging": false,
+        "debug": false,
+        "systems": {
+            "rootFolders": []
+        }
+    }
+}
-==== settings.update ====
+</syntaxhighlight>
+=== settings.update ===
 Update one or more settings in-memory and save changes to disk.
-=== Mappings ===
+This method will only write values which are supplied. Existing values will not be modified.
+==== Parameters ====
+An object:
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|reader
+|string[]
+|Yes
+|A list of manually configured [[Reader Drivers|reader driver]] connection strings. See [[Config File (tapto.ini)#Manual Reader Connection (reader)|reader]].
+|-
+|audioFeedback
+|boolean
+|Yes
+|
+|-
+|detectReaders
+|boolean
+|Yes
+|
+|-
+|insertMode
+|boolean
+|Yes
+|
+|-
+|insertModeBlocklist
+|string[]
+|Yes
+|
+|-
+|insertModeExitDelay
+|number
+|Yes
+|
+|-
+|consoleLogging
+|boolean
+|Yes
+|
+|-
+|debug
+|boolean
+|Yes
+|See [[Config File (tapto.ini)#Debug Logging (debug)|debug]].
+|-
+|systems
+|Systems config
+|Yes
+|The systems section of the config file.
+|}
+====== Systems config ======
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|rootFolder
+|string[]
+|Yes
+|
+|}
+==== Result ====
+Returns <code>null</code> on success.
+==== Example ====
+===== Request =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "562c0b60-7ae8-11ef-87d7-020304050607",
+    "method": "settings.update",
+    "params": {
+        "debug": false
+    }
+}
+</syntaxhighlight>
+===== Response =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "562c0b60-7ae8-11ef-87d7-020304050607",
+    "result": null
+}
+</syntaxhighlight>
-==== mappings ====
+== 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 =====
+==== Parameters ====
+None.
-===== Results =====
+==== Result ====
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|mappings
+|Mapping[]
+|Yes
+|List of all stored mappings. See [[API/Methods#Mapping object|mapping object]].
+|}
-==== mappings.new ====
+===== Mapping object =====
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|added
+|string
+|Yes
+|Timestamp of the time mapping was created in RFC3339 format.
+|-
+|enabled
+|boolean
+|Yes
+|True if the mapping will be used when looking up matching mappings.
+|-
+|id
+|number
+|Yes
+|Internal database ID of mapping entry. Used to reference mapping for updates and deletions.
+|-
+|label
+|string
+|No
+|An optional display name shown to the user.
+|-
+|type
+|string
+|Yes
+|The field which will be matched against:
+* <code>uid</code>: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
+* <code>text</code>: match on the stored text on token.
+* <code>data</code>: 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:
+* <code>exact</code>: match the entire string exactly to the field.
+* <code>partial</code>: match part of the string to the field.
+* <code>regex</code>: 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 =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "1a8bee28-7aef-11ef-8427-020304050607",
+    "method": "mappings"
+}
+</syntaxhighlight>
+===== Response =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "1a8bee28-7aef-11ef-8427-020304050607",
+    "result": {
+        "mappings": [
+            {
+                "added": "1970-01-21T06:08:18+08:00",
+                "enabled": true,
+                "id": "1",
+                "label": "barcode pokemon",
+                "match": "partial",
+                "override": "**launch.search:gbc/*pokemon*gold*",
+                "pattern": "9780307468031",
+                "type": "text"
+            }
+        ]
+    }
+}
+</syntaxhighlight>
+=== mappings.new ===
 Create a new mapping.
-===== Parameters =====
+==== Parameters ====
+An object:
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|enabled
+|boolean
+|Yes
+|True if the mapping will be used when looking up matching mappings.
+|-
+|label
+|string
+|No
+|An optional display name shown to the user.
+|-
+|type
+|string
+|Yes
+|The field which will be matched against:
+* <code>uid</code>: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
+* <code>text</code>: match on the stored text on token.
+* <code>data</code>: 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:
+* <code>exact</code>: match the entire string exactly to the field.
+* <code>partial</code>: match part of the string to the field.
+* <code>regex</code>: 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.
+|}
+==== Result ====
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|id
+|number
+|Yes
+|Database ID of new mapping entry.
+|}
-===== Results =====
+==== Example ====
-==== mappings.delete ====
+=== mappings.delete ===
 Delete an existing mapping.
-===== Parameters =====
+==== Parameters ====
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|id
+|number
+|Yes
+|Database ID of mapping.
+|}
+==== Result ====
+Returns <code>null</code> on success.
-===== Results =====
+==== Example ====
-==== mappings.update ====
+=== mappings.update ===
 Change an existing mapping.
-===== Parameters =====
+==== Parameters ====
+An object:
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|id
+|number
+|Yes
+|Internal database ID of mapping entry.
+|-
+|enabled
+|boolean
+|No
+|True if the mapping will be used when looking up matching mappings.
+|-
+|label
+|string
+|No
+|An optional display name shown to the user.
+|-
+|type
+|string
+|No
+|The field which will be matched against:
+* <code>uid</code>: match on UID, if available. UIDs are normalized before matching to remove spaces, colons and convert to lowercase.
+* <code>text</code>: match on the stored text on token.
+* <code>data</code>: 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:
+* <code>exact</code>: match the entire string exactly to the field.
+* <code>partial</code>: match part of the string to the field.
+* <code>regex</code>: 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.
+|}
+Only keys which are provided in the object will be updated in the database.
+==== Result ====
+Returns <code>null</code> on success.
+==== Example ====
+===== Request =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "e98fd686-7e62-11ef-8f8c-020304050607",
+    "method": "mappings.update",
+    "params": {
+        "enabled": false,
+        "id": 1
+    }
+}
+</syntaxhighlight>
-===== Results =====
+===== Result =====
-=== Readers ===
+== Readers ==
-==== readers ====
+=== readers ===
 List all currently connected readers.
-===== Parameters =====
+==== Parameters ====
-===== Results =====
+==== Result ====
-==== readers.write ====
+==== Example ====
+=== readers.write ===
 Attempt to write given text to the first available write-capable reader, if possible.
-===== Parameters =====
+==== Parameters ====
+An object:
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|text
+|string
+|Yes
+|ZapScript to be written to the token.
+|}
+==== Result ====
+Returns <code>null</code> on success.
-===== Results =====
+==== Example ====
-=== Clients ===
+== Clients ==
 ''Clients can only be managed through the API via a device-local connection.''
-==== clients ====
+=== clients ===
-List all clients (including disconnected) and associated data.
+List all registered clients and associated data.
+==== Parameters ====
+None.
+==== Result ====
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|clients
+|Client[]
+|Yes
+|List of all registered clients.
+|}
+===== Client object =====
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|id
+|string
+|Yes
+|Unique ID of client.
+|-
+|name
+|string
+|No
+|Display name of client.
+|-
+|secret
+|string
+|Yes
+|Secret key of client.
+|-
+|address
+|string
+|No
+|Last connected address of client.
+|}
+==== Example ====
+===== Request =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "aae4aaa4-7e48-11ef-9e36-020304050607",
+    "method": "clients"
+}
+</syntaxhighlight>
+===== Response =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "aae4aaa4-7e48-11ef-9e36-020304050607",
+    "result": {
+        "clients": [
+            {
+                "address": "",
+                "id": "0b150eae-0f1b-4ede-9d7c-09c0ae0509ea",
+                "name": "Test",
+                "secret": "d3edfd14ce20e64f01c06932dcb5553560d0995a8871b7398c9a7b7fcc42e670"
+            }
+        ]
+    }
+}
+</syntaxhighlight>
-==== clients.new ====
+=== clients.new ===
 Create a new client with a newly generated ID and secret.
-==== clients.delete ====
+==== Parameters ====
+Optionally, an object:
+{| class="wikitable"
+!Key
+!Type
+!Required
+!Description
+|-
+|name
+|string
+|No
+|Display name of client.
+|}
+==== Result ====
+==== Example ====
+=== clients.delete ===
 Delete an existing client.
-=== Service ===
+==== Parameters ====
+==== Result ====
+==== Example ====
+== Service ==
-==== version ====
+=== version ===
 Return server's current version and platform.
+==== Parameters ====
+None.
+==== Result ====
+{| class="wikitable"
+!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 =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "ca47f646-7e47-11ef-971a-020304050607",
+    "method": "version"
+}
+</syntaxhighlight>
+===== Response =====
+<syntaxhighlight lang="json">
+{
+    "jsonrpc": "2.0",
+    "id": "ca47f646-7e47-11ef-971a-020304050607",
+    "result": {
+        "platform": "mister",
+        "version": "2.0.0-dev"
+    }
+}
+</syntaxhighlight>