Audiobookshelf

Adds one or more books to an existing collection. Books already in the collection are ignored; books from a different library are rejected.

Appends books or podcast episodes to a playlist. All entries must come from the playlist’s library and match its kind — a podcast playlist needs an episode_id on every entry, a book playlist on none.

Creates a bookmark at a position of a book for the API key’s user. The position in seconds is the bookmark’s identity — a second bookmark at the same second is rejected.

Creates a collection of books. Audiobookshelf rejects empty collections, so at least one library item id is required, and every item must be a book from the given library.

Creates a playlist for the API key’s user. Unlike a collection it may start out empty and it may hold podcast episodes.

Deletes the bookmark at a given position. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it.

Deletes a collection. The books stay in the library, but the curated list and its order are gone. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it. Requires an Audiobookshelf account with delete permission.

Deletes a progress record of the API key’s user, which removes the listening history for that item — position, finished state and dates. Takes the media progress id (field "id" of get_media_progress), not the library item id. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it.

Deletes a playlist. The media stays in the library. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it.

Fetches a single author, optionally with the library items attributed to them.

Fetches one collection with the books it contains, in order.

Returns the chapter list of a book with start and end times in seconds. Separate from get_library_item because long audiobooks can have hundreds of chapters.

Fetches a single library including its folders and scanner settings.

Returns the values that can be filtered on in this library: authors, genres, tags, series, narrators, languages and publishers, each with the id or name to pass to list_library_items as filter_value.

Fetches one book or podcast including its metadata, tags and the listening progress of the API key’s user. Chapters, audio files and tracks are not part of the compact projection — use get_item_chapters for chapters, or detail="full" for everything.

Statistics for one library: number of items, authors and genres, total duration and size, longest and largest items.

Aggregated listening statistics of the current user: total time, time per weekday, the last 30 days, the ten most listened items and the ten most recent sessions. detail="full" returns the complete per-day history and the full metadata of every item ever listened to, which is the largest response this API produces.

Returns the Audiobookshelf user the API key acts on behalf of, with their permissions and accessible libraries. The compact projection reports media progress and bookmarks as counts — the full user object embeds every single one of them. Credential fields are removed from both projections.

The listening progress of the current user for one book or podcast episode: position, percentage and whether it is finished. Returns a 404 error when the item has never been started.

The shelves of the Audiobookshelf home screen for this user: Continue Listening, Continue Series, Recently Added, Newest Episodes, Listen Again and so on. The fastest answer to "what am I listening to right now?".

Fetches one playlist with its entries, in order.

Fetches one podcast episode with its publication date, duration and description.

Fetches a single series by id, including its books. To list the books with paging and sorting, use list_library_items with filter_group="series" instead.

Version and initialization state of the Audiobookshelf server. Useful to check connectivity and whether the server is new enough for API keys (2.26.0 or later).

The "year in review" statistics of the current user for one calendar year: books finished, time listened, top authors and genres.

Lists all authors of a book library with their number of books. To list the books of one author, call list_library_items with filter_group="authors" and filter_value=<author id>.

The bookmarks of the current user — either all of them, or those of one library item. A bookmark is a named position in seconds. Audiobookshelf has no bookmarks endpoint: they are a field on the account, so this reads /api/me and filters here. That is why there is no pagination — you get all of them.

Lists collections — the curated, ordered groups of books. Without library_id it returns the collections of every accessible library. Collections are shared server-wide; playlists are private per user.

Lists all genres used on the server, across libraries. Genres come from the media metadata, not from the user.

The items the user has started but not finished, newest first — the "Continue Listening" list across all libraries. The entries carry progressLastUpdate but not the position itself; use get_media_progress for that. For podcasts, recentEpisode names the episode in progress.

Lists the Audiobookshelf libraries the API key’s user can access, with their id, name and media type (book or podcast). Start here — every other library tool needs a library id.

Lists items (books or podcasts) of a library, paginated, sortable and filterable. Use get_library_filter_data first to learn the valid filter values. Filter groups — valued (need filter_value): genres, tags, series, authors, progress, narrators, publishers, publishedDecades, missing, languages, tracks, ebooks; standalone: issues, feed-open, share-open, recent.

The playback sessions of the current user, newest first — each entry is one listening stretch with device, position and time listened.

Lists the playlists of the API key’s user. Without library_id it returns the playlists of every accessible library. Playlists are private per user and can hold books or podcast episodes; collections are shared server-wide and hold books only.

Lists the most recently published episodes across a podcast library — the "Newest Episodes" view. Only works on libraries with mediaType "podcast".

Lists the series of a book library with their number of books and total duration. To list the books of one series, call list_library_items with filter_group="series" and filter_value=<series id>.

Lists all tags used on the server, across libraries. Tags are the user-defined labels on library items.

Removes books from a collection. The books themselves are untouched — only their membership in the collection ends, and it can be restored with add_books_to_collection. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it.

Removes entries from a playlist. The media itself is untouched and the entries can be added back with add_items_to_playlist. Note that Audiobookshelf deletes a playlist automatically once its last entry is removed. Asks a person first; where the client cannot show a dialog, call once to receive a token and again with it.

Full-text search within one library. Matches books, podcasts, series, authors, narrators and tags. Use this for "do I own X?" questions; use list_library_items with a filter for "show me all X" questions.

Creates or updates the listening progress of the API key’s user for one book or podcast episode. Set is_finished=true to mark it as finished, is_finished=false to reopen it (which resets the position to 0), or current_time to jump to a position in seconds. Audiobookshelf also marks an item finished on its own once less than ten seconds remain.

Renames the bookmark at a given position. The position itself cannot be changed — delete the bookmark and create a new one for that.

Renames a collection, changes its description or reorders its books. library_item_ids ONLY REORDERS. It cannot add or remove anything: Audiobookshelf sorts the books the collection already has by their position in this list, so an id that is not currently in the collection is ignored, and a book you leave out is not removed — it moves to the FRONT. Pass every current book, in the order you want. Use add_books_to_collection and remove_books_from_collection to change membership. Reordering asks a person first, because the order somebody arranged cannot be reconstructed afterwards; renaming and re-describing do not. Where the client cannot show a dialog, call once to receive a token and again with it.

Renames a playlist, changes its description or reorders its entries. items ONLY REORDERS. It cannot add or remove anything, and it must contain EXACTLY the entries the playlist already has: Audiobookshelf refuses a list of a different length with HTTP 400 "Invalid playlist items. Length mismatch". Read the current entries with get_playlist first, then send them in the order you want. Use add_items_to_playlist and remove_items_from_playlist to change membership. The library of a playlist cannot be changed. Reordering asks a person first, because the order somebody arranged cannot be reconstructed afterwards; renaming and re-describing do not. Where the client cannot show a dialog, call once to receive a token and again with it.