Import Lists
Import lists automatically sync books from external sources into your Narratorr library as “wanted” books. Once added, Narratorr searches for and downloads them like any other book.
Configure import lists in Settings > Import Lists.
List Types
Section titled “List Types”Two list types are available: NYT Bestsellers and Hardcover.
NYT Bestsellers
Section titled “NYT Bestsellers”Adds books from the New York Times bestseller lists. Good for automatically tracking popular new releases.
| Field | Description |
|---|---|
| Name | Display name for this list |
| API Key | NYT Developer API key (developer.nytimes.com) |
| Bestseller List | Dropdown with two choices: Audio Fiction (audio-fiction, default) or Audio Nonfiction (audio-nonfiction). |
Hardcover
Section titled “Hardcover”Syncs books from Hardcover (hardcover.app) — either trending books or a specific shelf.
| Field | Description |
|---|---|
| Name | Display name for this list |
| API Key | Hardcover API key |
| List Type | trending (popular books) or shelf (a specific shelf) |
| Shelf ID | Required when list type is shelf — the Hardcover shelf ID to sync |
Common Settings
Section titled “Common Settings”Every import list has these shared settings:
| Setting | Description |
|---|---|
| Enabled | Toggle the list on/off without deleting it |
| Sync Interval | How often to sync, in minutes (minimum 5). Default: 1440 (daily). |
How Sync Works
Section titled “How Sync Works”- On each sync cycle, Narratorr fetches items from the external source
- Each item is enriched with metadata. When an item has an ASIN, Narratorr resolves it directly. If that ASIN doesn’t resolve to an audiobook (for example, a print or Kindle ASIN), Narratorr automatically falls back to a title/author metadata search and adopts the matching audiobook’s ASIN instead — so a non-audiobook ASIN no longer dead-ends. Items without an ASIN are matched the same way, by title/author search. An item that genuinely can’t be resolved is still added, but flagged as needing attention (a “failed” enrichment state) and retried automatically later (roughly hourly)
- If the book doesn’t already exist in your library, it’s added with status
wanted - Duplicate books (matching ASIN or title+author) are silently skipped
- Newly added books appear in your library. If Search Immediately (quality settings) is enabled, an import-list-added book triggers a search right away; otherwise it’s picked up on the next scheduled search cycle
Testing and Preview
Section titled “Testing and Preview”- Test — verifies the connection and credentials are valid
- Preview — fetches the first 10 items from the list so you can see what would be imported before enabling
- Sync errors are stored and visible in the list settings — check here if a list stops syncing
- Books added by import lists track which list they came from, visible on the book detail page
- Deleting an import list doesn’t remove books it previously added