buzz.bookhive.getPersonalLibrary

Get the authenticated user's personal ebook library.

Repository @bookhive.buzz did:plc:enu2j5xjlqsjaylv3du4myh4 namespace authority
Details · query
Kindquery
Authoritybookhive.buzz
Commit rev3n2mntoqgyc2e
Indexed

Query

query · GET

Parameters

query string

cursor

string

Pagination cursor

limit

integer

Maximum number of books to return

  • minimum: 1
  • maximum: 100
  • default: 24

q

string

Case-insensitive substring match against title or authors. Mirrors the OPDS search feed.

  • minLength: 1
  • maxLength: 256

shelfId

integer

Filter by personal shelf ID

sort

string

Result ordering. `recent` is newest-added first (the default, matching the library page and the OPDS /all feed); `title` and `author` are ascending alphabetical, matching the OPDS search results feed. Not switched implicitly when `q` is set — pass it explicitly.

  • default: "recent"
  • knownValues: recent | title | author

Output

application/json

books

requiredarray
itemsref
Reference

cursor

string

Pagination cursor for the next page

This user's storage usage against their quota

Reference

total

integer

Total number of books matching the query, across all pages

#personalBookView

object

Properties

authors

string

Authors of the book (tab-separated)

contentHash

requiredstring

SHA-256 hash of the file content, used as stable identifier

coverUrl

string

URL of the book cover image. When it points at the public catalog image proxy it needs no authentication; the `/library/covers/...` form is session-authenticated, so a client using service auth should use `hasLocalCover` and getPersonalBookCover instead.

createdAt

requiredstring · datetime

When the book was added to the library

Synopsis from the linked BookHive catalog entry. Deliberately unbounded: this is scraped catalog copy, not user input, and 125 of the 367k descriptions in production already exceed 5000 bytes (longest 10386). A maxLength here would be a contract the data violates, and enforcing it would mean truncating a synopsis mid-sentence.

filename

string

Original uploaded file name. A sync client needs this to correlate the book with what is on the device.

format

requiredstring

File format (e.g. epub, pdf, mobi, fb2, cbz)

Whether a cover extracted from the uploaded file is stored. Fetch it with getPersonalBookCover, which works under any supported authentication.

hiveId

string

Linked BookHive catalog entry ID

language

string

Language of the book

mime

requiredstring

MIME type of the file

E-reader reading progress, when this book has been synced

Reference

IDs of the personal shelves this book belongs to

itemsinteger

sizeBytes

requiredinteger

File size in bytes

title

requiredstring

Title of the book

updatedAt

requiredstring · datetime

When the book record was last updated

#storageView

object

Properties

quotaBytes

requiredinteger

Total bytes this user is allowed to store

  • minimum: 0

usedBytes

requiredinteger

Total bytes currently stored for this user

  • minimum: 0

#syncProgressView

object

Properties

device

string

Name of the device that last reported progress

percentage

requiredstring

Reading progress as a fraction between 0 and 1

updatedAt

requiredstring · datetime

When progress was last synced

Similar lexicons

semantic match

Lexicons whose schemas describe something close to this one. Check them before publishing a new one that overlaps.

  • List the authenticated user's personal shelves with per-shelf book counts, plus library-wide totals and storage usage. This is the root call for a catalog client: it carries everything the OPDS root navigation feed renders, in one request. Unpaginated — `personal_shelf` is unique on (userDid, name) and these lists are small.

  • Get a single book from the authenticated user's personal library.

  • Download the raw ebook file for a book in the authenticated user's personal library. Responds with the stored bytes, a strong ETag equal to the content hash, and a `Content-Disposition: attachment` filename. Honours `If-None-Match` with a 304, so an e-reader syncing on a schedule does not re-download every book. The XRPC equivalent of GET /opds/books/{hash}/download/{name}.ext.

  • Cover image for a book in the authenticated user's personal library. Serves the cover extracted from the uploaded file when there is one; otherwise, if the book is linked to a BookHive catalog entry, responds 302 to the public image proxy for that entry. The XRPC equivalent of GET /opds/books/{hash}/cover.

  • Get books currently in a user's library.