Files

T

john-okeefe 44a0f8c7a4 docs(api): document unified tunable system settings endpoints

The scattered scan-settings JSON routes are superseded by the new
admin-only /api/system/settings pair backed by the SettingsRegistry
(introduced in 885f6d8 / bc47450).

- Rewrite system/settings.md around GET/PUT /api/system/settings:
  SettingEntry metadata shape (type, min/max, requires_restart,
  category, group, is_default), type-aware validation rules, and the
  full tunable-setting catalog (scanner, general, security, api, sync,
  performance) with defaults, ranges, and restart requirements
- Note the legacy /api/libraries/scan-settings routes as back-compat
  only (they now refresh the registry cache on write)
- Add system/config.md for GET/PUT /api/system/config: raw key/value
  system configuration (e.g. base_url), including validation notes and
  guidance to prefer the typed settings endpoint for registry keys

2026-08-20 14:40:45 -04:00

2.2 KiB

Raw Blame History

System Config API

Overview

Raw key/value system configuration storage (backed by the system_config table). Unlike the typed System Settings API, this endpoint reads and writes arbitrary config keys as plain strings — including keys without registry metadata, such as base_url.

Base URL: /api/system Authentication: Admin JWT token required Content-Type: application/json

Endpoints

Get System Configuration

Retrieve all system configuration entries as a flat key/value map.

Endpoint: GET /api/system/config

Authentication: Admin role required

Response: 200 OK

{
  "base_url": "http://192.168.1.100:8765",
  "default_timezone": "America/New_York"
}

Example:

curl -X GET https://bookhoard.example.com/api/system/config \
  -H "Authorization: Bearer <admin_token>"

Update System Configuration

Update one or more config values.

Endpoint: PUT /api/system/config

Authentication: Admin role required

Request Body: a flat map of keys to string values. Only the supplied keys are updated.

{
  "base_url": "https://bookhoard.example.com"
}

Validation: values for known keys are validated where applicable — for example, default_timezone must be a valid IANA timezone (time.LoadLocation); invalid values return 400 without persisting.

Response: 200 OK on success; 400 (invalid value/format), 401, 403, 500 on failure.