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

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

{
  "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&state=42"

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.

Also you must generate a random string and send it in the state parameter.

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

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

const state = generateRandomString()

On a valid request, it will return a 302-redirect (usually with a Location: header), which will point to the ABS-configured OAuth2 Provider. It will include your generated state-parameter, check if it matches. You would usually then have to open this redirect-URL in a Browser to present to the user.

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_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)
`state`	String	Required	A randomly generated string, which must match in subsequent requests

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"

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

If a redirect_uri was provided, this call returns user JSON data.
If a redirect_uri was not provided, it will redirect to /login (used internally by ABS-web).

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 generated in the first request
`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"

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

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

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

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

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

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

When updating folders you must pass in the full array of folders. Any missing folders from the array will be removed. New folders must not have an id set because this will be set automatically.

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"

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

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

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

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

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

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

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

type is book, podcast, or episode:
- entities will be an array of Library Item Minified.
type is episode:
- id is continue-listening, listen-again, or episodes-recently-added:
- Library items will have a recentEpisode attribute, a Podcast Episode, the episode to display.
type is series:
- entities will be an array of Series, with the following added attributes:

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.

type is author:
- entities will be an array of Author Expanded.
type is book, podcast, or series:
- If rssfeed was requested, the library items or series in entities will have an RSS Feed Minified object or null as rssFeed, the item's/series' open RSS feed.
id is continue-listening:
- Library items will have a progressLastUpdate attribute, an Integer, the time (in ms since POSIX epoch) when the book's or episode's progress was last updated.
id is continue-series:
- Library items will have a prevBookInProgressLastUpdate attribute, an Integer, the time (in ms since POSIX epoch) of the most recent progress update of any book in the series.
- The Book Metadata Minified in each library item will have a series attribute, a Series Sequence.
id is recommended:
- Library items will have a weight attribute, a Float, the recommendation weight of the library item.
id is listen-again:
- Library items will have a finishedAt attribute, an Integer, the time (in ms since POSIX epoch) when the book or episode was finished.

Get a Library's Filter Data

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

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

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

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

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

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

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

database
audiobookshelf
books-1
books-2
book-1
microphone-1
microphone-3
radio
podcast
rss
headphones
music
file-picture
rocket
power
star
heart

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"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

For permissions, all parameters must be present if including them in the request.

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"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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