NAV
shell

Introduction

Audiobookshelf API and this documentation is a work in progress.

Contributions to this documentation are welcome! View API docs GitHub repo

Authentication

Audiobookshelf uses a users API token as a Bearer token for requests. For GET requests the API token can optionally be passed in as a query string.

You can find your API token by logging into the Audiobookshelf web app as an admin, go to the config → users page, and click on your account.

You may also get the API token programmatically using the Login endpoint. The API token will be in the response at response.user.token.

API request header for authentication would look like this:

Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY

Optionally GET requests can use the API token like this:

https://abs.example.com/api/items/li_asdfalwkerioa?token=exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY

Server

Login

curl -X POST "https://abs.example.com/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "root", "password": "*****"}'

The above command returns JSON structured like this:

{
  "user": {
    "id": "root",
    "username": "root",
    "type": "root",
    "token": "exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY",
    "mediaProgress": [
      {
        "id": "li_bufnnmp4y5o2gbbxfm-ep_lh6ko39pumnrma3dhv",
        "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
        "episodeId": "ep_lh6ko39pumnrma3dhv",
        "duration": 1454.18449,
        "progress": 0.434998929881311,
        "currentTime": 632.568697,
        "isFinished": false,
        "hideFromContinueListening": false,
        "lastUpdate": 1668586015691,
        "startedAt": 1668120083771,
        "finishedAt": null
      }
    ],
    "seriesHideFromContinueListening": [],
    "bookmarks": [],
    "isActive": true,
    "isLocked": false,
    "lastSeen": 1669010786013,
    "createdAt": 1666543632566,
    "permissions": {
      "download": true,
      "update": true,
      "delete": true,
      "upload": true,
      "accessAllLibraries": true,
      "accessAllTags": true,
      "accessExplicitContent": true
    },
    "librariesAccessible": [],
    "itemTagsAccessible": []
  },
  "userDefaultLibraryId": "lib_c1u6t4p45c35rf0nzd",
  "serverSettings": {
    "id": "server-settings",
    "scannerFindCovers": false,
    "scannerCoverProvider": "audible",
    "scannerParseSubtitle": false,
    "scannerPreferMatchedMetadata": false,
    "scannerDisableWatcher": true,
    "storeCoverWithItem": false,
    "storeMetadataWithItem": false,
    "metadataFileFormat": "json",
    "rateLimitLoginRequests": 10,
    "rateLimitLoginWindow": 600000,
    "backupSchedule": "30 1 * * *",
    "backupsToKeep": 2,
    "maxBackupSize": 1,
    "loggerDailyLogsToKeep": 7,
    "loggerScannerLogsToKeep": 2,
    "homeBookshelfView": 1,
    "bookshelfView": 1,
    "sortingIgnorePrefix": false,
    "sortingPrefixes": [
      "the",
      "a"
    ],
    "chromecastEnabled": false,
    "dateFormat": "MM/dd/yyyy",
    "language": "en-us",
    "logLevel": 2,
    "version": "2.2.5"
  },
  "Source": "docker"
}

This endpoint logs in a client to the server, returning information about the user and server. The /api/authorize (Get Authorized User and Server Information) endpoint is also available if an API token was persisted.

HTTP Request

POST http://abs.example.com/login

Parameters

Parameter Type Description
username String The username to log in with.
password String The password of the user.

Response

Status Meaning Description Schema
200 OK Success See Below
401 Unauthorized Invalid username or password. Error Message

Response Schema

Attribute Type Description
user User Object The authenticated user.
userDefaultLibraryId String The ID of the first library in the list the user has access to.
serverSettings Server Settings Object The server's settings.
Source String The server's installation source.

Logout

curl -X POST "https://abs.example.com/logout" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"socketId": "AFcTcb7xBLsSPnIzAAAV"}'

This endpoint logs out a client from the server. If the socketId parameter is provided, the server removes the socket from the client list. When using a socket connection this allows a client to change the user without needing to re-create the socket connection.

HTTP Request

POST http://abs.example.com/logout

Optional Parameters

Parameter Type Description
socketId String The ID of the connected socket.

Response

Status Meaning Description
200 OK Success

OAuth2 Authorization Request

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"

Response header (depending on SSO provider)

Location: https://auth.example.com/application/o/authorize/?client_id=G9DbJqJ&scope=openid%20profile%20email&response_type=code&redirect_uri=https%3A%2F%2Fabs.example.com%2Fauth%2Fopenid%2Fmobile-redirect&state=2000&code_challenge=C424242&code_challenge_method=S256

This endpoint starts a standard OAuth2 flow with PKCE (required - S256; see RFC7636), to log the user in using SSO.

For the code_challenge, you must randomly generate a minimum 32-byte string called verifier (PKCE challenge). With the verifier, you can then generate the challenge. See the examples on the right side.

Code Challenge Pseudo-Code

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

Code Challenge plain Javascript Code (all used functions are available in NodeJS and Browsers)

function base64URLEncode(arrayBuffer) {
  let base64String = btoa(String.fromCharCode.apply(null, new Uint8Array(arrayBuffer)))
  return base64String.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '')
}

async function sha256(plain) {
  const encoder = new TextEncoder()
  const data = encoder.encode(plain)
  return await window.crypto.subtle.digest('SHA-256', data)
}

function generateRandomString() {
  var array = new Uint32Array(42)
  window.crypto.getRandomValues(array)
  return Array.from(array, (dec) => ('0' + dec.toString(16)).slice(-2)).join('') // return as hex
}

const verifier = generateRandomString()
const challenge = base64URLEncode(await sha256(verifier))

On a valid request, it will return a 302-redirect (usually with a Location: header), which will point to the ABS-configured OAuth2 Provider. You would usually have to open this redirect-URL in a Browser to present to the user. Note that inside the redirect URL, among other parameters, there is a state parameter; save it for below.

Note that you will have to preserve the cookies you receive in this call for using it in /auth/openid/callback (check if you need to set a parameter for the HTTP library you are using for that).

When the user has logged in (successfully) inside the Browser, the Browser will redirect to the URL redirect_uri which should be a URL your website or app can open (like a universal app link). The call to the redirect_uri will include state and code GET parameters. Check if the state parameter is the same as above and use the code for the call to /auth/openid/callback.

Redirect URL which is opened in the user's browser by the SSO Provider

redirect_uri?code=42&state=2000

HTTP Request

GET http://abs.example.com/auth/openid

Query Parameters

Parameter Type Default Description
code_challenge String Required PKCE code_challenge you generated from verifier
code_challenge_method String S256 Must be S256
response_type String code Only code is supported
redirect_uri String Required URL where to redirect after a successful login. Must be whitelisted in ABS
client_id String Required The name of your app (currently not used, but might be required at some point)

Other parameters are ignored.

Response

Status Meaning Description
302 REDIRECT Success, save the state-parameter and follow the redirect
400 Bad Request You submitted an invalid parameter
500 Internal Server Error Error in the flow

OAuth2 Callback

curl "https://abs.example.com/auth/openid/callback?state=2000&code=42&code_verifier=1234"

The above command returns a JSON structured like this:

{
   "userDefaultLibraryId":"b2bab335-d9aa-4141-8394-fd98767504d7",
   "serverSettings":{
      "scannerFindCovers":false,
      "metadataFileFormat":"json",
      "backupSchedule":false,
      "authOpenIDJwksURL":"https://auth.example.com/application/o/audiobookshelf/jwks/",
      "authOpenIDAutoLaunch":true,
      "…"
   },
   "Source":"docker",
   "user":{
      "oldUserId":"usr_1234lasdnlk",
      "itemTagsSelected":[],
      "createdAt":1672769098296,
      "librariesAccessible":[  ],
      "mediaProgress":[],
      "oldUserId":"usr_1234lasdnlk",
      "permissions":{
         "accessExplicitContent":true,
         "delete":true,
         "download":true,
         "upload":true,
         "accessAllLibraries":true,
         "…"
      },
      "seriesHideFromContinueListening":[],
      "token":"eyJhbGciOiJIUzI1NiIsInASDLKAMSDklmad.ASLDKlkma.PNKNASDPNdnknsdfoP",
      "type":"admin",
      "username":"example"
   },
   "ereaderDevices":[]
}

This API call finalizes the OAuth2 flow. The behavior of this call depends on whether a redirect_uri was provided in the /auth/openid request:

It's important to note that the call to /auth/openid/callback is stateful. This means that the cookies set during the /auth/openid call must be sent along with this request.

Query Parameters

Parameter Type Default Description
state String Required The state string you received when redirect_uri was called
code String Required The code you received when redirect_uri was called
code_verifier String Required This is the verifier you generated when providing the code_challenge in the first request

Other parameters are ignored.

Response

Status Meaning Description
200 OK Success, user data in payload
302 FOUND Success, redirect to /login (internal use)
400 Bad Request You have no session
401 Unauthorized Error from the SSO provider
500 Internal Server Error Error in the flow

Error details are provided in the response body and in ABS logs.

OAuth2 Mobile Redirect

curl "https://abs.example.com/auth/openid/mobile-redirect"

This is an internal endpoint, which should not be called directly by an application. It is intended purely for the redirection of SSO providers.

When you provide a redirect_uri in /auth/openid, ABS performs an important operation: it saves your redirect_uri and instructs the SSO provider to use /auth/openid/mobile-redirect instead. This endpoint, in turn, redirects to your original redirect_uri.

This mechanism allows ABS to provide a https callback URL, which is particularly useful for mobile apps.

This call does not require a cookie or session. It matches the redirect_uri using the state parameter.

HTTP Request

GET http://abs.example.com/auth/openid/mobile-redirect

Query Parameters

Parameter Type Default Description
code String Required OAuth2 state
state String Required OAuth2 code

Other parameters are ignored.

Response

Status Meaning Description
302 REDIRECT Success
400 Bad Request No state or no redirect_uri associated to state
500 Internal Server Error Error in the flow

Initialize the Server

curl -X POST "https://abs.example.com/init" \
  -H "Content-Type: application/json" \
  -d '{"newRoot": {"username": "root", "password": "*****"}}'

This endpoint initializes a server for use with a root user. This is required for new servers without a root user yet.

HTTP Request

POST http://abs.example.com/init

Parameters

Parameter Type Description
newRoot New Root User Object (See Below) The new root user.

New Root User Parameters

Parameter Type Description
username String The username of the new root user.
password String The password of the new root user, may be empty.

Response

Status Meaning Description
200 OK Success
500 Internal Server Error The server has already been initialized.

Check the Server's Status

curl "https://abs.example.com/status"

The above command returns JSON structured like this:

{
  "isInit": true,
  "language": "en-us"
}

This endpoint reports the server's initialization status.

HTTP Request

GET http://abs.example.com/status

Response

Status Meaning Description Schema
200 OK Success See Below

Response Schema

Attribute Type Description
isInit Boolean Whether the server has been initialized.
language String The server's default language.
ConfigPath String The server's config path. Will only exist if isInit is false.
MetadataPath String The server's metadata path. Will only exist if isInit is false.

Ping the Server

curl "https://abs.example.com/ping"

The above command returns JSON structured like this:

{
  "success": true
}

This endpoint is a simple check to see if the server is operating and responding with JSON correctly.

HTTP Request

GET http://abs.example.com/ping

Response

Status Meaning Description Schema
200 OK Success See Below

Response Schema

Attribute Type Description
success Boolean Will always be true.

Healthcheck

curl "https://abs.example.com/healthcheck"

This endpoint is a simple check to see if the server is operating and can respond.

HTTP Request

GET http://abs.example.com/healthcheck

Response

Status Meaning Description
200 OK Success

Libraries

Create a Library

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"}'

The above command returns JSON structured like this:

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

This endpoint creates a library with the specified options.

HTTP Request

POST https://abs.example.com/api/libraries

Parameters

Parameter Type Default Description
name String Required The name of the library.
folders Array of Folder Required The folders of the library. Only specify the fullPath.
icon String database The icon of the library. See Library Icons for a list of possible icons.
mediaType String book The type of media that the library contains. Must be book or podcast.
provider String google Preferred metadata provider for the library. See Metadata Providers for a list of possible providers.
settings Library Settings Object See Below The settings for the library.

Library Settings Parameters

Parameter Type Default Description
coverAspectRatio Integer 1 Whether the library should use square book covers. Must be 0 (for false) or 1 (for true).
disableWatcher Boolean false Whether to disable the folder watcher for the library.
skipMatchingMediaWithAsin Boolean false Whether to skip matching books that already have an ASIN.
skipMatchingMediaWithIsbn Boolean false Whether to skip matching books that already have an ISBN.
autoScanCronExpression String or null null The cron expression for when to automatically scan the library folders. If null, automatic scanning will be disabled.

Response

Status Meaning Description Schema
200 OK Success Library

Get All Libraries

curl "https://abs.example.com/api/libraries" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "libraries": [
    {
      "id": "lib_5yvub9dqvctlcrza6h",
      "name": "Main",
      "folders": [
        {
          "id": "audiobooks",
          "fullPath": "/audiobooks",
          "libraryId": "main"
        }
      ],
      "displayOrder": 1,
      "icon": "audiobookshelf",
      "mediaType": "book",
      "provider": "audible",
      "settings": {
        "coverAspectRatio": 1,
        "disableWatcher": false,
        "skipMatchingMediaWithAsin": false,
        "skipMatchingMediaWithIsbn": false,
        "autoScanCronExpression": null
      },
      "createdAt": 1633522963509,
      "lastUpdate": 1646520916818
    },
    {
      "id": "lib_c1u6t4p45c35rf0nzd",
      "name": "Podcasts",
      "folders": [
        {
          "id": "fol_bev1zuxhb0j0s1wehr",
          "fullPath": "/podcasts",
          "libraryId": "lib_c1u6t4p45c35rf0nzd",
          "addedAt": 1650462940610
        }
      ],
      "displayOrder": 4,
      "icon": "database",
      "mediaType": "podcast",
      "provider": "itunes",
      "settings": {
        "coverAspectRatio": 1,
        "disableWatcher": false,
        "skipMatchingMediaWithAsin": false,
        "skipMatchingMediaWithIsbn": false,
        "autoScanCronExpression": null
      },
      "createdAt": 1650462940610,
      "lastUpdate": 1650462940610
    }
  ]
}

This endpoint retrieves all libraries accessible to the user.

HTTP Request

GET http://abs.example.com/api/libraries

Response

Status Meaning Description Schema
200 OK Success See Below

Response Schema

Attribute Type Description
libraries Array of Library The requested libraries.

Get a Library

curl "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd?include=filterdata" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "filterdata": {
    "authors": [
      {
        "id": "aut_z3leimgybl7uf3y4ab",
        "name": "Terry Goodkind"
      }
    ],
    "genres": ["Fantasy"],
    "tags": [],
    "series": [
      {
        "id": "ser_cabkj4jeu8be3rap4g",
        "name": "Sword of Truth"
      }
    ],
    "narrators": ["Sam Tsoutsouvas"],
    "languages": []
  },
  "issues": 0,
  "numUserPlaylists": 0,
  "library": {
    "id": "lib_c1u6t4p45c35rf0nzd",
    "name": "Podcasts",
    "folders": [
      {
        "id": "fol_bev1zuxhb0j0s1wehr",
        "fullPath": "/podcasts",
        "libraryId": "lib_c1u6t4p45c35rf0nzd",
        "addedAt": 1650462940610
      }
    ],
    "displayOrder": 4,
    "icon": "database",
    "mediaType": "podcast",
    "provider": "itunes",
    "settings": {
      "coverAspectRatio": 1,
      "disableWatcher": false,
      "skipMatchingMediaWithAsin": false,
      "skipMatchingMediaWithIsbn": false,
      "autoScanCronExpression": null
    },
    "createdAt": 1650462940610,
    "lastUpdate": 1650462940610
  }
}

This endpoint retrieves a library.

HTTP Request

GET https://abs.example.com/api/libraries/<ID>

URL Parameters

Parameter Description
ID The ID of the library to retrieve.

Optional Query Parameters

Parameter Type Description
include String A comma separated list of what to include with the library item. The only current option is filterdata.

Response

Status Meaning Description Schema
200 OK Success Library or, if filterdata was requested, see below.
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Response Schema

Attribute Type Description
filterdata Library Filter Data Object The library's filter data that can be used for displaying a filter list.
issues Integer The number of library items in the library that have issues.
numUserPlaylists Integer The number of playlists belonging to this library for the authenticated user.
library Library Object The requested library.

Update a Library

curl -X PATCH "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json"
  -d '{"name": "Pods", "icon": "podcast"}'

The above command returns JSON structured like this:

{
  "id": "lib_c1u6t4p45c35rf0nzd",
  "name": "Pods",
  "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
}

This endpoint updates a library.

HTTP Request

PATCH https://abs.example.com/api/libraries/<ID>

URL Parameters

Parameter Description
ID The ID of the library to update.

Parameters

Parameter Type Description
name String The name of the library.
folders Array of Folder See the notice below. Only specify the fullPath for new folders.
displayOrder Integer Display position of the library in the list of libraries. Must be >= 1.
icon String The icon of the library. See Library Icons for a list of possible icons.
provider String Preferred metadata provider for the library. See Metadata Providers for a list of possible providers.
settings Library Settings Object The settings for the library.

Library Settings Parameters

Parameter Type Description
coverAspectRatio Integer Whether the library should use square book covers. Must be 0 (for false) or 1 (for true).
disableWatcher Boolean Whether to disable the folder watcher for the library.
skipMatchingMediaWithAsin Boolean Whether to skip matching books that already have an ASIN.
skipMatchingMediaWithIsbn Boolean Whether to skip matching books that already have an ISBN.
autoScanCronExpression String or null The cron expression for when to automatically scan the library folders. If null, automatic scanning will be disabled.

Response

Status Meaning Description Schema
200 OK Success Library
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Delete a Library

curl -X DELETE "https://abs.example.com/api/libraries/lib_5yvub9dqvctlcrza6h" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

If successful the deleted library will be returned like this:

{
  "id": "lib_5yvub9dqvctlcrza6h",
  "name": "audiobooks",
  "folders": [
    {
      "id": "fol_zdat63120karrt7i52",
      "fullPath": "/audiobooks",
      "libraryId": "lib_5yvub9dqvctlcrza6g",
      "addedAt": 1653396692539
    }
  ],
  "displayOrder": 5,
  "icon": "database",
  "mediaType": "book",
  "provider": "audible",
  "settings": {
    "coverAspectRatio": 1,
    "disableWatcher": false,
    "skipMatchingMediaWithAsin": false,
    "skipMatchingMediaWithIsbn": false,
    "autoScanCronExpression": null
  },
  "createdAt": 1653396692539,
  "lastUpdate": 1653396692539
}

This endpoint deletes a library.

HTTP Request

DELETE https://abs.example.com/api/libraries/<ID>

URL Parameters

Parameter Description
ID The ID of the library to delete.

Response

Status Meaning Description Schema
200 OK Success Library
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Get a Library's Items

curl "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/items?sort=media.metadata.title&filter=authors.YXV0X3ozbGVpbWd5Ymw3dWYzeTRhYg%3D%3D&collapseseries=1" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "results": [
    {
      "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,
      "collapsedSeries": {
        "id": "ser_cabkj4jeu8be3rap4g",
        "name": "Sword of Truth",
        "nameIgnorePrefix": "Sword of Truth",
        "numBooks": 1
      }
    }
  ],
  "total": 1,
  "limit": 0,
  "page": 0,
  "sortBy": "media.metadata.title",
  "sortDesc": false,
  "filterBy": "authors.YXV0X3ozbGVpbWd5Ymw3dWYzeTRhYg==",
  "mediaType": "book",
  "minified": false,
  "collapseseries": true,
  "include": ""
}

This endpoint returns a library's items, optionally sorted and/or filtered.

HTTP Request

GET https://abs.example.com/api/libraries/<ID>/items

URL Parameters

Parameter Description
ID The ID of the library.

Optional Query Parameters

Parameter Type Description
limit Integer Limit the number of returned results per page. If 0, no limit will be applied.
page Integer The page number (0 indexed) to request. If there is no limit applied, then page will have no effect and all results will be returned.
sort String What to sort the results by. Specify the attribute to sort by using JavaScript object notation. For example, to sort by title use sort=media.metadata.title. When filtering for a series, sort can also be sequence.
desc Binary Whether to reverse the sort order. 0 for false, 1 for true.
filter String What to filter the results by. See Filtering.
minified Binary Whether to request minified objects. 0 for false, 1 for true.
collapseseries Binary Whether to collapse books in a series to a single entry. 0 for false, 1 for true.
include String A comma separated list of what to include with the library items. The only current option is rssfeed.

Response

Status Meaning Description Schema
200 OK Success See Below
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Response Schema

Attribute Type Description
results Array of Library Item The requested library items. If minified is true, it will be an array of Library Item Minified. collapseseries will add a Series Num Books as collapsedSeries to the library items, with only one library item per series. However, if there is only one series in the results, they will not be collapsed. When filtering by series, media.metadata.series will be replaced by the matching Series Sequence object. If filtering by series, collapseseries is true, and there are multiple series, such as a subseries, a seriesSequenceList string attribute is added to collapsedSeries which represents the items in the subseries that are in the filtered series. rssfeed will add an RSS Feed Minified object or null as rssFeed to the library items, the item's RSS feed if it has one open.
total Integer The total number of results.
limit Integer The limit set in the request.
page Integer The page set in request.
sortBy String The sort set in the request. Will not exist if no sort was set.
sortDesc Boolean Whether to reverse the sort order.
filterBy String The filter set in the request, URL decoded. Will not exist if no filter was set.
mediaType String The media type of the library. Will be book or podcast.
minified Boolean Whether minified was set in the request.
collapseseries Boolean Whether collapseseries was set in the request.
include String The requested include.

Remove a Library's Items With Issues

curl -X DELETE "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/issues" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

This endpoint removes a library's items that have issues.

HTTP Request

DELETE https://abs.example.com/api/libraries/<ID>/issues

URL Parameters

Parameter Description
ID The ID of the library.

Response

Status Meaning Description
200 OK Success
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Get a Library's Podcast Episode Downloads

curl "https://abs.example.com/api/libraries/lib_p9wkw2i85qy9oltijt/episode-downloads" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "currentDownload": {
    "id": "epdl_pgv4d47j6dtqpk4r0v",
    "episodeDisplayTitle": "2 - Glow Cloud",
    "url": "https://www.podtrac.com/pts/redirect.mp3/dovetail.prxu.org/_/126/cb1dd91f-5d8d-42e9-ba22-14ff335d2cbb/2_Glow_Cloud.mp3",
    "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
    "libraryId": "lib_p9wkw2i85qy9oltijt",
    "isFinished": false,
    "failed": false,
    "startedAt": null,
    "createdAt": 1668122813409,
    "finishedAt": null,
    "podcastTitle": "Welcome to Night Vale",
    "podcastExplicit": false,
    "season": "",
    "episode": "",
    "episodeType": "full",
    "publishedAt": 1341144000000
  },
  "queue": []
}

This endpoint retrieves the podcast episodes downloads of the library.

HTTP Request

GET http://abs.example.com/api/libraries/<ID>/episode-downloads

URL Parameters

Parameter Description
ID The ID of the library.

Response

Status Meaning Description Schema
200 OK Success See below.
404 Not Found No library with the given ID exists, or the user cannot access it.

Response Schema

Attribute Type Description
currentDownload Podcast Episode Download Object The podcast episode currently being downloaded. Will only exist if an episode download is in progress.
queue Array of Podcast Episode Download The podcast episodes in the queue to be downloaded.

Get a Library's Series

curl "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/series" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": "ser_cabkj4jeu8be3rap4g",
      "name": "Sword of Truth",
      "nameIgnorePrefix": "Sword of Truth",
      "nameIgnorePrefixSort": "Sword of Truth",
      "type": "series",
      "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,
          "sequence": "1"
        }
      ],
      "addedAt": 1650621073750,
      "totalDuration": 12000.946
    }
  ],
  "total": 1,
  "limit": 0,
  "page": 0,
  "sortBy": "media.metadata.title",
  "sortDesc": false,
  "filterBy": "authors.YXV0X3ozbGVpbWd5Ymw3dWYzeTRhYg==",
  "mediaType": "book",
  "minified": false,
  "collapseseries": true,
  "include": ""
}

This endpoint returns a library's series.

HTTP Request

GET https://abs.example.com/api/libraries/<ID>/series

URL Parameters

Parameter Description
ID The ID of the library.

Query Parameters

Parameter Type Description
limit Integer Required. Limit the number of returned results per page. Must be greater than 0.
page Integer The page number (0 indexed) to request.
sort String What to sort the results by. By default, the results will be sorted by series name. Other sort options are: numBooks, totalDuration, and addedAt.
desc Binary Whether to reverse the sort order. 0 for false, 1 for true.
filter String What to filter the results by. See Filtering. The issues and feed-open filters are not available for this endpoint.
include String A comma separated list of what to include with the library items. The only current option is rssfeed.

Response

Status Meaning Description Schema
200 OK Success See Below
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Response Schema

Attribute Type Description
results Array of Series Books The requested series. If minified is true, the library items contained in the series will be Library Item Minified. If rssfeed was requested, an RSS Feed Minified object or null as rssFeed, the series' RSS feed if it has one open, will be added to the series.
total Integer The total number of results.
limit Integer The limit set in the request.
page Integer The page set in request.
sortBy String The sort set in the request. Will not exist if no sort was set.
sortDesc Boolean Whether to reverse the sort order.
filterBy String The filter set in the request, URL decoded. Will not exist if no filter was set.
minified Boolean Whether minified was set in the request.
include String The requested include.

Get a Library's Collections

curl "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/collections?minified=1" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "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": ""
}

This endpoint returns a library's collections.

HTTP Request

GET https://abs.example.com/api/libraries/<ID>/collections

URL Parameters

Parameter Description
ID The ID of the library.

Optional Query Parameters

Parameter Type Description
limit Integer Limit the number of returned results per page. If 0, no limit will be applied.
page Integer The page number (0 indexed) to request. If there is no limit applied, then page will have no effect and all results will be returned.
sort String What to sort the results by.
desc Binary Whether to reverse the sort order. 0 for false, 1 for true.
filter String What to filter the results by. See Filtering.
minified Binary Whether to request minified objects. 0 for false, 1 for true.
include String A comma separated list of what to include with the library items. The only current option is rssfeed.

Response

Status Meaning Description Schema
200 OK Success See Below
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Response Schema

Attribute Type Description
results Array of Collection Expanded The requested collections. If minified is true, the library items contained in the collections will be Library Item Minified. If rssfeed was requested, an RSS Feed Minified object or null as rssFeed, the collection's RSS feed if it has one open, will be added to the collections.
total Integer The total number of results.
limit Integer The limit set in the request.
page Integer The page set in request.
sortBy String The sort set in the request. Will not exist if no sort was set.
sortDesc Boolean Whether to reverse the sort order.
filterBy String The filter set in the request, URL decoded. Will not exist if no filter was set.
minified Boolean Whether minified was set in the request.
include String The requested include.

Get a Library's User Playlists

curl "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/playlists" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": "pl_qbwet64998s5ra6dcu",
      "libraryId": "lib_c1u6t4p45c35rf0nzd",
      "userId": "root",
      "name": "Favorites",
      "description": null,
      "coverPath": null,
      "items": [
        {
          "libraryItemId": "li_8gch9ve09orgn4fdz8",
          "episodeId": null,
          "libraryItem": {
            "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",
                    "tagComposer": "Terry Goodkind"
                  },
                  "mimeType": "audio/mpeg"
                },
                {
                  "index": 2,
                  "ino": "649644248522215261",
                  "metadata": {
                    "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                    "ext": ".mp3",
                    "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                    "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                    "size": 47972352,
                    "mtimeMs": 1632223180281,
                    "ctimeMs": 1645978261001,
                    "birthtimeMs": 0
                  },
                  "addedAt": 1650621074130,
                  "updatedAt": 1651830828023,
                  "trackNumFromMeta": 2,
                  "discNumFromMeta": null,
                  "trackNumFromFilename": 1,
                  "discNumFromFilename": null,
                  "manuallyVerified": false,
                  "exclude": false,
                  "error": null,
                  "format": "MP2/3 (MPEG audio layer 2/3)",
                  "duration": 5996.2785,
                  "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 02",
                    "tagTrack": "02/20",
                    "tagAlbumArtist": "Terry Goodkind",
                    "tagComposer": "Terry Goodkind"
                  },
                  "mimeType": "audio/mpeg"
                }
              ],
              "chapters": [
                {
                  "id": 0,
                  "start": 0,
                  "end": 6004.6675,
                  "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
                },
                {
                  "id": 1,
                  "start": 6004.6675,
                  "end": 12000.946,
                  "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02"
                }
              ],
              "duration": 33854.905,
              "size": 268824228,
              "tracks": [
                {
                  "index": 1,
                  "startOffset": 0,
                  "duration": 6004.6675,
                  "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
                  "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
                  "mimeType": "audio/mpeg",
                  "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
                  }
                },
                {
                  "index": 2,
                  "startOffset": 6004.6675,
                  "duration": 5996.2785,
                  "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                  "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                  "mimeType": "audio/mpeg",
                  "metadata": {
                    "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                    "ext": ".mp3",
                    "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                    "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 03.mp3",
                    "size": 47972352,
                    "mtimeMs": 1632223180281,
                    "ctimeMs": 1645978261001,
                    "birthtimeMs": 0
                  }
                }
              ],
              "ebookFile": null
            },
            "libraryFiles": [
              {
                "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": 1650621052494,
                "updatedAt": 1650621052494,
                "fileType": "audio"
              },
              {
                "ino": "649644248522215261",
                "metadata": {
                  "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                  "ext": ".mp3",
                  "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                  "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                  "size": 47972352,
                  "mtimeMs": 1632223180281,
                  "ctimeMs": 1645978261001,
                  "birthtimeMs": 0
                },
                "addedAt": 1650621052494,
                "updatedAt": 1650621052494,
                "fileType": "audio"
              },
              {
                "ino": "649644248522215267",
                "metadata": {
                  "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
                },
                "addedAt": 1650621052495,
                "updatedAt": 1650621052495,
                "fileType": "image"
              }
            ],
            "size": 268990279
          }
        }
      ],
      "lastUpdate": 1669623431313,
      "createdAt": 1669623431313
    }
  ],
  "total": 1,
  "limit": 0,
  "page": 0
}

This endpoint returns a library's playlists for the authenticated user.

HTTP Request

GET https://abs.example.com/api/libraries/<ID>/playlists

URL Parameters

Parameter Description
ID The ID of the library.

Query Parameters

Parameter Type Default Description
limit Integer 0 Limit the number of returned results per page. If 0, no limit will be applied.
page Integer 0 The page number (0 indexed) to request. If there is no limit applied, then page will have no effect and all results will be returned.

Response

Status Meaning Description Schema
200 OK Success See Below
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Response Schema

Attribute Type Description
results Array of Playlist Expanded The requested playlists.
total Integer The total number of results.
limit Integer The limit set in the request.
page Integer The page set in request.

Get a Library's Personalized View

curl "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/personalized" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

[
  {
    "id": "continue-listening",
    "label": "Continue Listening",
    "labelStringKey": "LabelContinueListening",
    "type": "book",
    "entities": [
      {
        "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,
        "progressLastUpdate": 1650621110769
      }
    ],
    "category": "recentlyListened"
  },
  {
    "id": "continue-series",
    "label": "Continue Series",
    "labelStringKey": "LabelContinueSeries",
    "type": "book",
    "entities": [
      {
        "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,
            "series": {
              "id": "ser_cabkj4jeu8be3rap4g",
              "name": "Sword of Truth",
              "sequence": "1"
            }
          },
          "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,
        "prevBookInProgressLastUpdate": 1650621110769
      }
    ],
    "category": "continueSeries"
  },
  {
    "id": "recently-added",
    "label": "Recently Added",
    "labelStringKey": "LabelRecentlyAdded",
    "type": "book",
    "entities": [
      {
        "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
      }
    ],
    "category": "newestItems"
  },
  {
    "id": "recent-series",
    "label": "Recent Series",
    "labelStringKey": "LabelRecentSeries",
    "type": "series",
    "entities": [
      {
        "id": "ser_cabkj4jeu8be3rap4g",
        "name": "Sword of Truth",
        "description": null,
        "addedAt": 1650621073750,
        "updatedAt": 1650621073750,
        "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,
            "seriesSequence": "1"
          }
        ],
        "inProgress": true,
        "hasActiveBook": true,
        "hideFromContinueListening": false,
        "bookInProgressLastUpdate": 1650621110769,
        "firstBookUnread": null
      }
    ],
    "category": "newestSeries"
  },
  {
    "id": "recommended",
    "label": "Recommended",
    "labelStringKey": "LabelRecommended",
    "type": "book",
    "entities": [
      {
        "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,
        "weight": 0.9215686274509803
      }
    ],
    "category": "recommended"
  },
  {
    "id": "listen-again",
    "label": "Listen Again",
    "labelStringKey": "LabelListenAgain",
    "type": "book",
    "entities": [
      {
        "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,
        "finishedAt": 1650621110769
      }
    ],
    "category": "recentlyFinished"
  },
  {
    "id": "newest-authors",
    "label": "Newest Authors",
    "labelStringKey": "LabelNewestAuthors",
    "type": "authors",
    "entities": [
      {
        "id": "aut_z3leimgybl7uf3y4ab",
        "asin": null,
        "name": "Terry Goodkind",
        "description": null,
        "imagePath": null,
        "addedAt": 1650621073750,
        "updatedAt": 1650621073750,
        "numBooks": 1
      }
    ],
    "category": "newestAuthors"
  }
]

This endpoint returns a library's personalized view for home page display.

HTTP Request

GET https://abs.example.com/api/libraries/<ID>/personalized

URL Parameters

Parameter Description
ID The ID of the library.

Optional Query Parameters

Parameter Type Description
limit Integer Limit the number of items in each 'shelf' of the response. Default value is 10.
include String A comma separated list of what to include with the library items. The only current option is rssfeed.

Response

Status Meaning Description Schema
200 OK Success Array of Shelf (See Below)
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Shelf

Attribute Type Description
id String The ID of the shelf.
label String The label of the shelf.
labelStringKey String The label string key of the shelf, for internationalization purposes.
type String The type of items the shelf represents. Can be book, series, authors, episode, or podcast.
entities Array The entities to be displayed on the shelf. See below.
category String The category of the shelf.

Shelf Entities

Attribute Type Description
books Array of Library Item Minified The books in the series. Each library item in books will have a seriesSequence attribute, a String or null, the position of the book in the series.
inProgress Boolean Whether the user has started listening to the series.
hasActiveBook Boolean Whether the user has started listening to the series, but has not finished it.
hideFromContinueListening Boolean Whether the series has been marked to hide it from the "Continue Series" shelf.
bookInProgressLastUpdate Integer The latest time (in ms since POSIX epoch) when the progress of a book in the series was updated.
firstBookUnread Library Item Minified or null The first book in the series (by sequence) to have not been started or finished. Will be null if the user has started or finished all books in the series. This library item will also have a seriesSequence attribute.

Get a Library's Filter Data

curl "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/filterdata" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "authors": [
    {
      "id": "aut_z3leimgybl7uf3y4ab",
      "name": "Terry Goodkind"
    }
  ],
  "genres": ["Fantasy"],
  "tags": [],
  "series": [
    {
      "id": "ser_cabkj4jeu8be3rap4g",
      "name": "Sword of Truth"
    }
  ],
  "narrators": ["Sam Tsoutsouvas"],
  "languages": []
}

This endpoint returns a library's filter data that can be used for displaying a filter list.

HTTP Request

GET https://abs.example.com/api/libraries/<ID>/filterdata

URL Parameters

Parameter Description
ID The ID of the library.

Response

Status Meaning Description Schema
200 OK Success Library Filter Data
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Search a Library

curl "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/search?q=Terry%20Goodkind" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "book": [
    {
      "libraryItem": {
        "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",
                "tagComposer": "Terry Goodkind"
              },
              "mimeType": "audio/mpeg"
            },
            {
              "index": 2,
              "ino": "649644248522215261",
              "metadata": {
                "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "ext": ".mp3",
                "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "size": 47972352,
                "mtimeMs": 1632223180281,
                "ctimeMs": 1645978261001,
                "birthtimeMs": 0
              },
              "addedAt": 1650621074130,
              "updatedAt": 1651830828023,
              "trackNumFromMeta": 2,
              "discNumFromMeta": null,
              "trackNumFromFilename": 1,
              "discNumFromFilename": null,
              "manuallyVerified": false,
              "exclude": false,
              "error": null,
              "format": "MP2/3 (MPEG audio layer 2/3)",
              "duration": 5996.2785,
              "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 02",
                "tagTrack": "02/20",
                "tagAlbumArtist": "Terry Goodkind",
                "tagComposer": "Terry Goodkind"
              },
              "mimeType": "audio/mpeg"
            }
          ],
          "chapters": [
            {
              "id": 0,
              "start": 0,
              "end": 6004.6675,
              "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
            },
            {
              "id": 1,
              "start": 6004.6675,
              "end": 12000.946,
              "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02"
            }
          ],
          "duration": 33854.905,
          "size": 268824228,
          "tracks": [
            {
              "index": 1,
              "startOffset": 0,
              "duration": 6004.6675,
              "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
              "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
              "mimeType": "audio/mpeg",
              "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
              }
            },
            {
              "index": 2,
              "startOffset": 6004.6675,
              "duration": 5996.2785,
              "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "mimeType": "audio/mpeg",
              "metadata": {
                "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "ext": ".mp3",
                "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 03.mp3",
                "size": 47972352,
                "mtimeMs": 1632223180281,
                "ctimeMs": 1645978261001,
                "birthtimeMs": 0
              }
            }
          ],
          "ebookFile": null
        },
        "libraryFiles": [
          {
            "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": 1650621052494,
            "updatedAt": 1650621052494,
            "fileType": "audio"
          },
          {
            "ino": "649644248522215261",
            "metadata": {
              "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "ext": ".mp3",
              "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "size": 47972352,
              "mtimeMs": 1632223180281,
              "ctimeMs": 1645978261001,
              "birthtimeMs": 0
            },
            "addedAt": 1650621052494,
            "updatedAt": 1650621052494,
            "fileType": "audio"
          },
          {
            "ino": "649644248522215267",
            "metadata": {
              "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
            },
            "addedAt": 1650621052495,
            "updatedAt": 1650621052495,
            "fileType": "image"
          }
        ],
        "size": 268990279
      },
      "matchKey": "authors",
      "matchText": "Terry Goodkind"
    }
  ],
  "tags": [],
  "authors": [
    {
      "id": "aut_z3leimgybl7uf3y4ab",
      "asin": null,
      "name": "Terry Goodkind",
      "description": null,
      "imagePath": null,
      "addedAt": 1650621073750,
      "updatedAt": 1650621073750,
      "numBooks": 1
    }
  ],
  "series": []
}

This endpoint searches a library for the query and returns the results.

HTTP Request

GET https://abs.example.com/api/libraries/<ID>/search?<q>

URL Parameters

Parameter Description
ID The ID of the library.

Query Parameters

Parameter Type Default Description
q String Required The URL encoded search query.
limit Integer 12 Limit the number of returned results.

Response

Status Meaning Description Schema
200 OK Success See Below
400 Bad Request No query string.
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Response Schema

Attribute Type Description
book or podcast Array of Library Item Search Result (See Below) The item results of the search. This attribute will be book or podcast depending on the library's media type.
tags Array of String The tag results of the search.
authors Array of Author Expanded The author results of the search.
series Array of Series Books The series results of the search.

Library Item Search Result

Attribute Type Description
libraryItem Library Item Expanded Object The matched library item.
matchKey String or null What the library item was matched on.
matchText String or null The text in the library item that the query matched to.

Get a Library's Stats

curl "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/stats" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "totalItems": 1,
  "totalAuthors": 1,
  "totalGenres": 1,
  "totalDuration": 12000.946,
  "longestItems": [
    {
      "id": "li_8gch9ve09orgn4fdz8",
      "title": "Wizards First Rule",
      "duration": 12000.946
    }
  ],
  "numAudioTrack": 2,
  "totalSize": 268990279,
  "largestItems": [
    {
      "id": "li_8gch9ve09orgn4fdz8",
      "title": "Wizards First Rule",
      "size": 268990279
    }
  ],
  "authorsWithCount": [
    {
      "id": "aut_z3leimgybl7uf3y4ab",
      "name": "Terry Goodkind",
      "count": 1
    }
  ],
  "genresWithCount": [
    {
      "genre": "Fantasy",
      "count": 1
    }
  ]
}

This endpoint returns a library's stats.

HTTP Request

GET https://abs.example.com/api/libraries/<ID>/stats

URL Parameters

Parameter Description
ID The ID of the library.

Response

Status Meaning Description Schema
200 OK Success See Below
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Response Schema

Attribute Type Description
totalItems Integer The total amount of library items in the library.
totalAuthors Integer The total amount of authors in the library.
totalGenres Integer The total amount of genres in the library.
totalDuration Float The total duration (in seconds) of all items in the library.
longestItems Array of Library Item Duration Stats The items with the longest durations in the library.
numAudioTrack Integer The total number of audio tracks in the library.
totalSize Integer The total size (in bytes) of all items in the library.
largestItems Array of Library Item Size Stats The items with the largest size in the library.
authorsWithCount Array of Author Stats The authors in the library.
genresWithCount Array of Genre Stats The genres in the library.

Library Item Duration Stats

Attribute Type Description
id String The ID of the library item.
title String The title of the library item.
duration Float The duration (in seconds) of the library item.

Library Item Size Stats

Attribute Type Description
id String The ID of the library item.
title String The title of the library item.
size Integer The size (in bytes) of the library item.

Author Stats

Attribute Type Description
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.

Genre Stats

Attribute Type Description
genre String The name of the genre.
count Integer The number of items in the library with the genre.

Get a Library's Authors

curl "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/authors" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "authors": [
    {
      "id": "aut_z3leimgybl7uf3y4ab",
      "asin": null,
      "name": "Terry Goodkind",
      "description": null,
      "imagePath": null,
      "addedAt": 1650621073750,
      "updatedAt": 1650621073750,
      "numBooks": 1
    }
  ]
}

This endpoint returns a library's authors.

HTTP Request

GET https://abs.example.com/api/libraries/<ID>/authors

URL Parameters

Parameter Description
ID The ID of the library.

Response

Status Meaning Description Schema
200 OK Success See Below
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Response Schema

Attribute Type Description
authors Array of Author Expanded The requested authors.

Match All of a Library's Items

curl "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/matchall" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

This endpoint matches all items in a library using quick match. Quick match populates empty book details and the cover with the first book result from the library's default metadata provider. Does not overwrite details unless the "Prefer matched metadata" server setting is enabled.

HTTP Request

GET https://abs.example.com/api/libraries/<ID>/matchall

URL Parameters

Parameter Description
ID The ID of the library.

Response

Status Meaning Description
200 OK Success
403 Forbidden An admin user is required to match library items.
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Scan a Library's Folders

curl -X POST "https://abs.example.com/api/libraries/lib_c1u6t4p45c35rf0nzd/scan" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

This endpoint starts a scan of a library's folders for new library items and changes to existing library items.

HTTP Request

POST https://abs.example.com/api/libraries/<ID>/scan

URL Parameters

Parameter Description
ID The ID of the library.

Optional Query Parameters

Parameter Type Description
force Binary Whether to force a rescan for all of a library's items. 0 for false, 1 for true.

Response

Status Meaning Description
200 OK Success
403 Forbidden An admin user is required to start a scan.
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Get a Library's Recent Episodes

curl "https://abs.example.com/api/libraries/lib_p9wkw2i85qy9oltijt/recent-episodes" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "episodes": [
    {
      "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
      "id": "ep_lh6ko39pumnrma3dhv",
      "index": 1,
      "season": "",
      "episode": "",
      "episodeType": "full",
      "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": "<div><br>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.<br><br></div><div><br>Weather: \"These and More Than These\" by Joseph Fink<br><br></div><div><br>Music: Disparition, disparition.info<br><br></div><div><br>Logo: Rob Wilson, silastom.com<br><br></div><div><br>Produced by Night Vale Presents. Written by Joseph Fink and Jeffrey Cranor. Narrated by Cecil Baldwin. More Info: welcometonightvale.com, and follow @NightValeRadio on Twitter or Facebook.<br><br></div>",
      "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"
      },
      "pubDate": "Fri, 15 Jun 2012 12:00:00 -0000",
      "audioFile": {
        "index": 1,
        "ino": "22587",
        "metadata": {
          "filename": "1 - Pilot.mp3",
          "ext": ".mp3",
          "path": "/podcasts/Welcome to Night Vale/1 - Pilot.mp3",
          "relPath": "1 - Pilot.mp3",
          "size": 23653735,
          "mtimeMs": 1667326682557,
          "ctimeMs": 1667326682557,
          "birthtimeMs": 1667326679508
        },
        "addedAt": 1667326682605,
        "updatedAt": 1667327311570,
        "trackNumFromMeta": null,
        "discNumFromMeta": null,
        "trackNumFromFilename": null,
        "discNumFromFilename": null,
        "manuallyVerified": false,
        "exclude": false,
        "error": null,
        "format": "MP2/3 (MPEG audio layer 2/3)",
        "duration": 1454.18449,
        "bitRate": 128000,
        "language": null,
        "codec": "mp3",
        "timeBase": "1/14112000",
        "channels": 2,
        "channelLayout": "stereo",
        "chapters": [],
        "embeddedCoverArt": "mjpeg",
        "metaTags": {
          "tagAlbum": "Welcome to Night Vale",
          "tagArtist": "Night Vale Presents",
          "tagGenre": "Podcast",
          "tagTitle": "1 - Pilot",
          "tagDate": "2012",
          "tagEncoder": "Lavf58.45.100"
        },
        "mimeType": "audio/mpeg"
      },
      "audioTrack": {
        "index": 1,
        "startOffset": 0,
        "duration": 1454.18449,
        "title": "1 - Pilot.mp3",
        "contentUrl": "/s/item/li_bufnnmp4y5o2gbbxfm/1 - Pilot.mp3",
        "mimeType": "audio/mpeg",
        "metadata": {
          "filename": "1 - Pilot.mp3",
          "ext": ".mp3",
          "path": "/podcasts/Welcome to Night Vale/1 - Pilot.mp3",
          "relPath": "1 - Pilot.mp3",
          "size": 23653735,
          "mtimeMs": 1667326682557,
          "ctimeMs": 1667326682557,
          "birthtimeMs": 1667326679508
        }
      },
      "publishedAt": 1339761600000,
      "addedAt": 1667326679503,
      "updatedAt": 1667428186431,
      "duration": 1454.18449,
      "size": 23653735,
      "podcast": {
        "metadata": {
          "title": "Welcome to Night Vale",
          "titleIgnorePrefix": "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
        },
        "coverPath": "/podcasts/Welcome to Night Vale/cover.jpg",
        "tags": [],
        "numEpisodes": 1,
        "autoDownloadEpisodes": false,
        "autoDownloadSchedule": "0 0 * * 1",
        "lastEpisodeCheck": 1667326662087,
        "maxEpisodesToKeep": 0,
        "maxNewEpisodesToDownload": 3,
        "size": 23653735
      }
    }
  ],
  "total": 1,
  "limit": 0,
  "page": 0
}

This endpoint returns a library's newest unfinished podcast episodes, sorted by episode publish time.

HTTP Request

GET https://abs.example.com/api/libraries/<ID>/recent-episodes

URL Parameters

Parameter Description
ID The ID of the library.

Optional Query Parameters

Parameter Type Description
limit Integer Limit the number of returned results per page. If 0, no limit will be applied.
page Integer The page number (0 indexed) to request. If there is no limit applied, then page will have no effect and all results will be returned.

Response

Status Meaning Description Schema
200 OK Success See Below
404 Not Found The user cannot access the library, or no library with the provided ID exists.

Response Schema

Attribute Type Description
episodes Array of Podcast Episode Expanded The library's newest unfinished podcast episodes, sorted by episode publish time. The episodes have an additional podcast attribute, a Podcast Minified, the podcast the episode belongs to.
total Integer The total number of podcast episodes in the library.
limit Integer The limit set in the request.
page Integer The page set in request.

Reorder Library List

curl -X POST "https://abs.example.com/api/libraries/order" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"
  -H "Content-Type: application/json"
  -d '[{"id": "lib_5yvub9dqvctlcrza6h", "newOrder": 1}, {"id": "lib_c1u6t4p45c35rf0nzd", "newOrder": 2}]'

The above command returns JSON structured like this:

{
  "libraries": [
    {
      "id": "lib_5yvub9dqvctlcrza6h",
      "name": "Main",
      "folders": [
        {
          "id": "audiobooks",
          "fullPath": "/audiobooks",
          "libraryId": "main"
        }
      ],
      "displayOrder": 1,
      "icon": "audiobookshelf",
      "mediaType": "book",
      "provider": "audible",
      "settings": {
        "coverAspectRatio": 1,
        "disableWatcher": false,
        "skipMatchingMediaWithAsin": false,
        "skipMatchingMediaWithIsbn": false,
        "autoScanCronExpression": null
      },
      "createdAt": 1633522963509,
      "lastUpdate": 1646520916818
    },
    {
      "id": "lib_c1u6t4p45c35rf0nzd",
      "name": "Podcasts",
      "folders": [
        {
          "id": "fol_bev1zuxhb0j0s1wehr",
          "fullPath": "/podcasts",
          "libraryId": "lib_c1u6t4p45c35rf0nzd",
          "addedAt": 1650462940610
        }
      ],
      "displayOrder": 2,
      "icon": "database",
      "mediaType": "podcast",
      "provider": "itunes",
      "settings": {
        "coverAspectRatio": 1,
        "disableWatcher": false,
        "skipMatchingMediaWithAsin": false,
        "skipMatchingMediaWithIsbn": false,
        "autoScanCronExpression": null
      },
      "createdAt": 1650462940610,
      "lastUpdate": 1650462940610
    }
  ]
}

This endpoint will change the displayOrder of the libraries specified. It will return an array of all libraries.

HTTP Request

POST https://abs.example.com/api/libraries/order

Required Parameters

The POST body should be an array of objects like so:

Parameter Type Description
id String The ID of the library to set the displayOrder of.
newOrder Integer The new displayOrder for the library.

Response

Status Meaning Description Schema
200 OK Success See Below
403 Forbidden An admin user is required to reorder libraries.
500 Internal Server Error One or more of the IDs do not match any libraries.

Response Schema

Attribute Type Description
libraries Array of Library All the libraries.

Library Icons

Available library icons are:

Library Items

Delete All Library Items

curl -X DELETE "https://abs.example.com/api/items/all" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

This endpoint will delete all library items from the database. No actual files will be deleted.

HTTP Request

DELETE http://abs.example.com/api/items/all

Response

Status Meaning Description
200 OK Success
403 Forbidden An admin user is required to delete all library items.
500 Internal Server Error Something went wrong with recreating the library item database.

Get a Library Item

curl "https://abs.example.com/api/items/li_8gch9ve09orgn4fdz8?expanded=1&include=progress,rssfeed,authors" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "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",
          "asin": null,
          "name": "Terry Goodkind",
          "description": null,
          "imagePath": null,
          "addedAt": 1650621073750,
          "updatedAt": 1650621073750
        }
      ],
      "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",
          "tagComposer": "Terry Goodkind"
        },
        "mimeType": "audio/mpeg"
      },
      {
        "index": 2,
        "ino": "649644248522215261",
        "metadata": {
          "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "ext": ".mp3",
          "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "size": 47972352,
          "mtimeMs": 1632223180281,
          "ctimeMs": 1645978261001,
          "birthtimeMs": 0
        },
        "addedAt": 1650621074130,
        "updatedAt": 1651830828023,
        "trackNumFromMeta": 2,
        "discNumFromMeta": null,
        "trackNumFromFilename": 1,
        "discNumFromFilename": null,
        "manuallyVerified": false,
        "exclude": false,
        "error": null,
        "format": "MP2/3 (MPEG audio layer 2/3)",
        "duration": 5996.2785,
        "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 02",
          "tagTrack": "02/20",
          "tagAlbumArtist": "Terry Goodkind",
          "tagComposer": "Terry Goodkind"
        },
        "mimeType": "audio/mpeg"
      }
    ],
    "chapters": [
      {
        "id": 0,
        "start": 0,
        "end": 6004.6675,
        "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
      },
      {
        "id": 1,
        "start": 6004.6675,
        "end": 12000.946,
        "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02"
      }
    ],
    "duration": 33854.905,
    "size": 268824228,
    "tracks": [
      {
        "index": 1,
        "startOffset": 0,
        "duration": 6004.6675,
        "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
        "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
        "mimeType": "audio/mpeg",
        "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
        }
      },
      {
        "index": 2,
        "startOffset": 6004.6675,
        "duration": 5996.2785,
        "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
        "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
        "mimeType": "audio/mpeg",
        "metadata": {
          "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "ext": ".mp3",
          "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 03.mp3",
          "size": 47972352,
          "mtimeMs": 1632223180281,
          "ctimeMs": 1645978261001,
          "birthtimeMs": 0
        }
      }
    ],
    "ebookFile": null
  },
  "libraryFiles": [
    {
      "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": 1650621052494,
      "updatedAt": 1650621052494,
      "fileType": "audio"
    },
    {
      "ino": "649644248522215261",
      "metadata": {
        "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
        "ext": ".mp3",
        "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
        "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
        "size": 47972352,
        "mtimeMs": 1632223180281,
        "ctimeMs": 1645978261001,
        "birthtimeMs": 0
      },
      "addedAt": 1650621052494,
      "updatedAt": 1650621052494,
      "fileType": "audio"
    },
    {
      "ino": "649644248522215267",
      "metadata": {
        "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
      },
      "addedAt": 1650621052495,
      "updatedAt": 1650621052495,
      "fileType": "image"
    }
  ],
  "size": 268990279,
  "userMediaProgress": {
    "id": "li_8gch9ve09orgn4fdz8",
    "libraryItemId": "li_8gch9ve09orgn4fdz8",
    "episodeId": null,
    "duration": 6004.6675,
    "progress": 0.002710910637433297,
    "currentTime": 16.278117,
    "isFinished": false,
    "hideFromContinueListening": false,
    "lastUpdate": 1650621052495,
    "startedAt": 1650621052495,
    "finishedAt": null
  },
  "rssFeedUrl": null
}

This endpoint retrieves a library item.

HTTP Request

GET http://abs.example.com/api/items/<ID>

URL Parameters

Parameter Description
ID The ID of the library item to retrieve.

Optional Query Parameters

Parameter Type Description
expanded Binary Whether to return Library Item Expanded instead. 0 for false, 1 for true.
include String A comma separated list of what to include with the library item. The options are: progress, rssfeed, authors (for books), and downloads (for podcasts). expanded must be 1 for include to have an effect.
episode String If requesting progress for a podcast, the episode ID to get progress for.

Response

Status Meaning Description Schema
200 OK Success Library Item or, if expanded was requested, Library Item Expanded with optional extra attributes (see below).

Extra Attributes

Attribute Type Description
userMediaProgress Media Progress Object If progress was requested, the user's progress for the book or podcast episode. If no progress exists, neither will this attribute.
rssFeed RSS Feed Minified Object or null If rssfeed was requested, the open RSS feed of the library item. Will be null if the RSS feed for this library item is closed.
media.metadata.authors Array of Author If authors was requested, replaces the normally minified authors in the metadata.
episodesDownloading Array of Podcast Episode Download If downloads was requested, the podcast episodes currently in the download queue.

Delete a Library Item

curl -X DELETE "https://abs.example.com/api/items/li_8gch9ve09orgn4fdz8" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

This endpoint deletes a library item from the database. No files are deleted.

HTTP Request

DELETE http://abs.example.com/api/items/<ID>

URL Parameters

Parameter Description
ID The ID of the library item to delete.

Response

Status Meaning Description
200 OK Success

Update a Library Item's Media

curl -X PATCH "https://abs.example.com/api/items/li_8gch9ve09orgn4fdz8/media" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"title": "Wizards First Rule"}}'

The above command returns JSON structured like this:

{
  "updated": true,
  "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,
  "lastScan": 1651830827825,
  "scanVersion": "2.0.21",
  "isMissing": false,
  "isInvalid": false,
  "mediaType": "book",
  "media": {
    "libraryItemId": "li_8gch9ve09orgn4fdz8",
    "metadata": {
      "title": "Wizards First Rule",
      "subtitle": null,
      "authors": [
        {
          "id": "aut_z3leimgybl7uf3y4ab",
          "name": "Terry Goodkind"
        }
      ],
      "narrators": [
        "Sam Tsoutsouvas"
      ],
      "series": [
        {
          "id": "ser_cabkj4jeu8be3rap4g",
          "name": "Sword of Truth",
          "sequence": null
        }
      ],
      "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": [],
    "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",
          "tagComposer": "Terry Goodkind"
        },
        "mimeType": "audio/mpeg"
      },
      {
        "index": 2,
        "ino": "649644248522215261",
        "metadata": {
          "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "ext": ".mp3",
          "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "size": 47972352,
          "mtimeMs": 1632223180281,
          "ctimeMs": 1645978261001,
          "birthtimeMs": 0
        },
        "addedAt": 1650621074130,
        "updatedAt": 1651830828023,
        "trackNumFromMeta": 2,
        "discNumFromMeta": null,
        "trackNumFromFilename": 1,
        "discNumFromFilename": null,
        "manuallyVerified": false,
        "exclude": false,
        "error": null,
        "format": "MP2/3 (MPEG audio layer 2/3)",
        "duration": 5996.2785,
        "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 02",
          "tagTrack": "02/20",
          "tagAlbumArtist": "Terry Goodkind",
          "tagComposer": "Terry Goodkind"
        },
        "mimeType": "audio/mpeg"
      }
    ],
    "chapters": [
      {
        "id": 0,
        "start": 0,
        "end": 6004.6675,
        "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
      },
      {
        "id": 1,
        "start": 6004.6675,
        "end": 12000.946,
        "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02"
      }
    ],
    "ebookFile": null
  },
  "libraryFiles": [
    {
      "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": 1650621052494,
      "updatedAt": 1650621052494,
      "fileType": "audio"
    },
    {
      "ino": "649644248522215261",
      "metadata": {
        "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
        "ext": ".mp3",
        "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
        "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
        "size": 47972352,
        "mtimeMs": 1632223180281,
        "ctimeMs": 1645978261001,
        "birthtimeMs": 0
      },
      "addedAt": 1650621052494,
      "updatedAt": 1650621052494,
      "fileType": "audio"
    },
    {
      "ino": "649644248522215267",
      "metadata": {
        "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
      },
      "addedAt": 1650621052495,
      "updatedAt": 1650621052495,
      "fileType": "image"
    }
  ]
}

This endpoint updates a library item's media and returns the updated library item.

HTTP Request

PATCH http://abs.example.com/api/items/<ID>/media

URL Parameters

Parameter Description
ID The ID of the library item.

Parameters

A library item's media can be either Book Parameters or Podcast Parameters (see below). Check the library item's mediaType before updating it.

Book Parameters

Parameter Type Description
metadata Book Metadata Object (See Below) The book's metadata.
coverPath String or null The absolute path on the server of the cover file. Use null to remove the cover. Prefer using the Update a Library Item's Cover endpoint.
tags Array of String The book's tags.
chapters Array of Book Chapter The book's chapters. Prefer using the Update a Library Item's Chapters endpoint.

Book Metadata Parameters

Parameter Type Description
title String or null The title of the book.
subtitle String or null The subtitle of the book.
authors Array of Author (See Below) The authors of the book.
narrators Array of String The narrators of the book.
series Array of Series Sequence (See Below) The series the book belongs to.
genres Array of String The genres of the book.
publishedYear String or null The year the book was published.
publishedDate String or null The date the book was published.
publisher String or null The publisher of the book.
description String or null A description of the book.
isbn String or null The ISBN of the book.
asin String or null The ASIN of the book.
language String or null The language of the book.
explicit Boolean Whether to mark the book as explicit.

Author Parameters

The server will automatically find the ID of the author or create one.

Parameter Type Description
name String The name of the author.

Series Parameters

The server will automatically find the ID of the series or create one.

Parameter Type Description
name String The name of the series.
sequence String or null The position in the series the book is.

Podcast Parameters

Parameter Type Description
metadata Podcast Metadata Object (See Below) The podcast's metadata.
coverPath String or null The absolute path on the server of the cover file. Use null to remove the cover. Prefer using the Update a Library Item's Cover endpoint.
tags Array of String The podcast's tags.
autoDownloadEpisodes Boolean Whether the server will automatically download podcast episodes according to the schedule.
autoDownloadSchedule String or null The cron expression for when to automatically download podcast episodes.
lastEpisodeCheck Integer The time (in ms since POSIX epoch) when the podcast was checked for new episodes.
maxEpisodesToKeep Integer The maximum number of podcast episodes to keep when automatically downloading new episodes. Episodes beyond this limit will be deleted. If 0, all episodes will be kept.
maxNewEpisodesToDownload Integer The maximum number of podcast episodes to download when automatically downloading new episodes. If 0, all episodes will be downloaded.

Podcast Metadata Parameters

Parameter Type Description
title String or null The title of the podcast.
author String or null The author of the podcast.
description String or null The description of the podcast.
releaseDate String or null The release date of the podcast.
genres Array of String The podcast's genres.
feedUrl String or null A URL of an RSS feed for the podcast.
imageUrl String or null A URL of a cover image for the podcast.
itunesPageUrl String or null A URL of an iTunes page for the podcast.
itunesId Integer or null The iTunes ID for the podcast.
itunesArtistId Integer or null The iTunes Artist ID for the author of the podcast.
explicit Boolean Whether to mark the podcast as explicit.
language String or null The language of the podcast.
type String The type of the podcast. Should be episodic or serial.

Response

Status Meaning Description Schema
200 OK Success Library Item with an updated attribute, a Boolean, whether anything was actually changed.

Get a Library Item's Cover

curl "https://abs.example.com/api/items/li_8gch9ve09orgn4fdz8/cover" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  --output cover.webp

The above command writes an image file.

This endpoint retrieves a library item's cover.

HTTP Request

GET http://abs.example.com/api/items/<ID>/cover

URL Parameters

Parameter Description
ID The ID of the library item.

Optional Query Parameters

Parameter Type Default Description
width Integer 400 The requested width of the cover image.
height Integer or null null The requested height of the cover image. If null the image is scaled proportionately.
format String webp or jpeg The requested format of the cover image. The default value depends on the request headers.
raw Binary 0 Whether to get the raw cover image file instead of a scaled version. 0 for false, 1 for true.

Response

Status Meaning Description
200 OK Success
404 Not Found Either no library item exists with the given ID, or the item does not have a cover.
500 Internal Server Error There was an error when attempting to read the cover file.

Upload a Library Item Cover

Upload a cover image:

curl -X POST "https://abs.example.com/api/items/li_8gch9ve09orgn4fdz8/cover" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -F cover=@cover.jpg

Or download a cover image from a URL:

curl -X POST "https://abs.example.com/api/items/li_8gch9ve09orgn4fdz8/cover" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://m.media-amazon.com/images/I/51xUwj8eKVL._SL500_.jpg"}'

The above commands return JSON structured like this:

{
  "success": true,
  "cover": "/metadata/items/li_8gch9ve09orgn4fdz8/cover.jpg"
}

This endpoint uploads a cover for a library item or requests the server to download a cover from a specified URL.

HTTP Request

POST http://abs.example.com/api/items/<ID>/cover

URL Parameters

Parameter Description
ID The ID of the library item.

Form Parameters

Parameter Type Description
cover Image Binary Data The cover to upload.

JSON Parameters

Parameter Type Description
url String The URL to download the cover from.

Response

Status Meaning Description Schema
200 OK Success See below.
400 Bad Request The request did not contain a file or URL.
403 Forbidden The user does not have permission to upload.
500 Internal Server Error Unknown error.

Response Schema

Attribute Type Description
success Boolean Whether the upload was successful.
cover String The full path of the cover on the server.

Update a Library Item's Cover

curl -X PATCH "https://abs.example.com/api/items/li_8gch9ve09orgn4fdz8/cover" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"cover": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg"}'

The above command returns JSON structured like this:

{
  "success": true,
  "cover": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg"
}

This endpoint updates a library item's cover with an image already on the server.

HTTP Request

PATCH http://abs.example.com/api/items/<ID>/cover

URL Parameters

Parameter Description
ID The ID of the library item.

Parameters

Parameter Type Description
cover String The absolute path of the image on the server to change the library item's cover to.

Response

Status Meaning Description Schema
200 OK Success See below.
400 Bad Request The cover parameter is required.
500 Internal Server Error Either the submitted path is invalid, does not exist, is not an image, or the server failed to copy the image to the library item's directory.

Response Schema

Attribute Type Description
success Boolean Whether the cover was updated successfully.
cover String The absolute path on the server of the library item's cover.

Remove a Library Item's Cover

curl -X DELETE "https://abs.example.com/api/items/li_8gch9ve09orgn4fdz8/cover" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

This endpoint removes a library item's cover.

HTTP Request

DELETE http://abs.example.com/api/items/<ID>/cover

URL Parameters

Parameter Description
ID The ID of the library item.

Response

Status Meaning Description
200 OK Success

Match a Library Item

curl -X POST "https://abs.example.com/api/items/li_8gch9ve09orgn4fdz8/match" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "openlibrary"}'

The above command returns JSON structured like this:

{
  "updated": true,
  "libraryItem": {
    "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",
            "tagComposer": "Terry Goodkind"
          },
          "mimeType": "audio/mpeg"
        },
        {
          "index": 2,
          "ino": "649644248522215261",
          "metadata": {
            "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "ext": ".mp3",
            "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "size": 47972352,
            "mtimeMs": 1632223180281,
            "ctimeMs": 1645978261001,
            "birthtimeMs": 0
          },
          "addedAt": 1650621074130,
          "updatedAt": 1651830828023,
          "trackNumFromMeta": 2,
          "discNumFromMeta": null,
          "trackNumFromFilename": 1,
          "discNumFromFilename": null,
          "manuallyVerified": false,
          "exclude": false,
          "error": null,
          "format": "MP2/3 (MPEG audio layer 2/3)",
          "duration": 5996.2785,
          "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 02",
            "tagTrack": "02/20",
            "tagAlbumArtist": "Terry Goodkind",
            "tagComposer": "Terry Goodkind"
          },
          "mimeType": "audio/mpeg"
        }
      ],
      "chapters": [
        {
          "id": 0,
          "start": 0,
          "end": 6004.6675,
          "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
        },
        {
          "id": 1,
          "start": 6004.6675,
          "end": 12000.946,
          "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02"
        }
      ],
      "duration": 33854.905,
      "size": 268824228,
      "tracks": [
        {
          "index": 1,
          "startOffset": 0,
          "duration": 6004.6675,
          "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
          "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
          "mimeType": "audio/mpeg",
          "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
          }
        },
        {
          "index": 2,
          "startOffset": 6004.6675,
          "duration": 5996.2785,
          "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "mimeType": "audio/mpeg",
          "metadata": {
            "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "ext": ".mp3",
            "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 03.mp3",
            "size": 47972352,
            "mtimeMs": 1632223180281,
            "ctimeMs": 1645978261001,
            "birthtimeMs": 0
          }
        }
      ],
      "ebookFile": null
    },
    "libraryFiles": [
      {
        "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": 1650621052494,
        "updatedAt": 1650621052494,
        "fileType": "audio"
      },
      {
        "ino": "649644248522215261",
        "metadata": {
          "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "ext": ".mp3",
          "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "size": 47972352,
          "mtimeMs": 1632223180281,
          "ctimeMs": 1645978261001,
          "birthtimeMs": 0
        },
        "addedAt": 1650621052494,
        "updatedAt": 1650621052494,
        "fileType": "audio"
      },
      {
        "ino": "649644248522215267",
        "metadata": {
          "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
        },
        "addedAt": 1650621052495,
        "updatedAt": 1650621052495,
        "fileType": "image"
      }
    ],
    "size": 268990279
  }
}

This endpoint matches the library item using quick match. Quick match populates empty book details and the cover with the first book result. Does not overwrite details unless the "Prefer matched metadata" server setting is enabled or the overrideDefaults parameter is true.

HTTP Request

POST http://abs.example.com/api/items/<ID>/match

URL Parameters

Parameter Description
ID The ID of the library item.

Parameters

Parameter Type Default Description
provider String google The metadata provider to search. See Metadata Providers for a list of options.
title String The library item's title. The title to search for.
author String The library item's author. The author to search for.
overrideDefaults Boolean false Whether to override the existing book details and cover. This will be true if the "Prefer matched metadata" server setting is enabled.
isbn String The book's ISBN. If the library item is a book, the ISBN to search for.
asin String The book's ASIN. If the library item is a book, the ASIN to search for.

Response

Status Meaning Description Schema
200 OK Success See below.

Response Schema

Attribute Type Description
updated Boolean Whether the library item was actually updated with new information.
libraryItem Library Item Expanded Object The updated library item.

Play a Library Item or Podcast Episode

curl -X POST "https://abs.example.com/api/items/li_bufnnmp4y5o2gbbxfm/play/ep_lh6ko39pumnrma3dhv" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"deviceInfo": {"clientVersion": "0.0.1"}, "supportedMimeTypes": ["audio/flac", "audio/mpeg", "audio/mp4"]}'

The above command returns JSON structured like this:

{
  "id": "play_c786zm3qtjz6bd5q3n",
  "userId": "root",
  "libraryId": "lib_p9wkw2i85qy9oltijt",
  "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
  "episodeId": "ep_lh6ko39pumnrma3dhv",
  "mediaType": "podcast",
  "mediaMetadata": {
    "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
  },
  "chapters": [],
  "displayTitle": "1 - Pilot",
  "displayAuthor": "Night Vale Presents",
  "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
  "duration": 1454.18449,
  "playMethod": 0,
  "mediaPlayer": "unknown",
  "deviceInfo": {
    "ipAddress": "192.168.1.118",
    "clientVersion": "0.0.1",
    "serverVersion": "2.2.2"
  },
  "date": "2022-11-11",
  "dayOfWeek": "Friday",
  "timeListening": 0,
  "startTime": 0,
  "currentTime": 0,
  "startedAt": 1668206493239,
  "updatedAt": 1668206493239,
  "audioTracks": [
    {
      "index": 1,
      "startOffset": 0,
      "duration": 1454.18449,
      "title": "1 - Pilot.mp3",
      "contentUrl": "/s/item/li_bufnnmp4y5o2gbbxfm/1 - Pilot.mp3",
      "mimeType": "audio/mpeg",
      "metadata": {
        "filename": "1 - Pilot.mp3",
        "ext": ".mp3",
        "path": "/podcasts/Welcome to Night Vale/1 - Pilot.mp3",
        "relPath": "1 - Pilot.mp3",
        "size": 23653735,
        "mtimeMs": 1667326682557,
        "ctimeMs": 1667326682557,
        "birthtimeMs": 1667326679508
      }
    }
  ],
  "videoTrack": null,
  "libraryItem": {
    "id": "li_bufnnmp4y5o2gbbxfm",
    "ino": "652",
    "libraryId": "lib_p9wkw2i85qy9oltijt",
    "folderId": "fol_crxarzs17jtw5k7ie9",
    "path": "/podcasts/Welcome to Night Vale",
    "relPath": "Welcome to Night Vale",
    "isFile": false,
    "mtimeMs": 1667326679508,
    "ctimeMs": 1667326679508,
    "birthtimeMs": 1667326662083,
    "addedAt": 1667326662087,
    "updatedAt": 1668157565937,
    "lastScan": 1667327311529,
    "scanVersion": "2.2.1",
    "isMissing": false,
    "isInvalid": false,
    "mediaType": "podcast",
    "media": {
      "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
      "metadata": {
        "title": "Welcome to Night Vale",
        "titleIgnorePrefix": "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
      },
      "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
      "tags": [],
      "episodes": [
        {
          "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
          "id": "ep_lh6ko39pumnrma3dhv",
          "index": 1,
          "season": "",
          "episode": "",
          "episodeType": "full",
          "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": "<div><br>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.<br><br></div><div><br>Weather: \"These and More Than These\" by Joseph Fink<br><br></div><div><br>Music: Disparition, disparition.info<br><br></div><div><br>Logo: Rob Wilson, silastom.com<br><br></div><div><br>Produced by Night Vale Presents. Written by Joseph Fink and Jeffrey Cranor. Narrated by Cecil Baldwin. More Info: welcometonightvale.com, and follow @NightValeRadio on Twitter or Facebook.<br><br></div>",
          "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"
          },
          "pubDate": "Fri, 15 Jun 2012 12:00:00 -0000",
          "audioFile": {
            "index": 1,
            "ino": "22587",
            "metadata": {
              "filename": "1 - Pilot.mp3",
              "ext": ".mp3",
              "path": "/podcasts/Welcome to Night Vale/1 - Pilot.mp3",
              "relPath": "1 - Pilot.mp3",
              "size": 23653735,
              "mtimeMs": 1667326682557,
              "ctimeMs": 1667326682557,
              "birthtimeMs": 1667326679508
            },
            "addedAt": 1667326682605,
            "updatedAt": 1667327311570,
            "trackNumFromMeta": null,
            "discNumFromMeta": null,
            "trackNumFromFilename": null,
            "discNumFromFilename": null,
            "manuallyVerified": false,
            "exclude": false,
            "error": null,
            "format": "MP2/3 (MPEG audio layer 2/3)",
            "duration": 1454.18449,
            "bitRate": 128000,
            "language": null,
            "codec": "mp3",
            "timeBase": "1/14112000",
            "channels": 2,
            "channelLayout": "stereo",
            "chapters": [],
            "embeddedCoverArt": "mjpeg",
            "metaTags": {
              "tagAlbum": "Welcome to Night Vale",
              "tagArtist": "Night Vale Presents",
              "tagGenre": "Podcast",
              "tagTitle": "1 - Pilot",
              "tagDate": "2012",
              "tagEncoder": "Lavf58.45.100"
            },
            "mimeType": "audio/mpeg"
          },
          "audioTrack": {
            "index": 1,
            "startOffset": 0,
            "duration": 1454.18449,
            "title": "1 - Pilot.mp3",
            "contentUrl": "/s/item/li_bufnnmp4y5o2gbbxfm/1 - Pilot.mp3",
            "mimeType": "audio/mpeg",
            "metadata": {
              "filename": "1 - Pilot.mp3",
              "ext": ".mp3",
              "path": "/podcasts/Welcome to Night Vale/1 - Pilot.mp3",
              "relPath": "1 - Pilot.mp3",
              "size": 23653735,
              "mtimeMs": 1667326682557,
              "ctimeMs": 1667326682557,
              "birthtimeMs": 1667326679508
            }
          },
          "publishedAt": 1339761600000,
          "addedAt": 1667326679503,
          "updatedAt": 1667428186431,
          "duration": 1454.18449,
          "size": 23653735
        }
      ],
      "autoDownloadEpisodes": false,
      "autoDownloadSchedule": "0 0 * * 1",
      "lastEpisodeCheck": 1667326662087,
      "maxEpisodesToKeep": 0,
      "maxNewEpisodesToDownload": 3,
      "size": 23653735
    },
    "libraryFiles": [
      {
        "ino": "22587",
        "metadata": {
          "filename": "1 - Pilot.mp3",
          "ext": ".mp3",
          "path": "/podcasts/Welcome to Night Vale/1 - Pilot.mp3",
          "relPath": "1 - Pilot.mp3",
          "size": 23653735,
          "mtimeMs": 1667326682557,
          "ctimeMs": 1667326682557,
          "birthtimeMs": 1667326679508
        },
        "addedAt": 1667326682561,
        "updatedAt": 1667326682561,
        "fileType": "audio"
      },
      {
        "ino": "10113",
        "metadata": {
          "filename": "cover.jpg",
          "ext": ".jpg",
          "path": "/podcasts/Welcome to Night Vale/cover.jpg",
          "relPath": "cover.jpg",
          "size": 52993,
          "mtimeMs": 1667326662178,
          "ctimeMs": 1667326662184,
          "birthtimeMs": 1667326662090
        },
        "addedAt": 1667327311529,
        "updatedAt": 1667327311529,
        "fileType": "image"
      }
    ],
    "size": 23706728
  }
}

This endpoint starts a playback session for a library item or podcast episode.

HTTP Request

URL Parameters

Parameter Description
ID The ID of the library item.
EpisodeID The ID of the podcast episode.

Parameters

Parameter Type Default Description
deviceInfo Device Info Parameters Object (See Below) Information about the device.
forceDirectPlay Boolean false Whether to force direct play of the library item.
forceTranscode Boolean false Whether to force the server to transcode the audio.
supportedMimeTypes Array of String [] The MIME types that are supported by the client. If the MIME type of the audio file is not in this list, the server will transcode it.
mediaPlayer String unknown The media player the client is using.

Device Info Parameters

Parameter Type Description
deviceId String The client device identifier.
clientName String The name of the client.
clientVersion String The version of the client.
manufacturer String The manufacturer of the client device.
model String The model of the client device.
sdkVersion Integer For an Android client, the Android SDK version of the client.

Response

Status Meaning Description Schema
200 OK Success Playback Session Expanded
404 Not Found The library item does not have any audio tracks to play.

Update a Library Item's Audio Tracks

curl -X PATCH "https://abs.example.com/api/items/li_bufnnmp4y5o2gbbxfm/tracks" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"orderedFileData": [{"ino": "649644248522215260"}, {"ino": "649644248522215261"}]}'

The above command returns JSON structured like this:

{
  "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,
  "lastScan": 1651830827825,
  "scanVersion": "2.0.21",
  "isMissing": false,
  "isInvalid": false,
  "mediaType": "book",
  "media": {
    "libraryItemId": "li_8gch9ve09orgn4fdz8",
    "metadata": {
      "title": "Wizards First Rule",
      "subtitle": null,
      "authors": [
        {
          "id": "aut_z3leimgybl7uf3y4ab",
          "name": "Terry Goodkind"
        }
      ],
      "narrators": [
        "Sam Tsoutsouvas"
      ],
      "series": [
        {
          "id": "ser_cabkj4jeu8be3rap4g",
          "name": "Sword of Truth",
          "sequence": null
        }
      ],
      "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": [],
    "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",
          "tagComposer": "Terry Goodkind"
        },
        "mimeType": "audio/mpeg"
      },
      {
        "index": 2,
        "ino": "649644248522215261",
        "metadata": {
          "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "ext": ".mp3",
          "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
          "size": 47972352,
          "mtimeMs": 1632223180281,
          "ctimeMs": 1645978261001,
          "birthtimeMs": 0
        },
        "addedAt": 1650621074130,
        "updatedAt": 1651830828023,
        "trackNumFromMeta": 2,
        "discNumFromMeta": null,
        "trackNumFromFilename": 1,
        "discNumFromFilename": null,
        "manuallyVerified": false,
        "exclude": false,
        "error": null,
        "format": "MP2/3 (MPEG audio layer 2/3)",
        "duration": 5996.2785,
        "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 02",
          "tagTrack": "02/20",
          "tagAlbumArtist": "Terry Goodkind",
          "tagComposer": "Terry Goodkind"
        },
        "mimeType": "audio/mpeg"
      }
    ],
    "chapters": [
      {
        "id": 0,
        "start": 0,
        "end": 6004.6675,
        "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
      },
      {
        "id": 1,
        "start": 6004.6675,
        "end": 12000.946,
        "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02"
      }
    ],
    "ebookFile": null
  },
  "libraryFiles": [
    {
      "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": 1650621052494,
      "updatedAt": 1650621052494,
      "fileType": "audio"
    },
    {
      "ino": "649644248522215261",
      "metadata": {
        "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
        "ext": ".mp3",
        "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
        "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
        "size": 47972352,
        "mtimeMs": 1632223180281,
        "ctimeMs": 1645978261001,
        "birthtimeMs": 0
      },
      "addedAt": 1650621052494,
      "updatedAt": 1650621052494,
      "fileType": "audio"
    },
    {
      "ino": "649644248522215267",
      "metadata": {
        "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
      },
      "addedAt": 1650621052495,
      "updatedAt": 1650621052495,
      "fileType": "image"
    }
  ]
}

This endpoint updates the order of and whether to exclude a library item's audio files. This only applies to books. The updated library item is returned.

HTTP Request

PATCH http://abs.example.com/api/items/<ID>/tracks

URL Parameters

Parameter Description
ID The ID of the library item.

Parameters

Parameter Type Description
orderedFileData Array of Audio File Data Parameters (See Below) The audio file data in the wanted order.

Audio File Data Parameters

Parameter Type Default Description
ino String Required The inode of the audio file. This is how the server matches this entry to the correct audio file.
exclude Boolean false Whether to exclude the audio file from playback. Excluded audio files will have their index set to -1.

Response

Status Meaning Description Schema
200 OK Success Library Item
500 Internal Server Error The library item's media type must be book for this endpoint.

Scan a Library Item

curl -X POST "https://abs.example.com/api/items/li_bufnnmp4y5o2gbbxfm/scan" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "result": "UPDATED"
}

This endpoint scans a library item's files for changes.

HTTP Request

POST http://abs.example.com/api/items/<ID>/scan

URL Parameters

Parameter Description
ID The ID of the library item.

Response

Status Meaning Description Schema
200 OK Success See below.
403 Forbidden An admin user is required to scan a library item.
500 Internal Server Error Rescanning file library items is not yet supported.

Response Schema

Attribute Type Description
result String The result of the scan operation. Can be NOTHING, ADDED, UPDATED, REMOVED, or UPTODATE.

Get a Library Item's Tone Metadata Object

curl "https://abs.example.com/api/items/li_bufnnmp4y5o2gbbxfm/tone-object" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "Title": "Wizards First Rule",
  "Album": "Wizards First Rule",
  "TrackTotal": 2,
  "Artist": "Terry Goodkind",
  "AlbumArtist": "Terry Goodkind",
  "Comment": "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.",
  "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.",
  "Narrator": "Sam Tsoutsouvas",
  "Composer": "Sam Tsoutsouvas",
  "MovementName": "Sword of Truth",
  "Movement": "1",
  "Genre": "Fantasy",
  "Publisher": "Brilliance Audio",
  "CoverFile": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
  "PublishingDate": "01/01/2008",
  "AdditionalFields": [
    "ASIN=B002V0QK4C"
  ]
}

This endpoint returns a library item's tone metadata object.

HTTP Request

GET http://abs.example.com/api/items/<ID>/tone-object

URL Parameters

Parameter Description
ID The ID of the library item.

Response

Status Meaning Description Schema
200 OK Success See below.
403 Forbidden An admin user is required to get a library item's tone metadata object.
500 Internal Server Error The library item has missing parts, does not have audio files, or is not a book.

Response Schema

Book metadata that is null will not exist in the response object, except for the title which will be replaced by an empty string.

Attribute Type Description
Title String The book's title.
Album String The book's title.
TrackTotal Integer The number of audio tracks for the book.
Artist String The book's author.
AlbumArtist String The book's author.
Comment String The book's description.
Description String The book's description.
Narrator String The book's narrators.
Composer String The book's narrators.
MovementName String The book's first series.
Movement String The sequence of the book in its first series.
Genre String All of the book's genres / separated.
Publisher String The book's publisher.
CoverFile String The book's cover path.
PublishingDate String January 1st of the book's published year.
AdditionalFields Array of String Additional metadata fields. Those are currently ASIN and ISBN.

Update a Library Item's Chapters

curl -X POST "https://abs.example.com/api/items/li_bufnnmp4y5o2gbbxfm/chapters" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"chapters": [{"id": 0, "start": 0, "end": 6004.6675, "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"}, {"id": 1, "start": 6004.6675, "end": 12000.946, "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02"}]}'

The above command returns JSON structured like this:

{
  "success": true,
  "updated": false
}

This endpoint updates a library item's chapters. This only applies to books.

HTTP Request

POST http://abs.example.com/api/items/<ID>/chapters

URL Parameters

Parameter Description
ID The ID of the library item.

Parameters

Parameter Type Description
chapters Array of Book Chapter The requested book chapters, in order.

Response

Status Meaning Description Schema
200 OK Success See below.
400 Bad Request The provided chapter list must have a non-zero length.
403 Forbidden The user does not have permission to update a library item.
500 Internal Server Error The library item has missing parts, does not have audio files, or is not a book.

Response Schema

Attribute Type Description
success Boolean Whether the update succeeded.
updated Boolean Whether the book's chapters were actually changed.

Tone Scan a Library Item

curl -X POST "https://abs.example.com/api/items/li_bufnnmp4y5o2gbbxfm/tone-scan/1" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "audio": {
    "bitrate": 64,
    "format": "MPEG Audio (Layer III)",
    "formatShort": "MPEG",
    "sampleRate": 22050,
    "duration": 6004667,
    "channels": {
      "count": 2,
      "description": "Joint Stereo"
    },
    "frames": {
      "offset": 3857,
      "length": 66381321
    },
    "metaFormat": [
      "id3V23",
      "id3V1"
    ]
  },
  "meta": {
    "album": "Sword of Truth",
    "albumArtist": "Terry Goodkind",
    "artist": "Terry Goodkind",
    "composer": "Sam Tsoutsouvas",
    "comment": "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.",
    "encoderSettings": "LAME 32bits version 3.99.5 (http://lame.sf.net)",
    "genre": "Fantasy",
    "recordingDate": "2008-01-01T00:00:00",
    "title": "Wizards First Rule",
    "trackNumber": 1,
    "additionalFields": {
      "ufid": "FID",
      "narratedby": "ARRATEDBY",
      "woas": "OAS"
    }
  },
  "file": {
    "size": 48037888,
    "created": "2022-04-22T09:51:14.299+00:00",
    "modified": "2022-04-22T09:51:14.299+00:00",
    "accessed": "2022-04-22T09:51:14.299+00:00",
    "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
    "name": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3"
  }
}

This endpoint uses tone to scan a library item and returns the results.

HTTP Request

POST http://abs.example.com/api/items/<ID>/tone-scan/<Index?>

URL Parameters

Parameter Type Default Description
ID String Required The ID of the library item.
Index Integer 1 The index of the audio file to tone scan.

Response

Status Meaning Description Schema
200 OK Success See below.
404 Not Found The library does not have any audio files to scan or the requested audio file index does not exist.

Response Schema

See tone for details.

Attribute Type Description
audio.bitrate Integer The bitrate of the audio file.
audio.format String The format of the audio file.
audio.formatShort String The short format of the audio file.
audio.duration Integer The duration (in ms) of the audio file.
audio.channels.count Integer The number of audio channels in the audio file.
audio.channels.description String The description of the channel setup of the audio file.
audio.frames.offset Integer The frame offset of the audio file.
audio.frames.length Integer The frame length of the audio file.
audio.metaFormat Array of String The metadata formats of the audio file.
meta Object The metadata tags of the audio file.
file.size Integer The size (in bytes) of the audio file.
file.created String When the audio file was created.
file.modified String When the audio file was last modified.
file.accessed String When the audio file was last accessed.
file.path String The parent path of the audio file.
file.name String The filename of the audio file.

Batch Delete Library Items

curl -X POST "https://abs.example.com/api/items/batch/delete" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"libraryItemIds: ["li_bufnnmp4y5o2gbbxfm"]}'

This endpoint batch deletes library items from the database. No files are deleted.

HTTP Request

POST http://abs.example.com/api/items/batch/delete

Parameters

Parameter Type Description
libraryItemIds Array of String The IDs of library items to delete.

Response

Status Meaning Description
200 OK Success
403 Forbidden The user does not have permission to delete library items.
404 Not Found None of the IDs provided match any library items.
500 Internal Server Error The libraryItemIds array must have a non-zero length.

Batch Update Library Items

curl -X POST "https://abs.example.com/api/items/batch/update" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '["id": "li_8gch9ve09orgn4fdz8", "mediaPayload": {"metadata": {"title": "Wizards First Rule"}}]'

The above command returns JSON structured like this:

{
  "success": true,
  "updates": 1
}

This endpoint batch updates library items.

HTTP Request

POST http://abs.example.com/api/items/batch/update

Parameters

Provide an array of objects with the following parameters:

Parameter Type Description
id String The ID of the library item to update.
mediaPayload Book Parameters or Podcast Parameters See Update a Library Item's Media for details.

Response

Status Meaning Description Schema
200 OK Success See below.
403 Forbidden The user does not have permission to update library items.
500 Internal Server Error The provided array must have a non-zero length.

Response Schema

Attribute Type Description
success Boolean Whether library items were updated successfully.
updates Integer The number library items that were actually changed.

Batch Get Library Items

curl -X POST "https://abs.example.com/api/items/batch/get" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"libraryItemIds": ["li_8gch9ve09orgn4fdz8"]}'

The above command returns JSON structured like this:

{
  "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",
              "tagComposer": "Terry Goodkind"
            },
            "mimeType": "audio/mpeg"
          },
          {
            "index": 2,
            "ino": "649644248522215261",
            "metadata": {
              "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "ext": ".mp3",
              "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "size": 47972352,
              "mtimeMs": 1632223180281,
              "ctimeMs": 1645978261001,
              "birthtimeMs": 0
            },
            "addedAt": 1650621074130,
            "updatedAt": 1651830828023,
            "trackNumFromMeta": 2,
            "discNumFromMeta": null,
            "trackNumFromFilename": 1,
            "discNumFromFilename": null,
            "manuallyVerified": false,
            "exclude": false,
            "error": null,
            "format": "MP2/3 (MPEG audio layer 2/3)",
            "duration": 5996.2785,
            "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 02",
              "tagTrack": "02/20",
              "tagAlbumArtist": "Terry Goodkind",
              "tagComposer": "Terry Goodkind"
            },
            "mimeType": "audio/mpeg"
          }
        ],
        "chapters": [
          {
            "id": 0,
            "start": 0,
            "end": 6004.6675,
            "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
          },
          {
            "id": 1,
            "start": 6004.6675,
            "end": 12000.946,
            "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02"
          }
        ],
        "duration": 33854.905,
        "size": 268824228,
        "tracks": [
          {
            "index": 1,
            "startOffset": 0,
            "duration": 6004.6675,
            "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
            "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
            "mimeType": "audio/mpeg",
            "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
            }
          },
          {
            "index": 2,
            "startOffset": 6004.6675,
            "duration": 5996.2785,
            "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "mimeType": "audio/mpeg",
            "metadata": {
              "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "ext": ".mp3",
              "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 03.mp3",
              "size": 47972352,
              "mtimeMs": 1632223180281,
              "ctimeMs": 1645978261001,
              "birthtimeMs": 0
            }
          }
        ],
        "ebookFile": null
      },
      "libraryFiles": [
        {
          "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": 1650621052494,
          "updatedAt": 1650621052494,
          "fileType": "audio"
        },
        {
          "ino": "649644248522215261",
          "metadata": {
            "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "ext": ".mp3",
            "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "size": 47972352,
            "mtimeMs": 1632223180281,
            "ctimeMs": 1645978261001,
            "birthtimeMs": 0
          },
          "addedAt": 1650621052494,
          "updatedAt": 1650621052494,
          "fileType": "audio"
        },
        {
          "ino": "649644248522215267",
          "metadata": {
            "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
          },
          "addedAt": 1650621052495,
          "updatedAt": 1650621052495,
          "fileType": "image"
        }
      ],
      "size": 268990279
    }
  ]
}

This endpoint batch gets library items.

HTTP Request

POST http://abs.example.com/api/items/batch/get

Parameters

Parameter Type Description
libraryItemIds Array of String The IDs of library items to get.

Response

Status Meaning Description Schema
200 OK Success See Below
403 Forbidden The libraryItemIds array must have a non-zero length.

Response Schema

Attribute Type Description
libraryItems Array of Library Item Expanded The requested library items.

Batch Quick Match Library Items

curl -X POST "https://abs.example.com/api/items/batch/quickmatch" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"options": {"provider": "openlibrary"}, "libraryItemIds: ["li_8gch9ve09orgn4fdz8"]}'

This endpoint batch matches library items using quick match. Quick match populates empty book details and the cover with the first book result. Does not overwrite existing details unless the "Prefer matched metadata" server setting is enabled or the overrideDefaults parameter is true.

HTTP Request

POST http://abs.example.com/api/items/batch/quickmatch

Parameters

Parameter Type Description
options Options Parameters Object (See Below) The options to use when quick matching.
libraryItemIds Array of String The IDs of library items to quick match.

Options Parameters

Parameter Type Default Description
provider String google The metadata provider to search. See Metadata Providers for a list of options.
overrideDefaults Boolean false Whether to override the existing book details and cover. This will be true if the "Prefer matched metadata" server setting is enabled.

Response

Status Meaning Description
200 OK Success
403 Forbidden An admin user is required to quick match library items.
500 Internal Server Error The libraryItemIds array must have a non-zero length.

Users

Create a User

curl -X POST "https://abs.example.com/api/users" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"username": "bob", "password": "12345", "type": "admin"}'

The above command returns JSON structured like this:

{
  "id": "usr_3vn1ywq2yc2aq4kfh4",
  "username": "bob",
  "type": "admin",
  "token": "exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY",
  "mediaProgress": [],
  "seriesHideFromContinueListening": [],
  "bookmarks": [],
  "isActive": true,
  "isLocked": false,
  "lastSeen": null,
  "createdAt": 1666569607117,
  "permissions": {
    "download": true,
    "update": true,
    "delete": false,
    "upload": true,
    "accessAllLibraries": true,
    "accessAllTags": true,
    "accessExplicitContent": true
  },
  "librariesAccessible": [],
  "itemTagsAccessible": []
}

This endpoint creates a user.

HTTP Request

POST http://abs.example.com/api/users

Parameters

Parameter Type Default Description
username String Required The new user's username.
password String Required The new user's password.
type String Required The new user's type. May be guest, user, or admin.
mediaProgress Array of Media Progress [] The new user's media progress.
bookmarks Array of Audio Bookmark [] The new user's bookmarks.
seriesHideFromContinueListening Array of String [] The IDs of series to hide from the new user's "Continue Series" shelf.
isActive Boolean true Whether the new user's account is active.
isLocked Boolean false Whether the new user is locked.
lastSeen Integer or null null The time (in ms since POSIX epoch) when the new user was last seen.
createdAt Integer Date.now() The time (in ms since POSIX epoch) when the new user was created.
permissions User Permissions Parameters Object See Below The new user's permissions.
librariesAccessible Array of String [] The IDs of libraries that are accessible to the new user. An empty array means all libraries are accessible.
itemTagsAccessible Array of String [] The tags that are accessible to the new user. An empty array means all tags are accessible.

User Permissions Parameters

Parameter Type Default Description
download Boolean true Whether the user can download items from the server.
update Boolean true Whether the user can update library items.
delete Boolean false Whether the user can delete library items.
upload Boolean false Whether the user can upload items to the server. The default value is true if the user's type is admin.
accessAllLibraries Boolean true Whether the user can access all libraries.
accessAllTags Boolean true Whether the user can access all tags.
accessExplicitContent Boolean true Whether the user can access explicit content.

Response

Status Meaning Description Schema
200 OK Success User
403 Forbidden The user does not have permission to create new users.
500 Internal Server Error Either the username provided is already taken, or the server failed to save the new user.

Get All Users

curl "https://abs.example.com/api/users" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "users": [
    {
      "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": []
    }
  ]
}

This endpoint retrieves all users.

HTTP Request

GET http://abs.example.com/api/users

Response

Status Meaning Description Schema
200 OK Success See Below
403 Forbidden An admin user is required to get all users.

Response Schema

Attribute Type Description
users Array of User with Progress Details The requested users.

Get Online Users

curl "https://abs.example.com/api/users/online" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "usersOnline": [
    {
      "id": "root",
      "username": "paul",
      "type": "root",
      "session": null,
      "lastSeen": 1668324661087,
      "createdAt": 1666543632566
    }
  ],
  "openSessions": [
    {
      "id": "play_3m7y81exxkpodebwvd",
      "userId": "root",
      "libraryId": "lib_p9wkw2i85qy9oltijt",
      "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
      "episodeId": "ep_lh6ko39pumnrma3dhv",
      "mediaType": "podcast",
      "mediaMetadata": {
        "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
      },
      "chapters": [],
      "displayTitle": "1 - Pilot",
      "displayAuthor": "Night Vale Presents",
      "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
      "duration": 1454.18449,
      "playMethod": 0,
      "mediaPlayer": "html5",
      "deviceInfo": {
        "ipAddress": "192.168.1.118",
        "browserName": "Firefox",
        "browserVersion": "106.0",
        "osName": "Linux",
        "osVersion": "x86_64",
        "serverVersion": "2.2.3"
      },
      "date": "2022-11-13",
      "dayOfWeek": "Sunday",
      "timeListening": 595,
      "startTime": 0,
      "currentTime": 595,
      "startedAt": 1668329239515,
      "updatedAt": 1668329240593
    }
  ]
}

This endpoint retrieves all online users.

HTTP Request

GET http://abs.example.com/api/users/online

Response

Status Meaning Description Schema
200 OK Success See below.
403 Forbidden An admin user is required to get users.

Response Schema

Attribute Type Description
usersOnline Array of User with Session The users that are currently online.
openSessions Array of Playback Session The currently playing playback sessions.

Get a User

curl "https://abs.example.com/api/users/root" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "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": []
}

This endpoint retrieves a user.

HTTP Request

GET http://abs.example.com/api/users/<ID>

URL Parameters

Parameter Description
ID The ID of the user.

Response

Status Meaning Description Schema
200 OK Success User with Progress Details
403 Forbidden An admin user is required to get users.
404 Not Found No user with the provided ID exists.

Update a User

curl -X PATCH "https://abs.example.com/api/users/root" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"username": "bob", "password": "12345"}'

The above command returns JSON structured like this:

{
  "id": "root",
  "username": "bob",
  "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": []
}

This endpoint updates a user.

HTTP Request

PATCH http://abs.example.com/api/users/<ID>

URL Parameters

Parameter Description
ID The ID of the user.

Parameters

For the root user, only username and password are changeable.

Parameter Type Description
username String The user's username.
password String The user's password.
type String The user's type. May be guest, user, or admin.
seriesHideFromContinueListening Array of String The IDs of series to hide from the user's "Continue Series" shelf.
isActive Boolean Whether the user's account is active.
permissions User Permissions Parameters Object (See Below) The user's permissions.
librariesAccessible Array of String The IDs of libraries that are accessible to the user. An empty array means all libraries are accessible.
itemTagsAccessible Array of String The tags that are accessible to the user. An empty array means all tags are accessible.

User Permissions Parameters

Parameter Type Description
download Boolean Whether the user can download items from the server.
update Boolean Whether the user can update library items.
delete Boolean Whether the user can delete library items.
upload Boolean Whether the user can upload items to the server.
accessAllLibraries Boolean Whether the user can access all libraries.
accessAllTags Boolean Whether the user can access all tags.
accessExplicitContent Boolean Whether the user can access explicit content.

Response

Status Meaning Description Schema
200 OK Success See below.
403 Forbidden An admin user is required to edit users and the root user is required to edit the root user.
404 Not Found No user with the provided ID exists.
500 Internal Server Error The provided username is already taken.

Response Schema

Attribute Type Description
success Boolean Whether the user was updated successfully.
user User Object The updated user.

Delete a User

curl -X DELETE "https://abs.example.com/api/users/usr_rfk7dgyjp8kg4waewi" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "success": true
}

This endpoint deletes a user.

HTTP Request

DELETE http://abs.example.com/api/users/<ID>

URL Parameters

Parameter Description
ID The ID of the user.

Response

Status Meaning Description Schema
200 OK Success See below.
404 Not Found No user with the provided ID exists.
500 Internal Server Error The root user cannot be deleted and users cannot delete themselves.

Response Schema

Attribute Type Description
success Boolean Whether the user was successfully deleted.

Get a User's Listening Sessions

curl "https://abs.example.com/api/users/root/listening-sessions?itemsPerPage=1" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "total": 37,
  "numPages": 37,
  "page": 0,
  "itemsPerPage": 1,
  "sessions": [
    {
      "id": "play_4oq00chunexu9s03jw",
      "userId": "root",
      "libraryId": "lib_p9wkw2i85qy9oltijt",
      "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
      "episodeId": "ep_lh6ko39pumnrma3dhv",
      "mediaType": "podcast",
      "mediaMetadata": {
        "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
      },
      "chapters": [],
      "displayTitle": "1 - Pilot",
      "displayAuthor": "Night Vale Presents",
      "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
      "duration": 1454.18449,
      "playMethod": 0,
      "mediaPlayer": "html5",
      "deviceInfo": {
        "ipAddress": "192.168.1.118",
        "browserName": "Firefox",
        "browserVersion": "106.0",
        "osName": "Linux",
        "osVersion": "x86_64",
        "serverVersion": "2.2.3"
      },
      "date": "2022-11-13",
      "dayOfWeek": "Sunday",
      "timeListening": 15,
      "startTime": 596.779402,
      "currentTime": 611.590717,
      "startedAt": 1668330137087,
      "updatedAt": 1668330152157
    }
  ]
}

This endpoint retrieves a user's listening sessions.

HTTP Request

GET http://abs.example.com/api/users/<ID>/listening-sessions

URL Parameters

Parameter Description
ID The ID of the user.

Query Parameters

Parameter Type Default Description
itemsPerPage Integer 10 The number of listening sessions to retrieve per page.
page Integer 0 The page (0 indexed) to retrieve.

Response

Status Meaning Description Schema
200 OK Success See below.
404 Not Found No user with the provided ID exists.

Response Schema

Attribute Type Description
total Integer The total number of listening sessions.
numPages Integer The total number of pages when using this itemsPerPage limit.
itemsPerPage Integer The provided itemsPerPage parameter.
sessions Array of Playback Session The requested listening sessions.

Get a User's Listening Stats

curl "https://abs.example.com/api/users/root/listening-stats" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "totalTime": 493,
  "items": {
    "li_bufnnmp4y5o2gbbxfm": {
      "id": "li_bufnnmp4y5o2gbbxfm",
      "timeListening": 63,
      "mediaMetadata": {
        "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,
        "type": "episodic"
      }
    },
    ...
  },
  "days": {
    "2022-11-13": 104,
    "2022-11-12": 3,
    "2022-11-11": 1,
    "2022-11-10": 30,
    "2022-11-06": 14,
    "2022-11-05": 12,
    "2022-11-04": 20,
    "2022-10-26": 12,
    "2022-10-25": 206,
    "2022-10-24": 73,
    "2022-10-23": 12
  },
  "dayOfWeek": {
    "Sunday": 130,
    "Saturday": 15,
    "Friday": 21,
    "Thursday": 30,
    "Wednesday": 12,
    "Tuesday": 206,
    "Monday": 73
  },
  "today": 104,
  "recentSessions": [
    {
      "id": "play_4oq00chunexu9s03jw",
      "userId": "root",
      "libraryId": "lib_p9wkw2i85qy9oltijt",
      "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
      "episodeId": "ep_lh6ko39pumnrma3dhv",
      "mediaType": "podcast",
      "mediaMetadata": {
        "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,
        "type": "episodic"
      },
      "chapters": [],
      "displayTitle": "1 - Pilot",
      "displayAuthor": "Night Vale Presents",
      "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
      "duration": 1454.18449,
      "playMethod": 0,
      "mediaPlayer": "html5",
      "deviceInfo": {
        "ipAddress": "192.168.1.118",
        "browserName": "Firefox",
        "browserVersion": "106.0",
        "osName": "Linux",
        "osVersion": "x86_64",
        "serverVersion": "2.2.3"
      },
      "date": "2022-11-13",
      "dayOfWeek": "Sunday",
      "timeListening": 15,
      "startTime": 596.779402,
      "currentTime": 611.590717,
      "startedAt": 1668330137087,
      "updatedAt": 1668330152157
    },
    ...
  ]
}

This endpoint retrieves a user's listening statistics.

HTTP Request

GET http://abs.example.com/api/users/<ID>/listening-stats

URL Parameters

Parameter Description
ID The ID of the user.

Response

Status Meaning Description Schema
200 OK Success See below.
404 Not Found No user with the provided ID exists.

Response Schema

Attribute Type Description
totalTime Integer The total time (in seconds) the user has listened to library items.
items Items Listened To Object (See Below) The library items that the user has listened to.
days Day Time Totals Object (See Below) The total time the user has listened to library items on each day.
dayOfWeek Day of Week Totals Object (See Below) The total time the user has listened to library items on each day of the week.
today Integer The time (in seconds) the user has listened to library items today.
recentSessions Array of Playback Session The 10 most recent playback sessions for the user.

Items Listened To

The keys of this object are the library item IDs of the item listened to. The value of each key is an object of the following structure:

Attribute Type Description
id String The ID of the library item that was listened to by the user.
timeListening Integer The time (in seconds) the user listened to the library item.
mediaMetadata Book Metadata or Podcast Metadata Object The metadata of the library item's media.

Day Time Totals

The keys of this object are each day (in the format YYYY-MM-DD) when the user listened to library items. The values are the total time (in seconds, Integer) the user listened to library items.

Day of Week Totals

The keys of this object are each day of the week. The values are the total time (in seconds, Integer) the user listened to library items on that day of the week.

Purge a User's Media Progress

curl -X POST "https://abs.example.com/api/users/root/purge-media-progress" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "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": []
}

This endpoint removes the user's media progress for library items that no longer exist.

HTTP Request

POST http://abs.example.com/api/users/<ID>/purge-media-progress

URL Parameters

Parameter Description
ID The ID of the user.

Response

Status Meaning Description Schema
200 OK Success User with Progress Details
403 Forbidden Only the root user can purge the root user's media progress.
404 Not Found No user with the provided ID exists.

Collections

Create a Collection

curl -X POST "https://abs.example.com/api/collections" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"libraryId": "lib_c1u6t4p45c35rf0nzd", "name": "Favorites"}'

The above command returns JSON structured like this:

{
  "id": "col_fpfstanv6gd7tq2qz7",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "Favorites",
  "description": null,
  "books": [],
  "lastUpdate": 1650621073750,
  "createdAt": 1650621073750
}

This endpoint creates a collection and returns it.

HTTP Request

POST http://abs.example.com/api/collections

Parameters

Parameter Type Default Description
libraryId String Required The ID of the library the collection belongs to.
name String Required The name of the collection.
description String or null null The collection's description.
books Array of String [] The IDs of book library items that are in the collection.

Response

Status Meaning Description Schema
200 OK Success Collection Expanded
403 Forbidden A user with update permissions is required to create collections.
500 Internal Server Error libraryId and name are required parameters.

Get All Collections

curl "https://abs.example.com/api/collections" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "collections": [
    {
      "id": "col_fpfstanv6gd7tq2qz7",
      "libraryId": "lib_c1u6t4p45c35rf0nzd",
      "userId": "root",
      "name": "Favorites",
      "description": null,
      "books": [],
      "lastUpdate": 1650621073750,
      "createdAt": 1650621073750
    }
  ]
}

This endpoint retrieves all collections.

HTTP Request

GET http://abs.example.com/api/collections

Response

Status Meaning Description Schema
200 OK Success See Below

Response Schema

Attribute Type Description
collections Array of Collection Expanded The requested collections.

Get a Collection

curl "https://abs.example.com/api/collections/col_fpfstanv6gd7tq2qz7" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "id": "col_fpfstanv6gd7tq2qz7",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "Favorites",
  "description": null,
  "books": [],
  "lastUpdate": 1650621073750,
  "createdAt": 1650621073750
}

This endpoint retrieves a collection.

HTTP Request

GET http://abs.example.com/api/collections/<ID>

URL Parameters

Parameter Description
ID The ID of the collection.

Optional Query Parameters

Parameter Type Description
include String A comma separated list of what to include with the library item. The only current option is rssfeed.

Response

Status Meaning Description Schema
200 OK Success Collection Expanded, with extra rssFeed attribute (see below) if requested.
404 Not Found No collection with the specified ID exists.

Extra Attributes

Attribute Type Description
rssFeed RSS Feed Minified Object or null If rssfeed was requested, the collection's currently open RSS feed. Will be null if the collection does not have an open RSS feed.

Update a Collection

curl -X PATCH "https://abs.example.com/api/collections/col_fpfstanv6gd7tq2qz7" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"name": "The Best Books"}'

The above command returns JSON structured like this:

{
  "id": "col_fpfstanv6gd7tq2qz7",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "The Best Books",
  "description": null,
  "books": [],
  "lastUpdate": 1650621110769,
  "createdAt": 1650621073750
}

This endpoint updates a collection and returns it.

HTTP Request

PATCH http://abs.example.com/api/collections/<ID>

URL Parameters

Parameter Description
ID The ID of the collection.

Parameters

Parameter Type Description
libraryId String The ID of the library the collection belongs to.
name String The name of the collection.
description String or null The collection's description.
books Array of String The IDs of book library items that are in the collection.

Response

Status Meaning Description Schema
200 OK Success Collection Expanded
403 Forbidden A user with update permissions is required to update collections.
404 Not Found No collection with the specified ID exists.

Delete a Collection

curl -X DELETE "https://abs.example.com/api/collections/col_fpfstanv6gd7tq2qz7" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

This endpoint deletes a collection from the database.

HTTP Request

DELETE http://abs.example.com/api/collections/<ID>

URL Parameters

Parameter Description
ID The ID of the collection.

Response

Status Meaning Description
200 OK Success
403 Forbidden A user with delete permissions is required to delete a collection.
404 Not Found No collection with the specified ID exists.

Add a Book to a Collection

curl -X POST "https://abs.example.com/api/collections/col_fpfstanv6gd7tq2qz7/book" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"id": "li_8gch9ve09orgn4fdz8"}'

The above command returns JSON structured like this:

{
  "id": "col_fpfstanv6gd7tq2qz7",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "The Best Books",
  "description": null,
  "books": [
    {
      "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",
              "tagComposer": "Terry Goodkind"
            },
            "mimeType": "audio/mpeg"
          },
          {
            "index": 2,
            "ino": "649644248522215261",
            "metadata": {
              "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "ext": ".mp3",
              "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "size": 47972352,
              "mtimeMs": 1632223180281,
              "ctimeMs": 1645978261001,
              "birthtimeMs": 0
            },
            "addedAt": 1650621074130,
            "updatedAt": 1651830828023,
            "trackNumFromMeta": 2,
            "discNumFromMeta": null,
            "trackNumFromFilename": 1,
            "discNumFromFilename": null,
            "manuallyVerified": false,
            "exclude": false,
            "error": null,
            "format": "MP2/3 (MPEG audio layer 2/3)",
            "duration": 5996.2785,
            "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 02",
              "tagTrack": "02/20",
              "tagAlbumArtist": "Terry Goodkind",
              "tagComposer": "Terry Goodkind"
            },
            "mimeType": "audio/mpeg"
          }
        ],
        "chapters": [
          {
            "id": 0,
            "start": 0,
            "end": 6004.6675,
            "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
          },
          {
            "id": 1,
            "start": 6004.6675,
            "end": 12000.946,
            "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02"
          }
        ],
        "duration": 33854.905,
        "size": 268824228,
        "tracks": [
          {
            "index": 1,
            "startOffset": 0,
            "duration": 6004.6675,
            "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
            "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
            "mimeType": "audio/mpeg",
            "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
            }
          },
          {
            "index": 2,
            "startOffset": 6004.6675,
            "duration": 5996.2785,
            "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "mimeType": "audio/mpeg",
            "metadata": {
              "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "ext": ".mp3",
              "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 03.mp3",
              "size": 47972352,
              "mtimeMs": 1632223180281,
              "ctimeMs": 1645978261001,
              "birthtimeMs": 0
            }
          }
        ],
        "ebookFile": null
      },
      "libraryFiles": [
        {
          "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": 1650621052494,
          "updatedAt": 1650621052494,
          "fileType": "audio"
        },
        {
          "ino": "649644248522215261",
          "metadata": {
            "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "ext": ".mp3",
            "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "size": 47972352,
            "mtimeMs": 1632223180281,
            "ctimeMs": 1645978261001,
            "birthtimeMs": 0
          },
          "addedAt": 1650621052494,
          "updatedAt": 1650621052494,
          "fileType": "audio"
        },
        {
          "ino": "649644248522215267",
          "metadata": {
            "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
          },
          "addedAt": 1650621052495,
          "updatedAt": 1650621052495,
          "fileType": "image"
        }
      ],
      "size": 268990279
    }
  ],
  "lastUpdate": 1650621110769,
  "createdAt": 1650621073750
}

This endpoint adds a book to a collection and returns the collection.

HTTP Request

POST http://abs.example.com/api/collections/<ID>/book

URL Parameters

Parameter Description
ID The ID of the collection.

Parameters

Parameter Type Description
id String The ID of the book library item to add to the collection.

Response

Status Meaning Description Schema
200 OK Success Collection Expanded
403 Forbidden A user with update permissions is required to update collections.
404 Not Found No collection with the specified ID exists.
500 Internal Server Error The provided library item ID could not be found, is in a different library, or is already in the collection.

Remove a Book From a Collection

curl -X DELETE "https://abs.example.com/api/collections/col_fpfstanv6gd7tq2qz7/book/li_8gch9ve09orgn4fdz8" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "id": "col_fpfstanv6gd7tq2qz7",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "Favorites",
  "description": null,
  "books": [],
  "lastUpdate": 1650621073750,
  "createdAt": 1650621073750
}

This endpoint removes a book from a collection and returns the collection.

HTTP Request

DELETE http://abs.example.com/api/collections/<ID>/book/<BookID>

URL Parameters

Parameter Description
ID The ID of the collection.
BookID The ID of the book library item to remove from the collection.

Response

Status Meaning Description Schema
200 OK Success Collection Expanded
403 Forbidden A user with delete permissions is required to remove a book from a collection.
404 Not Found No collection with the specified ID exists.

Batch Add Books to a Collection

curl -X POST "https://abs.example.com/api/collections/col_fpfstanv6gd7tq2qz7/batch/add" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"books": ["li_8gch9ve09orgn4fdz8"]}'

The above command returns JSON structured like this:

{
  "id": "col_fpfstanv6gd7tq2qz7",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "The Best Books",
  "description": null,
  "books": [
    {
      "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",
              "tagComposer": "Terry Goodkind"
            },
            "mimeType": "audio/mpeg"
          },
          {
            "index": 2,
            "ino": "649644248522215261",
            "metadata": {
              "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "ext": ".mp3",
              "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "size": 47972352,
              "mtimeMs": 1632223180281,
              "ctimeMs": 1645978261001,
              "birthtimeMs": 0
            },
            "addedAt": 1650621074130,
            "updatedAt": 1651830828023,
            "trackNumFromMeta": 2,
            "discNumFromMeta": null,
            "trackNumFromFilename": 1,
            "discNumFromFilename": null,
            "manuallyVerified": false,
            "exclude": false,
            "error": null,
            "format": "MP2/3 (MPEG audio layer 2/3)",
            "duration": 5996.2785,
            "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 02",
              "tagTrack": "02/20",
              "tagAlbumArtist": "Terry Goodkind",
              "tagComposer": "Terry Goodkind"
            },
            "mimeType": "audio/mpeg"
          }
        ],
        "chapters": [
          {
            "id": 0,
            "start": 0,
            "end": 6004.6675,
            "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
          },
          {
            "id": 1,
            "start": 6004.6675,
            "end": 12000.946,
            "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02"
          }
        ],
        "duration": 33854.905,
        "size": 268824228,
        "tracks": [
          {
            "index": 1,
            "startOffset": 0,
            "duration": 6004.6675,
            "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
            "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
            "mimeType": "audio/mpeg",
            "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
            }
          },
          {
            "index": 2,
            "startOffset": 6004.6675,
            "duration": 5996.2785,
            "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "mimeType": "audio/mpeg",
            "metadata": {
              "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "ext": ".mp3",
              "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 03.mp3",
              "size": 47972352,
              "mtimeMs": 1632223180281,
              "ctimeMs": 1645978261001,
              "birthtimeMs": 0
            }
          }
        ],
        "ebookFile": null
      },
      "libraryFiles": [
        {
          "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": 1650621052494,
          "updatedAt": 1650621052494,
          "fileType": "audio"
        },
        {
          "ino": "649644248522215261",
          "metadata": {
            "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "ext": ".mp3",
            "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
            "size": 47972352,
            "mtimeMs": 1632223180281,
            "ctimeMs": 1645978261001,
            "birthtimeMs": 0
          },
          "addedAt": 1650621052494,
          "updatedAt": 1650621052494,
          "fileType": "audio"
        },
        {
          "ino": "649644248522215267",
          "metadata": {
            "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
          },
          "addedAt": 1650621052495,
          "updatedAt": 1650621052495,
          "fileType": "image"
        }
      ],
      "size": 268990279
    }
  ],
  "lastUpdate": 1650621110769,
  "createdAt": 1650621073750
}

This endpoint batch adds books to a collection and returns the collection.

HTTP Request

POST http://abs.example.com/api/collections/<ID>/batch/add

URL Parameters

Parameter Description
ID The ID of the collection.

Parameters

Parameter Type Description
books Array of String The IDs of the book library items to add to the collection.

Response

Status Meaning Description Schema
200 OK Success Collection Expanded
403 Forbidden A user with update permissions is required to update collections.
404 Not Found No collection with the specified ID exists.
500 Internal Server Error The provided books array must not be empty.

Batch Remove Books From a Collection

curl -X POST "https://abs.example.com/api/collections/col_fpfstanv6gd7tq2qz7/batch/remove" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"books": ["li_8gch9ve09orgn4fdz8"]}'

The above command returns JSON structured like this:

{
  "id": "col_fpfstanv6gd7tq2qz7",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "The Best Books",
  "description": null,
  "books": [],
  "lastUpdate": 1650621110769,
  "createdAt": 1650621073750
}

This endpoint batch removes books from a collection and returns the collection.

HTTP Request

POST http://abs.example.com/api/collections/<ID>/batch/remove

URL Parameters

Parameter Description
ID The ID of the collection.

Parameters

Parameter Type Description
books Array of String The IDs of the book library items to remove from the collection.

Response

Status Meaning Description Schema
200 OK Success Collection Expanded
403 Forbidden A user with update permissions is required to update collections.
404 Not Found No collection with the specified ID exists.
500 Internal Server Error The provided books array must not be empty.

Playlists

Create a Playlist

curl -X POST "https://abs.example.com/api/playlists" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"libraryId": "lib_c1u6t4p45c35rf0nzd", "name": "Favorites", items: ["libraryItemId": "li_8gch9ve09orgn4fdz8"]}'

The above command returns JSON structured like this:

{
  "id": "pl_qbwet64998s5ra6dcu",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "Favorites",
  "description": null,
  "coverPath": null,
  "items": [
    {
      "libraryItemId": "li_8gch9ve09orgn4fdz8",
      "episodeId": null,
      "libraryItem": {
        "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",
                "tagComposer": "Terry Goodkind"
              },
              "mimeType": "audio/mpeg"
            },
            {
              "index": 2,
              "ino": "649644248522215261",
              "metadata": {
                "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "ext": ".mp3",
                "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "size": 47972352,
                "mtimeMs": 1632223180281,
                "ctimeMs": 1645978261001,
                "birthtimeMs": 0
              },
              "addedAt": 1650621074130,
              "updatedAt": 1651830828023,
              "trackNumFromMeta": 2,
              "discNumFromMeta": null,
              "trackNumFromFilename": 1,
              "discNumFromFilename": null,
              "manuallyVerified": false,
              "exclude": false,
              "error": null,
              "format": "MP2/3 (MPEG audio layer 2/3)",
              "duration": 5996.2785,
              "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 02",
                "tagTrack": "02/20",
                "tagAlbumArtist": "Terry Goodkind",
                "tagComposer": "Terry Goodkind"
              },
              "mimeType": "audio/mpeg"
            }
          ],
          "chapters": [
            {
              "id": 0,
              "start": 0,
              "end": 6004.6675,
              "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
            },
            {
              "id": 1,
              "start": 6004.6675,
              "end": 12000.946,
              "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02"
            }
          ],
          "duration": 33854.905,
          "size": 268824228,
          "tracks": [
            {
              "index": 1,
              "startOffset": 0,
              "duration": 6004.6675,
              "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
              "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
              "mimeType": "audio/mpeg",
              "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
              }
            },
            {
              "index": 2,
              "startOffset": 6004.6675,
              "duration": 5996.2785,
              "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "mimeType": "audio/mpeg",
              "metadata": {
                "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "ext": ".mp3",
                "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 03.mp3",
                "size": 47972352,
                "mtimeMs": 1632223180281,
                "ctimeMs": 1645978261001,
                "birthtimeMs": 0
              }
            }
          ],
          "ebookFile": null
        },
        "libraryFiles": [
          {
            "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": 1650621052494,
            "updatedAt": 1650621052494,
            "fileType": "audio"
          },
          {
            "ino": "649644248522215261",
            "metadata": {
              "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "ext": ".mp3",
              "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "size": 47972352,
              "mtimeMs": 1632223180281,
              "ctimeMs": 1645978261001,
              "birthtimeMs": 0
            },
            "addedAt": 1650621052494,
            "updatedAt": 1650621052494,
            "fileType": "audio"
          },
          {
            "ino": "649644248522215267",
            "metadata": {
              "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
            },
            "addedAt": 1650621052495,
            "updatedAt": 1650621052495,
            "fileType": "image"
          }
        ],
        "size": 268990279
      }
    }
  ],
  "lastUpdate": 1669623431313,
  "createdAt": 1669623431313
}

This endpoint creates a playlist and returns it.

HTTP Request

POST http://abs.example.com/api/playlists

Parameters

Parameter Type Default Description
libraryId String Required The ID of the library the playlist belongs to.
name String Required The playlist's name.
description String or null null The playlist's description.
coverPath String or null null The path of the playlist's cover.
items Array of Playlist Item [] The items in the playlist.

Response

Status Meaning Description Schema
200 OK Success Playlist Expanded
400 Bad Request The provided playlist data was invalid.

Get All User Playlists

curl "https://abs.example.com/api/playlists" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "playlists": [
    {
      "id": "pl_qbwet64998s5ra6dcu",
      "libraryId": "lib_c1u6t4p45c35rf0nzd",
      "userId": "root",
      "name": "Favorites",
      "description": null,
      "coverPath": null,
      "items": [
        {
          "libraryItemId": "li_8gch9ve09orgn4fdz8",
          "episodeId": null,
          "libraryItem": {
            "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",
                    "tagComposer": "Terry Goodkind"
                  },
                  "mimeType": "audio/mpeg"
                },
                {
                  "index": 2,
                  "ino": "649644248522215261",
                  "metadata": {
                    "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                    "ext": ".mp3",
                    "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                    "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                    "size": 47972352,
                    "mtimeMs": 1632223180281,
                    "ctimeMs": 1645978261001,
                    "birthtimeMs": 0
                  },
                  "addedAt": 1650621074130,
                  "updatedAt": 1651830828023,
                  "trackNumFromMeta": 2,
                  "discNumFromMeta": null,
                  "trackNumFromFilename": 1,
                  "discNumFromFilename": null,
                  "manuallyVerified": false,
                  "exclude": false,
                  "error": null,
                  "format": "MP2/3 (MPEG audio layer 2/3)",
                  "duration": 5996.2785,
                  "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 02",
                    "tagTrack": "02/20",
                    "tagAlbumArtist": "Terry Goodkind",
                    "tagComposer": "Terry Goodkind"
                  },
                  "mimeType": "audio/mpeg"
                }
              ],
              "chapters": [
                {
                  "id": 0,
                  "start": 0,
                  "end": 6004.6675,
                  "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
                },
                {
                  "id": 1,
                  "start": 6004.6675,
                  "end": 12000.946,
                  "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02"
                }
              ],
              "duration": 33854.905,
              "size": 268824228,
              "tracks": [
                {
                  "index": 1,
                  "startOffset": 0,
                  "duration": 6004.6675,
                  "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
                  "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
                  "mimeType": "audio/mpeg",
                  "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
                  }
                },
                {
                  "index": 2,
                  "startOffset": 6004.6675,
                  "duration": 5996.2785,
                  "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                  "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                  "mimeType": "audio/mpeg",
                  "metadata": {
                    "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                    "ext": ".mp3",
                    "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                    "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 03.mp3",
                    "size": 47972352,
                    "mtimeMs": 1632223180281,
                    "ctimeMs": 1645978261001,
                    "birthtimeMs": 0
                  }
                }
              ],
              "ebookFile": null
            },
            "libraryFiles": [
              {
                "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": 1650621052494,
                "updatedAt": 1650621052494,
                "fileType": "audio"
              },
              {
                "ino": "649644248522215261",
                "metadata": {
                  "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                  "ext": ".mp3",
                  "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                  "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                  "size": 47972352,
                  "mtimeMs": 1632223180281,
                  "ctimeMs": 1645978261001,
                  "birthtimeMs": 0
                },
                "addedAt": 1650621052494,
                "updatedAt": 1650621052494,
                "fileType": "audio"
              },
              {
                "ino": "649644248522215267",
                "metadata": {
                  "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
                },
                "addedAt": 1650621052495,
                "updatedAt": 1650621052495,
                "fileType": "image"
              }
            ],
            "size": 268990279
          }
        }
      ],
      "lastUpdate": 1669623431313,
      "createdAt": 1669623431313
    }
  ]
}

This endpoint retrieves all playlists belonging to the authenticated user.

HTTP Request

GET http://abs.example.com/api/playlists

Response

Status Meaning Description Schema
200 OK Success See Below

Response Schema

Attribute Type Description
playlists Array of Playlist Expanded The requested playlists.

Get a Playlist

curl "https://abs.example.com/api/playlists/pl_qbwet64998s5ra6dcu" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

The above command returns JSON structured like this:

{
  "id": "pl_qbwet64998s5ra6dcu",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "Favorites",
  "description": null,
  "coverPath": null,
  "items": [
    {
      "libraryItemId": "li_8gch9ve09orgn4fdz8",
      "episodeId": null,
      "libraryItem": {
        "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",
                "tagComposer": "Terry Goodkind"
              },
              "mimeType": "audio/mpeg"
            },
            {
              "index": 2,
              "ino": "649644248522215261",
              "metadata": {
                "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "ext": ".mp3",
                "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "size": 47972352,
                "mtimeMs": 1632223180281,
                "ctimeMs": 1645978261001,
                "birthtimeMs": 0
              },
              "addedAt": 1650621074130,
              "updatedAt": 1651830828023,
              "trackNumFromMeta": 2,
              "discNumFromMeta": null,
              "trackNumFromFilename": 1,
              "discNumFromFilename": null,
              "manuallyVerified": false,
              "exclude": false,
              "error": null,
              "format": "MP2/3 (MPEG audio layer 2/3)",
              "duration": 5996.2785,
              "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 02",
                "tagTrack": "02/20",
                "tagAlbumArtist": "Terry Goodkind",
                "tagComposer": "Terry Goodkind"
              },
              "mimeType": "audio/mpeg"
            }
          ],
          "chapters": [
            {
              "id": 0,
              "start": 0,
              "end": 6004.6675,
              "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
            },
            {
              "id": 1,
              "start": 6004.6675,
              "end": 12000.946,
              "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02"
            }
          ],
          "duration": 33854.905,
          "size": 268824228,
          "tracks": [
            {
              "index": 1,
              "startOffset": 0,
              "duration": 6004.6675,
              "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
              "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
              "mimeType": "audio/mpeg",
              "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
              }
            },
            {
              "index": 2,
              "startOffset": 6004.6675,
              "duration": 5996.2785,
              "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "contentUrl": "/s/item/li_8gch9ve09orgn4fdz8/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "mimeType": "audio/mpeg",
              "metadata": {
                "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "ext": ".mp3",
                "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 03.mp3",
                "size": 47972352,
                "mtimeMs": 1632223180281,
                "ctimeMs": 1645978261001,
                "birthtimeMs": 0
              }
            }
          ],
          "ebookFile": null
        },
        "libraryFiles": [
          {
            "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": 1650621052494,
            "updatedAt": 1650621052494,
            "fileType": "audio"
          },
          {
            "ino": "649644248522215261",
            "metadata": {
              "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "ext": ".mp3",
              "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
              "size": 47972352,
              "mtimeMs": 1632223180281,
              "ctimeMs": 1645978261001,
              "birthtimeMs": 0
            },
            "addedAt": 1650621052494,
            "updatedAt": 1650621052494,
            "fileType": "audio"
          },
          {
            "ino": "649644248522215267",
            "metadata": {
              "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
            },
            "addedAt": 1650621052495,
            "updatedAt": 1650621052495,
            "fileType": "image"
          }
        ],
        "size": 268990279
      }
    }
  ],
  "lastUpdate": 1669623431313,
  "createdAt": 1669623431313
}

This endpoint retrieves a playlist.

HTTP Request

GET http://abs.example.com/api/playlists/<ID>

URL Parameters

Parameter Description
ID The ID of the playlist.

Response

Status Meaning Description Schema
200 OK Success Playlist Expanded
403 Forbidden The playlist does not belong to the authenticated user.
404 Not Found No playlist with the provided ID exists.

Update a Playlist

curl -X PATCH "https://abs.example.com/api/playlists/pl_qbwet64998s5ra6dcu" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"name": "The Best Books"}'

The above command returns JSON structured like this:

{
  "id": "pl_qbwet64998s5ra6dcu",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "The Best Books",
  "description": null,
  "coverPath": null,
  "items": [
    {
      "libraryItemId": "li_8gch9ve09orgn4fdz8",
      "episodeId": null,
      "libraryItem": {
        "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",
                "tagComposer": "Terry Goodkind"
              },
              "mimeType": "audio/mpeg"
            },
            {
              "index": 2,
              "ino": "649644248522215261",
              "metadata": {
                "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "ext": ".mp3",
                "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "size": 47972352,
                "mtimeMs": 1632223180281,
                "ctimeMs": 1645978261001,
                "birthtimeMs": 0
              },
              "addedAt": 1650621074130,
              "updatedAt": 1651830828023,
              "trackNumFromMeta": 2,
              "discNumFromMeta": null,
              "trackNumFromFilename": 1,
              "discNumFromFilename": null,
              "manuallyVerified": false,
              "exclude": false,
              "error": null,
              "format": "MP2/3 (MPEG audio layer 2/3)",
              "duration": 5996.2785,
              "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 02",
                "tagTrack": "02/20",
                "tagAlbumArtist"