### Get All Backups Example Request
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_backups.md
Example shell command using curl to fetch all backups from the Audiobookshelf API.
```shell
curl "https://abs.example.com/api/backups" \
-H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"
```
--------------------------------
### Get All Backups Example Response
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_backups.md
Example JSON response structure for the 'Get All Backups' API endpoint.
```json
{
"backups": [
{
"id": "2022-11-25T0100",
"backupMetadataCovers": true,
"backupDirPath": "/metadata/backups",
"datePretty": "Fri, Nov 25 2022 01:00",
"fullPath": "/metadata/backups/2022-11-25T0100.audiobookshelf",
"path": "backups/2022-11-25T0100.audiobookshelf",
"filename": "2022-11-25T0100.audiobookshelf",
"fileSize": 39819077,
"createdAt": 1669366800272,
"serverVersion": "2.2.5"
}
]
}
```
--------------------------------
### Login Request Example
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_server.md
Example of how to log in to the Audiobookshelf server using a curl command.
```shell
curl -X POST "https://abs.example.com/login" \
-H "Content-Type: application/json" \
-d '{"username": "root", "password": "*****"}'
```
--------------------------------
### Create Library Request Example
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_libraries.md
Example cURL command to create a new library with specified folders, icon, media type, and provider.
```shell
curl -X POST "https://abs.example.com/api/libraries" \
-H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
-H "Content-Type: application/json" \
-d '{"name": "Podcasts", "folders": [{"fullPath": "/podcasts"}], "icon": "podcast", "mediaType": "podcast", "provider": "itunes"}'
```
--------------------------------
### Create Library Response Example
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_libraries.md
Example JSON response structure for a successfully created library.
```json
{
"id": "lib_c1u6t4p45c35rf0nzd",
"name": "Podcasts",
"folders": [
{
"id": "fol_bev1zuxhb0j0s1wehr",
"fullPath": "/podcasts",
"libraryId": "lib_c1u6t4p45c35rf0nzd",
"addedAt": 1650462940610
}
],
"displayOrder": 4,
"icon": "podcast",
"mediaType": "podcast",
"provider": "itunes",
"settings": {
"coverAspectRatio": 1,
"disableWatcher": false,
"skipMatchingMediaWithAsin": false,
"skipMatchingMediaWithIsbn": false,
"autoScanCronExpression": null
},
"createdAt": 1650462940610,
"lastUpdate": 1655423464567
}
```
--------------------------------
### Book Chapter JSON Example
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_schemas.md
An example JSON object representing a single book chapter, including its ID, start and end times within the audiobook, and its title.
```JSON
{
"id": 0,
"start": 0,
"end": 6004.6675,
"title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
}
```
--------------------------------
### Initiate OAuth2 Authorization Request (cURL)
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_server.md
Example cURL command to start the OAuth2 authorization flow. This request includes parameters for PKCE, redirect URI, client ID, response type, and state.
```shell
curl "https://abs.example.com/auth/openid?code_challenge=1234&code_challenge_method=S256&redirect_uri=audiobookshelf%3A%2F%2Foauth&client_id=Audiobookshelf-App&response_type=code&state=42"
```
--------------------------------
### Create Backup Example Response
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_backups.md
Example JSON response structure after creating a backup, showing the updated list of backups.
```json
{
"backups": [
{
"id": "2022-11-14T0130",
"backupMetadataCovers": true,
"backupDirPath": "/metadata/backups",
"datePretty": "Mon, Nov 14 2022 01:30",
"fullPath": "/metadata/backups/2022-11-14T0130.audiobookshelf",
"path": "backups/2022-11-14T0130.audiobookshelf",
"filename": "2022-11-14T0130.audiobookshelf",
"fileSize": 7776983,
"createdAt": 1668411000329,
"serverVersion": "2.2.4"
},
{
"id": "2022-11-15T0105",
"backupMetadataCovers": true,
"backupDirPath": "/metadata/backups",
"datePretty": "Tue, Nov 15 2022 01:05",
"fullPath": "/metadata/backups/2022-11-15T0105.audiobookshelf",
"path": "backups/2022-11-15T0105.audiobookshelf",
"filename": "2022-11-15T0105.audiobookshelf",
"fileSize": 7777148,
"createdAt": 1668495954701,
"serverVersion": "2.2.4"
}
]
}
```
--------------------------------
### Create Backup Example Request
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_backups.md
Example shell command using curl to trigger the creation of a new backup via the Audiobookshelf API.
```shell
curl -X POST "https://abs.example.com/api/backups" \
-H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"
```
--------------------------------
### Apply Backup Example Request
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_backups.md
Example shell command using curl to apply a specific backup identified by its ID to the Audiobookshelf server.
```shell
curl "https://abs.example.com/api/backups/2022-11-15T0105/apply" \
-H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"
```
--------------------------------
### Search Podcast Example (Shell)
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_search.md
An example using curl to search for a podcast. It demonstrates how to make the request with an authorization header.
```shell
curl "https://abs.example.com/api/search/podcast?term=Welcome%20To%20Night%20Vale" \
-H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"
```
--------------------------------
### Get User Listening Sessions (cURL)
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_users.md
Example command to fetch a user's listening sessions using cURL, including authorization header and pagination parameter.
```shell
curl "https://abs.example.com/api/users/root/listening-sessions?itemsPerPage=1" \
-H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"
```
--------------------------------
### Redirect URL Example
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_server.md
Example of the redirect URI that the SSO provider will open in the user's browser after successful authentication. It includes the authorization code and the state parameter.
```txt
redirect_uri?code=42&state=2000
```
--------------------------------
### Get Library Playlists (Shell)
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_libraries.md
Example using curl to fetch user playlists for a specific library. It requires an Authorization header with a Bearer token.
```shell
curl "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/playlists" \
-H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"
```
--------------------------------
### Search Podcast Response Example (JSON)
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_search.md
An example of the JSON response structure returned by the podcast search API endpoint.
```json
[
{
"id": 536258179,
"artistId": 718704794,
"title": "Welcome to Night Vale",
"artistName": "Night Vale Presents",
"description": "",
"descriptionPlain": "",
"releaseDate": "2022-11-15T05:00:00Z",
"genres": [
"Science Fiction",
"Podcasts",
"Fiction"
],
"cover": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
"trackCount": 280,
"feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
"pageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
"explicit": false
},
...
]
```
--------------------------------
### Audio File Metadata Example
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_playlists.md
An example JSON structure representing metadata for an audio file within the Audiobookshelf system, including path, size, and timestamps.
```json
{
"ino": "649644248522215261",
"metadata": {
"filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
"ext": ".mp3",
"path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
"relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
"size": 48037888,
"mtimeMs": 1632223180278,
"ctimeMs": 1645978261001,
"birthtimeMs": 0
},
"addedAt": 1650621052494,
"updatedAt": 1650621052494,
"fileType": "audio"
}
```
--------------------------------
### File Metadata Example
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_items.md
Example JSON structure representing file metadata, including path, size, and timestamps.
```json
{
"filename": "cover.jpg",
"ext": ".jpg",
"path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
"relPath": "cover.jpg",
"size": 325531,
"mtimeMs": 1638754803540,
"ctimeMs": 1645978261003,
"birthtimeMs": 0
}
```
--------------------------------
### Batch Update Library Items (Response Example)
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_items.md
Example JSON response structure for a successful batch update operation on library items.
```json
{
"success": true,
"updates": 1
}
```
--------------------------------
### Logout Request Example
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_server.md
Example of how to log out from the Audiobookshelf server using a curl command, including an authorization token.
```shell
curl -X POST "https://abs.example.com/logout" \
-H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
-H "Content-Type: application/json" \
-d '{"socketId": "AFcTcb7xBLsSPnIzAAAV"}'
```
--------------------------------
### Book Metadata JSON Examples
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_schemas.md
Examples of book metadata represented in JSON format. Includes a standard structure, a minified version, and an expanded version with additional fields.
```json
{
"title": "Wizards First Rule",
"subtitle": null,
"authors": [...],
"narrators": [
"Sam Tsoutsouvas"
],
"series": [...],
"genres": [
"Fantasy"
],
"publishedYear": "2008",
"publishedDate": null,
"publisher": "Brilliance Audio",
"description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
"isbn": null,
"asin": "B002V0QK4C",
"language": null,
"explicit": false
}
```
```json
{
"title": "Wizards First Rule",
"titleIgnorePrefix": "Wizards First Rule",
"subtitle": null,
"authorName": "Terry Goodkind",
"authorNameLF": "Goodkind, Terry",
"narratorName": "Sam Tsoutsouvas",
"seriesName": "Sword of Truth",
"genres": [
"Fantasy"
],
"publishedYear": "2008",
"publishedDate": null,
"publisher": "Brilliance Audio",
"description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
"isbn": null,
"asin": "B002V0QK4C",
"language": null,
"explicit": false
}
```
```json
{
"title": "Wizards First Rule",
"titleIgnorePrefix": "Wizards First Rule",
"subtitle": null,
"authors": [...],
"narrators": [
"Sam Tsoutsouvas"
],
"series": [...],
"genres": [
"Fantasy"
],
"publishedYear": "2008",
"publishedDate": null,
"publisher": "Brilliance Audio",
"description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
"isbn": null,
"asin": "B002V0QK4C",
"language": null,
"explicit": false,
"authorName": "Terry Goodkind",
"authorNameLF": "Goodkind, Terry",
"narratorName": "Sam Tsoutsouvas",
"seriesName": "Sword of Truth"
}
```
--------------------------------
### Delete Backup Example Response
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_backups.md
Example JSON response structure after deleting a backup, showing the remaining backups.
```json
{
"backups": [
{
"id": "2022-11-15T0105",
"backupMetadataCovers": true,
"backupDirPath": "/metadata/backups",
"datePretty": "Tue, Nov 15 2022 01:05",
"fullPath": "/metadata/backups/2022-11-15T0105.audiobookshelf",
"path": "backups/2022-11-15T0105.audiobookshelf",
"filename": "2022-11-15T0105.audiobookshelf",
"fileSize": 7777148,
"createdAt": 1668495954701,
"serverVersion": "2.2.4"
}
]
}
```
--------------------------------
### Get Notification Settings Response (JSON)
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_notifications.md
Example JSON structure returned by the GET /api/notifications endpoint, detailing notification events and server settings. Includes event names, variables, defaults, test data, and configured notification settings.
```json
{
"data": {
"events": [
{
"name": "onPodcastEpisodeDownloaded",
"requiresLibrary": true,
"libraryMediaType": "podcast",
"description": "Triggered when a podcast episode is auto-downloaded",
"variables": [
"libraryItemId",
"libraryId",
"libraryName",
"mediaTags",
"podcastTitle",
"podcastAuthor",
"podcastDescription",
"podcastGenres",
"episodeId",
"episodeTitle",
"episodeSubtitle",
"episodeDescription"
],
"defaults": {
"title": "New {{podcastTitle}} Episode!",
"body": "{{episodeTitle}} has been added to {{libraryName}} library."
},
"testData": {
"libraryItemId": "li_notification_test",
"libraryId": "lib_test",
"libraryName": "Podcasts",
"podcastTitle": "Abs Test Podcast",
"episodeId": "ep_notification_test",
"episodeTitle": "Successful Test"
}
},
{
"name": "onTest",
"requiresLibrary": false,
"description": "Event for testing the notification system",
"variables": [
"version"
],
"defaults": {
"title": "Test Notification on Abs {{version}}",
"body": "Test notificataion body for abs {{version}}."
},
"testData": {
"version": "v2.2.5"
}
}
]
},
"settings": {
"id": "notification-settings",
"appriseType": "api",
"appriseApiUrl": "https://apprise.example.com/notify",
"notifications": [
{
"id": "noti_nod281qwkj5ow7h7fi",
"libraryId": null,
"eventName": "onPodcastEpisodeDownloaded",
"urls": [
"apprises://apprise.example.com/email"
],
"titleTemplate": "New {{podcastTitle}} Episode!",
"bodyTemplate": "{{episodeTitle}} has been added to {{libraryName}} library.",
"enabled": true,
"type": "info",
"lastFiredAt": 1668776410792,
"lastAttemptFailed": false,
"numConsecutiveFailedAttempts": 0,
"numTimesFired": 5,
"createdAt": 1666545142424
}
],
"maxFailedAttempts": 5,
"maxNotificationQueue": 20,
"notificationDelay": 1000
}
}
```
--------------------------------
### Get Listening Stats (Shell)
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_me.md
Example using curl to fetch listening statistics from the Audiobookshelf API. Requires an Authorization header.
```shell
curl "https://abs.example.com/api/me/listening-stats" \
-H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"
```
--------------------------------
### Get Library Items In Progress
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_me.md
Retrieves library items that are currently in progress (started but not finished). Supports optional limiting of results.
```APIDOC
GET http://abs.example.com/api/me/items-in-progress
Optional Query Parameters:
Parameter | Type | Default | Description
--------- | ---- | ------- |
`limit` | Integer | `25` | A limit for how many library items to return.
Response Schema:
Attribute | Type | Description
--------- | ---- | -----------
`libraryItems` | Array of [Library Item Minified](#library-item-minified) | The in progress library items. They have extra attributes which are described below.
Extra Attributes:
Attribute | Type | Description
--------- | ---- | -----------
`recentEpisode` | [Podcast Episode](#podcast-episode) Object | If the library item is for a podcast, the media progress's corresponding podcast episode. Will not exist for book library items.
`progressLastUpdate` | Integer | The time (in ms since POSIX epoch) when the corresponding media progress was last updated.
```
--------------------------------
### Podcast Feed Response Structure
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_podcasts.md
Example JSON output from the Get Podcast Feed API endpoint, detailing the structure of podcast metadata and episodes.
```json
{
"podcast": {
"metadata": {
"image": "https://f.prxu.org/126/images/1f749c5d-c83a-4db9-8112-a3245da49c54/nightvalelogo-web4.jpg",
"categories": [
"Fiction:Science Fiction"
],
"feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
"description": "\n Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.
\n ",
"descriptionPlain": "\n Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n ",
"title": "Welcome to Night Vale",
"language": "en",
"explicit": "false",
"author": "Night Vale Presents",
"pubDate": "Thu, 17 Nov 2022 16:04:42 -0000",
"link": "http://welcometonightvale.com"
},
"episodes": [
{
"title": "1 - Pilot",
"subtitle": "Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting. Weather: \"These and More Than These\" by Joseph Fink Music:...",
"description": "\n Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting.
\n\nWeather: \"These and More Than These\" by Joseph Fink
\n\nMusic: Disparition, disparition.info
\n\nLogo: Rob Wilson, silastom.com
\n\nProduced by\u00a0Night Vale Presents. Written by Joseph Fink and Jeffrey Cranor. Narrated by Cecil Baldwin. More\u00a0Info: welcometonightvale.com, and follow @NightValeRadio on Twitter or Facebook.
\n ",
"descriptionPlain": "\n Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting.\n\nWeather: \"These and More Than These\" by Joseph Fink\n\nMusic: Disparition, disparition.info\n\nLogo: Rob Wilson, silastom.com\n\nProduced by\u00a0Night Vale Presents. Written by Joseph Fink and Jeffrey Cranor. Narrated by Cecil Baldwin. More\u00a0Info: welcometonightvale.com, and follow @NightValeRadio on Twitter or Facebook.\n ",
"pubDate": "Fri, 15 Jun 2012 12:00:00 -0000",
"episodeType": "full",
"season": "",
"episode": "",
"author": "",
"duration": "21:02",
"explicit": "",
"publishedAt": 1339761600000,
"enclosure": {
"url": "https://www.podtrac.com/pts/redirect.mp3/dovetail.prxu.org/_/126/1fadf1ad-aad8-449f-843b-6e8bb6949622/1_Pilot.mp3",
"type": "audio/mpeg",
"length": "20588611"
}
}
]
}
}
```
--------------------------------
### Get Podcast Episode Request (Shell)
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_podcasts.md
Example using curl to fetch a specific podcast episode from the Audiobookshelf API. It includes the necessary authorization header.
```shell
curl "https://abs.example.com/api/podcasts/li_bufnnmp4y5o2gbbxfm/episode/ep_lh6ko39pumnrma3dhv" \
-H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"
```
--------------------------------
### Initialize Server Endpoint
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_server.md
Initializes the server by creating a root user. This is a mandatory step for new servers lacking a root user.
```shell
curl -X POST "https://abs.example.com/init" \
-H "Content-Type: application/json" \
-d '{"newRoot": {"username": "root", "password": "*****"}}'
```
```APIDOC
Endpoint: /init
Method: POST
Description:
Initializes the server by creating a root user. This endpoint must be called on new servers before any other operations that require authentication.
Parameters:
- newRoot (Object, Required): An object containing the new root user's credentials.
- username (String): The username for the new root user.
- password (String): The password for the new root user (can be empty).
Response Status Codes:
- 200 OK: Server successfully initialized.
- 500 Internal Server Error: The server has already been initialized.
```
--------------------------------
### Get Library Collections Response (JSON)
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_libraries.md
Example JSON structure for a successful response when retrieving a library's collections. It includes details about each collection and its associated books.
```json
{
"results": [
{
"id": "col_fpfstanv6gd7tq2qz7",
"libraryId": "lib_c1u6t4p45c35rf0nzd",
"userId": "root",
"name": "Favorites",
"description": null,
"books": [
{
"id": "li_8gch9ve09orgn4fdz8",
"ino": "649641337522215266",
"libraryId": "main",
"folderId": "audiobooks",
"path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
"relPath": "Terry Goodkind/Sword of Truth/Wizards First Rule",
"isFile": false,
"mtimeMs": 1650621074299,
"ctimeMs": 1650621074299,
"birthtimeMs": 0,
"addedAt": 1650621073750,
"updatedAt": 1650621110769,
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"metadata": {
"title": "Wizards First Rule",
"titleIgnorePrefix": "Wizards First Rule",
"subtitle": null,
"authorName": "Terry Goodkind",
"narratorName": "Sam Tsoutsouvas",
"seriesName": "Sword of Truth",
"genres": ["Fantasy"],
"publishedYear": "2008",
"publishedDate": null,
"publisher": "Brilliance Audio",
"description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
"isbn": null,
"asin": "B002V0QK4C",
"language": null,
"explicit": false
},
"coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
"tags": [],
"numTracks": 2,
"numAudioFiles": 2,
"numChapters": 2,
"duration": 12000.946,
"size": 96010240,
"ebookFileFormat": null
},
"numFiles": 3,
"size": 96335771
}
],
"lastUpdate": 1650621110769,
"createdAt": 1650621073750
}
],
"total": 1,
"limit": 0,
"page": 0,
"sortDesc": false,
"minified": true,
"include": ""
}
```
--------------------------------
### Create Podcast via API (Shell)
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_podcasts.md
Example using curl to create a new podcast entry via the Audiobookshelf API. It includes authorization headers, content type, and a JSON payload with podcast metadata.
```shell
curl -X POST "https://abs.example.com/api/podcasts" \
-H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
-H "Content-Type: application/json" \
-d $'{"libraryId": "lib_p9wkw2i85qy9oltijt", "folderId": "fol_crxarzs17jtw5k7ie9", "path": "/podcasts/Welcome to Night Vale", "media": {"metadata": {"title": "Welcome to Night Vale", "author": "Night Vale Presents", "description": "\n Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It\'s an ongoing radio show. Start with the current episode, and you\'ll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n ", "releaseDate": "2022-10-20T19:00:00Z", "genres": ["Science Fiction", "Podcasts", "Fiction"], "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast", "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg", "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4", "itunesId": 536258179, "itunesArtistId": 718704794, "explicit": false, "language": null}}}'
```
--------------------------------
### Server Settings API Reference
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_schemas.md
Detailed reference for all configurable server settings. Each attribute is described with its data type, purpose, and any specific constraints or options available.
```APIDOC
Server Settings:
This section details the various server settings that can be configured.
Attributes:
id (String): The ID of the server settings.
scannerFindCovers (Boolean): Whether the scanner will attempt to find a cover if your audiobook does not have an embedded cover or a cover image inside the folder. Note: This will extend scan time.
scannerCoverProvider (String): If `scannerFindCovers` is `true`, which metadata provider to use. See [Metadata Providers](#metadata-providers) for options.
scannerParseSubtitle (Boolean): Whether to extract subtitles from audiobook folder names. Subtitles must be separated by ` - `, i.e. `/audiobooks/Book Title - A Subtitle Here/` has the subtitle `A Subtitle Here`.
scannerPreferMatchedMetadata (Boolean): Whether matched data will override item details when using Quick Match. By default, Quick Match will only fill in missing details.
scannerDisableWatcher (Boolean): Whether to disable the automatic adding/updating of items when file changes are detected. *Requires server restart* for changes to take effect.
storeCoverWithItem (Boolean): Whether to store covers in the library item's folder. By default, covers are stored in `/metadata/items`. Only one file named `cover` will be kept.
storeMetadataWithItem (Boolean): Whether to store metadata files in the library item's folder. By default, metadata files are stored in `/metadata/items`. Uses the `.abs` file extension.
metadataFileFormat (String): Must be either `json` or `abs`.
rateLimitLoginRequests (Integer): The maximum number of login requests per `rateLimitLoginWindow`.
rateLimitLoginWindow (Integer): The length (in ms) of each login rate limit window.
backupSchedule (String): The [cron expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) for when to do automatic backups.
backupsToKeep (Integer): The number of backups to keep.
maxBackupSize (Integer): The maximum backup size (in GB) before they fail, a safeguard against misconfiguration.
loggerDailyLogsToKeep (Integer): The number of daily logs to keep.
loggerScannerLogsToKeep (Integer): The number of scanner logs to keep.
homeBookshelfView (Binary): Whether the home page should use a skeuomorphic design with wooden shelves.
bookshelfView (Binary): Whether other bookshelf pages should use a skeuomorphic design with wooden shelves.
sortingIgnorePrefix (Boolean): Whether to ignore prefixes when sorting. For example, for the prefix `the`, the book title `The Book Title` would sort as `Book Title, The`.
sortingPrefixes (Array of String): If `sortingIgnorePrefix` is `true`, what prefixes to ignore.
chromecastEnabled (Boolean): Whether to enable streaming to Chromecast devices.
dateFormat (String): What date format to use. Options are `MM/dd/yyyy`, `dd/MM/yyyy`, `dd.MM.yyyy`, `yyyy-MM-dd`, `MMM do, yyyy`, `MMMM do, yyyy`, `dd MMM yyyy`, or `dd MMMM yyyy`.
timeFormat (String): What time format to use. Options are `HH:mm` (24-hour) and `h:mma` (am/pm).
language (String): The default server language.
logLevel (Integer): What log level the server should use when logging. `1` for debug, `2` for info, or `3` for warnings.
version (String): The server's version.
```
--------------------------------
### Get User Listening Stats (Shell)
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_users.md
Example using curl to retrieve a user's listening statistics from the Audiobookshelf API. Requires authentication via a Bearer token.
```shell
curl "https://abs.example.com/api/users/root/listening-stats" \
-H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"
```
--------------------------------
### Get Library Authors API
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_libraries.md
Retrieves a list of authors associated with a specific library. Includes example `curl` command, JSON response structure, and detailed API endpoint information.
```shell
curl "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/authors" \
-H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"
```
```json
{
"authors": [
{
"id": "aut_z3leimgybl7uf3y4ab",
"asin": null,
"name": "Terry Goodkind",
"description": null,
"imagePath": null,
"addedAt": 1650621073750,
"updatedAt": 1650621073750,
"numBooks": 1
}
]
}
```
```APIDOC
GET https://abs.example.com/api/libraries//authors
URL Parameters:
ID: The ID of the library.
Response:
200 OK: Success. Schema: Array of [Author Expanded](#author-expanded)
404 Not Found: The user cannot access the library, or no library with the provided ID exists.
Author Expanded Schema:
id: String - The ID of the author.
name: String - The title of the author.
count: Integer - The number of books by the author in the library.
```
--------------------------------
### Batch Get Library Items Response (JSON)
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_items.md
Example JSON structure returned by the /api/items/batch/get endpoint. It details the retrieved library items, including their metadata, file paths, and audio file information.
```json
{
"libraryItems": [
{
"id": "li_8gch9ve09orgn4fdz8",
"ino": "649641337522215266",
"libraryId": "lib_c1u6t4p45c35rf0nzd",
"folderId": "fol_bev1zuxhb0j0s1wehr",
"path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
"relPath": "Terry Goodkind/Sword of Truth/Wizards First Rule",
"isFile": false,
"mtimeMs": 1650621074299,
"ctimeMs": 1650621074299,
"birthtimeMs": 0,
"addedAt": 1650621073750,
"updatedAt": 1650621110769,
"lastScan": 1651830827825,
"scanVersion": "2.0.21",
"isMissing": false,
"isInvalid": false,
"mediaType": "book",
"media": {
"libraryItemId": "li_8gch9ve09orgn4fdz8",
"metadata": {
"title": "Wizards First Rule",
"titleIgnorePrefix": "Wizards First Rule",
"subtitle": null,
"authors": [
{
"id": "aut_z3leimgybl7uf3y4ab",
"name": "Terry Goodkind"
}
],
"narrators": [
"Sam Tsoutsouvas"
],
"series": [
{
"id": "ser_cabkj4jeu8be3rap4g",
"name": "Sword of Truth",
"sequence": "1"
}
],
"genres": [
"Fantasy"
],
"publishedYear": "2008",
"publishedDate": null,
"publisher": "Brilliance Audio",
"description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
"isbn": null,
"asin": "B002V0QK4C",
"language": null,
"explicit": false,
"authorName": "Terry Goodkind",
"authorNameLF": "Goodkind, Terry",
"narratorName": "Sam Tsoutsouvas",
"seriesName": "Sword of Truth"
},
"coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
"tags": [
"Favorite"
],
"audioFiles": [
{
"index": 1,
"ino": "649644248522215260",
"metadata": {
"filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
"ext": ".mp3",
"path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
"relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
"size": 48037888,
"mtimeMs": 1632223180278,
"ctimeMs": 1645978261001,
"birthtimeMs": 0
},
"addedAt": 1650621074131,
"updatedAt": 1651830828023,
"trackNumFromMeta": 1,
"discNumFromMeta": null,
"trackNumFromFilename": 1,
"discNumFromFilename": null,
"manuallyVerified": false,
"exclude": false,
"error": null,
"format": "MP2/3 (MPEG audio layer 2/3)",
"duration": 6004.6675,
"bitRate": 64000,
"language": null,
"codec": "mp3",
"timeBase": "1/14112000",
"channels": 2,
"channelLayout": "stereo",
"chapters": [],
"embeddedCoverArt": null,
"metaTags": {
"tagAlbum": "SOT Bk01",
"tagArtist": "Terry Goodkind",
"tagGenre": "Audiobook Fantasy",
"tagTitle": "Wizards First Rule 01",
"tagTrack": "01/20",
"tagAlbumArtist": "Terry Goodkind"
}
}
]
}
}
]
}
```
--------------------------------
### Example API Response for Purge Media Progress
Source: https://github.com/audiobookshelf/audiobookshelf-api-docs/blob/main/source/includes/_users.md
An example JSON payload representing a successful response from the purge media progress endpoint, showing user details and media progress status.
```json
{
"id": "root",
"username": "root",
"type": "root",
"token": "exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY",
"mediaProgress": [],
"seriesHideFromContinueListening": [],
"bookmarks": [],
"isActive": true,
"isLocked": false,
"lastSeen": 1667687240810,
"createdAt": 1666569607117,
"permissions": {
"download": true,
"update": true,
"delete": true,
"upload": true,
"accessAllLibraries": true,
"accessAllTags": true,
"accessExplicitContent": true
},
"librariesAccessible": [],
"itemTagsAccessible": []
}
```