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**:

```json
{
  "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**:

```bash
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**:

```json
{
  "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**:

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

**Error Response Body**:

```json
{
  "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**:

```bash
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