Scripting API

Kiosk can be driven from a script. The Scripting API lets technical artists provision libraries headlessly — create a database, add categories, and register source folders — without ever opening the interface. It’s ideal for bootstrapping a new studio library or scripting repeatable setup across machines.

The Scripting API is a Pro feature (included in Pro and Studio). On the free tier, --run-script prints an upgrade notice and exits before any script runs.

How it works

You run a script through the Kiosk executable with the --run-script flag:

kiosk.exe --run-script setup_library.py

The script runs inside Kiosk’s own interpreter, with a kiosk object already injected into its global namespace — no import, no separate install, and the license is already loaded. Writes go through the same database layer as the GUI, so there’s no risk of corrupting the library.

add_source is register-only: it writes the source row but does not scan the folder. Files are indexed on the next normal app scan. This keeps scripts fast and light — no thumbnailing or background workers are spun up.

If a Kiosk window is already open on the same library, it won’t see new sources until the next rescan or restart.

Example

# setup_library.py  —  kiosk.exe --run-script setup_library.py

# Create (or open) a library: makes the folder + kiosk.db, seeded with the
# default categories, exactly like first run.
db = kiosk.create_database(r"D:\Studio\AssetLibrary")

# Add a custom category and register a source folder under it.
db.add_category("props")
db.add_source(
    "props",
    "Kitchen",
    r"D:\assets\kitchen",
    extensions=[".fbx", ".obj"],
)

API reference

The script’s global kiosk object is the entry point. Database operations return a LibraryDatabase you call methods on.

Call	Does
kiosk.create_database(dir)	Create (or open) a library: makes the folder + kiosk.db, seeded with the default categories like first run. Returns a LibraryDatabase.
kiosk.open_database(dir)	Open an existing library; raises if there’s no kiosk.db.
kiosk.local_database()	Open the user’s active/local library (the one the app uses).
db.add_category(name, icon=…)	Create a category. Idempotent — duplicates are skipped.
db.add_source(cat, name, folder, extensions=…, color_space=…)	Register a source folder under a category. Register-only — no scan.
db.categories()	Read back the registered categories.
db.sources(cat)	Read back the sources registered under a category.

Errors

Validation failures raise a clear KioskScriptError — for an empty name, a missing category, a non-existent folder, or a duplicate source — instead of a raw database error, so scripts fail with a message you can act on.

Stability

The Scripting API is treated as a stable contract: methods are added over time, not renamed or removed, so scripts keep working across Kiosk updates. This mirrors the Extension API policy.