Configuration & API

Two pieces of configuration — the database registry (which databases and image folders) and the server TOML (how the server runs) — plus a REST API for everything the UI can do.

Databases: the registry

The server manages any number of scheduler databases. The list lives in a JSON registry at the platform config location — not in the TOML:

PlatformRegistry path
Windows%APPDATA%\psf-guard\config.json
macOS~/Library/Application Support/psf-guard/config.json
Linux~/.config/psf-guard/config.json

psf-guard server <db> <dirs...> registers that database on first run and reuses it afterwards; you can also manage the list from the desktop app's Settings panel or the /api/databases endpoints. For a one-off session that shouldn't touch your real config, pass --registry /tmp/scratch.json.

The default N.I.N.A. scheduler database on Windows lives at %LOCALAPPDATA%\NINA\SchedulerPlugin\schedulerdb.sqlite.

Server knobs: the TOML

cp psf-guard.toml.example psf-guard.toml
psf-guard server --config psf-guard.toml
[server]
port = 3000
host = "0.0.0.0"
# Optional: fraction of CPU cores for parallel work (both default sensibly).
# Interactive jobs (occlusion scans, on-demand previews) get scan_worker_ratio;
# background pre-generation gets background_worker_ratio and pauses entirely
# while an interactive job runs.
#scan_worker_ratio = 0.5
#background_worker_ratio = 0.25

[cache]
directory = "./cache"
file_ttl = "5m"        # 30s, 5m, 1h, 2h30m, 1d ...
directory_ttl = "5m"

[pregeneration]        # optional background preview warming
enabled = true
screen = true          # 1200px previews
large = false          # 2000px previews

Command-line arguments override the config file. A legacy [database]/[images] section is still parsed but ignored in server mode — databases come from the registry.

REST API

Per-database endpoints are nested under /api/db/{db_id}/; GET /api/databases lists the configured databases and their ids.

# List images with filters
curl "localhost:3000/api/db/my-db/images?project_id=2&status=pending"

# Update a grade
curl -X PUT localhost:3000/api/db/my-db/images/123/grade \
  -H "Content-Type: application/json" \
  -d '{"status": "accepted"}'

# Fetch processed images
curl "localhost:3000/api/db/my-db/images/123/preview?size=large" -o preview.png
curl "localhost:3000/api/db/my-db/images/123/annotated" -o stars.png

Preview and annotated images generate asynchronously: a cache miss returns HTTP 202 ({"state": "generating"}) and a batch generation-status endpoint reports readiness — the UI uses this to show its "Generating…" badges without long-lived requests.

Database management endpoints (POST/PUT/DELETE /api/databases) are disabled unless the server runs with --allow-database-management, since they let any reachable client edit your configured database list. The desktop app always enables them for its own local server.

Known limitations