Skip to content

Connecting to the ebook library

What is this?

A read-only WebDAV view of the BookWarehouse ebook library — about 159,000 titles. Point a WebDAV client at it and the library appears as an ordinary folder tree, so you can browse it in a file manager or mount it as a drive.

It is read-only by design: uploads, renames and deletes will fail.

How do I order access?

Order from the ClearStreamer store:

Ebooks & Audiobooks store category

If you already have an S3 account, choose Ebooks/Audiobooks API Access - Hosting Included.

Once your order is provisioned you'll have a BookWarehouse API key. That key is what you use as your WebDAV password below.

What do I need to connect?

Three values:

Value Looks like Notes
URL https://webdav.bookwarehouse.org/ always include https://
Username rclone the same for everyone, and not a secret
Password your BookWarehouse API key your own key — see below

Your password is your BookWarehouse API key

There is no separate WebDAV password, and nobody will send you one. Use the same API key you use for the BookWarehouse API. If you don't have one yet, create it in BookWarehouse first.

The key is tied to your account, so keep it private. Revoking it in BookWarehouse also revokes your WebDAV access, within about five minutes.

How is the library organised?

By the first letter of the author's surname, then author, then series or title:

/
├── ebooks/
│   └── T/                        ← first letter of the author's surname
│       └── Taylor, Dan/
│           └── HIVE/             ← series, or the title on its own
│               └── HIVE.epub
└── audiobooks/                   ← empty for now

Where an author has two books with the same title, one carries a (2) suffix.

How do I connect?

The best-tested route, and much faster than a built-in client on large folders.

rclone config create bookwarehouse webdav \
  url=https://webdav.bookwarehouse.org/ \
  vendor=other \
  user=rclone \
  pass="$(rclone obscure 'YOUR_BOOKWAREHOUSE_API_KEY')"

vendor = other is required

Without it, rclone guesses the server type and listings misbehave. This is the single most common setup mistake.

Mount it as a drive (needs FUSE on Linux and macOS, or WinFsp on Windows):

rclone mount bookwarehouse: /mnt/books --read-only --vfs-cache-mode full

File Explorer → Map network drive → https://webdav.bookwarehouse.org/

The built-in Windows client is slow on very large folders. Prefer rclone if you can.

Finder → Go → Connect to Server → https://webdav.bookwarehouse.org/

In GNOME Files or KDE Dolphin, connect to:

davs://webdav.bookwarehouse.org/

KOReader, Moon+ Reader, FBReader, Librera and similar all work. Choose WebDAV as the connection type — not Calibre and not OPDS — then enter the same URL, username and API key.

How do I check it's working?

Five checks, in order. Each exercises a different part of the system, so a failure tells us where to look.

# 1. Can you see the top level?
rclone lsd bookwarehouse:

# 2. Can you list inside a folder?
rclone lsf "bookwarehouse:ebooks/T/Taylor, Dan/HIVE/"

# 3. Do sizes and file types come back correctly?
rclone lsjson "bookwarehouse:ebooks/T/Taylor, Dan/HIVE/"

# 4. Can you download a whole book?
rclone copy "bookwarehouse:ebooks/T/Taylor, Dan/HIVE/HIVE.epub" ./

# 5. Can you read part of a file? Should print exactly: 1000
rclone cat --offset 1000 --count 1000 \
  "bookwarehouse:ebooks/T/Taylor, Dan/HIVE/HIVE.epub" | wc -c

Check 5 matters more than it looks: it's what e-reader apps do when they jump to a chapter.

What do the error codes mean?

Code What it means What to do
401 Your API key was rejected. Check the same key works against the BookWarehouse API — it has to work in both places.
503 We can't verify keys right now. Your credentials are fine. Wait a moment and retry. Don't change your key.
502 That book's recorded size disagrees with the actual file, so we refuse to serve it rather than hand you a damaged copy. Report the path. Try a different book meanwhile.

A 503 is not a password problem

If key checking is briefly unavailable we return 503, never 401. If you see 503, waiting is the correct response — reissuing your key will not help.

What's expected behaviour?

  • /audiobooks is empty. Ebooks only for now.
  • Writes fail. It's a read-only mirror of the library, not a permissions problem.
  • New books take up to five minutes to appear.
  • A new API key may take a few seconds to start working, and a revoked one can keep working for up to five minutes. That's a deliberate caching window.
  • A small number of books return 502 instead of downloading. See the table above.
  • The first listing after an idle spell can be slow, then speeds up.

What should I report?

Include the full path of the book, the client you used, and the exact error text:

  • Folders that won't open, or take more than about ten seconds to list
  • A book that downloads but won't open in your reader
  • A download that produces a file of the wrong size
  • A book you expected to find that isn't there
  • An author or title filed under the wrong letter or folder