# Audiobookshelf

> 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.

App · 36 actions. Web page: https://docs.lodol.com/docs/integrations/audiobookshelf

## Actions

### 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_url`, text, required): The podcast's RSS feed, such as https://feeds.example.com/show.xml.
- Library (`library`, text): The podcast library, by name or ID. Leave blank when there's only one.
- Title (`title`, text): A title of your own, which also names its folder. Leave blank for the feed's.
- Download latest (`download_latest`, number): How many of its newest episodes to download now. Defaults to none. From 0 to 50.
- Download new episodes automatically (`auto_download`, true/false): Have Audiobookshelf download new episodes on its own, every hour by default. Default: `false`.

**Outputs**

- `added_at` (text): When it was added (UTC)
- `already_added` (true/false): Whether the library already had this feed; nothing was added then
- `asin` (text): Its Audible ASIN (books)
- `author` (text): The same, separated by commas
- `authors` (list): Its authors (a podcast's author)
- `description` (text): What it's about
- `downloaded_count` (number): How many of them are downloaded
- `downloads_finished` (true/false): Whether every one finished within a minute; the rest keep downloading
- `duration` (text): The same, such as 11 h 32 min
- `duration_seconds` (number): How long it is, in seconds (books)
- `episode_count` (number): How many episodes a podcast has downloaded
- `episodes_queued` (list): The episodes sent to download
- `explicit` (true/false): Whether it's marked explicit
- `feed_episode_count` (number): How many episodes the feed lists
- `feed_url` (text): A podcast's RSS feed address
- `genres` (list): Its genres
- `id` (text): The book's or podcast's ID, for other Audiobookshelf steps
- `isbn` (text): Its ISBN (books)
- `language` (text): Its language
- `library_id` (text): Its library's ID
- `link` (text): A link to it in Audiobookshelf
- `media_type` (text): book or podcast
- `missing` (true/false): Whether its files are missing
- `narrators` (list): Its narrators (books)
- `path` (text): Its folder on the Audiobookshelf server
- `published_year` (text): The year it was published (a podcast's release date)
- `publisher` (text): Its publisher (books)
- `queued_count` (number): How many episodes were sent to download
- `series` (list): Its series, with the book's number, such as Harbor Tales #1
- `size` (number): Its files' size in bytes
- `subtitle` (text): Its subtitle (books)
- `tags` (list): Its tags
- `title` (text): Its title
- `updated_at` (text): When it last changed (UTC)

**Example output**

```json
{
  "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 (`collection`, text, required): The collection, by name or ID.
- Books (`books`, text, required): One or more books, by title or ID, separated by commas.

**Outputs**

- `added` (list): The titles added
- `book_count` (number): How many books it holds
- `books` (list): Its books
- `created_at` (text): When it was made (UTC)
- `description` (text): Its description
- `id` (text): The collection's ID
- `library_id` (text): Its library's ID
- `link` (text): A link to it in Audiobookshelf
- `name` (text): Its name
- `removed` (list): The titles taken out

**Example output**

```json
{
  "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 (`playlist`, text, required): The playlist, by name or ID. Only the API key's user's own.
- Book or podcast (`item`, text, required): The book or podcast, by its title or its ID in Audiobookshelf.
- Episode (`episode`, text): For a podcast, the episode, by title or ID. Leave blank for its newest; leave blank for a book.

**Outputs**

- `changed_item` (object): The book or episode added or taken out
- `created_at` (text): When it was made (UTC)
- `deleted` (true/false): Whether Audiobookshelf deleted the playlist, as it does when its last item is taken out
- `description` (text): Its description
- `id` (text): The playlist's ID
- `item_count` (number): How many books or episodes it holds
- `items` (list): What it holds, in order
- `library_id` (text): Its library's ID
- `link` (text): A link to it in Audiobookshelf
- `name` (text): Its name

**Example output**

```json
{
  "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 (`podcast`, text, required): The podcast, by its title or its ID in Audiobookshelf.
- Most to download (`limit`, number): The most new episodes to download. Defaults to 3. From 1 to 50.

**Outputs**

- `added_at` (text): When it was added (UTC)
- `asin` (text): Its Audible ASIN (books)
- `author` (text): The same, separated by commas
- `authors` (list): Its authors (a podcast's author)
- `description` (text): What it's about
- `downloaded_count` (number): How many of them are downloaded
- `downloads_finished` (true/false): Whether every one finished within a minute; the rest keep downloading
- `duration` (text): The same, such as 11 h 32 min
- `duration_seconds` (number): How long it is, in seconds (books)
- `episode_count` (number): How many episodes a podcast has downloaded
- `episodes_queued` (list): The episodes sent to download
- `explicit` (true/false): Whether it's marked explicit
- `feed_url` (text): A podcast's RSS feed address
- `genres` (list): Its genres
- `id` (text): The book's or podcast's ID, for other Audiobookshelf steps
- `isbn` (text): Its ISBN (books)
- `language` (text): Its language
- `library_id` (text): Its library's ID
- `link` (text): A link to it in Audiobookshelf
- `media_type` (text): book or podcast
- `missing` (true/false): Whether its files are missing
- `narrators` (list): Its narrators (books)
- `path` (text): Its folder on the Audiobookshelf server
- `published_year` (text): The year it was published (a podcast's release date)
- `publisher` (text): Its publisher (books)
- `queued_count` (number): How many episodes were sent to download
- `series` (list): Its series, with the book's number, such as Harbor Tales #1
- `size` (number): Its files' size in bytes
- `subtitle` (text): Its subtitle (books)
- `tags` (list): Its tags
- `title` (text): Its title
- `updated_at` (text): When it last changed (UTC)

**Example output**

```json
{
  "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 (`name`, text, required): The collection's name.
- Books (`books`, text, required): One or more books, by title or ID, separated by commas.
- Description (`description`, text): What the collection is for.

**Outputs**

- `book_count` (number): How many books it holds
- `books` (list): Its books
- `created_at` (text): When it was made (UTC)
- `description` (text): Its description
- `id` (text): The collection's ID
- `library_id` (text): Its library's ID
- `link` (text): A link to it in Audiobookshelf
- `name` (text): Its name

**Example output**

```json
{
  "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 (`name`, text, required): The playlist's name.
- Book or podcast (`item`, text, required): The book or podcast, by its title or its ID in Audiobookshelf.
- Episode (`episode`, text): For a podcast, the episode, by title or ID. Leave blank for its newest; leave blank for a book.
- Description (`description`, text): What the playlist is for.

**Outputs**

- `created_at` (text): When it was made (UTC)
- `description` (text): Its description
- `id` (text): The playlist's ID
- `item_count` (number): How many books or episodes it holds
- `items` (list): What it holds, in order
- `library_id` (text): Its library's ID
- `link` (text): A link to it in Audiobookshelf
- `name` (text): Its name

**Example output**

```json
{
  "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 (`username`, text, required): Their username.
- Password (`password`, text, required): Their first password; they can change it under Account.
- Account type (`account_type`, text): Admins can do everything; guests can only listen. One of: `user`, `admin`, `guest`. Default: `user`.
- Email (`email`, text): Their email address.
- Libraries (`libraries`, text): The libraries they can open, by name or ID. Leave blank for all. Separate several with commas.
- Can download (`can_download`, true/false): Let them download books and episodes. Admins always can. Default: `true`.
- Can update (`can_update`, true/false): Let them change books' details. Admins always can. Default: `false`.
- Can delete (`can_delete`, true/false): Let them delete books. Admins always can. Default: `false`.
- Can upload (`can_upload`, true/false): Let them upload books. Admins always can. Default: `false`.

**Outputs**

- `account_type` (text): root, admin, user or guest
- `active` (true/false): Whether they can sign in
- `can_delete` (true/false): Whether they may delete items
- `can_download` (true/false): Whether they may download
- `can_update` (true/false): Whether they may change items
- `can_upload` (true/false): Whether they may upload
- `created_at` (text): When they were made (UTC)
- `email` (text): Their email address
- `id` (text): The user's ID
- `last_seen` (text): When they were last seen (UTC)
- `libraries` (list): The libraries they can open, or all
- `locked` (true/false): Whether they're kept from changing their password
- `username` (text): Their username

**Example output**

```json
{
  "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 (`item`, text, required): The book or podcast, by its title or its ID in Audiobookshelf.
- Delete files (`delete_files`, true/false): Also delete its folder and files from the server. This can't be undone. Default: `false`.

**Outputs**

- `deleted` (true/false): Always true
- `files_deleted` (true/false): Whether its folder and files were deleted too
- `id` (text): The deleted item's ID
- `library_id` (text): Its library's ID
- `media_type` (text): book or podcast
- `path` (text): Its folder on the server
- `title` (text): Its title

**Example output**

```json
{
  "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 (`collection`, text, required): The collection, by name or ID.

**Outputs**

- `deleted` (true/false): Always true
- `id` (text): The deleted record's ID
- `name` (text): Its name

**Example output**

```json
{
  "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 (`playlist`, text, required): The playlist, by name or ID. Only the API key's user's own.

**Outputs**

- `deleted` (true/false): Always true
- `id` (text): The deleted record's ID
- `name` (text): Its name

**Example output**

```json
{
  "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 (`user`, text, required): The user, by username or ID. Not the API key's own user.

**Outputs**

- `deleted` (true/false): Always true
- `id` (text): The deleted user's ID
- `username` (text): Their username

**Example output**

```json
{
  "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 (`podcast`, text, required): The podcast, by its title or its ID in Audiobookshelf.
- How many (`count`, number): How many of the newest missing episodes to download. Defaults to 1. From 1 to 50.

**Outputs**

- `added_at` (text): When it was added (UTC)
- `asin` (text): Its Audible ASIN (books)
- `author` (text): The same, separated by commas
- `authors` (list): Its authors (a podcast's author)
- `description` (text): What it's about
- `downloaded_count` (number): How many of them are downloaded
- `downloads_finished` (true/false): Whether every one finished within a minute; the rest keep downloading
- `duration` (text): The same, such as 11 h 32 min
- `duration_seconds` (number): How long it is, in seconds (books)
- `episode_count` (number): How many episodes a podcast has downloaded
- `episodes_queued` (list): The episodes sent to download
- `explicit` (true/false): Whether it's marked explicit
- `feed_url` (text): A podcast's RSS feed address
- `genres` (list): Its genres
- `id` (text): The book's or podcast's ID, for other Audiobookshelf steps
- `isbn` (text): Its ISBN (books)
- `language` (text): Its language
- `library_id` (text): Its library's ID
- `link` (text): A link to it in Audiobookshelf
- `media_type` (text): book or podcast
- `missing` (true/false): Whether its files are missing
- `narrators` (list): Its narrators (books)
- `path` (text): Its folder on the Audiobookshelf server
- `published_year` (text): The year it was published (a podcast's release date)
- `publisher` (text): Its publisher (books)
- `queued_count` (number): How many episodes were sent to download
- `series` (list): Its series, with the book's number, such as Harbor Tales #1
- `size` (number): Its files' size in bytes
- `subtitle` (text): Its subtitle (books)
- `tags` (list): Its tags
- `title` (text): Its title
- `updated_at` (text): When it last changed (UTC)

**Example output**

```json
{
  "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 (`author`, text, required): The author, by name or ID.

**Outputs**

- `added_at` (text): When they were added (UTC)
- `asin` (text): Their Audible ASIN
- `book_count` (number): How many of their books the library has
- `books` (list): Their books
- `description` (text): About them
- `id` (text): The author's ID
- `library_id` (text): Their library's ID
- `link` (text): A link to them in Audiobookshelf
- `name` (text): Their name
- `series` (list): Their series

**Example output**

```json
{
  "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 (`item`, text, required): The book or podcast, by its title or its ID in Audiobookshelf.

**Outputs**

- `added_at` (text): When it was added (UTC)
- `asin` (text): Its Audible ASIN (books)
- `audio_files` (list): Its audio files' names
- `author` (text): The same, separated by commas
- `authors` (list): Its authors (a podcast's author)
- `chapters` (list): Its chapters
- `description` (text): What it's about
- `duration` (text): The same, such as 11 h 32 min
- `duration_seconds` (number): How long it is, in seconds (books)
- `episode_count` (number): How many episodes a podcast has downloaded
- `explicit` (true/false): Whether it's marked explicit
- `feed_url` (text): A podcast's RSS feed address
- `genres` (list): Its genres
- `id` (text): The book's or podcast's ID, for other Audiobookshelf steps
- `isbn` (text): Its ISBN (books)
- `language` (text): Its language
- `library_id` (text): Its library's ID
- `link` (text): A link to it in Audiobookshelf
- `media_type` (text): book or podcast
- `missing` (true/false): Whether its files are missing
- `narrators` (list): Its narrators (books)
- `path` (text): Its folder on the Audiobookshelf server
- `progress` (object): The API key's user's progress
- `published_year` (text): The year it was published (a podcast's release date)
- `publisher` (text): Its publisher (books)
- `series` (list): Its series, with the book's number, such as Harbor Tales #1
- `size` (number): Its files' size in bytes
- `subtitle` (text): Its subtitle (books)
- `tags` (list): Its tags
- `title` (text): Its title
- `updated_at` (text): When it last changed (UTC)

**Example output**

```json
{
  "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 (`library`, text): The library, by name or ID. Leave blank when there's only one.

**Outputs**

- `authors` (list): Its authors' names
- `created_at` (text): When it was made (UTC)
- `folders` (list): The folders on the server it reads
- `genres` (list): Its genres
- `id` (text): The library's ID, for other Audiobookshelf steps
- `issues` (number): How many items are missing or can't be read
- `item_count` (number): How many books or podcasts it has
- `languages` (list): Its languages
- `last_scan` (text): When it was last scanned (UTC)
- `link` (text): A link to it in Audiobookshelf
- `media_type` (text): book or podcast
- `metadata_provider` (text): Where it looks up details, such as google
- `name` (text): Its name
- `narrators` (list): Its narrators
- `series` (list): Its series' names
- `tags` (list): Its tags

**Example output**

```json
{
  "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 (`library`, text): The library, by name or ID. Leave blank when there's only one.

**Outputs**

- `audio_tracks` (number): How many audio files
- `genres` (list): Each genre and how many items have it
- `largest_items` (list): The largest items
- `library_id` (text): The library's ID
- `library_name` (text): Its name
- `longest_items` (list): The longest items
- `media_type` (text): book or podcast
- `top_authors` (list): The authors with the most books
- `total_authors` (number): How many authors
- `total_duration` (text): The same, such as 312 h 5 min
- `total_duration_seconds` (number): Everything's length together, in seconds
- `total_genres` (number): How many genres
- `total_items` (number): How many books or podcasts
- `total_size` (number): Its files' size in bytes
- `total_size_text` (text): The same, such as 45.2 GB

**Example output**

```json
{
  "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 (`days`, number): How many recent days to total and list day by day. Defaults to 7. From 1 to 365.

**Outputs**

- `by_day` (list): Each of those days and how long they listened
- `by_weekday` (list): Each weekday and how long they listened on it in all
- `days` (number): How many days 'recent' covers
- `items` (list): Each book or podcast and how long they listened to it, most first
- `recent` (text): The same, such as 6 h 10 min
- `recent_seconds` (number): How long they listened in those days, in seconds
- `today_seconds` (number): How long they listened today
- `total` (text): The same, such as 312 h 5 min
- `total_seconds` (number): How long the user has listened in all, in seconds

**Example output**

```json
{
  "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 (`item`, text, required): The book or podcast, by its title or its ID in Audiobookshelf.
- Episode (`episode`, text): For a podcast, the episode, by title or ID. Leave blank for its newest; leave blank for a book.

**Outputs**

- `author` (text): Its author
- `current_time_seconds` (number): Where the user is, in seconds
- `duration_seconds` (number): How long it is, in seconds
- `episode_id` (text): The episode's ID, for a podcast
- `episode_title` (text): The episode's title, for a podcast
- `finished_at` (text): When the user finished it (UTC)
- `is_finished` (true/false): Whether it's finished
- `item_id` (text): The book's or podcast's ID
- `last_update` (text): When the user last listened (UTC)
- `link` (text): A link to it in Audiobookshelf
- `progress_percent` (number): How much is listened to, from 0 to 100
- `started` (true/false): Whether the user has started it
- `started_at` (text): When the user started it (UTC)
- `title` (text): The book's or podcast's title

**Example output**

```json
{
  "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 (`series`, text, required): The series, by name or ID.

**Outputs**

- `added_at` (text): When it was added (UTC)
- `book_count` (number): How many of its books the library has
- `books` (list): Its books, in order
- `description` (text): About it
- `finished_count` (number): How many of its books the user finished
- `id` (text): The series' ID
- `is_finished` (true/false): Whether the user finished every book
- `library_id` (text): Its library's ID
- `link` (text): A link to it in Audiobookshelf
- `name` (text): Its name

**Example output**

```json
{
  "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 (`library`, text): The audiobook library, by name or ID. Leave blank when there's only one.
- Name contains (`name_contains`, text): Only authors whose name contains this.
- How many (`limit`, number): The most to list. Defaults to 50. From 1 to 500.

**Outputs**

- `authors` (list): The authors, by last name
- `count` (number): How many are listed
- `library_id` (text): The library's ID
- `total` (number): How many match in all

**Example output**

```json
{
  "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 (`library`, text): The library, by name or ID. Leave blank when there's only one.
- Author (`author`, text): Only this author's books. Give one filter at most.
- Series (`series`, text): Only this series' books, such as Harbor Tales. Give one filter at most.
- Genre (`genre`, text): Only items of this genre. Give one filter at most.
- Tag (`tag`, text): Only items with this tag. Give one filter at most.
- Narrator (`narrator`, text): Only books read by this narrator. Give one filter at most.
- Progress (`progress`, text): 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 (`sort`, text): 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 (`limit`, number): The most to list. Defaults to 50. From 1 to 500.
- Page (`page`, number): Which page of the list, from 1. Defaults to 1. From 1 to 10000.

**Outputs**

- `count` (number): How many are listed
- `has_more` (true/false): Whether there are more pages
- `items` (list): The books or podcasts
- `library_id` (text): The library's ID
- `library_name` (text): Its name
- `page` (number): The page listed, from 1
- `total` (number): How many match in all

**Example output**

```json
{
  "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 (`library`, text): Only this library's collections. Leave blank for all.

**Outputs**

- `collections` (list): The collections
- `count` (number): How many

**Example output**

```json
{
  "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 (`podcast`, text, required): The podcast, by its title or its ID in Audiobookshelf.
- Only unfinished (`only_unfinished`, true/false): Only episodes the user hasn't finished. Default: `false`.
- How many (`limit`, number): The most to list. Defaults to 50. From 1 to 500.

**Outputs**

- `count` (number): How many are listed
- `downloads_waiting` (number): How many episodes are waiting to download
- `episodes` (list): Its downloaded episodes, newest first
- `podcast_id` (text): The podcast's ID
- `podcast_title` (text): Its title
- `total` (number): How many match in all

**Example output**

```json
{
  "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 (`limit`, number): The most to list. Defaults to 25. From 1 to 500.

**Outputs**

- `count` (number): How many
- `items` (list): What the user is partway through, most recent first

**Example output**

```json
{
  "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**

- `count` (number): How many
- `libraries` (list): The libraries the API key's user can open

**Example output**

```json
{
  "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 (`limit`, number): The most to list. Defaults to 25. From 1 to 200.
- Page (`page`, number): Which page of the list, from 1. Defaults to 1. From 1 to 10000.

**Outputs**

- `count` (number): How many are listed
- `has_more` (true/false): Whether there are more pages
- `page` (number): The page listed, from 1
- `sessions` (list): The user's listening sessions, newest first
- `total` (number): How many there are in all

**Example output**

```json
{
  "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 (`library`, text): Only this library's playlists. Leave blank for all.

**Outputs**

- `count` (number): How many
- `playlists` (list): The API key's user's playlists

**Example output**

```json
{
  "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 (`library`, text): The audiobook library, by name or ID. Leave blank when there's only one.
- How many (`limit`, number): The most to list. Defaults to 50. From 1 to 500.
- Page (`page`, number): Which page of the list, from 1. Defaults to 1. From 1 to 10000.

**Outputs**

- `count` (number): How many are listed
- `has_more` (true/false): Whether there are more pages
- `library_id` (text): The library's ID
- `library_name` (text): Its name
- `page` (number): The page listed, from 1
- `series` (list): The series, by name
- `total` (number): How many match in all

**Example output**

```json
{
  "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**

- `count` (number): How many
- `users` (list): The users

**Example output**

```json
{
  "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 (`item`, text, required): The book or podcast, by its title or its ID in Audiobookshelf.
- Episode (`episode`, text): For a podcast, the episode, by title or ID. Leave blank for its newest; leave blank for a book.
- Finished (`finished`, true/false): On marks it finished; off marks it not finished. Default: `true`.

**Outputs**

- `author` (text): Its author
- `current_time_seconds` (number): Where the user is, in seconds
- `duration_seconds` (number): How long it is, in seconds
- `episode_id` (text): The episode's ID, for a podcast
- `episode_title` (text): The episode's title, for a podcast
- `finished_at` (text): When the user finished it (UTC)
- `is_finished` (true/false): Whether it's finished
- `item_id` (text): The book's or podcast's ID
- `last_update` (text): When the user last listened (UTC)
- `link` (text): A link to it in Audiobookshelf
- `progress_percent` (number): How much is listened to, from 0 to 100
- `started` (true/false): Whether the user has started it
- `started_at` (text): When the user started it (UTC)
- `title` (text): The book's or podcast's title

**Example output**

```json
{
  "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 (`item`, text, required): The book or podcast, by its title or its ID in Audiobookshelf.
- Look up at (`provider`, text): 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 (`title`, text): The title to search for. Leave blank for the item's own.
- Author (`author`, text): The author to search for. Leave blank for the item's own.
- ISBN (`isbn`, text): An ISBN to search for.
- ASIN (`asin`, text): An Audible ASIN to search for.
- Replace details (`override_details`, true/false): Replace details it already has with the ones found. Off fills in only what's missing. Default: `false`.
- Replace cover (`override_cover`, true/false): Replace the cover it already has with the one found. Default: `false`.

**Outputs**

- `added_at` (text): When it was added (UTC)
- `asin` (text): Its Audible ASIN (books)
- `author` (text): The same, separated by commas
- `authors` (list): Its authors (a podcast's author)
- `description` (text): What it's about
- `duration` (text): The same, such as 11 h 32 min
- `duration_seconds` (number): How long it is, in seconds (books)
- `episode_count` (number): How many episodes a podcast has downloaded
- `explicit` (true/false): Whether it's marked explicit
- `feed_url` (text): A podcast's RSS feed address
- `genres` (list): Its genres
- `id` (text): The book's or podcast's ID, for other Audiobookshelf steps
- `isbn` (text): Its ISBN (books)
- `language` (text): Its language
- `library_id` (text): Its library's ID
- `link` (text): A link to it in Audiobookshelf
- `matched` (true/false): Whether the provider found it
- `media_type` (text): book or podcast
- `message` (text): What happened, such as No google match found
- `missing` (true/false): Whether its files are missing
- `narrators` (list): Its narrators (books)
- `path` (text): Its folder on the Audiobookshelf server
- `provider` (text): Where it was looked up, such as google
- `published_year` (text): The year it was published (a podcast's release date)
- `publisher` (text): Its publisher (books)
- `series` (list): Its series, with the book's number, such as Harbor Tales #1
- `size` (number): Its files' size in bytes
- `subtitle` (text): Its subtitle (books)
- `tags` (list): Its tags
- `title` (text): Its title
- `updated` (true/false): Whether its details or cover changed
- `updated_at` (text): When it last changed (UTC)

**Example output**

```json
{
  "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 (`collection`, text, required): The collection, by name or ID.
- Books (`books`, text, required): One or more books, by title or ID, separated by commas.

**Outputs**

- `added` (list): The titles added
- `book_count` (number): How many books it holds
- `books` (list): Its books
- `created_at` (text): When it was made (UTC)
- `description` (text): Its description
- `id` (text): The collection's ID
- `library_id` (text): Its library's ID
- `link` (text): A link to it in Audiobookshelf
- `name` (text): Its name
- `removed` (list): The titles taken out

**Example output**

```json
{
  "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 (`playlist`, text, required): The playlist, by name or ID. Only the API key's user's own.
- Book or podcast (`item`, text, required): The book or podcast, by its title or its ID in Audiobookshelf.
- Episode (`episode`, text): For a podcast, the episode, by title or ID. Leave blank for its newest; leave blank for a book.

**Outputs**

- `changed_item` (object): The book or episode added or taken out
- `created_at` (text): When it was made (UTC)
- `deleted` (true/false): Whether Audiobookshelf deleted the playlist, as it does when its last item is taken out
- `description` (text): Its description
- `id` (text): The playlist's ID
- `item_count` (number): How many books or episodes it holds
- `items` (list): What it holds, in order
- `library_id` (text): Its library's ID
- `link` (text): A link to it in Audiobookshelf
- `name` (text): Its name

**Example output**

```json
{
  "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 (`library`, text): The library, by name or ID. Leave blank when there's only one.
- Wait for it (`wait`, true/false): Wait up to a minute for the scan to finish. Off only starts it. Default: `true`.

**Outputs**

- `finished` (true/false): Whether the scan finished while the step waited
- `item_count` (number): How many books or podcasts it has now
- `last_scan` (text): When the library was last scanned (UTC)
- `library_id` (text): The library's ID
- `library_name` (text): Its name
- `link` (text): A link to the library
- `status` (text): finished, or started when it was still running after a minute

**Example output**

```json
{
  "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 (`library`, text): The library to search, by name or ID. Leave blank when there's only one.
- Search for (`query`, text, required): The words to look for, such as a title or an author's name.
- How many (`limit`, number): The most of each kind to return. Defaults to 10. From 1 to 50.

**Outputs**

- `authors` (list): The authors found
- `count` (number): How many items, authors and series were found
- `genres` (list): The genres found
- `items` (list): The books or podcasts found
- `library_id` (text): The library's ID
- `narrators` (list): The narrators found
- `query` (text): What was looked for
- `series` (list): The series found
- `tags` (list): The tags found

**Example output**

```json
{
  "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 (`item`, text, required): The book or podcast, by its title or its ID in Audiobookshelf.
- Title (`title`, text): The new title.
- Subtitle (`subtitle`, text): A book's new subtitle.
- Authors (`authors`, text): The authors, replacing the ones it has; a podcast's author. Separate several with commas.
- Narrators (`narrators`, text): A book's narrators, replacing the ones it has. Separate several with commas.
- Series (`series`, text): A book's series, replacing the ones it has, each with its number after #, such as Harbor Tales #2. Separate several with commas.
- Genres (`genres`, text): The genres, replacing the ones it has. Separate several with commas.
- Tags (`tags`, text): The tags, replacing the ones it has. Separate several with commas.
- Add tags (`add_tags`, text): Tags to add, keeping the ones it has. Separate several with commas.
- Remove tags (`remove_tags`, text): Tags to take off. Separate several with commas.
- Description (`description`, text): The new description.
- Publisher (`publisher`, text): A book's publisher.
- Published year (`published_year`, text): The year a book was published, such as 2019.
- Language (`language`, text): Its language, such as English.
- ISBN (`isbn`, text): A book's ISBN.
- ASIN (`asin`, text): A book's Audible ASIN, such as B0036I54I6.

**Outputs**

- `added_at` (text): When it was added (UTC)
- `asin` (text): Its Audible ASIN (books)
- `author` (text): The same, separated by commas
- `authors` (list): Its authors (a podcast's author)
- `changed` (list): What changed: title, authors, series, genres, tags and so on
- `description` (text): What it's about
- `duration` (text): The same, such as 11 h 32 min
- `duration_seconds` (number): How long it is, in seconds (books)
- `episode_count` (number): How many episodes a podcast has downloaded
- `explicit` (true/false): Whether it's marked explicit
- `feed_url` (text): A podcast's RSS feed address
- `genres` (list): Its genres
- `id` (text): The book's or podcast's ID, for other Audiobookshelf steps
- `isbn` (text): Its ISBN (books)
- `language` (text): Its language
- `library_id` (text): Its library's ID
- `link` (text): A link to it in Audiobookshelf
- `media_type` (text): book or podcast
- `missing` (true/false): Whether its files are missing
- `narrators` (list): Its narrators (books)
- `path` (text): Its folder on the Audiobookshelf server
- `published_year` (text): The year it was published (a podcast's release date)
- `publisher` (text): Its publisher (books)
- `series` (list): Its series, with the book's number, such as Harbor Tales #1
- `size` (number): Its files' size in bytes
- `subtitle` (text): Its subtitle (books)
- `tags` (list): Its tags
- `title` (text): Its title
- `updated` (true/false): Whether anything changed
- `updated_at` (text): When it last changed (UTC)

**Example output**

```json
{
  "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"
}
```
