bookhoard/docs/developer/api/system/settings.md

System Scan Settings API

Overview

The System Scan Settings API allows administrators to configure system-wide scan settings that apply to all libraries. These settings control the automatic scanning behavior for the entire Bookhoard system.

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

---

Endpoints

Get System Scan Settings

Retrieve the current system-wide scan settings.

Endpoint: GET /api/libraries/scan-settings

Authentication: Admin role required

Response:

• 200 OK: Returns current scan settings
• 401 Unauthorized: Invalid or missing authentication
• 403 Forbidden: User does not have admin role
• 500 Internal Server Error: Server error

Response Body:

{
  "scan_poll_interval_seconds": 60,
  "auto_scan_enabled": true
}

Fields:

• scan_poll_interval_seconds (integer): How often to scan all libraries in minutes (15-1440)
• auto_scan_enabled (boolean): Whether auto-scanning is enabled system-wide

Example:

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

---

Update System Scan Settings

Update the system-wide scan settings.

Endpoint: PUT /api/libraries/scan-settings

Authentication: Admin role required

Request Body:

{
  "scan_poll_interval_seconds": 30,
  "auto_scan_enabled": true
}

Fields:

• scan_poll_interval_seconds (integer, required): How often to scan all libraries in minutes
  • Minimum: 15 (15 minutes)
  • Maximum: 1440 (24 hours)
  • Default: 60
• auto_scan_enabled (boolean, required): Whether auto-scanning is enabled system-wide
  • Default: true

Response:

• 200 OK: Settings updated successfully
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Invalid or missing authentication
• 403 Forbidden: User does not have admin role
• 500 Internal Server Error: Server error

Success Response Body:

{
  "scan_poll_interval_seconds": 30,
  "auto_scan_enabled": true,
  "message": "scan settings updated successfully"
}

Error Response Body:

{
  "error": "error message"
}

Validation Rules:

• scan_poll_interval_seconds must be between 15 and 1440 minutes
• Both fields are required

Example:

curl -X PUT https://bookhoard.example.com/api/libraries/scan-settings \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "scan_poll_interval_seconds": 30,
    "auto_scan_enabled": true
  }'

---

Behavior

Scan Frequency

The scan_poll_interval_seconds setting determines how often the system will automatically scan all libraries for new media files. The scheduler will trigger scans for all libraries at the configured interval.

Constraints:

• Minimum: 15 minutes (to prevent excessive scanning)
• Maximum: 1440 minutes (24 hours)
• Default: 60 minutes (1 hour)

Auto-Scan Toggle

The auto_scan_enabled setting acts as a master switch for automatic scanning:

• When true: All libraries will be scanned automatically at the configured interval
• When false: No automatic scans will occur (manual scans still available)

System-Wide Scope

These settings apply to all libraries in the system. Individual users can no longer configure per-user scan settings. This ensures consistent scanning behavior across the entire Bookhoard instance.

---

Error Codes

Status Code	Error Description
400	Invalid request parameters (e.g., frequency outside range)
401	Missing or invalid JWT token
403	User lacks admin role
500	Internal server error (e.g., database connection issue)

---

Related Endpoints

• POST /api/libraries/{id}/scan - Manually trigger a scan for a specific library (admin only)
• GET /api/libraries - List all libraries
• GET /api/libraries/{id} - Get details for a specific library

---

Migration Notes

This API replaces the previous per-user scan settings system. The following changes were made:

• Removed: Per-user scan settings (previously in users table)
• Added: System-wide scan settings (now in system_settings table)
• Changed: Access control from user-specific to admin-only
• Preserved: Endpoint paths remain the same for backward compatibility

The migration ensures that:

1. All libraries scan at the same frequency
2. Only administrators can modify scan settings
3. The API endpoints remain unchanged for existing clients
4. The scheduler uses system-wide settings instead of user-specific settings