Audiobookshelf

App · 36 actions

Run your Audiobookshelf audiobook and podcast server from workflows: list, search and update books and podcasts, match them, scan libraries, manage collections and playlists, add podcasts and download episodes, track listening progress and stats, and add users. Start a workflow when a book or episode arrives, a book is finished, or someone starts listening.

Actions

ActionWhat it does
Add podcastAdd a podcast to a podcast library by its RSS feed address, and optionally download its latest episodes.
Add to collectionAdd one or more books to a collection.
Add to playlistAdd a book, or a podcast episode, to the end of a playlist, such as a new episode to a commute queue.
Check for new episodesHave Audiobookshelf check a podcast's feed for episodes published since it last looked, and download them, as its Check & Download button does.
Create collectionMake a collection of books, which everyone with the library sees, such as a book club's picks.
Create playlistMake a playlist for the API key's user, starting with a book or a podcast episode.
Create userAdd a user who can sign in to Audiobookshelf, such as a family member, with the libraries and permissions they get.
Delete book or podcastRemove a book or podcast from its library, and optionally delete its files from the server.
Delete collectionDelete a collection.
Delete playlistDelete one of the API key's user's playlists.
Delete userDelete a user, with their progress, playlists and listening history.
Download episodesDownload a podcast's newest episodes that aren't in the library yet, whenever they were published.
Get authorGet an author with their books and series.
Get book or podcastGet a book or podcast with its details, chapters and files, and how far the API key's user has listened.
Get libraryGet a library: how many books or podcasts it has, and its authors, series, genres, tags and narrators.
Get library statsGet a library's totals: items, hours, size on disk, authors and genres (with how many items each), and its longest and largest items.
Get listening statsGet how long the API key's user has listened: in all, today, day by day over the last days, and per book or podcast, such as for a weekly summary.
Get progressGet how far the API key's user is through a book or podcast episode, and whether and when they finished it.
Get seriesGet a series with its books in order, and which of them the API key's user has finished, such as to find the next one to read.
List authorsList the authors in an audiobook library, by last name, with how many of their books it has.
List books and podcastsList a library's books or podcasts, of one author, series, genre, tag or narrator, or by the user's progress, sorted as you choose.
List collectionsList the collections of books, everyone's or one library's.
List episodesList a podcast's downloaded episodes, newest first, with whether the API key's user has finished each.
List in progressList the books and podcast episodes the API key's user is partway through, most recently played first, as Continue Listening shows them.
List librariesList the audiobook and podcast libraries the API key's user can open, with their folders and when they were last scanned.
List listening sessionsList the API key's user's listening sessions, newest first: what they listened to, when, for how long and on which device.
List playlistsList the API key's user's playlists, with what's in each.
List seriesList the series in an audiobook library, by name, with their books.
List usersList Audiobookshelf's users with their account type, permissions and libraries.
Mark finishedMark a book or podcast episode finished, or not finished, for the API key's user, as Audiobookshelf's Mark as Finished does.
Match book or podcastLook a book up at Google Books, Open Library, Audible or iTunes (a podcast at iTunes) and fill in its missing details and cover, as Audiobookshelf's Quick Match does.
Remove from collectionTake one or more books out of a collection.
Remove from playlistTake a book, or a podcast episode, out of a playlist.
Scan libraryHave Audiobookshelf scan a library's folders for new, changed and removed books, as its Scan button does, such as after a download lands.
Search librarySearch a library, as Audiobookshelf's search box does, for books or podcasts by title, author, narrator, series, ISBN or ASIN, and for authors, series, tags and genres.
Update book or podcastChange a book's or podcast's details: title, authors, series, genres, tags and more.

Add podcast

Add a podcast to a podcast library by its RSS feed address, and optionally download its latest episodes. One whose feed is already there is returned as it is. Needs an admin's key.

Inputs

RSS feed addressfeed_urltextRequired
The podcast's RSS feed, such as https://feeds.example.com/show.xml.
Librarylibrarytext
The podcast library, by name or ID. Leave blank when there's only one.
Titletitletext
A title of your own, which also names its folder. Leave blank for the feed's.
Download latestdownload_latestnumber
How many of its newest episodes to download now. Defaults to none.From 0 to 50.
Download new episodes automaticallyauto_downloadtrue/false
Have Audiobookshelf download new episodes on its own, every hour by default.Default: false.

Outputs

added_attext
When it was added (UTC)
already_addedtrue/false
Whether the library already had this feed; nothing was added then
asintext
Its Audible ASIN (books)
authortext
The same, separated by commas
authorslist
Its authors (a podcast's author)
descriptiontext
What it's about
downloaded_countnumber
How many of them are downloaded
downloads_finishedtrue/false
Whether every one finished within a minute; the rest keep downloading
durationtext
The same, such as 11 h 32 min
duration_secondsnumber
How long it is, in seconds (books)
episode_countnumber
How many episodes a podcast has downloaded
episodes_queuedlist
The episodes sent to download
explicittrue/false
Whether it's marked explicit
feed_episode_countnumber
How many episodes the feed lists
feed_urltext
A podcast's RSS feed address
genreslist
Its genres
idtext
The book's or podcast's ID, for other Audiobookshelf steps
isbntext
Its ISBN (books)
languagetext
Its language
library_idtext
Its library's ID
linktext
A link to it in Audiobookshelf
media_typetext
book or podcast
missingtrue/false
Whether its files are missing
narratorslist
Its narrators (books)
pathtext
Its folder on the Audiobookshelf server
published_yeartext
The year it was published (a podcast's release date)
publishertext
Its publisher (books)
queued_countnumber
How many episodes were sent to download
serieslist
Its series, with the book's number, such as Harbor Tales #1
sizenumber
Its files' size in bytes
subtitletext
Its subtitle (books)
tagslist
Its tags
titletext
Its title
updated_attext
When it last changed (UTC)
Example output
{
  "added_at": "2026-11-12T22:36:10Z",
  "already_added": false,
  "asin": "",
  "author": "Lodol QA",
  "authors": [
    "Lodol QA"
  ],
  "description": "A tiny test podcast.",
  "downloaded_count": 1,
  "downloads_finished": true,
  "duration": "",
  "duration_seconds": 0.0,
  "episode_count": 2,
  "episodes_queued": [
    {
      "duration": "42 min",
      "published_at": "2026-11-12T22:35:42Z",
      "title": "Episode 3: Harbor sounds"
    }
  ],
  "explicit": false,
  "feed_episode_count": 3,
  "feed_url": "https://feeds.example.com/lodol-qa-radio.xml",
  "genres": [
    "Technology"
  ],
  "id": "edd197d4-b979-49e8-9ea1-1ca1e61f3dba",
  "isbn": "",
  "language": "English",
  "library_id": "9c8f3bff-a033-4fac-80b5-c0ef9786e9a5",
  "link": "http://192.168.1.20:13378/item/edd197d4-b979-49e8-9ea1-1ca1e61f3dba",
  "media_type": "podcast",
  "missing": false,
  "narrators": [],
  "path": "/podcasts/Lodol QA Radio",
  "published_year": "",
  "publisher": "",
  "queued_count": 1,
  "series": [],
  "size": 97956,
  "subtitle": "",
  "tags": [],
  "title": "Lodol QA Radio",
  "updated_at": "2026-11-12T22:36:10Z"
}

Add to collection

Add one or more books to a collection.

Inputs

CollectioncollectiontextRequired
The collection, by name or ID.
BooksbookstextRequired
One or more books, by title or ID, separated by commas.

Outputs

addedlist
The titles added
book_countnumber
How many books it holds
bookslist
Its books
created_attext
When it was made (UTC)
descriptiontext
Its description
idtext
The collection's ID
library_idtext
Its library's ID
linktext
A link to it in Audiobookshelf
nametext
Its name
removedlist
The titles taken out
Example output
{
  "added": [
    "Second Tide"
  ],
  "book_count": 2,
  "books": [
    {
      "author": "Ada Lovell",
      "duration": "11 h 32 min",
      "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
      "published_year": "2019",
      "sequence": "1",
      "series": [
        "Harbor Tales #1"
      ],
      "title": "The Quiet Harbor"
    },
    {
      "author": "Ada Lovell",
      "duration": "11 h 32 min",
      "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
      "published_year": "2019",
      "sequence": "1",
      "series": [
        "Harbor Tales #1"
      ],
      "title": "Second Tide"
    }
  ],
  "created_at": "2026-11-12T23:05:00Z",
  "description": "This year's picks",
  "id": "5f0c1e7a-2b7d-4f8e-9a51-3c4d2e1f0a9b",
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "link": "http://192.168.1.20:13378/collection/5f0c1e7a-2b7d-4f8e-9a51-3c4d2e1f0a9b",
  "name": "Book club 2026",
  "removed": []
}

Add to playlist

Add a book, or a podcast episode, to the end of a playlist, such as a new episode to a commute queue.

Inputs

PlaylistplaylisttextRequired
The playlist, by name or ID. Only the API key's user's own.
Book or podcastitemtextRequired
The book or podcast, by its title or its ID in Audiobookshelf.
Episodeepisodetext
For a podcast, the episode, by title or ID. Leave blank for its newest; leave blank for a book.

Outputs

changed_itemobject
The book or episode added or taken out
created_attext
When it was made (UTC)
deletedtrue/false
Whether Audiobookshelf deleted the playlist, as it does when its last item is taken out
descriptiontext
Its description
idtext
The playlist's ID
item_countnumber
How many books or episodes it holds
itemslist
What it holds, in order
library_idtext
Its library's ID
linktext
A link to it in Audiobookshelf
nametext
Its name
Example output
{
  "changed_item": {
    "episode_id": "",
    "episode_title": "",
    "item_id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
    "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
    "title": "Second Tide"
  },
  "created_at": "2026-11-12T23:06:00Z",
  "deleted": false,
  "description": "",
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "item_count": 2,
  "items": [
    {
      "episode_id": "",
      "episode_title": "",
      "item_id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "title": "The Quiet Harbor"
    },
    {
      "episode_id": "",
      "episode_title": "",
      "item_id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "title": "Second Tide"
    }
  ],
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "link": "http://192.168.1.20:13378/playlist/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Commute"
}

Check for new episodes

Have Audiobookshelf check a podcast's feed for episodes published since it last looked, and download them, as its Check & Download button does. Needs an admin's key.

Inputs

PodcastpodcasttextRequired
The podcast, by its title or its ID in Audiobookshelf.
Most to downloadlimitnumber
The most new episodes to download. Defaults to 3.From 1 to 50.

Outputs

added_attext
When it was added (UTC)
asintext
Its Audible ASIN (books)
authortext
The same, separated by commas
authorslist
Its authors (a podcast's author)
descriptiontext
What it's about
downloaded_countnumber
How many of them are downloaded
downloads_finishedtrue/false
Whether every one finished within a minute; the rest keep downloading
durationtext
The same, such as 11 h 32 min
duration_secondsnumber
How long it is, in seconds (books)
episode_countnumber
How many episodes a podcast has downloaded
episodes_queuedlist
The episodes sent to download
explicittrue/false
Whether it's marked explicit
feed_urltext
A podcast's RSS feed address
genreslist
Its genres
idtext
The book's or podcast's ID, for other Audiobookshelf steps
isbntext
Its ISBN (books)
languagetext
Its language
library_idtext
Its library's ID
linktext
A link to it in Audiobookshelf
media_typetext
book or podcast
missingtrue/false
Whether its files are missing
narratorslist
Its narrators (books)
pathtext
Its folder on the Audiobookshelf server
published_yeartext
The year it was published (a podcast's release date)
publishertext
Its publisher (books)
queued_countnumber
How many episodes were sent to download
serieslist
Its series, with the book's number, such as Harbor Tales #1
sizenumber
Its files' size in bytes
subtitletext
Its subtitle (books)
tagslist
Its tags
titletext
Its title
updated_attext
When it last changed (UTC)
Example output
{
  "added_at": "2026-11-12T22:36:10Z",
  "asin": "",
  "author": "Lodol QA",
  "authors": [
    "Lodol QA"
  ],
  "description": "A tiny test podcast.",
  "downloaded_count": 1,
  "downloads_finished": true,
  "duration": "",
  "duration_seconds": 0.0,
  "episode_count": 2,
  "episodes_queued": [
    {
      "duration": "42 min",
      "published_at": "2026-11-12T22:35:42Z",
      "title": "Episode 3: Harbor sounds"
    }
  ],
  "explicit": false,
  "feed_url": "https://feeds.example.com/lodol-qa-radio.xml",
  "genres": [
    "Technology"
  ],
  "id": "edd197d4-b979-49e8-9ea1-1ca1e61f3dba",
  "isbn": "",
  "language": "English",
  "library_id": "9c8f3bff-a033-4fac-80b5-c0ef9786e9a5",
  "link": "http://192.168.1.20:13378/item/edd197d4-b979-49e8-9ea1-1ca1e61f3dba",
  "media_type": "podcast",
  "missing": false,
  "narrators": [],
  "path": "/podcasts/Lodol QA Radio",
  "published_year": "",
  "publisher": "",
  "queued_count": 1,
  "series": [],
  "size": 97956,
  "subtitle": "",
  "tags": [],
  "title": "Lodol QA Radio",
  "updated_at": "2026-11-12T22:36:10Z"
}

Create collection

Make a collection of books, which everyone with the library sees, such as a book club's picks. Needs a user allowed to update.

Inputs

NamenametextRequired
The collection's name.
BooksbookstextRequired
One or more books, by title or ID, separated by commas.
Descriptiondescriptiontext
What the collection is for.

Outputs

book_countnumber
How many books it holds
bookslist
Its books
created_attext
When it was made (UTC)
descriptiontext
Its description
idtext
The collection's ID
library_idtext
Its library's ID
linktext
A link to it in Audiobookshelf
nametext
Its name
Example output
{
  "book_count": 1,
  "books": [
    {
      "author": "Ada Lovell",
      "duration": "11 h 32 min",
      "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
      "published_year": "2019",
      "sequence": "1",
      "series": [
        "Harbor Tales #1"
      ],
      "title": "The Quiet Harbor"
    }
  ],
  "created_at": "2026-11-12T23:05:00Z",
  "description": "This year's picks",
  "id": "5f0c1e7a-2b7d-4f8e-9a51-3c4d2e1f0a9b",
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "link": "http://192.168.1.20:13378/collection/5f0c1e7a-2b7d-4f8e-9a51-3c4d2e1f0a9b",
  "name": "Book club 2026"
}

Create playlist

Make a playlist for the API key's user, starting with a book or a podcast episode. A playlist holds books, or podcast episodes, of one library.

Inputs

NamenametextRequired
The playlist's name.
Book or podcastitemtextRequired
The book or podcast, by its title or its ID in Audiobookshelf.
Episodeepisodetext
For a podcast, the episode, by title or ID. Leave blank for its newest; leave blank for a book.
Descriptiondescriptiontext
What the playlist is for.

Outputs

created_attext
When it was made (UTC)
descriptiontext
Its description
idtext
The playlist's ID
item_countnumber
How many books or episodes it holds
itemslist
What it holds, in order
library_idtext
Its library's ID
linktext
A link to it in Audiobookshelf
nametext
Its name
Example output
{
  "created_at": "2026-11-12T23:06:00Z",
  "description": "",
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "item_count": 1,
  "items": [
    {
      "episode_id": "",
      "episode_title": "",
      "item_id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "title": "The Quiet Harbor"
    }
  ],
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "link": "http://192.168.1.20:13378/playlist/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Commute"
}

Create user

Add a user who can sign in to Audiobookshelf, such as a family member, with the libraries and permissions they get. Needs an admin's key.

Inputs

UsernameusernametextRequired
Their username.
PasswordpasswordtextRequired
Their first password; they can change it under Account.
Account typeaccount_typetext
Admins can do everything; guests can only listen.One of: user, admin, guest. Default: user.
Emailemailtext
Their email address.
Librarieslibrariestext
The libraries they can open, by name or ID. Leave blank for all. Separate several with commas.
Can downloadcan_downloadtrue/false
Let them download books and episodes. Admins always can.Default: true.
Can updatecan_updatetrue/false
Let them change books' details. Admins always can.Default: false.
Can deletecan_deletetrue/false
Let them delete books. Admins always can.Default: false.
Can uploadcan_uploadtrue/false
Let them upload books. Admins always can.Default: false.

Outputs

account_typetext
root, admin, user or guest
activetrue/false
Whether they can sign in
can_deletetrue/false
Whether they may delete items
can_downloadtrue/false
Whether they may download
can_updatetrue/false
Whether they may change items
can_uploadtrue/false
Whether they may upload
created_attext
When they were made (UTC)
emailtext
Their email address
idtext
The user's ID
last_seentext
When they were last seen (UTC)
librarieslist
The libraries they can open, or all
lockedtrue/false
Whether they're kept from changing their password
usernametext
Their username
Example output
{
  "account_type": "user",
  "active": true,
  "can_delete": false,
  "can_download": true,
  "can_update": false,
  "can_upload": false,
  "created_at": "2026-11-01T09:00:00Z",
  "email": "maya@example.com",
  "id": "c10b57bb-1829-48c3-9134-62777b4a1429",
  "last_seen": "2026-11-12T21:42:05Z",
  "libraries": [
    "all"
  ],
  "locked": false,
  "username": "maya"
}

Delete book or podcast

Remove a book or podcast from its library, and optionally delete its files from the server. A book whose files stay is added again at the next scan. Needs a user allowed to delete.

Inputs

Book or podcastitemtextRequired
The book or podcast, by its title or its ID in Audiobookshelf.
Delete filesdelete_filestrue/false
Also delete its folder and files from the server. This can't be undone.Default: false.

Outputs

deletedtrue/false
Always true
files_deletedtrue/false
Whether its folder and files were deleted too
idtext
The deleted item's ID
library_idtext
Its library's ID
media_typetext
book or podcast
pathtext
Its folder on the server
titletext
Its title
Example output
{
  "deleted": true,
  "files_deleted": true,
  "id": "edd197d4-b979-49e8-9ea1-1ca1e61f3dba",
  "library_id": "9c8f3bff-a033-4fac-80b5-c0ef9786e9a5",
  "media_type": "podcast",
  "path": "/podcasts/Lodol QA Radio",
  "title": "Lodol QA Radio"
}

Delete collection

Delete a collection. Its books stay in the library.

Inputs

CollectioncollectiontextRequired
The collection, by name or ID.

Outputs

deletedtrue/false
Always true
idtext
The deleted record's ID
nametext
Its name
Example output
{
  "deleted": true,
  "id": "5f0c1e7a-2b7d-4f8e-9a51-3c4d2e1f0a9b",
  "name": "Book club 2026"
}

Delete playlist

Delete one of the API key's user's playlists. What was in it stays in the library.

Inputs

PlaylistplaylisttextRequired
The playlist, by name or ID. Only the API key's user's own.

Outputs

deletedtrue/false
Always true
idtext
The deleted record's ID
nametext
Its name
Example output
{
  "deleted": true,
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Commute"
}

Delete user

Delete a user, with their progress, playlists and listening history. This can't be undone. Needs an admin's key.

Inputs

UserusertextRequired
The user, by username or ID. Not the API key's own user.

Outputs

deletedtrue/false
Always true
idtext
The deleted user's ID
usernametext
Their username
Example output
{
  "deleted": true,
  "id": "c10b57bb-1829-48c3-9134-62777b4a1429",
  "username": "maya"
}

Download episodes

Download a podcast's newest episodes that aren't in the library yet, whenever they were published. Needs an admin's key.

Inputs

PodcastpodcasttextRequired
The podcast, by its title or its ID in Audiobookshelf.
How manycountnumber
How many of the newest missing episodes to download. Defaults to 1.From 1 to 50.

Outputs

added_attext
When it was added (UTC)
asintext
Its Audible ASIN (books)
authortext
The same, separated by commas
authorslist
Its authors (a podcast's author)
descriptiontext
What it's about
downloaded_countnumber
How many of them are downloaded
downloads_finishedtrue/false
Whether every one finished within a minute; the rest keep downloading
durationtext
The same, such as 11 h 32 min
duration_secondsnumber
How long it is, in seconds (books)
episode_countnumber
How many episodes a podcast has downloaded
episodes_queuedlist
The episodes sent to download
explicittrue/false
Whether it's marked explicit
feed_urltext
A podcast's RSS feed address
genreslist
Its genres
idtext
The book's or podcast's ID, for other Audiobookshelf steps
isbntext
Its ISBN (books)
languagetext
Its language
library_idtext
Its library's ID
linktext
A link to it in Audiobookshelf
media_typetext
book or podcast
missingtrue/false
Whether its files are missing
narratorslist
Its narrators (books)
pathtext
Its folder on the Audiobookshelf server
published_yeartext
The year it was published (a podcast's release date)
publishertext
Its publisher (books)
queued_countnumber
How many episodes were sent to download
serieslist
Its series, with the book's number, such as Harbor Tales #1
sizenumber
Its files' size in bytes
subtitletext
Its subtitle (books)
tagslist
Its tags
titletext
Its title
updated_attext
When it last changed (UTC)
Example output
{
  "added_at": "2026-11-12T22:36:10Z",
  "asin": "",
  "author": "Lodol QA",
  "authors": [
    "Lodol QA"
  ],
  "description": "A tiny test podcast.",
  "downloaded_count": 1,
  "downloads_finished": true,
  "duration": "",
  "duration_seconds": 0.0,
  "episode_count": 2,
  "episodes_queued": [
    {
      "duration": "42 min",
      "published_at": "2026-11-12T22:35:42Z",
      "title": "Episode 3: Harbor sounds"
    }
  ],
  "explicit": false,
  "feed_url": "https://feeds.example.com/lodol-qa-radio.xml",
  "genres": [
    "Technology"
  ],
  "id": "edd197d4-b979-49e8-9ea1-1ca1e61f3dba",
  "isbn": "",
  "language": "English",
  "library_id": "9c8f3bff-a033-4fac-80b5-c0ef9786e9a5",
  "link": "http://192.168.1.20:13378/item/edd197d4-b979-49e8-9ea1-1ca1e61f3dba",
  "media_type": "podcast",
  "missing": false,
  "narrators": [],
  "path": "/podcasts/Lodol QA Radio",
  "published_year": "",
  "publisher": "",
  "queued_count": 1,
  "series": [],
  "size": 97956,
  "subtitle": "",
  "tags": [],
  "title": "Lodol QA Radio",
  "updated_at": "2026-11-12T22:36:10Z"
}

Get author

Get an author with their books and series.

Inputs

AuthorauthortextRequired
The author, by name or ID.

Outputs

added_attext
When they were added (UTC)
asintext
Their Audible ASIN
book_countnumber
How many of their books the library has
bookslist
Their books
descriptiontext
About them
idtext
The author's ID
library_idtext
Their library's ID
linktext
A link to them in Audiobookshelf
nametext
Their name
serieslist
Their series
Example output
{
  "added_at": "2026-11-12T22:36:09Z",
  "asin": "",
  "book_count": 2,
  "books": [
    {
      "author": "Ada Lovell",
      "duration": "11 h 32 min",
      "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
      "published_year": "2019",
      "sequence": "1",
      "series": [
        "Harbor Tales #1"
      ],
      "title": "The Quiet Harbor"
    }
  ],
  "description": "",
  "id": "35713bbc-7af8-4936-a292-09db69e5e750",
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "link": "http://192.168.1.20:13378/author/35713bbc-7af8-4936-a292-09db69e5e750",
  "name": "Ada Lovell",
  "series": [
    "Harbor Tales"
  ]
}

Get book or podcast

Get a book or podcast with its details, chapters and files, and how far the API key's user has listened.

Inputs

Book or podcastitemtextRequired
The book or podcast, by its title or its ID in Audiobookshelf.

Outputs

added_attext
When it was added (UTC)
asintext
Its Audible ASIN (books)
audio_fileslist
Its audio files' names
authortext
The same, separated by commas
authorslist
Its authors (a podcast's author)
chapterslist
Its chapters
descriptiontext
What it's about
durationtext
The same, such as 11 h 32 min
duration_secondsnumber
How long it is, in seconds (books)
episode_countnumber
How many episodes a podcast has downloaded
explicittrue/false
Whether it's marked explicit
feed_urltext
A podcast's RSS feed address
genreslist
Its genres
idtext
The book's or podcast's ID, for other Audiobookshelf steps
isbntext
Its ISBN (books)
languagetext
Its language
library_idtext
Its library's ID
linktext
A link to it in Audiobookshelf
media_typetext
book or podcast
missingtrue/false
Whether its files are missing
narratorslist
Its narrators (books)
pathtext
Its folder on the Audiobookshelf server
progressobject
The API key's user's progress
published_yeartext
The year it was published (a podcast's release date)
publishertext
Its publisher (books)
serieslist
Its series, with the book's number, such as Harbor Tales #1
sizenumber
Its files' size in bytes
subtitletext
Its subtitle (books)
tagslist
Its tags
titletext
Its title
updated_attext
When it last changed (UTC)
Example output
{
  "added_at": "2026-11-12T22:36:10Z",
  "asin": "",
  "audio_files": [
    "The Quiet Harbor.m4b"
  ],
  "author": "Ada Lovell",
  "authors": [
    "Ada Lovell"
  ],
  "chapters": [
    {
      "start_seconds": 0.0,
      "title": "Chapter 1"
    },
    {
      "start_seconds": 1830.5,
      "title": "Chapter 2"
    }
  ],
  "description": "A lighthouse keeper's last winter on the coast.",
  "duration": "11 h 32 min",
  "duration_seconds": 41520.0,
  "episode_count": 0,
  "explicit": false,
  "feed_url": "",
  "genres": [
    "Fiction"
  ],
  "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
  "isbn": "9780000000001",
  "language": "English",
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
  "media_type": "book",
  "missing": false,
  "narrators": [
    "Sam Reed"
  ],
  "path": "/audiobooks/Ada Lovell/Harbor Tales/Book 1 - The Quiet Harbor",
  "progress": {
    "current_time_seconds": 14117.0,
    "finished_at": "",
    "is_finished": false,
    "last_update": "2026-11-12T21:40:05Z",
    "progress_percent": 34.0,
    "started": true,
    "started_at": "2026-11-10T19:02:11Z"
  },
  "published_year": "2019",
  "publisher": "Northlight",
  "series": [
    "Harbor Tales #1"
  ],
  "size": 160662000,
  "subtitle": "",
  "tags": [
    "book-club"
  ],
  "title": "The Quiet Harbor",
  "updated_at": "2026-11-12T22:36:10Z"
}

Get library

Get a library: how many books or podcasts it has, and its authors, series, genres, tags and narrators.

Inputs

Librarylibrarytext
The library, by name or ID. Leave blank when there's only one.

Outputs

authorslist
Its authors' names
created_attext
When it was made (UTC)
folderslist
The folders on the server it reads
genreslist
Its genres
idtext
The library's ID, for other Audiobookshelf steps
issuesnumber
How many items are missing or can't be read
item_countnumber
How many books or podcasts it has
languageslist
Its languages
last_scantext
When it was last scanned (UTC)
linktext
A link to it in Audiobookshelf
media_typetext
book or podcast
metadata_providertext
Where it looks up details, such as google
nametext
Its name
narratorslist
Its narrators
serieslist
Its series' names
tagslist
Its tags
Example output
{
  "authors": [
    "Ada Lovell",
    "June Okafor",
    "Milo Brandt"
  ],
  "created_at": "2026-11-12T22:36:09Z",
  "folders": [
    "/audiobooks"
  ],
  "genres": [
    "Fiction",
    "Mystery",
    "Nonfiction"
  ],
  "id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "issues": 0,
  "item_count": 4,
  "languages": [
    "English"
  ],
  "last_scan": "2026-11-12T22:36:10Z",
  "link": "http://192.168.1.20:13378/library/19e23cab-70e8-480a-958c-755021ca8d7a",
  "media_type": "book",
  "metadata_provider": "google",
  "name": "Audiobooks",
  "narrators": [],
  "series": [
    "Harbor Tales"
  ],
  "tags": [
    "book-club"
  ]
}

Get library stats

Get a library's totals: items, hours, size on disk, authors and genres (with how many items each), and its longest and largest items.

Inputs

Librarylibrarytext
The library, by name or ID. Leave blank when there's only one.

Outputs

audio_tracksnumber
How many audio files
genreslist
Each genre and how many items have it
largest_itemslist
The largest items
library_idtext
The library's ID
library_nametext
Its name
longest_itemslist
The longest items
media_typetext
book or podcast
top_authorslist
The authors with the most books
total_authorsnumber
How many authors
total_durationtext
The same, such as 312 h 5 min
total_duration_secondsnumber
Everything's length together, in seconds
total_genresnumber
How many genres
total_itemsnumber
How many books or podcasts
total_sizenumber
Its files' size in bytes
total_size_texttext
The same, such as 45.2 GB
Example output
{
  "audio_tracks": 4,
  "genres": [
    {
      "count": 2,
      "name": "Fiction"
    },
    {
      "count": 1,
      "name": "Mystery"
    }
  ],
  "largest_items": [
    {
      "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "size": "160.7 MB",
      "title": "The Quiet Harbor"
    }
  ],
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "library_name": "Audiobooks",
  "longest_items": [
    {
      "duration": "6 h",
      "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "title": "The Quiet Harbor"
    }
  ],
  "media_type": "book",
  "top_authors": [
    {
      "count": 2,
      "name": "Ada Lovell"
    }
  ],
  "total_authors": 3,
  "total_duration": "15 h",
  "total_duration_seconds": 54000.0,
  "total_genres": 3,
  "total_items": 4,
  "total_size": 430760000,
  "total_size_text": "410.8 MB"
}

Get listening stats

Get how long the API key's user has listened: in all, today, day by day over the last days, and per book or podcast, such as for a weekly summary.

Inputs

Daysdaysnumber
How many recent days to total and list day by day. Defaults to 7.From 1 to 365.

Outputs

by_daylist
Each of those days and how long they listened
by_weekdaylist
Each weekday and how long they listened on it in all
daysnumber
How many days 'recent' covers
itemslist
Each book or podcast and how long they listened to it, most first
recenttext
The same, such as 6 h 10 min
recent_secondsnumber
How long they listened in those days, in seconds
today_secondsnumber
How long they listened today
totaltext
The same, such as 312 h 5 min
total_secondsnumber
How long the user has listened in all, in seconds
Example output
{
  "by_day": [
    {
      "date": "2026-11-11",
      "seconds": 6480.0
    },
    {
      "date": "2026-11-12",
      "seconds": 2520.0
    }
  ],
  "by_weekday": [
    {
      "day": "Thursday",
      "seconds": 2520.0
    }
  ],
  "days": 7,
  "items": [
    {
      "author": "Ada Lovell",
      "item_id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "listened": "6 h 10 min",
      "seconds": 22200.0,
      "title": "The Quiet Harbor"
    }
  ],
  "recent": "2 h 30 min",
  "recent_seconds": 9000.0,
  "today_seconds": 2520.0,
  "total": "6 h 10 min",
  "total_seconds": 22200.0
}

Get progress

Get how far the API key's user is through a book or podcast episode, and whether and when they finished it.

Inputs

Book or podcastitemtextRequired
The book or podcast, by its title or its ID in Audiobookshelf.
Episodeepisodetext
For a podcast, the episode, by title or ID. Leave blank for its newest; leave blank for a book.

Outputs

authortext
Its author
current_time_secondsnumber
Where the user is, in seconds
duration_secondsnumber
How long it is, in seconds
episode_idtext
The episode's ID, for a podcast
episode_titletext
The episode's title, for a podcast
finished_attext
When the user finished it (UTC)
is_finishedtrue/false
Whether it's finished
item_idtext
The book's or podcast's ID
last_updatetext
When the user last listened (UTC)
linktext
A link to it in Audiobookshelf
progress_percentnumber
How much is listened to, from 0 to 100
startedtrue/false
Whether the user has started it
started_attext
When the user started it (UTC)
titletext
The book's or podcast's title
Example output
{
  "author": "Ada Lovell",
  "current_time_seconds": 14117.0,
  "duration_seconds": 41520.0,
  "episode_id": "",
  "episode_title": "",
  "finished_at": "",
  "is_finished": false,
  "item_id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
  "last_update": "2026-11-12T21:40:05Z",
  "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
  "progress_percent": 34.0,
  "started": true,
  "started_at": "2026-11-10T19:02:11Z",
  "title": "The Quiet Harbor"
}

Get series

Get a series with its books in order, and which of them the API key's user has finished, such as to find the next one to read.

Inputs

SeriesseriestextRequired
The series, by name or ID.

Outputs

added_attext
When it was added (UTC)
book_countnumber
How many of its books the library has
bookslist
Its books, in order
descriptiontext
About it
finished_countnumber
How many of its books the user finished
idtext
The series' ID
is_finishedtrue/false
Whether the user finished every book
library_idtext
Its library's ID
linktext
A link to it in Audiobookshelf
nametext
Its name
Example output
{
  "added_at": "2026-11-12T22:36:09Z",
  "book_count": 1,
  "books": [
    {
      "author": "Ada Lovell",
      "duration": "11 h 32 min",
      "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "is_finished": true,
      "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
      "published_year": "2019",
      "sequence": "1",
      "series": [
        "Harbor Tales #1"
      ],
      "title": "The Quiet Harbor"
    }
  ],
  "description": "",
  "finished_count": 1,
  "id": "9b8472df-15a0-4891-8d8e-545f84e83c38",
  "is_finished": true,
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "link": "http://192.168.1.20:13378/library/19e23cab-70e8-480a-958c-755021ca8d7a/series/9b8472df-15a0-4891-8d8e-545f84e83c38",
  "name": "Harbor Tales"
}

List authors

List the authors in an audiobook library, by last name, with how many of their books it has.

Inputs

Librarylibrarytext
The audiobook library, by name or ID. Leave blank when there's only one.
Name containsname_containstext
Only authors whose name contains this.
How manylimitnumber
The most to list. Defaults to 50.From 1 to 500.

Outputs

authorslist
The authors, by last name
countnumber
How many are listed
library_idtext
The library's ID
totalnumber
How many match in all
Example output
{
  "authors": [
    {
      "added_at": "2026-11-12T22:36:09Z",
      "asin": "",
      "book_count": 2,
      "description": "",
      "id": "35713bbc-7af8-4936-a292-09db69e5e750",
      "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
      "link": "http://192.168.1.20:13378/author/35713bbc-7af8-4936-a292-09db69e5e750",
      "name": "Ada Lovell"
    }
  ],
  "count": 1,
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "total": 1
}

List books and podcasts

List a library's books or podcasts, of one author, series, genre, tag or narrator, or by the user's progress, sorted as you choose.

Inputs

Librarylibrarytext
The library, by name or ID. Leave blank when there's only one.
Authorauthortext
Only this author's books. Give one filter at most.
Seriesseriestext
Only this series' books, such as Harbor Tales. Give one filter at most.
Genregenretext
Only items of this genre. Give one filter at most.
Tagtagtext
Only items with this tag. Give one filter at most.
Narratornarratortext
Only books read by this narrator. Give one filter at most.
Progressprogresstext
Only items the API key's user has finished, started, not started or not finished. Give one filter at most.One of: any, finished, in-progress (In progress), not-started (Not started), not-finished (Not finished). Default: any.
Sort bysorttext
The order to list them in.One of: title, author (Author (last name)), added (Newest added first), published (Newest published first), duration (Longest first), size (Largest first). Default: title.
How manylimitnumber
The most to list. Defaults to 50.From 1 to 500.
Pagepagenumber
Which page of the list, from 1. Defaults to 1.From 1 to 10000.

Outputs

countnumber
How many are listed
has_moretrue/false
Whether there are more pages
itemslist
The books or podcasts
library_idtext
The library's ID
library_nametext
Its name
pagenumber
The page listed, from 1
totalnumber
How many match in all
Example output
{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "added_at": "2026-11-12T22:36:10Z",
      "asin": "",
      "author": "Ada Lovell",
      "authors": [
        "Ada Lovell"
      ],
      "description": "A lighthouse keeper's last winter on the coast.",
      "duration": "11 h 32 min",
      "duration_seconds": 41520.0,
      "episode_count": 0,
      "explicit": false,
      "feed_url": "",
      "genres": [
        "Fiction"
      ],
      "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "isbn": "9780000000001",
      "language": "English",
      "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
      "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
      "media_type": "book",
      "missing": false,
      "narrators": [
        "Sam Reed"
      ],
      "path": "/audiobooks/Ada Lovell/Harbor Tales/Book 1 - The Quiet Harbor",
      "published_year": "2019",
      "publisher": "Northlight",
      "series": [
        "Harbor Tales #1"
      ],
      "size": 160662000,
      "subtitle": "",
      "tags": [
        "book-club"
      ],
      "title": "The Quiet Harbor",
      "updated_at": "2026-11-12T22:36:10Z"
    }
  ],
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "library_name": "Audiobooks",
  "page": 1,
  "total": 1
}

List collections

List the collections of books, everyone's or one library's.

Inputs

Librarylibrarytext
Only this library's collections. Leave blank for all.

Outputs

collectionslist
The collections
countnumber
How many
Example output
{
  "collections": [
    {
      "book_count": 1,
      "books": [
        {
          "author": "Ada Lovell",
          "duration": "11 h 32 min",
          "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
          "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
          "published_year": "2019",
          "sequence": "1",
          "series": [
            "Harbor Tales #1"
          ],
          "title": "The Quiet Harbor"
        }
      ],
      "created_at": "2026-11-12T23:05:00Z",
      "description": "This year's picks",
      "id": "5f0c1e7a-2b7d-4f8e-9a51-3c4d2e1f0a9b",
      "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
      "link": "http://192.168.1.20:13378/collection/5f0c1e7a-2b7d-4f8e-9a51-3c4d2e1f0a9b",
      "name": "Book club 2026"
    }
  ],
  "count": 1
}

List episodes

List a podcast's downloaded episodes, newest first, with whether the API key's user has finished each.

Inputs

PodcastpodcasttextRequired
The podcast, by its title or its ID in Audiobookshelf.
Only unfinishedonly_unfinishedtrue/false
Only episodes the user hasn't finished.Default: false.
How manylimitnumber
The most to list. Defaults to 50.From 1 to 500.

Outputs

countnumber
How many are listed
downloads_waitingnumber
How many episodes are waiting to download
episodeslist
Its downloaded episodes, newest first
podcast_idtext
The podcast's ID
podcast_titletext
Its title
totalnumber
How many match in all
Example output
{
  "count": 1,
  "downloads_waiting": 0,
  "episodes": [
    {
      "added_at": "2026-11-12T22:40:46Z",
      "description": "Episode 3 of the test podcast.",
      "duration": "42 min",
      "duration_seconds": 2520.0,
      "episode": "3",
      "id": "4815e05d-f295-44d5-87ca-2d7750f07053",
      "is_finished": false,
      "link": "http://192.168.1.20:13378/item/edd197d4-b979-49e8-9ea1-1ca1e61f3dba",
      "podcast_id": "edd197d4-b979-49e8-9ea1-1ca1e61f3dba",
      "progress_percent": 0.0,
      "published_at": "2026-11-12T22:35:42Z",
      "season": "",
      "size": 40320000,
      "title": "Episode 3: Harbor sounds"
    }
  ],
  "podcast_id": "edd197d4-b979-49e8-9ea1-1ca1e61f3dba",
  "podcast_title": "Lodol QA Radio",
  "total": 1
}

List in progress

List the books and podcast episodes the API key's user is partway through, most recently played first, as Continue Listening shows them.

Inputs

How manylimitnumber
The most to list. Defaults to 25.From 1 to 500.

Outputs

countnumber
How many
itemslist
What the user is partway through, most recent first
Example output
{
  "count": 1,
  "items": [
    {
      "author": "Ada Lovell",
      "current_time_seconds": 14117.0,
      "duration": "11 h 32 min",
      "episode_id": "",
      "episode_title": "",
      "item_id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "last_update": "2026-11-12T21:40:05Z",
      "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
      "media_type": "book",
      "progress_percent": 34.0,
      "title": "The Quiet Harbor"
    }
  ]
}

List libraries

List the audiobook and podcast libraries the API key's user can open, with their folders and when they were last scanned.

Inputs

None.

Outputs

countnumber
How many
librarieslist
The libraries the API key's user can open
Example output
{
  "count": 2,
  "libraries": [
    {
      "created_at": "2026-11-12T22:36:09Z",
      "folders": [
        "/audiobooks"
      ],
      "id": "19e23cab-70e8-480a-958c-755021ca8d7a",
      "last_scan": "2026-11-12T22:36:10Z",
      "link": "http://192.168.1.20:13378/library/19e23cab-70e8-480a-958c-755021ca8d7a",
      "media_type": "book",
      "metadata_provider": "google",
      "name": "Audiobooks"
    },
    {
      "created_at": "2026-11-12T22:36:09Z",
      "folders": [
        "/podcasts"
      ],
      "id": "9c8f3bff-a033-4fac-80b5-c0ef9786e9a5",
      "last_scan": "2026-11-12T22:36:10Z",
      "link": "http://192.168.1.20:13378/library/9c8f3bff-a033-4fac-80b5-c0ef9786e9a5",
      "media_type": "podcast",
      "metadata_provider": "itunes",
      "name": "Podcasts"
    }
  ]
}

List listening sessions

List the API key's user's listening sessions, newest first: what they listened to, when, for how long and on which device.

Inputs

How manylimitnumber
The most to list. Defaults to 25.From 1 to 200.
Pagepagenumber
Which page of the list, from 1. Defaults to 1.From 1 to 10000.

Outputs

countnumber
How many are listed
has_moretrue/false
Whether there are more pages
pagenumber
The page listed, from 1
sessionslist
The user's listening sessions, newest first
totalnumber
How many there are in all
Example output
{
  "count": 1,
  "has_more": false,
  "page": 1,
  "sessions": [
    {
      "author": "Ada Lovell",
      "date": "2026-11-12",
      "day_of_week": "Thursday",
      "device": "Abs Android Pixel 8",
      "duration_seconds": 41520.0,
      "end_position_seconds": 14117.0,
      "episode_id": "",
      "id": "e40e270c-98da-4ab6-a1ce-9904c3d522e3",
      "item_id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
      "listened": "42 min",
      "media_type": "book",
      "player": "exo-player",
      "seconds_listened": 2520.0,
      "start_position_seconds": 11597.0,
      "started_at": "2026-11-12T21:00:05Z",
      "title": "The Quiet Harbor",
      "updated_at": "2026-11-12T21:42:05Z"
    }
  ],
  "total": 1
}

List playlists

List the API key's user's playlists, with what's in each.

Inputs

Librarylibrarytext
Only this library's playlists. Leave blank for all.

Outputs

countnumber
How many
playlistslist
The API key's user's playlists
Example output
{
  "count": 1,
  "playlists": [
    {
      "created_at": "2026-11-12T23:06:00Z",
      "description": "",
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "item_count": 1,
      "items": [
        {
          "episode_id": "",
          "episode_title": "",
          "item_id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
          "title": "The Quiet Harbor"
        }
      ],
      "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
      "link": "http://192.168.1.20:13378/playlist/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Commute"
    }
  ]
}

List series

List the series in an audiobook library, by name, with their books.

Inputs

Librarylibrarytext
The audiobook library, by name or ID. Leave blank when there's only one.
How manylimitnumber
The most to list. Defaults to 50.From 1 to 500.
Pagepagenumber
Which page of the list, from 1. Defaults to 1.From 1 to 10000.

Outputs

countnumber
How many are listed
has_moretrue/false
Whether there are more pages
library_idtext
The library's ID
library_nametext
Its name
pagenumber
The page listed, from 1
serieslist
The series, by name
totalnumber
How many match in all
Example output
{
  "count": 1,
  "has_more": false,
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "library_name": "Audiobooks",
  "page": 1,
  "series": [
    {
      "added_at": "2026-11-12T22:36:09Z",
      "book_count": 1,
      "books": [
        {
          "author": "Ada Lovell",
          "duration": "11 h 32 min",
          "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
          "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
          "published_year": "2019",
          "sequence": "1",
          "series": [
            "Harbor Tales #1"
          ],
          "title": "The Quiet Harbor"
        }
      ],
      "description": "",
      "id": "9b8472df-15a0-4891-8d8e-545f84e83c38",
      "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
      "link": "http://192.168.1.20:13378/library/19e23cab-70e8-480a-958c-755021ca8d7a/series/9b8472df-15a0-4891-8d8e-545f84e83c38",
      "name": "Harbor Tales"
    }
  ],
  "total": 1
}

List users

List Audiobookshelf's users with their account type, permissions and libraries. Needs an admin's key.

Inputs

None.

Outputs

countnumber
How many
userslist
The users
Example output
{
  "count": 1,
  "users": [
    {
      "account_type": "user",
      "active": true,
      "can_delete": false,
      "can_download": true,
      "can_update": false,
      "can_upload": false,
      "created_at": "2026-11-01T09:00:00Z",
      "email": "maya@example.com",
      "id": "c10b57bb-1829-48c3-9134-62777b4a1429",
      "last_seen": "2026-11-12T21:42:05Z",
      "libraries": [
        "all"
      ],
      "locked": false,
      "username": "maya"
    }
  ]
}

Mark finished

Mark a book or podcast episode finished, or not finished, for the API key's user, as Audiobookshelf's Mark as Finished does.

Inputs

Book or podcastitemtextRequired
The book or podcast, by its title or its ID in Audiobookshelf.
Episodeepisodetext
For a podcast, the episode, by title or ID. Leave blank for its newest; leave blank for a book.
Finishedfinishedtrue/false
On marks it finished; off marks it not finished.Default: true.

Outputs

authortext
Its author
current_time_secondsnumber
Where the user is, in seconds
duration_secondsnumber
How long it is, in seconds
episode_idtext
The episode's ID, for a podcast
episode_titletext
The episode's title, for a podcast
finished_attext
When the user finished it (UTC)
is_finishedtrue/false
Whether it's finished
item_idtext
The book's or podcast's ID
last_updatetext
When the user last listened (UTC)
linktext
A link to it in Audiobookshelf
progress_percentnumber
How much is listened to, from 0 to 100
startedtrue/false
Whether the user has started it
started_attext
When the user started it (UTC)
titletext
The book's or podcast's title
Example output
{
  "author": "Ada Lovell",
  "current_time_seconds": 41520.0,
  "duration_seconds": 41520.0,
  "episode_id": "",
  "episode_title": "",
  "finished_at": "2026-11-12T23:10:00Z",
  "is_finished": true,
  "item_id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
  "last_update": "2026-11-12T21:40:05Z",
  "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
  "progress_percent": 100.0,
  "started": true,
  "started_at": "2026-11-10T19:02:11Z",
  "title": "The Quiet Harbor"
}

Match book or podcast

Look a book up at Google Books, Open Library, Audible or iTunes (a podcast at iTunes) and fill in its missing details and cover, as Audiobookshelf's Quick Match does. Needs the server to reach the internet.

Inputs

Book or podcastitemtextRequired
The book or podcast, by its title or its ID in Audiobookshelf.
Look up atprovidertext
Where to look a book up. A podcast is always looked up at iTunes.One of: google (Google Books), openlibrary (Open Library), itunes, audible (Audible.com), audible.uk (Audible.co.uk), audible.ca, audible.au (Audible.com.au), audible.de, audible.fr, audible.it, and 4 more. Default: google.
Titletitletext
The title to search for. Leave blank for the item's own.
Authorauthortext
The author to search for. Leave blank for the item's own.
ISBNisbntext
An ISBN to search for.
ASINasintext
An Audible ASIN to search for.
Replace detailsoverride_detailstrue/false
Replace details it already has with the ones found. Off fills in only what's missing.Default: false.
Replace coveroverride_covertrue/false
Replace the cover it already has with the one found.Default: false.

Outputs

added_attext
When it was added (UTC)
asintext
Its Audible ASIN (books)
authortext
The same, separated by commas
authorslist
Its authors (a podcast's author)
descriptiontext
What it's about
durationtext
The same, such as 11 h 32 min
duration_secondsnumber
How long it is, in seconds (books)
episode_countnumber
How many episodes a podcast has downloaded
explicittrue/false
Whether it's marked explicit
feed_urltext
A podcast's RSS feed address
genreslist
Its genres
idtext
The book's or podcast's ID, for other Audiobookshelf steps
isbntext
Its ISBN (books)
languagetext
Its language
library_idtext
Its library's ID
linktext
A link to it in Audiobookshelf
matchedtrue/false
Whether the provider found it
media_typetext
book or podcast
messagetext
What happened, such as No google match found
missingtrue/false
Whether its files are missing
narratorslist
Its narrators (books)
pathtext
Its folder on the Audiobookshelf server
providertext
Where it was looked up, such as google
published_yeartext
The year it was published (a podcast's release date)
publishertext
Its publisher (books)
serieslist
Its series, with the book's number, such as Harbor Tales #1
sizenumber
Its files' size in bytes
subtitletext
Its subtitle (books)
tagslist
Its tags
titletext
Its title
updatedtrue/false
Whether its details or cover changed
updated_attext
When it last changed (UTC)
Example output
{
  "added_at": "2026-11-12T22:36:10Z",
  "asin": "",
  "author": "Ada Lovell",
  "authors": [
    "Ada Lovell"
  ],
  "description": "A lighthouse keeper's last winter on the coast.",
  "duration": "11 h 32 min",
  "duration_seconds": 41520.0,
  "episode_count": 0,
  "explicit": false,
  "feed_url": "",
  "genres": [
    "Fiction"
  ],
  "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
  "isbn": "9780000000001",
  "language": "English",
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
  "matched": true,
  "media_type": "book",
  "message": "Matched; the item's details were filled in.",
  "missing": false,
  "narrators": [
    "Sam Reed"
  ],
  "path": "/audiobooks/Ada Lovell/Harbor Tales/Book 1 - The Quiet Harbor",
  "provider": "google",
  "published_year": "2019",
  "publisher": "Northlight",
  "series": [
    "Harbor Tales #1"
  ],
  "size": 160662000,
  "subtitle": "",
  "tags": [
    "book-club"
  ],
  "title": "The Quiet Harbor",
  "updated": true,
  "updated_at": "2026-11-12T22:36:10Z"
}

Remove from collection

Take one or more books out of a collection. The books stay in the library.

Inputs

CollectioncollectiontextRequired
The collection, by name or ID.
BooksbookstextRequired
One or more books, by title or ID, separated by commas.

Outputs

addedlist
The titles added
book_countnumber
How many books it holds
bookslist
Its books
created_attext
When it was made (UTC)
descriptiontext
Its description
idtext
The collection's ID
library_idtext
Its library's ID
linktext
A link to it in Audiobookshelf
nametext
Its name
removedlist
The titles taken out
Example output
{
  "added": [],
  "book_count": 1,
  "books": [
    {
      "author": "Ada Lovell",
      "duration": "11 h 32 min",
      "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
      "published_year": "2019",
      "sequence": "1",
      "series": [
        "Harbor Tales #1"
      ],
      "title": "The Quiet Harbor"
    }
  ],
  "created_at": "2026-11-12T23:05:00Z",
  "description": "This year's picks",
  "id": "5f0c1e7a-2b7d-4f8e-9a51-3c4d2e1f0a9b",
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "link": "http://192.168.1.20:13378/collection/5f0c1e7a-2b7d-4f8e-9a51-3c4d2e1f0a9b",
  "name": "Book club 2026",
  "removed": [
    "Second Tide"
  ]
}

Remove from playlist

Take a book, or a podcast episode, out of a playlist. Audiobookshelf deletes a playlist when its last item is taken out.

Inputs

PlaylistplaylisttextRequired
The playlist, by name or ID. Only the API key's user's own.
Book or podcastitemtextRequired
The book or podcast, by its title or its ID in Audiobookshelf.
Episodeepisodetext
For a podcast, the episode, by title or ID. Leave blank for its newest; leave blank for a book.

Outputs

changed_itemobject
The book or episode added or taken out
created_attext
When it was made (UTC)
deletedtrue/false
Whether Audiobookshelf deleted the playlist, as it does when its last item is taken out
descriptiontext
Its description
idtext
The playlist's ID
item_countnumber
How many books or episodes it holds
itemslist
What it holds, in order
library_idtext
Its library's ID
linktext
A link to it in Audiobookshelf
nametext
Its name
Example output
{
  "changed_item": {
    "episode_id": "",
    "episode_title": "",
    "item_id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
    "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
    "title": "Second Tide"
  },
  "created_at": "2026-11-12T23:06:00Z",
  "deleted": false,
  "description": "",
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "item_count": 1,
  "items": [
    {
      "episode_id": "",
      "episode_title": "",
      "item_id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "title": "The Quiet Harbor"
    }
  ],
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "link": "http://192.168.1.20:13378/playlist/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Commute"
}

Scan library

Have Audiobookshelf scan a library's folders for new, changed and removed books, as its Scan button does, such as after a download lands. Needs an admin's key.

Inputs

Librarylibrarytext
The library, by name or ID. Leave blank when there's only one.
Wait for itwaittrue/false
Wait up to a minute for the scan to finish. Off only starts it.Default: true.

Outputs

finishedtrue/false
Whether the scan finished while the step waited
item_countnumber
How many books or podcasts it has now
last_scantext
When the library was last scanned (UTC)
library_idtext
The library's ID
library_nametext
Its name
linktext
A link to the library
statustext
finished, or started when it was still running after a minute
Example output
{
  "finished": true,
  "item_count": 5,
  "last_scan": "2026-11-12T23:01:44Z",
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "library_name": "Audiobooks",
  "link": "http://192.168.1.20:13378/library/19e23cab-70e8-480a-958c-755021ca8d7a",
  "status": "finished"
}

Search library

Search a library, as Audiobookshelf's search box does, for books or podcasts by title, author, narrator, series, ISBN or ASIN, and for authors, series, tags and genres.

Inputs

Librarylibrarytext
The library to search, by name or ID. Leave blank when there's only one.
Search forquerytextRequired
The words to look for, such as a title or an author's name.
How manylimitnumber
The most of each kind to return. Defaults to 10.From 1 to 50.

Outputs

authorslist
The authors found
countnumber
How many items, authors and series were found
genreslist
The genres found
itemslist
The books or podcasts found
library_idtext
The library's ID
narratorslist
The narrators found
querytext
What was looked for
serieslist
The series found
tagslist
The tags found
Example output
{
  "authors": [],
  "count": 2,
  "genres": [],
  "items": [
    {
      "added_at": "2026-11-12T22:36:10Z",
      "asin": "",
      "author": "Ada Lovell",
      "authors": [
        "Ada Lovell"
      ],
      "description": "A lighthouse keeper's last winter on the coast.",
      "duration": "11 h 32 min",
      "duration_seconds": 41520.0,
      "episode_count": 0,
      "explicit": false,
      "feed_url": "",
      "genres": [
        "Fiction"
      ],
      "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
      "isbn": "9780000000001",
      "language": "English",
      "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
      "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
      "media_type": "book",
      "missing": false,
      "narrators": [
        "Sam Reed"
      ],
      "path": "/audiobooks/Ada Lovell/Harbor Tales/Book 1 - The Quiet Harbor",
      "published_year": "2019",
      "publisher": "Northlight",
      "series": [
        "Harbor Tales #1"
      ],
      "size": 160662000,
      "subtitle": "",
      "tags": [
        "book-club"
      ],
      "title": "The Quiet Harbor",
      "updated_at": "2026-11-12T22:36:10Z"
    }
  ],
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "narrators": [],
  "query": "harbor",
  "series": [
    {
      "book_count": 2,
      "id": "9b8472df-15a0-4891-8d8e-545f84e83c38",
      "name": "Harbor Tales"
    }
  ],
  "tags": []
}

Update book or podcast

Change a book's or podcast's details: title, authors, series, genres, tags and more. Blank fields stay as they are. Needs a user allowed to update.

Inputs

Book or podcastitemtextRequired
The book or podcast, by its title or its ID in Audiobookshelf.
Titletitletext
The new title.
Subtitlesubtitletext
A book's new subtitle.
Authorsauthorstext
The authors, replacing the ones it has; a podcast's author. Separate several with commas.
Narratorsnarratorstext
A book's narrators, replacing the ones it has. Separate several with commas.
Seriesseriestext
A book's series, replacing the ones it has, each with its number after #, such as Harbor Tales #2. Separate several with commas.
Genresgenrestext
The genres, replacing the ones it has. Separate several with commas.
Tagstagstext
The tags, replacing the ones it has. Separate several with commas.
Add tagsadd_tagstext
Tags to add, keeping the ones it has. Separate several with commas.
Remove tagsremove_tagstext
Tags to take off. Separate several with commas.
Descriptiondescriptiontext
The new description.
Publisherpublishertext
A book's publisher.
Published yearpublished_yeartext
The year a book was published, such as 2019.
Languagelanguagetext
Its language, such as English.
ISBNisbntext
A book's ISBN.
ASINasintext
A book's Audible ASIN, such as B0036I54I6.

Outputs

added_attext
When it was added (UTC)
asintext
Its Audible ASIN (books)
authortext
The same, separated by commas
authorslist
Its authors (a podcast's author)
changedlist
What changed: title, authors, series, genres, tags and so on
descriptiontext
What it's about
durationtext
The same, such as 11 h 32 min
duration_secondsnumber
How long it is, in seconds (books)
episode_countnumber
How many episodes a podcast has downloaded
explicittrue/false
Whether it's marked explicit
feed_urltext
A podcast's RSS feed address
genreslist
Its genres
idtext
The book's or podcast's ID, for other Audiobookshelf steps
isbntext
Its ISBN (books)
languagetext
Its language
library_idtext
Its library's ID
linktext
A link to it in Audiobookshelf
media_typetext
book or podcast
missingtrue/false
Whether its files are missing
narratorslist
Its narrators (books)
pathtext
Its folder on the Audiobookshelf server
published_yeartext
The year it was published (a podcast's release date)
publishertext
Its publisher (books)
serieslist
Its series, with the book's number, such as Harbor Tales #1
sizenumber
Its files' size in bytes
subtitletext
Its subtitle (books)
tagslist
Its tags
titletext
Its title
updatedtrue/false
Whether anything changed
updated_attext
When it last changed (UTC)
Example output
{
  "added_at": "2026-11-12T22:36:10Z",
  "asin": "",
  "author": "Ada Lovell",
  "authors": [
    "Ada Lovell"
  ],
  "changed": [
    "tags"
  ],
  "description": "A lighthouse keeper's last winter on the coast.",
  "duration": "11 h 32 min",
  "duration_seconds": 41520.0,
  "episode_count": 0,
  "explicit": false,
  "feed_url": "",
  "genres": [
    "Fiction"
  ],
  "id": "08558a2d-cab0-44dc-8e0b-0f4866197975",
  "isbn": "9780000000001",
  "language": "English",
  "library_id": "19e23cab-70e8-480a-958c-755021ca8d7a",
  "link": "http://192.168.1.20:13378/item/08558a2d-cab0-44dc-8e0b-0f4866197975",
  "media_type": "book",
  "missing": false,
  "narrators": [
    "Sam Reed"
  ],
  "path": "/audiobooks/Ada Lovell/Harbor Tales/Book 1 - The Quiet Harbor",
  "published_year": "2019",
  "publisher": "Northlight",
  "series": [
    "Harbor Tales #1"
  ],
  "size": 160662000,
  "subtitle": "",
  "tags": [
    "book-club",
    "favourites"
  ],
  "title": "The Quiet Harbor",
  "updated": true,
  "updated_at": "2026-11-12T22:36:10Z"
}

On this page