Configure PSF Guard and Use the API

The JSON registry lists database catalogs and image folders, while the server TOML file controls runtime configuration settings. The REST API exposes the same operations as the graphical user interface.

Understand the catalog registry

The server can manage multiple image catalogs. Each catalog uses the Target Scheduler database mapping. The database list is stored in a JSON registry file at the platform config location, rather than in the TOML configuration file:

The psf-guard server <db> <dirs...> command registers the specified database on the first execution and reuses it in subsequent sessions. You can also manage this list using the Settings panel in the desktop application or the /api/databases endpoints. If you want to run a temporary session without modifying your permanent configuration, pass a scratch path to the --registry flag, such as --registry /tmp/scratch.json.

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

Each registry entry can also set export_dir to an absolute server-side destination:

{
  "id": "archive",
  "name": "Archive",
  "db_path": "/data/archive.sqlite",
  "image_dirs": ["/data/images"],
  "export_dir": "/data/stacking-exports"
}

When this is configured, overview exports run as background jobs under the specified directory. The client selects a project, target, and layout, rather than specifying an arbitrary path. You can set this field in the user interface under Settings → Databases → Edit. Leaving this value empty disables server-side exports.

Configure Seiza catalogs and plate solving

PSF Guard uses the standard catalog discovery process from Seiza. Data installed by running seiza setup is discovered automatically. You can specify a custom catalog bundle directory by setting the SEIZA_CATALOG_DIR environment variable or by defining the top-level astrometry.data_dir field in the registry file:

"astrometry": {
  "data_dir": "/path/to/seiza-data",
  "satellite_elements": "historical-or-active.tle"
}

You must restart PSF Guard after changing this environment variable or registry field. For more details on download commands, required files, Docker volume mounts, validating capabilities, the user interface workflow, and solution cache behavior, see the Sky Context & Plate Solving section.

Configure server settings with the TOML file

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 settings specified in the configuration file. The server continues to parse legacy [database] and [images] sections but ignores them in server mode, as it reads database configurations from the registry file instead.

Use the REST API

Per-database endpoints are located under the /api/db/{db_id}/ path. Sending a GET request to /api/databases returns a list of configured databases and their unique identifiers.

# 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"}'

# Start and inspect a target-aware quality scan
curl -X POST localhost:3000/api/db/my-db/analysis/quality-scan \
  -H "Content-Type: application/json" \
  -d '{"target_id": 42}'
curl localhost:3000/api/db/my-db/analysis/quality-scan

# 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

# Catalog capability diagnostics and on-demand plate solving
curl "localhost:3000/api/astrometry/capabilities"
curl "localhost:3000/api/db/my-db/images/123/astrometry"
curl -X POST "localhost:3000/api/db/my-db/images/123/astrometry"

# Cached or on-demand satellite prediction
curl "localhost:3000/api/db/my-db/images/123/satellites"
curl -X POST "localhost:3000/api/db/my-db/images/123/satellites"

The export API provides three distinct routes. The read-only route streams the exported files as a ZIP archive. The local path route can write files to any directory on the server file system and requires database management permissions. The GET/POST /api/db/{db_id}/export/server route reports the operation's progress and restricts file writes to the configured export_dir directory. For more details on request options and code examples, see the Export for Stacking section.

Preview and annotated images are generated asynchronously. If the requested image is not cached, the server returns an HTTP 202 status code containing {"state": "generating"}. The client can poll the batch generation-status endpoint to verify when the files are ready. This design allows the user interface to display generation badges without maintaining long-lived HTTP requests.

The quality scan calculates spatial and photometric metrics, and then generates fresh plate solutions from image pixels. These results are saved in the database-specific cache and are used by the sequence analysis endpoint. For more details about target coordinates, failure handling, and regrading safety, see the Astrometry Quality section.

The database management endpoints (such as POST/PUT/DELETE /api/databases) are disabled by default unless the server is started with the --allow-database-management flag. This prevents unauthorized clients on the network from modifying your database list. The desktop application always enables these endpoints for its integrated local server.

Review known limitations

• One-shot-color (OSC) images are displayed in luminance-first mode: raw OSC FITS files that contain a recognized BAYERPAT header are debayered and then converted to grayscale luminance for grading and quality analysis. The single-frame grader does not render them in full color.
• The scanner makes directory path assumptions: directory layouts matching the %DATEMINUS12%/%TARGETNAME%/%DATEMINUS12%/LIGHT/... pattern (with or without the leading date) are detected automatically. Other directory structures might not be recognized correctly. If you need support for additional directory structures, please open an issue on GitHub.
• You should create database and file backups: back up your database catalog before performing bulk edits, and back up your raw FITS files before executing file-moving commands.