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
| Action | What it does |
|---|---|
| Add podcast | Add a podcast to a podcast library by its RSS feed address, and optionally download its latest episodes. |
| Add to collection | Add one or more books to a collection. |
| 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. |
| 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. |
| Create collection | Make a collection of books, which everyone with the library sees, such as a book club's picks. |
| Create playlist | Make a playlist for the API key's user, starting with a book or a podcast episode. |
| Create user | Add a user who can sign in to Audiobookshelf, such as a family member, with the libraries and permissions they get. |
| Delete book or podcast | Remove a book or podcast from its library, and optionally delete its files from the server. |
| Delete collection | Delete a collection. |
| Delete playlist | Delete one of the API key's user's playlists. |
| Delete user | Delete a user, with their progress, playlists and listening history. |
| Download episodes | Download a podcast's newest episodes that aren't in the library yet, whenever they were published. |
| Get author | Get an author with their books and series. |
| 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. |
| Get library | Get a library: how many books or podcasts it has, and its authors, series, genres, tags and narrators. |
| 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. |
| 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. |
| Get progress | Get how far the API key's user is through a book or podcast episode, and whether and when they finished it. |
| 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. |
| List authors | List the authors in an audiobook library, by last name, with how many of their books it has. |
| 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. |
| List collections | List the collections of books, everyone's or one library's. |
| List episodes | List a podcast's downloaded episodes, newest first, with whether the API key's user has finished each. |
| 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. |
| List libraries | List the audiobook and podcast libraries the API key's user can open, with their folders and when they were last scanned. |
| 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. |
| List playlists | List the API key's user's playlists, with what's in each. |
| List series | List the series in an audiobook library, by name, with their books. |
| List users | List Audiobookshelf's users with their account type, permissions and libraries. |
| 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. |
| 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. |
| Remove from collection | Take one or more books out of a collection. |
| Remove from playlist | Take a book, or a podcast episode, out of a playlist. |
| 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. |
| 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. |
| Update book or podcast | Change 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 address
feed_urltextRequired - The podcast's RSS feed, such as https://feeds.example.com/show.xml.
- Library
librarytext - The podcast library, by name or ID. Leave blank when there's only one.
- Title
titletext - A title of your own, which also names its folder. Leave blank for the feed's.
- Download latest
download_latestnumber - How many of its newest episodes to download now. Defaults to none.From 0 to 50.
- Download new episodes automatically
auto_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
- Collection
collectiontextRequired - The collection, by name or ID.
- Books
bookstextRequired - 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
- Playlist
playlisttextRequired - The playlist, by name or ID. Only the API key's user's own.
- Book or podcast
itemtextRequired - The book or podcast, by its title or its ID in Audiobookshelf.
- Episode
episodetext - 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
- Podcast
podcasttextRequired - The podcast, by its title or its ID in Audiobookshelf.
- Most to download
limitnumber - 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
- Name
nametextRequired - The collection's name.
- Books
bookstextRequired - One or more books, by title or ID, separated by commas.
- Description
descriptiontext - 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
- Name
nametextRequired - The playlist's name.
- Book or podcast
itemtextRequired - The book or podcast, by its title or its ID in Audiobookshelf.
- Episode
episodetext - For a podcast, the episode, by title or ID. Leave blank for its newest; leave blank for a book.
- Description
descriptiontext - 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
- Username
usernametextRequired - Their username.
- Password
passwordtextRequired - Their first password; they can change it under Account.
- Account type
account_typetext - Admins can do everything; guests can only listen.One of:
user,admin,guest. Default:user. - Email
emailtext - Their email address.
- Libraries
librariestext - The libraries they can open, by name or ID. Leave blank for all. Separate several with commas.
- Can download
can_downloadtrue/false - Let them download books and episodes. Admins always can.Default:
true. - Can update
can_updatetrue/false - Let them change books' details. Admins always can.Default:
false. - Can delete
can_deletetrue/false - Let them delete books. Admins always can.Default:
false. - Can upload
can_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 podcast
itemtextRequired - The book or podcast, by its title or its ID in Audiobookshelf.
- Delete files
delete_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
- Collection
collectiontextRequired - 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
- Playlist
playlisttextRequired - 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
- User
usertextRequired - 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
- Podcast
podcasttextRequired - The podcast, by its title or its ID in Audiobookshelf.
- How many
countnumber - 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
- Author
authortextRequired - 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 podcast
itemtextRequired - 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
- Library
librarytext - 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
- Library
librarytext - 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
- Days
daysnumber - 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 podcast
itemtextRequired - The book or podcast, by its title or its ID in Audiobookshelf.
- Episode
episodetext - 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
- Series
seriestextRequired - 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
- Library
librarytext - The audiobook library, by name or ID. Leave blank when there's only one.
- Name contains
name_containstext - Only authors whose name contains this.
- How many
limitnumber - 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
- Library
librarytext - The library, by name or ID. Leave blank when there's only one.
- Author
authortext - Only this author's books. Give one filter at most.
- Series
seriestext - Only this series' books, such as Harbor Tales. Give one filter at most.
- Genre
genretext - Only items of this genre. Give one filter at most.
- Tag
tagtext - Only items with this tag. Give one filter at most.
- Narrator
narratortext - Only books read by this narrator. Give one filter at most.
- Progress
progresstext - 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 by
sorttext - 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 many
limitnumber - The most to list. Defaults to 50.From 1 to 500.
- Page
pagenumber - 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
- Library
librarytext - 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
- Podcast
podcasttextRequired - The podcast, by its title or its ID in Audiobookshelf.
- Only unfinished
only_unfinishedtrue/false - Only episodes the user hasn't finished.Default:
false. - How many
limitnumber - 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 many
limitnumber - 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 many
limitnumber - The most to list. Defaults to 25.From 1 to 200.
- Page
pagenumber - 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
- Library
librarytext - 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
- Library
librarytext - The audiobook library, by name or ID. Leave blank when there's only one.
- How many
limitnumber - The most to list. Defaults to 50.From 1 to 500.
- Page
pagenumber - 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 podcast
itemtextRequired - The book or podcast, by its title or its ID in Audiobookshelf.
- Episode
episodetext - For a podcast, the episode, by title or ID. Leave blank for its newest; leave blank for a book.
- Finished
finishedtrue/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 podcast
itemtextRequired - The book or podcast, by its title or its ID in Audiobookshelf.
- Look up at
providertext - 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. - Title
titletext - The title to search for. Leave blank for the item's own.
- Author
authortext - The author to search for. Leave blank for the item's own.
- ISBN
isbntext - An ISBN to search for.
- ASIN
asintext - An Audible ASIN to search for.
- Replace details
override_detailstrue/false - Replace details it already has with the ones found. Off fills in only what's missing.Default:
false. - Replace cover
override_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
- Collection
collectiontextRequired - The collection, by name or ID.
- Books
bookstextRequired - 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
- Playlist
playlisttextRequired - The playlist, by name or ID. Only the API key's user's own.
- Book or podcast
itemtextRequired - The book or podcast, by its title or its ID in Audiobookshelf.
- Episode
episodetext - 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
- Library
librarytext - The library, by name or ID. Leave blank when there's only one.
- Wait for it
waittrue/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
- Library
librarytext - The library to search, by name or ID. Leave blank when there's only one.
- Search for
querytextRequired - The words to look for, such as a title or an author's name.
- How many
limitnumber - 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 podcast
itemtextRequired - The book or podcast, by its title or its ID in Audiobookshelf.
- Title
titletext - The new title.
- Subtitle
subtitletext - A book's new subtitle.
- Authors
authorstext - The authors, replacing the ones it has; a podcast's author. Separate several with commas.
- Narrators
narratorstext - A book's narrators, replacing the ones it has. Separate several with commas.
- Series
seriestext - A book's series, replacing the ones it has, each with its number after #, such as Harbor Tales #2. Separate several with commas.
- Genres
genrestext - The genres, replacing the ones it has. Separate several with commas.
- Tags
tagstext - The tags, replacing the ones it has. Separate several with commas.
- Add tags
add_tagstext - Tags to add, keeping the ones it has. Separate several with commas.
- Remove tags
remove_tagstext - Tags to take off. Separate several with commas.
- Description
descriptiontext - The new description.
- Publisher
publishertext - A book's publisher.
- Published year
published_yeartext - The year a book was published, such as 2019.
- Language
languagetext - Its language, such as English.
- ISBN
isbntext - A book's ISBN.
- ASIN
asintext - 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"
}