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 poll for file changes in seconds (1-3600)
• 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 poll for file changes in seconds
  • Minimum: 1 (1 second)
  • Maximum: 3600 (1 hour)
  • 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 1 and 3600 seconds (1 second to 1 hour)
• 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

Poll Interval

The scan_poll_interval_seconds setting determines how often the system will poll library folders for file changes as a fallback to real-time file watching.

Constraints:

• Minimum: 1 second
• Maximum: 3600 seconds (1 hour)
• Default: 60 seconds

Auto-Scan Toggle

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

• When true: File watching and polling fallback are active for all libraries
• When false: No automatic file monitoring occurs (manual scans still available)

File Watching System

The scan settings control the file watching system which consists of:

1. Real-time file watching: Uses fsnotify to detect file changes immediately
2. Polling fallback: If file watching fails or is unavailable, polls folders at the configured interval

The system applies these settings to all configured libraries automatically on startup.

---

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 has been updated to use a new polling-based scanning system. The following changes were made:

• Changed: scan_frequency_minutes renamed to scan_poll_interval_seconds
• Changed: Unit changed from minutes to seconds (15-1440 minutes → 1-3600 seconds)
• Removed: Old scheduler-based scanning system
• Added: Real-time file watching with polling fallback
• Preserved: API endpoint paths remain the same

The new system ensures that:

1. File changes are detected in real-time when possible (via fsnotify)
2. Polling fallback catches missed events at the configured interval
3. Settings apply to all libraries system-wide
4. Only administrators can modify scan settings
5. The auto_scan_enabled setting controls both file watching and polling