Pub Version GitHub Workflow Status Codecov

A Dart wrapper for the audiobookshelf API, a self-hosted audiobook and podcast server.

Works with audiobookshelf v2.2.15.


  • Provides a Dart idiomatic wrapper for every audiobookshelf API endpoint.
  • Provides access to audiobookshelf's Socket.IO interface with Dart Streams.
  • All response schema are freezed objects.


Authentication / Login

To access most of the API endpoints a token is needed. This can either be provided when creating the AudiobookshelfApi object, or by logging in.

final api = AudiobookshelfApi(baseUrl: Uri.https(''));

final loginResponse =
  await api.login(username: 'username', password: 'password');
if (loginResponse == null) {
  throw Exception('Error logging in');

// After logging in, the token is written to the `AudiobookshelfApi` object.
// It can be stored for future use.
final token = api.token;

final apiWithToken = AudiobookshelfApi(
  baseUrl: Uri.https(''),
  token: token,


The AudiobookshelfApi class is set up to mostly mirror the API URLs. For example, continuing the above example, to get a library and print its name:

final getLibraryResponse = await api.libraries.get(
  libraryId: loginResponse.userDefaultLibraryId,
if (getLibraryResponse == null) {
  throw Exception('Error getting default library');

// e.g. 'Audiobooks'


To use the socket, first set up your callbacks and then initialize it.

final onInitSub = api.socket.miscEvents.onInit.listen((initEvent) {
  // e.g. 'username'

await onInitSub.cancel();

Clean Up

When finished, make sure to dispose the AudiobookshelfApi object.


Further Usage

Review audiobookshelf's API docs for more information.