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 scan all libraries in minutes (15-1440)
- `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 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**:

```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 15 and 1440 minutes
- 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

### 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