HomeBranch API v1.3.0
Book deduplication, EPUB file naming convention, and file drop detection
What’s new
Book deduplication
Admins can now scan the library for duplicate EPUB files and resolve each pair directly from the API. A background scan job inspects the library and records duplicate candidates. Each duplicate can then be resolved with one of three actions:
- Merge — keep the original, delete the duplicate and its file
- Replace — promote the duplicate as the canonical copy, delete the original
- Keep both — mark the pair as resolved without deleting either book
New endpoints (admin only):
| Method | Path | Description |
|---|---|---|
GET | /api/books/duplicates | List unresolved duplicates (paginated) |
POST | /api/books/duplicates/scan | Enqueue a duplicate scan job (returns 202) |
POST | /api/books/duplicates/:id/resolve | Resolve a duplicate pair |
EPUB file naming convention
EPUB files previously stored under auto-generated UUID filenames are now renamed to Author - Title.epub when the library scanner runs. Newly uploaded files are also stored under this convention going forward.
File drop detection
The library scanner now detects EPUB files dropped directly into the uploads directory without going through the upload API. Dropped files are processed through the same metadata extraction and enrichment pipeline as uploaded books, and are subject to the same three-way bidirectional metadata sync.
Infrastructure
Redis now required
Redis is required for background job processing (BullMQ). Add a Redis service to your deployment and set the following environment variables on the HomeBranch API:
| Variable | Default | Description |
|---|---|---|
REDIS_HOST | localhost | Redis hostname |
REDIS_PORT | 6379 | Redis port |
REDIS_PASSWORD | (none) | Redis password (optional) |
See the Configuration reference and Getting Started guide for an updated Docker Compose example.
Upgrade notes
No breaking changes to the REST API. Database migrations run automatically on startup. Update your deployment to include a Redis service before upgrading — the API will fail to start if Redis is unreachable.