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": "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 updates a playlist and returns it.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the playlist.

Parameters

Parameter	Type	Description
`name`	String	The playlist's name.
`description`	String or null	The playlist's description.
`coverPath`	String or 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
403	Forbidden	The playlist does not belong to the authenticated user.
404	Not Found	No playlist with the provided ID exists.

Delete a Playlist

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

This endpoint deletes a playlist.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the playlist.

Response

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

Add an Item to a Playlist

curl -X POST "https://abs.example.com/api/playlists/pl_qbwet64998s5ra6dcu/item" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"libraryItemId": "li_8gch9ve09orgn4fdz8"}'

{
  "id": "pl_qbwet64998s5ra6dcu",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "The Best Books",
  "description": null,
  "coverPath": null,
  "items": [
    {
      "libraryItemId": "li_8gch9ve09orgn4fdz8",
      "episodeId": null,
      "libraryItem": {
        "id": "li_8gch9ve09orgn4fdz8",
        "ino": "649641337522215266",
        "libraryId": "lib_c1u6t4p45c35rf0nzd",
        "folderId": "fol_bev1zuxhb0j0s1wehr",
        "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
        "relPath": "Terry Goodkind/Sword of Truth/Wizards First Rule",
        "isFile": false,
        "mtimeMs": 1650621074299,
        "ctimeMs": 1650621074299,
        "birthtimeMs": 0,
        "addedAt": 1650621073750,
        "updatedAt": 1650621110769,
        "lastScan": 1651830827825,
        "scanVersion": "2.0.21",
        "isMissing": false,
        "isInvalid": false,
        "mediaType": "book",
        "media": {
          "libraryItemId": "li_8gch9ve09orgn4fdz8",
          "metadata": {
            "title": "Wizards First Rule",
            "titleIgnorePrefix": "Wizards First Rule",
            "subtitle": null,
            "authors": [
              {
                "id": "aut_z3leimgybl7uf3y4ab",
                "name": "Terry Goodkind"
              }
            ],
            "narrators": [
              "Sam Tsoutsouvas"
            ],
            "series": [
              {
                "id": "ser_cabkj4jeu8be3rap4g",
                "name": "Sword of Truth",
                "sequence": "1"
              }
            ],
            "genres": [
              "Fantasy"
            ],
            "publishedYear": "2008",
            "publishedDate": null,
            "publisher": "Brilliance Audio",
            "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
            "isbn": null,
            "asin": "B002V0QK4C",
            "language": null,
            "explicit": false,
            "authorName": "Terry Goodkind",
            "authorNameLF": "Goodkind, Terry",
            "narratorName": "Sam Tsoutsouvas",
            "seriesName": "Sword of Truth"
          },
          "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
          "tags": [
            "Favorite"
          ],
          "audioFiles": [
            {
              "index": 1,
              "ino": "649644248522215260",
              "metadata": {
                "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
                "ext": ".mp3",
                "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
                "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
                "size": 48037888,
                "mtimeMs": 1632223180278,
                "ctimeMs": 1645978261001,
                "birthtimeMs": 0
              },
              "addedAt": 1650621074131,
              "updatedAt": 1651830828023,
              "trackNumFromMeta": 1,
              "discNumFromMeta": null,
              "trackNumFromFilename": 1,
              "discNumFromFilename": null,
              "manuallyVerified": false,
              "exclude": false,
              "error": null,
              "format": "MP2/3 (MPEG audio layer 2/3)",
              "duration": 6004.6675,
              "bitRate": 64000,
              "language": null,
              "codec": "mp3",
              "timeBase": "1/14112000",
              "channels": 2,
              "channelLayout": "stereo",
              "chapters": [],
              "embeddedCoverArt": null,
              "metaTags": {
                "tagAlbum": "SOT Bk01",
                "tagArtist": "Terry Goodkind",
                "tagGenre": "Audiobook Fantasy",
                "tagTitle": "Wizards First Rule 01",
                "tagTrack": "01/20",
                "tagAlbumArtist": "Terry Goodkind",
                "tagComposer": "Terry Goodkind"
              },
              "mimeType": "audio/mpeg"
            },
            {
              "index": 2,
              "ino": "649644248522215261",
              "metadata": {
                "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "ext": ".mp3",
                "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "size": 47972352,
                "mtimeMs": 1632223180281,
                "ctimeMs": 1645978261001,
                "birthtimeMs": 0
              },
              "addedAt": 1650621074130,
              "updatedAt": 1651830828023,
              "trackNumFromMeta": 2,
              "discNumFromMeta": null,
              "trackNumFromFilename": 1,
              "discNumFromFilename": null,
              "manuallyVerified": false,
              "exclude": false,
              "error": null,
              "format": "MP2/3 (MPEG audio layer 2/3)",
              "duration": 5996.2785,
              "bitRate": 64000,
              "language": null,
              "codec": "mp3",
              "timeBase": "1/14112000",
              "channels": 2,
              "channelLayout": "stereo",
              "chapters": [],
              "embeddedCoverArt": null,
              "metaTags": {
                "tagAlbum": "SOT Bk01",
                "tagArtist": "Terry Goodkind",
                "tagGenre": "Audiobook Fantasy",
                "tagTitle": "Wizards First Rule 02",
                "tagTrack": "02/20",
                "tagAlbumArtist": "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 adds an item to a playlist and returns the updated playlist.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the playlist.

Parameters

Parameter	Type	Default	Description
`libraryItemId`	String	Required	The ID of the library item the playlist item is for.
`episodeId`	String or null	`null`	The ID of the podcast episode the playlist item is for.

Response

Status	Meaning	Description	Schema
200	OK	Success	Playlist Expanded
400	Bad Request	No library item with the provided ID exists, the library item is in a different library from the playlist, the library item is already in the playlist, the library item is not a podcast and an `episodeId` was provided, the library item is a podcast and an `episodeId` was not provided, or no podcast episode with the provided ID exists in the library item.
403	Forbidden	The playlist does not belong to the authenticated user.
404	Not Found	No playlist with the provided ID exists.

Remove an Item From a Playlist

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

{
  "id": "pl_qbwet64998s5ra6dcu",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "The Best Books",
  "description": null,
  "coverPath": null,
  "items": [],
  "lastUpdate": 1669623431313,
  "createdAt": 1669623431313
}

This endpoint removes an item from a playlist and returns the updated playlist. Then, if the playlist is empty, it will be deleted.

HTTP Request

DELETE http://abs.example.com/api/playlists/<ID>/item/<LibraryItemID>
DELETE http://abs.example.com/api/playlists/<ID>/item/<LibraryItemID>/<EpisodeID>

URL Parameters

Parameter	Description
ID	The ID of the playlist.
LibraryItemID	The ID of the library item the playlist item to remove is for.
EpisodeID	The ID of the podcast episode the playlist item to remove is for.

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, or the playlist does not contain the provided item.

Batch Add Items to a Playlist

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

{
  "id": "pl_qbwet64998s5ra6dcu",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "The Best Books",
  "description": null,
  "coverPath": null,
  "items": [
    {
      "libraryItemId": "li_8gch9ve09orgn4fdz8",
      "episodeId": null,
      "libraryItem": {
        "id": "li_8gch9ve09orgn4fdz8",
        "ino": "649641337522215266",
        "libraryId": "lib_c1u6t4p45c35rf0nzd",
        "folderId": "fol_bev1zuxhb0j0s1wehr",
        "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
        "relPath": "Terry Goodkind/Sword of Truth/Wizards First Rule",
        "isFile": false,
        "mtimeMs": 1650621074299,
        "ctimeMs": 1650621074299,
        "birthtimeMs": 0,
        "addedAt": 1650621073750,
        "updatedAt": 1650621110769,
        "lastScan": 1651830827825,
        "scanVersion": "2.0.21",
        "isMissing": false,
        "isInvalid": false,
        "mediaType": "book",
        "media": {
          "libraryItemId": "li_8gch9ve09orgn4fdz8",
          "metadata": {
            "title": "Wizards First Rule",
            "titleIgnorePrefix": "Wizards First Rule",
            "subtitle": null,
            "authors": [
              {
                "id": "aut_z3leimgybl7uf3y4ab",
                "name": "Terry Goodkind"
              }
            ],
            "narrators": [
              "Sam Tsoutsouvas"
            ],
            "series": [
              {
                "id": "ser_cabkj4jeu8be3rap4g",
                "name": "Sword of Truth",
                "sequence": "1"
              }
            ],
            "genres": [
              "Fantasy"
            ],
            "publishedYear": "2008",
            "publishedDate": null,
            "publisher": "Brilliance Audio",
            "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
            "isbn": null,
            "asin": "B002V0QK4C",
            "language": null,
            "explicit": false,
            "authorName": "Terry Goodkind",
            "authorNameLF": "Goodkind, Terry",
            "narratorName": "Sam Tsoutsouvas",
            "seriesName": "Sword of Truth"
          },
          "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
          "tags": [
            "Favorite"
          ],
          "audioFiles": [
            {
              "index": 1,
              "ino": "649644248522215260",
              "metadata": {
                "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
                "ext": ".mp3",
                "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
                "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
                "size": 48037888,
                "mtimeMs": 1632223180278,
                "ctimeMs": 1645978261001,
                "birthtimeMs": 0
              },
              "addedAt": 1650621074131,
              "updatedAt": 1651830828023,
              "trackNumFromMeta": 1,
              "discNumFromMeta": null,
              "trackNumFromFilename": 1,
              "discNumFromFilename": null,
              "manuallyVerified": false,
              "exclude": false,
              "error": null,
              "format": "MP2/3 (MPEG audio layer 2/3)",
              "duration": 6004.6675,
              "bitRate": 64000,
              "language": null,
              "codec": "mp3",
              "timeBase": "1/14112000",
              "channels": 2,
              "channelLayout": "stereo",
              "chapters": [],
              "embeddedCoverArt": null,
              "metaTags": {
                "tagAlbum": "SOT Bk01",
                "tagArtist": "Terry Goodkind",
                "tagGenre": "Audiobook Fantasy",
                "tagTitle": "Wizards First Rule 01",
                "tagTrack": "01/20",
                "tagAlbumArtist": "Terry Goodkind",
                "tagComposer": "Terry Goodkind"
              },
              "mimeType": "audio/mpeg"
            },
            {
              "index": 2,
              "ino": "649644248522215261",
              "metadata": {
                "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "ext": ".mp3",
                "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "relPath": "Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3",
                "size": 47972352,
                "mtimeMs": 1632223180281,
                "ctimeMs": 1645978261001,
                "birthtimeMs": 0
              },
              "addedAt": 1650621074130,
              "updatedAt": 1651830828023,
              "trackNumFromMeta": 2,
              "discNumFromMeta": null,
              "trackNumFromFilename": 1,
              "discNumFromFilename": null,
              "manuallyVerified": false,
              "exclude": false,
              "error": null,
              "format": "MP2/3 (MPEG audio layer 2/3)",
              "duration": 5996.2785,
              "bitRate": 64000,
              "language": null,
              "codec": "mp3",
              "timeBase": "1/14112000",
              "channels": 2,
              "channelLayout": "stereo",
              "chapters": [],
              "embeddedCoverArt": null,
              "metaTags": {
                "tagAlbum": "SOT Bk01",
                "tagArtist": "Terry Goodkind",
                "tagGenre": "Audiobook Fantasy",
                "tagTitle": "Wizards First Rule 02",
                "tagTrack": "02/20",
                "tagAlbumArtist": "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 batch adds items to a playlist and returns the updated playlist.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the playlist.

Parameters

Parameter	Type	Description
`items`	Array of Playlist Item	The items to add to the playlist.

Response

Status	Meaning	Description	Schema
200	OK	Success	Playlist Expanded
400	Bad Request	One or more of the provided items does not have a `libraryItemId`.
403	Forbidden	The playlist does not belong to the authenticated user.
404	Not Found	No playlist with the provided ID exists.
500	Internal Server Error	The provided `items` array was empty or did not exist.

Batch Remove Items From a Playlist

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

{
  "id": "pl_qbwet64998s5ra6dcu",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "The Best Books",
  "description": null,
  "coverPath": null,
  "items": [],
  "lastUpdate": 1669623431313,
  "createdAt": 1669623431313
}

This endpoint batch removes items from a playlist and returns the updated playlist. Then, if the playlist is empty, it will be deleted.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the playlist.

Parameters

Parameter	Type	Description
`items`	Array of Playlist Item	The items to remove from the playlist.

Response

Status	Meaning	Description	Schema
200	OK	Success	Playlist Expanded
400	Bad Request	One or more of the provided items does not have a `libraryItemId`.
403	Forbidden	The playlist does not belong to the authenticated user.
404	Not Found	No playlist with the provided ID exists.
500	Internal Server Error	The provided `items` array was empty or did not exist.

Create a Playlist From a Collection

curl -X POST "https://abs.example.com/api/playlists/collection/col_fpfstanv6gd7tq2qz7" \
  -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 creates a playlist from a collection. The newly created playlist is returned.

HTTP Request

POST http://abs.example.com/api/playlists/collection/<CollectionID>

URL Parameters

Parameter	Description
CollectionID	The ID of the collection.

Response

Status	Meaning	Description	Schema
200	OK	Success	Playlist Expanded
400	Bad Request	The user cannot access any books contained in the collection.
404	Not Found	No collection with the given ID exists.

Me

All the "Me" endpoints are based off of the authenticated user. In these docs, "you" will refer to the authenticated user.

Get Your User

curl "https://abs.example.com/api/me" \
  -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 your user.

HTTP Request

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

Response

Status	Meaning	Description	Schema
200	OK	Success	User

Get Your Listening Sessions

curl "https://abs.example.com/api/me/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 your listening sessions.

HTTP Request

GET http://abs.example.com/api/me/listening-sessions

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.

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 Your Listening Stats

curl "https://abs.example.com/api/me/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
      },
      "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 your listening statistics.

HTTP Request

GET http://abs.example.com/api/me/listening-stats

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.

Response Schema

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

Your 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 you listened to.
`timeListening`	Integer	The time (in seconds) you listened to the library item.
`mediaMetadata`	Book Metadata or Podcast Metadata Object	The metadata of the library item's media.

Your Day Time Totals

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

Your Day of Week Totals

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

Remove an Item From Continue Listening

curl "https://abs.example.com/api/me/progress/li_bufnnmp4y5o2gbbxfm-ep_lh6ko39pumnrma3dhv/remove-from-continue-listening" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "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.42057298864465265,
      "currentTime": 611.590717,
      "isFinished": false,
      "hideFromContinueListening": true,
      "lastUpdate": 1668330152157,
      "startedAt": 1668120083771,
      "finishedAt": null
    }
  ],
  "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 a library item, that has media progress associated with your user, from your "Continue Listening" shelf. Your user is returned.

HTTP Request

GET http://abs.example.com/api/me/progress/<ID>/remove-from-continue-listening

URL Parameters

Parameter	Description
ID	The ID of the media progress that refers to the library item to remove.

Response

Status	Meaning	Description	Schema
200	OK	Success	User

Get a Media Progress

curl "https://abs.example.com/api/me/progress/li_bufnnmp4y5o2gbbxfm/ep_lh6ko39pumnrma3dhv" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "id": "li_bufnnmp4y5o2gbbxfm-ep_lh6ko39pumnrma3dhv",
  "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
  "episodeId": "ep_lh6ko39pumnrma3dhv",
  "duration": 1454.18449,
  "progress": 0.42057298864465265,
  "currentTime": 611.590717,
  "isFinished": false,
  "hideFromContinueListening": false,
  "lastUpdate": 1668330152157,
  "startedAt": 1668120083771,
  "finishedAt": null
}

This endpoint retrieves your media progress that is associated with the given library item ID or podcast episode ID.

HTTP Request

GET http://abs.example.com/api/me/progress/<LibraryItemID>
GET http://abs.example.com/api/me/progress/<LibraryItemID>/<EpisodeID>

URL Parameters

Parameter	Description
LibraryItemID	The ID of the library item to retrieve the media progress for.
EpisodeID	The ID of the podcast episode to retrieve the media progress for.

Response

Status	Meaning	Description	Schema
200	OK	Success	Media Progress
404	Not Found	No media progress was found that matches the given IDs.

Batch Create/Update Media Progress

curl -X PATCH "https://abs.example.com/api/me/progress/batch/update" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '[{"libraryItemId": "li_bufnnmp4y5o2gbbxfm", "episodeId": "ep_lh6ko39pumnrma3dhv", "isFinished": true}]'

This endpoint batch creates/updates your media progress.

HTTP Request

PATCH http://abs.example.com/api/me/progress/batch/update

Parameters

Provide an array of objects with the following parameters:

Parameter	Type	Default	Description
`libraryItemId`	String	Required	The ID of the library item the media progress is for.
`episodeId`	String or null	`null`	The ID of the podcast episode the media progress is for.
`duration`	Float	`0`	The total duration (in seconds) of the media.
`progress`	Float	`0` or `1`	The percentage completion progress of the media. Will automatically be set to `1` if the media is finished.
`currentTime`	Float	`0`	The current time (in seconds) of your progress.
`isFinished`	Boolean	`false`	Whether the media is finished.
`hideFromContinueListening`	Boolean	`false`	Whether the media will be hidden from the "Continue Listening" shelf.
`finishedAt`	Integer or null	`null` or `Date.now()`	The time (in ms since POSIX epoch) when the user finished the media. The default will be `Date.now()` if `isFinished` is `true`.
`startedAt`	Integer	`Date.now()` or `finishedAt`	The time (in ms since POSIX epoch) when the user started consuming the media. The default will be the value of `finishedAt` if `isFinished` is `true`.

Response

Status	Meaning	Description
200	OK	Success
400	Bad Request	The provided array must have a non-zero length.

Create/Update Media Progress

curl -X PATCH "https://abs.example.com/api/me/progress/li_bufnnmp4y5o2gbbxfm/ep_lh6ko39pumnrma3dhv" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"isFinished": true}'

This endpoint creates/updates your media progress for a library item or podcast episode.

HTTP Request

PATCH http://abs.example.com/api/me/progress/<LibraryItemID>
PATCH http://abs.example.com/api/me/progress/<LibraryItemID>/<EpisodeID>

URL Parameters

Parameter	Description
LibraryItemID	The ID of the library item to create/update media progress for.
EpisodeID	The ID of the podcast episode to create/update media progress for.

Parameters

Parameter	Type	Default	Description
`duration`	Float	`0`	The total duration (in seconds) of the media.
`progress`	Float	`0` or `1`	The percentage completion progress of the media. Will automatically be set to `1` if the media is finished.
`currentTime`	Float	`0`	The current time (in seconds) of your progress.
`isFinished`	Boolean	`false`	Whether the media is finished.
`hideFromContinueListening`	Boolean	`false`	Whether the media will be hidden from the "Continue Listening" shelf.
`finishedAt`	Integer or null	`null` or `Date.now()`	The time (in ms since POSIX epoch) when the user finished the media. The default will be `Date.now()` if `isFinished` is `true`.
`startedAt`	Integer	`Date.now()` or `finishedAt`	The time (in ms since POSIX epoch) when the user started consuming the media. The default will be the value of `finishedAt` if `isFinished` is `true`.

Response

Status	Meaning	Description
200	OK	Success
404	Not Found	No library items or podcast episodes were found with the given IDs.

Remove a Media Progress

curl -X DELETE "https://abs.example.com/api/me/progress/li_bufnnmp4y5o2gbbxfm-ep_lh6ko39pumnrma3dhv" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

This endpoint removes a media progress entry from your user.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the media progress to remove.

Response

Status	Meaning	Description
200	OK	Success

Create a Bookmark

curl -X POST "https://abs.example.com/api/me/item/li_bufnnmp4y5o2gbbxfm/bookmark" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"time": 16, "title": "the good part"}'

{
  "libraryItemId": "li_8gch9ve09orgn4fdz8",
  "title": "the good part",
  "time": 16,
  "createdAt": 1668120083771
}

This endpoint creates a bookmark for a book library item and returns the created bookmark.

HTTP Request

POST http://abs.example.com/api/me/item/<ID>/bookmark

URL Parameters

Parameter	Description
ID	The ID of the library item to create a bookmark for.

Parameters

Parameter	Type	Description
`time`	Integer	The time (in seconds) in the book to create the bookmark at.
`title`	String	The title of the bookmark.

Response

Status	Meaning	Description	Schema
200	OK	Success	Audio Bookmark
404	Not Found	No library item with the provided ID exists.

Update a Bookmark

curl -X PATCH "https://abs.example.com/api/me/item/li_bufnnmp4y5o2gbbxfm/bookmark" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"time": 16, "title": "the better part"}'

{
  "libraryItemId": "li_8gch9ve09orgn4fdz8",
  "title": "the better part",
  "time": 16,
  "createdAt": 1668120083771
}

This endpoint updates a bookmark and returns it.

HTTP Request

PATCH http://abs.example.com/api/me/item/<ID>/bookmark

URL Parameters

Parameter	Description
ID	The ID of the library item to update a bookmark for.

Parameters

Parameter	Type	Description
`time`	Integer	The time (in seconds) of the bookmark.
`title`	String	The title of the bookmark.

Response

Status	Meaning	Description	Schema
200	OK	Success	Audio Bookmark
404	Not Found	No library item with the provided ID exists or no bookmark at the given `time` exists.
500	Internal Server Error	Could not find the bookmark.

Remove a Bookmark

curl -X DELETE "https://abs.example.com/api/me/item/li_bufnnmp4y5o2gbbxfm/bookmark/16" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

This endpoint removes a bookmark.

HTTP Request

DELETE http://abs.example.com/api/me/item/<ID>/bookmark/<Time>

URL Parameters

Parameter	Description
ID	The ID of the library item to remove a bookmark from.
Time	The time (in seconds) the bookmark is at.

Response

Status	Meaning	Description
200	OK	Success
404	Not Found	No library item with the provided ID exists or no bookmark at the given Time exists.
500	Internal Server Error	The Time URL parameter must be a number.

Change Your Password

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

{
  "success": true
}

This endpoint changes your password.

HTTP Request

PATCH http://abs.example.com/api/me/password

Parameters

Parameter	Type	Description
`password`	String	Your current password.
`newPassword`	String	Your new password.

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
500	Internal Server Error	Guest users cannot change their password.

Response Schema

Attribute	Type	Description
`success`	Boolean	Will only exist and be `true` if the password was updated successfully.
`error`	String	The error that occurred. Will only exist if there was an error updating your password.

Sync Local Media Progress

curl -X POST "https://abs.example.com/api/me/sync-local-progress" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"localMediaProgress": [{ "id": "local_li_bufnnmp4y5o2gbbxfm-local_ep_lh6ko39pumnrma3dhv", "libraryItemId": "li_bufnnmp4y5o2gbbxfm", "episodeId": "ep_lh6ko39pumnrma3dhv", "duration": 1454.18449, "progress": 0.011193983371394644, "currentTime": 16.278117, "isFinished": false, "hideFromContinueListening": false, "lastUpdate": 1668120246620, "startedAt": 1668120083771, "finishedAt": null}]}'

{
  "numServerProgressUpdates": 1,
  "localProgressUpdates": [],
  "serverProgressUpdates": {
    "id": "li_bufnnmp4y5o2gbbxfm-ep_lh6ko39pumnrma3dhv",
    "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
    "episodeId": "ep_lh6ko39pumnrma3dhv",
    "duration": 1454.18449,
    "progress": 0.011193983371394644,
    "currentTime": 16.278117,
    "isFinished": false,
    "hideFromContinueListening": false,
    "lastUpdate": 1668120246620,
    "startedAt": 1668120083771,
    "finishedAt": null
  },
}

This endpoint syncs a mobile client's local media progress with the server. For any local media progress with a greater lastUpdate time than the lastUpdate time of the matching media progress on the server, the server's media progress is updated. If the server's lastUpdate time is greater, than the local media progress will be returned with the updated information.

HTTP Request

POST http://abs.example.com/api/me/sync-local-progress

Parameters

Parameter	Type	Description
`localMediaProgress`	Array of Media Progress	The client's local media progress.

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
500	Internal Server Error	The `localMediaProgress` parameter is required.

Response Schema

Attribute	Type	Description
`numServerProgressUpdates`	Integer	The number of media progress items that were updated on the server.
`localProgressUpdates`	Array of Media Progress	Local media progress items with updated information from the server (server more recent).
`serverProgressUpdates`	Array of Media Progress	Media progress items that were updated on the server (local more recent).

Get Library Items In Progress

curl "https://abs.example.com/api/me/items-in-progress?limit=1" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "libraryItems": [
    {
      "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": 1668124892694,
      "ctimeMs": 1668124892694,
      "birthtimeMs": 1667326662083,
      "addedAt": 1667326662087,
      "updatedAt": 1668157565937,
      "isMissing": false,
      "isInvalid": false,
      "mediaType": "podcast",
      "media": {
        "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": [],
        "numEpisodes": 1,
        "autoDownloadEpisodes": false,
        "autoDownloadSchedule": "0 0 * * 1",
        "lastEpisodeCheck": 1667326662087,
        "maxEpisodesToKeep": 0,
        "maxNewEpisodesToDownload": 3,
        "size": 23653735
      },
      "numFiles": 2,
      "size": 23706728,
      "recentEpisode": {
        "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": 1668234380150,
          "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"
        },
        "publishedAt": 1339761600000,
        "addedAt": 1667326679503,
        "updatedAt": 1667428186431
      },
      "progressLastUpdate": 1668434165531
    }
  ]
}

This endpoint retrieves library items that are in progress (started, not finished).

HTTP Request

GET http://abs.example.com/api/me/items-in-progress

Optional Query Parameters

Parameter	Type	Default	Description
`limit`	Integer	`25`	A limit for how many library items to return.

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.

Response Schema

Attribute	Type	Description
`libraryItems`	Array of Library Item Minified	The in progress library items. They have extra attributes which are described below.

Extra Attributes

Attribute	Type	Description
`recentEpisode`	Podcast Episode Object	If the library item is for a podcast, the media progress's corresponding podcast episode. Will not exist for book library items.
`progressLastUpdate`	Integer	The time (in ms since POSIX epoch) when the corresponding media progress was last updated.

Remove a Series From Continue Listening

curl "https://abs.example.com/api/me/series/ser_cabkj4jeu8be3rap4g/remove-from-continue-listening" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "id": "root",
  "username": "root",
  "type": "root",
  "token": "exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY",
  "mediaProgress": [
    {
      "id": "li_8gch9ve09orgn4fdz8",
      "libraryItemId": "li_8gch9ve09orgn4fdz8",
      "episodeId": null,
      "duration": 33854.905,
      "progress": 0,
      "currentTime": 0,
      "isFinished": false,
      "hideFromContinueListening": false,
      "lastUpdate": 1668330152157,
      "startedAt": 1668120083771,
      "finishedAt": null
    }
  ],
  "seriesHideFromContinueListening": [
    "ser_cabkj4jeu8be3rap4g"
  ],
  "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 a series from your "Continue Series" shelf. Your user is returned.

HTTP Request

GET http://abs.example.com/api/me/series/<ID>/remove-from-continue-listening

URL Parameters

Parameter	Description
ID	The ID of the series to remove from continue listening.

Response

Status	Meaning	Description	Schema
200	OK	Success	User
404	Not Found	No series matching the provided ID was found.

Backups

Get All Backups

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

{
  "backups": [
    {
      "id": "2022-11-25T0100",
      "backupMetadataCovers": true,
      "backupDirPath": "/metadata/backups",
      "datePretty": "Fri, Nov 25 2022 01:00",
      "fullPath": "/metadata/backups/2022-11-25T0100.audiobookshelf",
      "path": "backups/2022-11-25T0100.audiobookshelf",
      "filename": "2022-11-25T0100.audiobookshelf",
      "fileSize": 39819077,
      "createdAt": 1669366800272,
      "serverVersion": "2.2.5"
    }
  ]
}

This endpoint retrieves all backups.

HTTP Request

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

Response

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

Response Schema

Attribute	Type	Description
`backups`	Array of Backup	The backups on the server.

Create a Backup

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

{
  "backups": [
    {
      "id": "2022-11-14T0130",
      "backupMetadataCovers": true,
      "backupDirPath": "/metadata/backups",
      "datePretty": "Mon, Nov 14 2022 01:30",
      "fullPath": "/metadata/backups/2022-11-14T0130.audiobookshelf",
      "path": "backups/2022-11-14T0130.audiobookshelf",
      "filename": "2022-11-14T0130.audiobookshelf",
      "fileSize": 7776983,
      "createdAt": 1668411000329,
      "serverVersion": "2.2.4"
    },
    {
      "id": "2022-11-15T0105",
      "backupMetadataCovers": true,
      "backupDirPath": "/metadata/backups",
      "datePretty": "Tue, Nov 15 2022 01:05",
      "fullPath": "/metadata/backups/2022-11-15T0105.audiobookshelf",
      "path": "backups/2022-11-15T0105.audiobookshelf",
      "filename": "2022-11-15T0105.audiobookshelf",
      "fileSize": 7777148,
      "createdAt": 1668495954701,
      "serverVersion": "2.2.4"
    }
  ]
}

This endpoint creates a backup. All existing backups will be returned.

HTTP Request

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

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below
403	Forbidden	An admin user is required to create backups.
500	Internal Server Error	The server failed to create a backup.

Response Schema

Attribute	Type	Description
`backups`	Array of Backup	The backups on the server.

Delete a Backup

curl -X DELETE "https://abs.example.com/api/backups/2022-11-14T0130" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "backups": [
    {
      "id": "2022-11-15T0105",
      "backupMetadataCovers": true,
      "backupDirPath": "/metadata/backups",
      "datePretty": "Tue, Nov 15 2022 01:05",
      "fullPath": "/metadata/backups/2022-11-15T0105.audiobookshelf",
      "path": "backups/2022-11-15T0105.audiobookshelf",
      "filename": "2022-11-15T0105.audiobookshelf",
      "fileSize": 7777148,
      "createdAt": 1668495954701,
      "serverVersion": "2.2.4"
    }
  ]
}

This endpoint deletes a backup. All existing backups will be returned.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the backup.

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below
403	Forbidden	An admin user is required to delete backups.
404	Not Found	No backup with the provided ID exists.

Response Schema

Attribute	Type	Description
`backups`	Array of Backup	The backups on the server.

Apply a Backup

curl "https://abs.example.com/api/backups/2022-11-15T0105/apply" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

This endpoint applies a backup.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the backup.

Response

Status	Meaning	Description
200	OK	Success
403	Forbidden	An admin user is required to apply backups.
404	Not Found	No backup with the provided ID exists.

Upload a Backup

curl -X POST "https://abs.example.com/api/backups/upload" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -F file=@2022-11-15T0105.audiobookshelf

{
  "backups": [
    {
      "id": "2022-11-14T0130",
      "backupMetadataCovers": true,
      "backupDirPath": "/metadata/backups",
      "datePretty": "Mon, Nov 14 2022 01:30",
      "fullPath": "/metadata/backups/2022-11-14T0130.audiobookshelf",
      "path": "backups/2022-11-14T0130.audiobookshelf",
      "filename": "2022-11-14T0130.audiobookshelf",
      "fileSize": 7776983,
      "createdAt": 1668411000329,
      "serverVersion": "2.2.4"
    },
    {
      "id": "2022-11-15T0105",
      "backupMetadataCovers": true,
      "backupDirPath": "/metadata/backups",
      "datePretty": "Tue, Nov 15 2022 01:05",
      "fullPath": "/metadata/backups/2022-11-15T0105.audiobookshelf",
      "path": "backups/2022-11-15T0105.audiobookshelf",
      "filename": "2022-11-15T0105.audiobookshelf",
      "fileSize": 7777148,
      "createdAt": 1668495954701,
      "serverVersion": "2.2.4"
    }
  ]
}

This endpoint uploads a backup to the server. All backups will be returned.

HTTP Request

POST http://abs.example.com/api/backups/upload

Form Parameters

Parameter	Type	Description
`file`	audiobookshelf Backup File	The backup to upload.

Response

Status	Meaning	Description	Schema
200	OK	Success	Array of Backup
403	Forbidden	An admin user is required to upload backups.
500	Internal Server Error	The backup data is invalid, or the server failed to save it.

Response Schema

Attribute	Type	Description
`backups`	Array of Backup	The backups on the server.

Filesystem

Get All Filesystem Paths

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

{
  "directories": [
    ...,
    {
      "path": "/home",
      "dirname": "home",
      "fullPath": "/home",
      "level": 0,
      "dirs": [
        {
          "path": "/home/node",
          "dirname": "node",
          "fullPath": "/home/node",
          "level": 1,
          "dirs": []
        }
      ]
    },
    {
      "path": "/lib",
      "dirname": "lib",
      "fullPath": "/lib",
      "level": 0,
      "dirs": [
        {
          "path": "/lib/apk",
          "dirname": "apk",
          "fullPath": "/lib/apk",
          "level": 1,
          "dirs": [
            {
              "path": "/lib/apk/db",
              "dirname": "db",
              "fullPath": "/lib/apk/db",
              "level": 2,
              "dirs": []
            }
          ]
        },
        {
          "path": "/lib/firmware",
          "dirname": "firmware",
          "fullPath": "/lib/firmware",
          "level": 1,
          "dirs": []
        },
        {
          "path": "/lib/mdev",
          "dirname": "mdev",
          "fullPath": "/lib/mdev",
          "level": 1,
          "dirs": []
        },
        {
          "path": "/lib/modules-load.d",
          "dirname": "modules-load.d",
          "fullPath": "/lib/modules-load.d",
          "level": 1,
          "dirs": []
        },
        {
          "path": "/lib/sysctl.d",
          "dirname": "sysctl.d",
          "fullPath": "/lib/sysctl.d",
          "level": 1,
          "dirs": []
        }
      ]
    },
    ...
  ]
}

This endpoint retrieves the filesystem paths of the server.

HTTP Request

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

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.

Response Schema

Attribute	Type	Description
`directories`	Array of Directory	The filesystem's directory paths.

Authors

Get an Author

curl "https://abs.example.com/api/authors/aut_z3leimgybl7uf3y4ab?include=items,series" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "id": "aut_z3leimgybl7uf3y4ab",
  "asin": null,
  "name": "Terry Goodkind",
  "description": null,
  "imagePath": null,
  "addedAt": 1650621073750,
  "updatedAt": 1650621073750,
  "libraryItems": [
    {
      "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
    }
  ],
  "series": [
    {
      "id": "ser_cabkj4jeu8be3rap4g",
      "name": "Sword of Truth",
      "items": [
        {
          "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
        }
      ]
    }
  ]
}

This endpoint retrieves an author.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the author.

Optional Query Parameters

Parameter	Type	Description
`include`	String	A comma separated list of what to include with the author. The options are `items` and `series`. `series` will only have an effect if `items` are included.
`library`	String	The ID of the library to filter included items from.

Response

Status	Meaning	Description	Schema
200	OK	Success	Author with optional extra attributes from `include` (see below).
404	Not Found	No author with provided ID exists.

Extra Attributes

Attribute	Type	Description
`libraryItems`	Array of Library Item Minified	If `items` was requested, the library items written by the author.
`series`	Array of Author Series (See Below)	If `items` and `series` were requested, the series that have books written by the author.

Author Series

Attribute	Type	Description
`id`	String	The ID of the series.
`name`	String	The name of the series.
`items`	Array of Library Item Minified	The items in the series. Each library item's media's metadata will have a `series` attribute, a Series Sequence, which is the matching series.

Update an Author

curl -X PATCH "https://abs.example.com/api/authors/aut_z3leimgybl7uf3y4ab" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"asin": "B000APZOQA"}'

{
  "author": {
    "id": "aut_z3leimgybl7uf3y4ab",
    "asin": "B000APZOQA",
    "name": "Terry Goodkind",
    "description": null,
    "imagePath": null,
    "addedAt": 1650621073750,
    "updatedAt": 1668506755298
  },
  "success": true
}

This endpoint updates an author. It also allows for merging of two authors if the name of this author is set to the name of another author.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the author.

Parameters

Parameter	Type	Description
`asin`	String or null	The ASIN of the author.
`name`	String	The name of the author.
`description`	String or null	A description of the author.
`imagePath`	String or null	The absolute path for the author image.

Response

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

Response Schema

Attribute	Type	Description
`author`	Author Object	The updated author.
`merged`	Boolean	Will only exist and be `true` if the author was merged with another author.
`updated`	Boolean	Whether the author was updated normally. Will only exist if the author was not merged.

Match an Author

curl -X POST "https://abs.example.com/api/authors/aut_z3leimgybl7uf3y4ab/match" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"q": "Terry Goodkind"}'

{
  "updated": true,
  "author": {
    "id": "aut_z3leimgybl7uf3y4ab",
    "asin": "B000APZOQA",
    "name": "Terry Goodkind",
    "description": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork, ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20 languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's brilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind has an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying situations. With masterful storytelling, Goodkind brings us into the lives of his characters; characters that must rise to face not only challenges, but their deepest fears. For that reason, Goodkind’s characters speak to the best and worst in all of us. While ‘The Sword of Truth’ series is confirmation enough of Goodkind’s incredible storytelling abilities, his broad talents are also clearly evident in his contemporary novels, set within our own world. His post-‘Sword of Truth’ books are a thrilling, dizzying, mix of modern narrative, with every bit of Goodkind’s masterful voice intact. The bond built between the reader and one of the world’s great authors, rises above worlds and settings, mere backdrops for Goodkind’s uniquely intricate stories of life, love, challenge, and triumph. \"My privilege in life is the joy of writing books and telling stories about people who fascinate me, the good and the bad. I am grateful to all of my readers for the critical role they play in making these books possible. Your passion is my passion, and I thank you.\" - Terry Goodkind For more, please visit: http://terrygoodkind.com",
    "imagePath": "/metadata/authors/aut_z3leimgybl7uf3y4ab.jpg",
    "addedAt": 1650621073750,
    "updatedAt": 1668506755298
  }
}

This endpoint matches the author using quick match. Quick match updates the author's description and image (if no image already existed) with information from audible.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the author.

Parameters

Either asin or q are required. If both are provided, asin will be used.

Parameter	Type	Description
`asin`	String	The ASIN to search for.
`q`	String	The author name to search for.

Response

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

Response Schema

Attribute	Type	Description
`updated`	Boolean	Whether the author was updated.
`author`	Author Object	The updated author.

Get an Author's Image

curl "https://abs.example.com/api/authors/aut_z3leimgybl7uf3y4ab/image" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  --output author.webp

This endpoint retrieves an author's image.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the author.

Optional Query Parameters

Parameter	Type	Default	Description
`width`	Integer	`400`	The requested width of the image.
`height`	Integer or null	`null`	The requested height of the image. If `null` the image is scaled proportionately.
`format`	String	`webp` or `jpeg`	The requested format of the 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	No author with provided ID exists, or the author does not have an image.
500	Internal Server Error	There was an error when attempting to read the image file.

Series Endpoints

Get a Series

curl "https://abs.example.com/api/series/ser_cabkj4jeu8be3rap4g?include=progress" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "id": "ser_cabkj4jeu8be3rap4g",
  "name": "Sword of Truth",
  "description": null,
  "addedAt": 1650621073750,
  "updatedAt": 1650621073750,
  "progress": {
    "libraryItemIds": [
      "li_8gch9ve09orgn4fdz8"
    ],
    "libraryItemIdsFinished": [
      "li_8gch9ve09orgn4fdz8"
    ],
    "isFinished": true
  }
}

This endpoint retrieves a series.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the series.

Optional Query Parameters

Parameter	Type	Description
`include`	String	A comma separated list of what to include with the series. The options are `progress` and `rssfeed`.

Response

Status	Meaning	Description	Schema
200	OK	Success	Series with optional extra attributes from `include` (see below).
404	Not Found	No series with provided ID exists.

Extra Attributes

Attribute	Type	Description
`progress`	Series Progress Object (See Below)	If `progress` was requested, the series' progress.
`rssFeed`	RSS Feed Minified Object or null	If `rssfeed` was requested, the series' open RSS feed. Will be `null` if the series' RSS feed is closed.

Series Progress

Attribute	Type	Description
`libraryItemIds`	Array of String	The IDs of the library items in the series.
`libraryItemIdsFinished`	Array of String	The IDs of the library items in the series that are finished.
`isFinished`	Boolean	Whether the series is finished.

Update a Series

curl -X PATCH "https://abs.example.com/api/series/ser_cabkj4jeu8be3rap4g" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"description": "A really cool series."}'

{
  "id": "ser_cabkj4jeu8be3rap4g",
  "name": "Sword of Truth",
  "description": "A really cool series.",
  "addedAt": 1650621073750,
  "updatedAt": 1650621073750
}

This endpoint updates a series and returns it.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the series.

Parameters

Parameter	Type	Description
`name`	String	The name of the series.
`description`	String or null	A description for the series.

Response

Status	Meaning	Description	Schema
200	OK	Success	Series
404	Not Found	No series with provided ID exists.

Sessions

Get All Sessions

curl "https://abs.example.com/api/sessions?user=root&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
    }
  ],
  "userFilter": "root"
}

This endpoint retrieves all listening sessions.

HTTP Request

GET https://abs.example.com/api/sessions

Optional Query Parameters

Parameter	Type	Default	Description
`user`	String		The ID of the user to filter listening sessions by.
`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	An admin user is required to get all sessions.

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. If `user` was not provided, then the sessions will have an extra attribute, `user`, listed below.
`userFilter`	String	If provided, the `user` parameter.

Extra Attribute

Attribute	Type	Description
`user`	Session User Object (See Below)	The user the playback session is for.

Session User

Attribute	Type	Description
`id`	UUIDv4	The ID of the user.
`username`	String	The username of the user.

Delete a Session

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

This endpoint deletes a listening session.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the listening session.

Response

Status	Meaning	Description
200	OK	Success
403	Forbidden	A user with delete permissions is required to delete sessions.
404	Not Found	No session with provided ID exists.

Sync a Local Session

curl -X POST "https://abs.example.com/api/session/local" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d $'{"id": "97751c1c-bc78-46c5-85c3-62367972de87", "userId": "855cc493-507a-4626-b664-36b7f259e102", "libraryId": "f08dce63-e5c8-4a6d-87c7-0cca53d47f0a", "libraryItemId": "54973194-1cff-4ae9-b2b6-957ae9ca2e61", "episodeId": "4e145fa0-c185-4ad2-b85c-50c956e4d242", "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.4"}, "date": "2022-11-16", "dayOfWeek": "Wednesday", "timeListening": 20, "startTime": 616.291374, "currentTime": 636.09262, "startedAt": 1668580247687, "updatedAt": 1668580396623}'

This endpoint creates/updates a local listening session on the server. Local listening sessions are used for syncing offline sessions. The client must use UUIDv4 as the id for the local listening session because this will be used as the identifier on the server as well.

HTTP Request

POST http://abs.example.com/api/session/local

Parameters

Provide the local Playback Session as the body.

Response

Status	Meaning	Description
200	OK	Success
500	Internal Server Error	Either the local session is already syncing, or the library item was not found.

Sync Local Sessions

curl -X POST "https://abs.example.com/api/session/local-all" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d $'{"sessions": [{"id": "97751c1c-bc78-46c5-85c3-62367972de87", "userId": "855cc493-507a-4626-b664-36b7f259e102", "libraryId": "f08dce63-e5c8-4a6d-87c7-0cca53d47f0a", "libraryItemId": "54973194-1cff-4ae9-b2b6-957ae9ca2e61", "episodeId": "4e145fa0-c185-4ad2-b85c-50c956e4d242", "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.4"}, "date": "2022-11-16", "dayOfWeek": "Wednesday", "timeListening": 20, "startTime": 616.291374, "currentTime": 636.09262, "startedAt": 1668580247687, "updatedAt": 1668580396623}]}'

{
  "results": [
    {
      "id": "97751c1c-bc78-46c5-85c3-62367972de87",
      "success": true,
      "progressSynced": true
    }
  ]
}

This endpoint creates/updates multiple local listening sessions on the server. Used for syncing offline listening sessions. The client must use UUIDv4 as the id for the local listening sessions because this will be used as the identifier on the server as well.

HTTP Request

POST http://abs.example.com/api/session/local-all

Parameters

Parameter	Type	Description
`sessions`	Array of Playback Session	The local playback sessions to sync.

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below

Response Schema

Attribute	Type	Description
`results`	Array of Sync Local Session Result	The results from the session syncs.

Sync Local Session Result

Attribute	Type	Description
`id`	UUIDv4	The ID of the playback session.
`success`	Boolean	Whether the session was successfully synced.
`error`	String	Will only exist if `success` is `false`. The error that occurred when syncing.
`progressSynced`	Boolean	Will only exist if `success` is `true`. Whether the progress for the session's library item was updated.

Get an Open Session

curl "https://abs.example.com/api/session/39045d34-7758-492d-aa5e-9bd872e884f5" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "id": "39045d34-7758-492d-aa5e-9bd872e884f5",
  "userId": "855cc493-507a-4626-b664-36b7f259e102",
  "libraryId": "f08dce63-e5c8-4a6d-87c7-0cca53d47f0a",
  "libraryItemId": "54973194-1cff-4ae9-b2b6-957ae9ca2e61",
  "episodeId": "4e145fa0-c185-4ad2-b85c-50c956e4d242",
  "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.4"
  },
  "date": "2022-11-16",
  "dayOfWeek": "Wednesday",
  "timeListening": 15,
  "startTime": 616.291374,
  "currentTime": 631.09262,
  "startedAt": 1668580247687,
  "updatedAt": 1668580396623,
  "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": "54973194-1cff-4ae9-b2b6-957ae9ca2e61",
    "ino": "652",
    "libraryId": "f08dce63-e5c8-4a6d-87c7-0cca53d47f0a",
    "folderId": "348b6bdc-eb29-4ac3-b30e-df471f29cb31",
    "path": "/podcasts/Welcome to Night Vale",
    "relPath": "Welcome to Night Vale",
    "isFile": false,
    "mtimeMs": 1668124892694,
    "ctimeMs": 1668124892694,
    "birthtimeMs": 1667326662083,
    "addedAt": 1667326662087,
    "updatedAt": 1668157565937,
    "lastScan": 1668234374487,
    "scanVersion": "2.2.2",
    "isMissing": false,
    "isInvalid": false,
    "mediaType": "podcast",
    "media": {
      "libraryItemId": "54973194-1cff-4ae9-b2b6-957ae9ca2e61",
      "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/54973194-1cff-4ae9-b2b6-957ae9ca2e61/cover.jpg",
      "tags": [],
      "episodes": [
        {
          "libraryItemId": "54973194-1cff-4ae9-b2b6-957ae9ca2e61",
          "id": "4e145fa0-c185-4ad2-b85c-50c956e4d242",
          "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": 1668234380150,
            "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 retrieves an open listening session.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the listening session.

Response

Status	Meaning	Description	Schema
200	OK	Success	Playback Session Expanded
404	Not Found	No listening session with the provided ID is open, or the session belongs to another user.

Sync an Open Session

curl -X POST "https://abs.example.com/api/session/play_i00492kps6ow4axlvq/sync" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"currentTime": 636.09262, "timeListened": 5, "duration": 1454.18449}'

This endpoint syncs the position of an open listening session from the client to the server and returns the session.

HTTP Request

POST http://abs.example.com/api/session/<ID>/sync

URL Parameters

Parameter	Description
ID	The ID of the listening session.

Parameters

Parameter	Type	Description
`currentTime`	Float	The current time (in seconds) of the playback position.
`timeListened`	Float	The amount of time (in seconds) the user has spent listening since the last session sync.
`duration`	Float	The total duration (in seconds) of the playing item.

Response

Status	Meaning	Description
200	OK	Success
404	Not Found	No listening session with the provided ID is open, or the session belongs to another user.
500	Internal Server Error	There was an error syncing the session.

Close an Open Session

curl -X POST "https://abs.example.com/api/session/play_i00492kps6ow4axlvq/close" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"currentTime": 636.09262, "timeListened": 5, "duration": 1454.18449}'

This endpoint closes an open listening session. Optionally provide sync data to update the session before closing it.

HTTP Request

POST http://abs.example.com/api/session/<ID>/close

URL Parameters

Parameter	Description
ID	The ID of the listening session.

Optional Parameters

Parameter	Type	Description
`currentTime`	Float	The current time (in seconds) of the playback position.
`timeListened`	Float	The amount of time (in seconds) the user has spent listening since the last session sync.
`duration`	Float	The total duration (in seconds) of the playing item.

Response

Status	Meaning	Description
200	OK	Success
404	Not Found	No listening session with the provided ID is open, or the session belongs to another user.

Podcasts

Create a Podcast

curl -X POST "https://abs.example.com/api/podcasts" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d $'{"libraryId": "lib_p9wkw2i85qy9oltijt", "folderId": "fol_crxarzs17jtw5k7ie9", "path": "/podcasts/Welcome to Night Vale", "media": {"metadata": {"title": "Welcome to Night Vale", "author": "Night Vale Presents", "description": "\\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It\'s an ongoing radio show. Start with the current episode, and you\'ll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\\n    ", "releaseDate": "2022-10-20T19:00:00Z", "genres": ["Science Fiction", "Podcasts", "Fiction"], "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast", "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg", "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4", "itunesId": 536258179, "itunesArtistId": 718704794, "explicit": false, "language": null}}}'

{
  "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": 1668124892694,
  "ctimeMs": 1668124892694,
  "birthtimeMs": 1667326662083,
  "addedAt": 1667326662087,
  "updatedAt": 1668157565937,
  "lastScan": 1668234374487,
  "scanVersion": "2.2.2",
  "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,
      "type": "episodic"
    },
    "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
    "tags": [],
    "episodes": [],
    "autoDownloadEpisodes": false,
    "autoDownloadSchedule": "0 * * * *",
    "lastEpisodeCheck": 1667326662087,
    "maxEpisodesToKeep": 0,
    "maxNewEpisodesToDownload": 3,
    "size": 52993
  },
  "libraryFiles": [
    {
      "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": 52993
}

This endpoint creates a podcast and returns it.

HTTP Request

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

Parameters

Parameter	Type	Description
`path`	String	The path of the new podcast library item on the server.
`folderId`	String	The ID of the folder to put the new podcast library item in.
`libraryId`	String	The ID of the library the new podcast item will belong to.
`media`	New Podcast Parameters Object (See Below)	The created library item's podcast media.
`episodesToDownload`	Array of Podcast Episode Parameters (See Below)	Podcast episodes to download and add to the new podcast.

New Podcast Parameters

Parameter	Type	Default	Description
`metadata`	New Podcast Metadata Parameters Object (See Below)	See Below	The podcast's metadata.
`coverPath`	String or null	`null`	The absolute path on the server of the cover file.
`autoDownloadEpisodes`	Boolean	`false`	Whether the server will automatically download podcast episodes according to the schedule.
`autoDownloadSchedule`	String	The "Podcast Episode Schedule" server setting.	The cron expression for when to automatically download new podcast episodes.

New Podcast Metadata Parameters

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

Podcast Episode Parameters

Parameter	Type	Default	Description
`season`	String	`''`	The season of the podcast episode, if known.
`episode`	String	`''`	The episode of the season of the podcast, if known.
`episodeType`	String	`''`	The type of episode that the podcast episode is.
`title`	String	`''`	The title of the podcast episode.
`subtitle`	String	`''`	The subtitle of the podcast episode.
`description`	String	`''`	A HTML encoded, description of the podcast episode.
`enclosure`	Podcast Episode Enclosure Object or null	`null`	The podcast episode download information.
`pubDate`	String	`''`	When the podcast episode was published.
`publishedAt`	Integer	`0`	The time (in ms since POSIX epoch) when the podcast episode was published.

Response

Status	Meaning	Description	Schema
200	OK	Success	Library Item Expanded
400	Bad Request	The podcast already exists, or the podcast's path is invalid.
403	Forbidden	An admin user is required to create podcasts.
404	Not Found	The given library ID or folder ID does not exist.

Get a Podcast's Feed

curl -X POST "https://abs.example.com/api/podcasts/feed" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"rssFeed": "http://feeds.nightvalepresents.com/welcometonightvalepodcast"}'

{
  "podcast": {
    "metadata": {
      "image": "https://f.prxu.org/126/images/1f749c5d-c83a-4db9-8112-a3245da49c54/nightvalelogo-web4.jpg",
      "categories": [
        "Fiction:Science Fiction"
      ],
      "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
      "description": "\n      <p>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.</p>\n    ",
      "descriptionPlain": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
      "title": "Welcome to Night Vale",
      "language": "en",
      "explicit": "false",
      "author": "Night Vale Presents",
      "pubDate": "Thu, 17 Nov 2022 16:04:42 -0000",
      "link": "http://welcometonightvale.com"
    },
    "episodes": [
      ...,
      {
        "title": "1 - Pilot",
        "subtitle": "Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting. Weather: \"These and More Than These\" by Joseph Fink Music:...",
        "description": "\n        <p>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.</p>\n\n<p>Weather: \"These and More Than These\" by Joseph Fink</p>\n\n<p>Music: Disparition, <a target=\"_blank\">disparition.info</a></p>\n\n<p>Logo: Rob Wilson, <a target=\"_blank\">silastom.com</a></p>\n\n<p>Produced by Night Vale Presents. Written by Joseph Fink and Jeffrey Cranor. Narrated by Cecil Baldwin. More Info: <a target=\"_blank\">welcometonightvale.com</a>, and follow <a target=\"_blank\">@NightValeRadio</a> on Twitter or <a target=\"_blank\">Facebook</a>.</p>\n      ",
        "descriptionPlain": "\n        Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting.\n\nWeather: \"These and More Than These\" by Joseph Fink\n\nMusic: Disparition, disparition.info\n\nLogo: Rob Wilson, silastom.com\n\nProduced by 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.\n      ",
        "pubDate": "Fri, 15 Jun 2012 12:00:00 -0000",
        "episodeType": "full",
        "season": "",
        "episode": "",
        "author": "",
        "duration": "21:02",
        "explicit": "",
        "publishedAt": 1339761600000,
        "enclosure": {
          "url": "https://www.podtrac.com/pts/redirect.mp3/dovetail.prxu.org/_/126/1fadf1ad-aad8-449f-843b-6e8bb6949622/1_Pilot.mp3",
          "type": "audio/mpeg",
          "length": "20588611"
        }
      },
      ...
    ]
  }
}

This endpoint takes a podcast's RSS feed and returns the feed's data.

HTTP Request

POST http://abs.example.com/api/podcasts/feed

Parameters

Parameter	Type	Description
`rssFeed`	String	A URL of an RSS feed for the podcast.

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
400	Bad Request	The `rssFeed` parameter is required.
404	Not Found	The podcast RSS feed request failed or had invalid response data.

Response Schema

Attribute	Type	Description
`podcast`	Podcast Feed Object	The requested podcast feed data.

Get Podcast Feeds From OPML

curl -X POST "https://abs.example.com/api/podcasts/opml" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d $'{"opmlText": "<?xml version=\'1.0\' encoding=\'UTF-8\' standalone=\'yes\' ?><opml version=\'1.0\'><head><title>Pocket Casts Feeds</title></head><body><outline type=\'rss\' text=\'Welcome to Night Vale\' xmlUrl=\'http://feeds.nightvalepresents.com/welcometonightvalepodcast\' /></body></opml>"}'

{
  "feeds": [
    {
      "metadata": {
        "image": "https://f.prxu.org/126/images/1f749c5d-c83a-4db9-8112-a3245da49c54/nightvalelogo-web4.jpg",
        "categories": [
          "Fiction:Science Fiction"
        ],
        "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
        "description": "\n      <p>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.</p>\n    ",
        "descriptionPlain": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
        "title": "Welcome to Night Vale",
        "language": "en",
        "explicit": "false",
        "author": "Night Vale Presents",
        "pubDate": "Thu, 17 Nov 2022 16:04:42 -0000",
        "link": "http://welcometonightvale.com"
      },
      "numEpisodes": 280
    }
  ]
}

This endpoint takes OPML text and returns the contained RSS feeds' data.

HTTP Request

POST http://abs.example.com/api/podcasts/opml

Parameters

Parameter	Type	Description
`opmlText`	String	OPML text containing podcast RSS feeds.

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
400	Bad Request	The `opmlText` parameter is required.

Response Schema

Attribute	Type	Description
`feeds`	Array of Podcast Feed Minified	The podcast feeds retrieved from the RSS feeds in the OPML text.

Or if there is an error (i.e. no RSS feeds were in the OPML text):

Attribute	Type	Description
`error`	String	The error that occurred.

Check for New Podcast Episodes

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

{
  "episodes": [
    {
      "title": "1 - Pilot",
      "subtitle": "Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting. Weather: \"These and More Than These\" by Joseph Fink Music:...",
      "description": "\n        <p>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.</p>\n\n<p>Weather: \"These and More Than These\" by Joseph Fink</p>\n\n<p>Music: Disparition, <a target=\"_blank\">disparition.info</a></p>\n\n<p>Logo: Rob Wilson, <a target=\"_blank\">silastom.com</a></p>\n\n<p>Produced by Night Vale Presents. Written by Joseph Fink and Jeffrey Cranor. Narrated by Cecil Baldwin. More Info: <a target=\"_blank\">welcometonightvale.com</a>, and follow <a target=\"_blank\">@NightValeRadio</a> on Twitter or <a target=\"_blank\">Facebook</a>.</p>\n      ",
      "descriptionPlain": "\n        Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting.\n\nWeather: \"These and More Than These\" by Joseph Fink\n\nMusic: Disparition, disparition.info\n\nLogo: Rob Wilson, silastom.com\n\nProduced by 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.\n      ",
      "pubDate": "Fri, 15 Jun 2012 12:00:00 -0000",
      "episodeType": "full",
      "season": "",
      "episode": "",
      "author": "",
      "duration": "21:02",
      "explicit": "",
      "publishedAt": 1339761600000,
      "enclosure": {
        "url": "https://www.podtrac.com/pts/redirect.mp3/dovetail.prxu.org/_/126/1fadf1ad-aad8-449f-843b-6e8bb6949622/1_Pilot.mp3",
        "type": "audio/mpeg",
        "length": "20588611"
      }
    }
  ]
}

This endpoint checks for new episodes for a podcast, which the server downloads, and returns the podcast episode feed data.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the podcast library item.

Optional Query Parameters

Parameter	Type	Default	Description
`limit`	Integer	`3`	The maximum number of new episodes to download. If `0`, all episodes will be downloaded.

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
403	Forbidden	The user is not allowed to access the library item. An admin user is required to check for new podcast episodes.
404	Not Found	No library item with the given ID exists.
500	Internal Server Error	The library item is not a podcast. The podcast must have an RSS feed URL.

Response Schema

Attribute	Type	Description
`episodes`	Array of Podcast Feed Episode	The new podcast episodes that will be downloaded.

Get Podcast Episode Downloads

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

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

This endpoint retrieves the episodes currently in the download queue for the podcast.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the podcast library item.

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
403	Forbidden	The user is not allowed to access the library item.
404	Not Found	No library item with the given ID exists.
500	Internal Server Error	The library item is not a podcast.

Response Schema

Attribute	Type	Description
`downloads`	Array of Podcast Episode Download	The episodes currently in the download queue for the podcast.

Clear a Podcast's Episode Download Queue

curl "https://abs.example.com/api/podcasts/li_bufnnmp4y5o2gbbxfm/clear-queue" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

This endpoint clears a podcast's episode download queue.

HTTP Request

GET http://abs.example.com/api/podcasts/<ID>/clear-queue

URL Parameters

Parameter	Description
ID	The ID of the podcast library item.

Response

Status	Meaning	Description
200	OK	Success
403	Forbidden	The user is not allowed to access the library item. An admin user is required to clear a podcast's episode download queue.
404	Not Found	No library item with the given ID exists.
500	Internal Server Error	The library item is not a podcast.

Search a Podcast's Feed for Episodes

curl "https://abs.example.com/api/podcasts/li_bufnnmp4y5o2gbbxfm/search-episode?title=Pilot" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "episodes": [
    {
      "episode": {
        "title": "1 - Pilot",
        "subtitle": "Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting. Weather: \"These and More Than These\" by Joseph Fink Music:...",
        "description": "\n        <p>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.</p>\n\n<p>Weather: \"These and More Than These\" by Joseph Fink</p>\n\n<p>Music: Disparition, <a target=\"_blank\">disparition.info</a></p>\n\n<p>Logo: Rob Wilson, <a target=\"_blank\">silastom.com</a></p>\n\n<p>Produced by Night Vale Presents. Written by Joseph Fink and Jeffrey Cranor. Narrated by Cecil Baldwin. More Info: <a target=\"_blank\">welcometonightvale.com</a>, and follow <a target=\"_blank\">@NightValeRadio</a> on Twitter or <a target=\"_blank\">Facebook</a>.</p>\n      ",
        "descriptionPlain": "\n        Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting.\n\nWeather: \"These and More Than These\" by Joseph Fink\n\nMusic: Disparition, disparition.info\n\nLogo: Rob Wilson, silastom.com\n\nProduced by 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.\n      ",
        "pubDate": "Fri, 15 Jun 2012 12:00:00 -0000",
        "episodeType": "full",
        "season": "",
        "episode": "",
        "author": "",
        "duration": "21:02",
        "explicit": "",
        "publishedAt": 1339761600000,
        "enclosure": {
          "url": "https://www.podtrac.com/pts/redirect.mp3/dovetail.prxu.org/_/126/1fadf1ad-aad8-449f-843b-6e8bb6949622/1_Pilot.mp3",
          "type": "audio/mpeg",
          "length": "20588611"
        }
      },
      "levenshtein": 4
    }
  ]
}

This endpoint searches a podcast's feed for an episode with the given title.

HTTP Request

GET http://abs.example.com/api/podcasts/<ID>/search-episode

URL Parameters

Parameter	Description
ID	The ID of the podcast library item.

Query Parameters

Parameter	Type	Description
`title`	String	The podcast episode title to search for.

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
403	Forbidden	The user is not allowed to access the library item.
404	Not Found	No library item with the given ID exists.
500	Internal Server Error	The library item is not a podcast. The podcast must have an RSS feed URL. `title` is a required parameter.

Response Schema

Attribute	Type	Description
`episodes`	Array of Podcast Search Episode (See Below)	The matching podcast episodes.

Podcast Search Episode

Attribute	Type	Description
`episode`	Podcast Feed Episode Object	The podcast episode feed data.
`levenshtein`	Integer	The Levenshtein distance between the search title and the podcast episode's title.

Download Podcast Episodes

curl -X POST "https://abs.example.com/api/podcasts/li_bufnnmp4y5o2gbbxfm/download-episodes" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '[{"episodeType": "full", "title": "2 - Glow Cloud", "subtitle": "A mysterious, glowing cloud makes its way across Night Vale. Plus, new Boy Scouts hierarchy, community events calendar, and a PTA bake sale for a great cause! Weather: \"The Bus is Late\" by Satellite High, satellite-high.com Music: Disparition,...", "description": "\n        <p>A mysterious, glowing cloud makes its way across Night Vale. Plus, new Boy Scouts hierarchy, community events calendar, and a PTA bake sale for a great cause!</p>\n\n<p>Weather: \"The Bus is Late\" by Satellite High, <a target=\"_blank\">satellite-high.com</a></p>\n\n<p>Music: Disparition, <a target=\"_blank\">disparition.info</a></p>\n\n<p>Logo: Rob Wilson, <a target=\"_blank\">silastom.com</a></p>\n\n<p>Produced by Night Vale Presents. Written by Joseph Fink and Jeffrey Cranor. Narrated by Cecil Baldwin. More Info: <a target=\"_blank\">welcometonightvale.com</a>, and follow <a target=\"_blank\">@NightValeRadio</a> on Twitter or <a target=\"_blank\">Facebook</a>.</p>\n      ", "enclosure": {"url": "https://www.podtrac.com/pts/redirect.mp3/dovetail.prxu.org/_/126/cb1dd91f-5d8d-42e9-ba22-14ff335d2cbb/2_Glow_Cloud.mp3", "type": "audio/mpeg", "length": "19937018"}, "pubDate": "Sun, 01 Jul 2012 12:00:00 -0000", "publishedAt": 1341144000000}]'

This endpoint downloads new episodes for a podcast to the server.

HTTP Request

POST http://abs.example.com/api/podcasts/<ID>/download-episodes

URL Parameters

Parameter	Description
ID	The ID of the podcast library item.

Parameters

Provided an array of objects with the following parameters for each episode to download.

Parameter	Type	Default	Description
`season`	String	`''`	The season of the podcast episode, if known.
`episode`	String	`''`	The episode of the season of the podcast, if known.
`episodeType`	String	`''`	The type of episode that the podcast episode is.
`title`	String	`''`	The title of the podcast episode.
`subtitle`	String	`''`	The subtitle of the podcast episode.
`description`	String	`''`	A HTML encoded, description of the podcast episode.
`enclosure`	Podcast Episode Enclosure Object or null	`null`	The podcast episode download information.
`pubDate`	String	`''`	When the podcast episode was published.
`publishedAt`	Integer	`0`	The time (in ms since POSIX epoch) when the podcast episode was published.

Response

Status	Meaning	Description
200	OK	Success
400	Bad Request	The provided array must have a non-zero length.
403	Forbidden	The user is not allowed to access the library item. An admin user is required to download new podcast episodes.
404	Not Found	No library item with the given ID exists.
500	Internal Server Error	The library item is not a podcast.

Match a Podcast's Episodes

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

{
  "numEpisodesUpdated": 1
}

This endpoint matches the podcast's episodes using quick match. Quick match populates empty details. Does not overwrite details unless the "Prefer matched metadata" server setting is enabled or the override query parameter is 1.

HTTP Request

POST http://abs.example.com/api/podcasts/<ID>/match-episodes

URL Parameters

Parameter	Description
ID	The ID of the podcast library item.

Query Parameters

Parameter	Type	Default	Description
`override`	Binary	`0`	Whether the podcast's episodes' details will be overridden. `0` for false, `1` for true.

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below
403	Forbidden	An admin user is required to match a podcast's episodes.

Response Schema

Attribute	Type	Description
`numEpisodesUpdated`	Integer	The number of podcast episodes that were updated.

Get a Podcast Episode

curl "https://abs.example.com/api/podcasts/li_bufnnmp4y5o2gbbxfm/episode/ep_lh6ko39pumnrma3dhv" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "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": 1668234380150,
    "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"
  },
  "publishedAt": 1339761600000,
  "addedAt": 1667326679503,
  "updatedAt": 1667428186431
}

This endpoint retrieves a podcast episode.

HTTP Request

GET http://abs.example.com/api/podcasts/<ID>/episode/<EpisodeID>

URL Parameters

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

Response

Status	Meaning	Description	Schema
200	OK	Success	Podcast Episode
403	Forbidden	The user is not allowed to access the library item.
404	Not Found	No podcast episode with the given ID exists.
500	Internal Server Error	The library item is not a podcast.

Update a Podcast Episode

curl -X PATCH "https://abs.example.com/api/podcasts/li_bufnnmp4y5o2gbbxfm/episode/ep_lh6ko39pumnrma3dhv" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"subtitle": "A really cool podcast episode."}'

{
  "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": 1668124892694,
  "ctimeMs": 1668124892694,
  "birthtimeMs": 1667326662083,
  "addedAt": 1667326662087,
  "updatedAt": 1668853355724,
  "lastScan": 1668234374487,
  "scanVersion": "2.2.2",
  "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,
      "type": "episodic"
    },
    "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
    "tags": [],
    "episodes": [
      {
        "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
        "id": "ep_lh6ko39pumnrma3dhv",
        "index": 3,
        "season": "",
        "episode": "",
        "episodeType": "full",
        "title": "1 - Pilot",
        "subtitle": "A really cool podcast episode.",
        "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": 1668234380150,
          "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 updates a podcast episode and returns the library item.

HTTP Request

PATCH http://abs.example.com/api/podcasts/<ID>/episode/<EpisodeID>

URL Parameters

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

Parameters

Parameter	Type	Description
`index`	Integer	The index of the podcast episode.
`season`	String	The season of the podcast episode, if known.
`episode`	String	The episode of the season of the podcast, if known.
`episodeType`	String	The type of episode that the podcast episode is.
`title`	String	The title of the podcast episode.
`subtitle`	String	The subtitle of the podcast episode.
`description`	String	A HTML encoded, description of the podcast episode.
`enclosure`	Podcast Episode Enclosure Object	The podcast episode download information.
`pubDate`	String	When the podcast episode was published.
`audioFile`	Audio File Object	The audio file for the podcast episode.
`publishedAt`	Integer	The time (in ms since POSIX epoch) when the podcast episode was published.

Response

Status	Meaning	Description	Schema
200	OK	Success	Library Item Expanded
403	Forbidden	The user is not allowed to access the library item. A user with update permissions is required to update podcast episodes.
404	Not Found	No library item with the given ID exists, or no episode with the given ID exists.
500	Internal Server Error	The library item is not a podcast.

Delete a Podcast Episode

curl -X DELETE "https://abs.example.com/api/podcasts/li_bufnnmp4y5o2gbbxfm/episode/ep_lh6ko39pumnrma3dhv?hard=1" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "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": 1668124892694,
  "ctimeMs": 1668124892694,
  "birthtimeMs": 1667326662083,
  "addedAt": 1667326662087,
  "updatedAt": 1668853355724,
  "lastScan": 1668234374487,
  "scanVersion": "2.2.2",
  "isMissing": false,
  "isInvalid": false,
  "mediaType": "podcast",
  "media": {
    "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
    "metadata": {
      "title": "Welcome to Night Vale",
      "author": "Night Vale Presents",
      "description": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
      "releaseDate": "2022-10-20T19:00:00Z",
      "genres": [
        "Science Fiction",
        "Podcasts",
        "Fiction"
      ],
      "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
      "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
      "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
      "itunesId": 536258179,
      "itunesArtistId": 718704794,
      "explicit": false,
      "language": null,
      "type": "episodic"
    },
    "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
    "tags": [],
    "episodes": [],
    "autoDownloadEpisodes": false,
    "autoDownloadSchedule": "0 0 * * 1",
    "lastEpisodeCheck": 1667326662087,
    "maxEpisodesToKeep": 0,
    "maxNewEpisodesToDownload": 3
  },
  "libraryFiles": [
    {
      "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"
    }
  ]
}

This endpoint deletes a podcast episode from the database. If providing the hard parameter, the file will be deleted as well.

HTTP Request

DELETE http://abs.example.com/api/podcasts/<ID>/episode/<EpisodeID>

URL Parameters

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

Query Parameters

Parameter	Type	Description
`hard`	Binary	Whether to delete the podcast episode files from the server. `0` for false, `1` for true.

Response

Status	Meaning	Description	Schema
200	OK	Success	Library Item
403	Forbidden	The user is not allowed to access the library item. A user with delete permissions is required to delete podcast episodes.
404	Not Found	No library item with the given ID exists, or no episode with the given ID exists.
500	Internal Server Error	The library item is not a podcast.

Notifications

Get Notification Settings

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

{
  "data": {
    "events": [
      {
        "name": "onPodcastEpisodeDownloaded",
        "requiresLibrary": true,
        "libraryMediaType": "podcast",
        "description": "Triggered when a podcast episode is auto-downloaded",
        "variables": [
          "libraryItemId",
          "libraryId",
          "libraryName",
          "mediaTags",
          "podcastTitle",
          "podcastAuthor",
          "podcastDescription",
          "podcastGenres",
          "episodeId",
          "episodeTitle",
          "episodeSubtitle",
          "episodeDescription"
        ],
        "defaults": {
          "title": "New {{podcastTitle}} Episode!",
          "body": "{{episodeTitle}} has been added to {{libraryName}} library."
        },
        "testData": {
          "libraryItemId": "li_notification_test",
          "libraryId": "lib_test",
          "libraryName": "Podcasts",
          "podcastTitle": "Abs Test Podcast",
          "episodeId": "ep_notification_test",
          "episodeTitle": "Successful Test"
        }
      },
      {
        "name": "onTest",
        "requiresLibrary": false,
        "description": "Event for testing the notification system",
        "variables": [
          "version"
        ],
        "defaults": {
          "title": "Test Notification on Abs {{version}}",
          "body": "Test notificataion body for abs {{version}}."
        },
        "testData": {
          "version": "v2.2.5"
        }
      }
    ]
  },
  "settings": {
    "id": "notification-settings",
    "appriseType": "api",
    "appriseApiUrl": "https://apprise.example.com/notify",
    "notifications": [
      {
        "id": "noti_nod281qwkj5ow7h7fi",
        "libraryId": null,
        "eventName": "onPodcastEpisodeDownloaded",
        "urls": [
          "apprises://apprise.example.com/email"
        ],
        "titleTemplate": "New {{podcastTitle}} Episode!",
        "bodyTemplate": "{{episodeTitle}} has been added to {{libraryName}} library.",
        "enabled": true,
        "type": "info",
        "lastFiredAt": 1668776410792,
        "lastAttemptFailed": false,
        "numConsecutiveFailedAttempts": 0,
        "numTimesFired": 5,
        "createdAt": 1666545142424
      }
    ],
    "maxFailedAttempts": 5,
    "maxNotificationQueue": 20,
    "notificationDelay": 1000
  }
}

This endpoint retrieves the server's Apprise notification settings and event data.

HTTP Request

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

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
404	Not Found	An admin user is required get notification settings.

Response Schema

Attribute	Type	Description
`data.events`	Array of Notification Event	The notification event data.
`settings`	Notification Settings Object	The notification settings of the server.

Update Notification Settings

curl -X PATCH "https://abs.example.com/api/notifications" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"appriseApiUrl": "https://apprise.example.com/notify"}'

HTTP Request

PATCH http://abs.example.com/api/notifications

Parameters

Parameter	Type	Default	Description
`appriseApiUrl`	String or null		The full URL where the Apprise API to use is located.
`maxFailedAttempts`	Integer	`5`	The maximum number of times a notification fails before being disabled.
`maxNotificationQueue`	Integer	`20`	The maximum number of notifications in the notification queue before events are ignored.

Response

Status	Meaning	Description
200	OK	Success
404	Not Found	An admin user is required to update notification settings.

Get Notification Event Data

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

{
  "events": [
    {
      "name": "onPodcastEpisodeDownloaded",
      "requiresLibrary": true,
      "libraryMediaType": "podcast",
      "description": "Triggered when a podcast episode is auto-downloaded",
      "variables": [
        "libraryItemId",
        "libraryId",
        "libraryName",
        "mediaTags",
        "podcastTitle",
        "podcastAuthor",
        "podcastDescription",
        "podcastGenres",
        "episodeId",
        "episodeTitle",
        "episodeSubtitle",
        "episodeDescription"
      ],
      "defaults": {
        "title": "New {{podcastTitle}} Episode!",
        "body": "{{episodeTitle}} has been added to {{libraryName}} library."
      },
      "testData": {
        "libraryItemId": "li_notification_test",
        "libraryId": "lib_test",
        "libraryName": "Podcasts",
        "podcastTitle": "Abs Test Podcast",
        "episodeId": "ep_notification_test",
        "episodeTitle": "Successful Test"
      }
    },
    {
      "name": "onTest",
      "requiresLibrary": false,
      "description": "Event for testing the notification system",
      "variables": [
        "version"
      ],
      "defaults": {
        "title": "Test Notification on Abs {{version}}",
        "body": "Test notificataion body for abs {{version}}."
      },
      "testData": {
        "version": "v2.2.5"
      }
    }
  ]
}

This endpoint retrieves the server's notification event data.

HTTP Request

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

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
404	Not Found	An admin user is required get notification event data.

Response Schema

Attribute	Type	Description
`events`	Array of Notification Event	The notification event data.

Fire Test Notification Event

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

This endpoint fires the test notification event.

HTTP Request

GET http://abs.example.com/api/notifications/test

Optional Query Parameters

Parameter	Type	Description
`fail`	Binary	Whether to intentionally cause the notification to fail. `0` for false, `1` for true.

Response

Status	Meaning	Description
200	OK	Success
404	Not Found	An admin user is required to fire notification events.

Create a Notification

curl -X POST "https://abs.example.com/api/notifications" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"eventName": "onPodcastEpisodeDownloaded", "urls": ["apprises://apprise.example.com/email"], "titleTemplate": "New {{podcastTitle}} Episode!", "bodyTemplate": "{{episodeTitle}} has been added to {{libraryName}} library.", "enabled": true, "type": "info"}'

{
  "id": "notification-settings",
  "appriseType": "api",
  "appriseApiUrl": "https://apprise.example.com/notify",
  "notifications": [
    {
      "id": "noti_nod281qwkj5ow7h7fi",
      "libraryId": null,
      "eventName": "onPodcastEpisodeDownloaded",
      "urls": [
        "apprises://apprise.example.com/email"
      ],
      "titleTemplate": "New {{podcastTitle}} Episode!",
      "bodyTemplate": "{{episodeTitle}} has been added to {{libraryName}} library.",
      "enabled": true,
      "type": "info",
      "lastFiredAt": 1668776410792,
      "lastAttemptFailed": false,
      "numConsecutiveFailedAttempts": 0,
      "numTimesFired": 5,
      "createdAt": 1666545142424
    }
  ],
  "maxFailedAttempts": 5,
  "maxNotificationQueue": 20,
  "notificationDelay": 1000
}

This endpoint creates a notification and returns the server's updated notification settings.

HTTP Request

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

Parameters

Parameter	Type	Default	Description
`libraryId`	String or null	`null`	The ID of the library the notification is associated with.
`eventName`	String	Required	The name of the event the notification will fire on.
`urls`	Array of String	Required	The Apprise URLs to use for the notification.
`titleTemplate`	String	Required	The template for the notification title.
`bodyTemplate`	String	Required	The template for the notification body.
`enabled`	Boolean	`false`	Whether the notification is enabled.
`type`	String or null	`null`	The notification's type.

The urls array parameter must have a non-zero length for the notification to be saved.

Response

Status	Meaning	Description	Schema
200	OK	Success	Notification Settings
404	Not Found	An admin user is required create notifications.

Delete a Notification

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

{
  "id": "notification-settings",
  "appriseType": "api",
  "appriseApiUrl": "https://apprise.example.com/notify",
  "notifications": [],
  "maxFailedAttempts": 5,
  "maxNotificationQueue": 20,
  "notificationDelay": 1000
}

This endpoint deletes a notification and returns the server's updated notification settings.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the notification.

Response

Status	Meaning	Description	Schema
200	OK	Success	Notification Settings
404	Not Found	An admin user is required delete notifications, or no notification with the given ID exists.

Update a Notification

curl -X PATCH "https://abs.example.com/api/notifications/noti_nod281qwkj5ow7h7fi" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"id": "noti_nod281qwkj5ow7h7fi", "titleTemplate": "New {{podcastTitle}} Episode: {{episodeTitle}}"}'

{
  "id": "notification-settings",
  "appriseType": "api",
  "appriseApiUrl": "https://apprise.example.com/notify",
  "notifications": [
    {
      "id": "noti_nod281qwkj5ow7h7fi",
      "libraryId": null,
      "eventName": "onPodcastEpisodeDownloaded",
      "urls": [
        "apprises://apprise.example.com/email"
      ],
      "titleTemplate": "New {{podcastTitle}} Episode: {{episodeTitle}}",
      "bodyTemplate": "{{episodeTitle}} has been added to {{libraryName}} library.",
      "enabled": true,
      "type": "info",
      "lastFiredAt": 1668776410792,
      "lastAttemptFailed": false,
      "numConsecutiveFailedAttempts": 0,
      "numTimesFired": 5,
      "createdAt": 1666545142424
    }
  ],
  "maxFailedAttempts": 5,
  "maxNotificationQueue": 20,
  "notificationDelay": 1000
}

This endpoint updates a notification and returns the server's updated notification settings.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the notification.

Parameters

Parameter	Type	Description
`id`	String	Required The ID of the notification.
`libraryId`	String or null	The ID of the library the notification is associated with.
`eventName`	String	The name of the event the notification will fire on.
`urls`	Array of String	The Apprise URLs to use for the notification.
`titleTemplate`	String	The template for the notification title.
`bodyTemplate`	String	The template for the notification body.
`enabled`	Boolean	Whether the notification is enabled.
`type`	String or null	The notification's type.

The id parameter must be included for the notification to be saved.

Response

Status	Meaning	Description	Schema
200	OK	Success	Notification Settings
404	Not Found	An admin user is required update notifications, or no notification with the given ID exists.

Send Notification Test

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

This endpoint sends a test to the given notification.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the notification.

Response

Status	Meaning	Description
200	OK	Success
404	Not Found	An admin user is required to send notification tests, or no notification with the given ID exists.
500	Internal Server Error	The Apprise URL is not set, or the notification failed to send.

Search

Search for Covers

curl "https://abs.example.com/api/search/covers?title=Wizards%20First%20Rule&author=Terry%20Goodkind&provider=openlibrary" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "results": [
    "https://covers.openlibrary.org/b/id/1005963-L.jpg",
    "https://covers.openlibrary.org/b/id/791977-L.jpg",
    "https://covers.openlibrary.org/b/id/766531-L.jpg",
    "https://covers.openlibrary.org/b/id/910943-L.jpg",
    "https://covers.openlibrary.org/b/id/8782857-L.jpg",
    "https://covers.openlibrary.org/b/id/8788596-L.jpg",
    "https://covers.openlibrary.org/b/id/8783892-L.jpg",
    "https://covers.openlibrary.org/b/id/8993240-L.jpg",
    "https://covers.openlibrary.org/b/id/10505009-L.jpg",
    "https://covers.openlibrary.org/b/id/1005881-L.jpg",
    "https://covers.openlibrary.org/b/id/8776837-L.jpg",
    "https://covers.openlibrary.org/b/id/10778344-L.jpg",
    "https://covers.openlibrary.org/b/id/11239659-L.jpg",
    "https://covers.openlibrary.org/b/id/12224404-L.jpg",
    "https://covers.openlibrary.org/b/OLID/OL9034948M-L.jpg",
    "https://covers.openlibrary.org/b/id/8785389-L.jpg"
  ]
}

This endpoint searches a metadata provider for covers.

HTTP Request

GET http://abs.example.com/api/search/covers

Query Parameters

Parameter	Type	Default	Description
`podcast`	Binary	`0`	Whether to search for podcast covers. Only the `title` parameter is needed for podcasts. `0` for false, `1` for true.
`title`	String	Required	The media title to search for.
`author`	String or null	`null`	If searching for a book cover, the author to search for.
`provider`	String	`google`	If searching for a book cover, the metadata provider to use. See Metadata Providers for options.

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below

Response Schema

Attribute	Type	Description
`results`	Array of String	URLs of cover image search results.

Search for Books

curl "https://abs.example.com/api/search/books?title=Wizard's%20First%20Rule&author=Terry%20Goodkind&provider=google" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

[
  {
    "id": "WzO7jSs6XTYC",
    "title": "Wizard's First Rule",
    "subtitle": null,
    "author": "Terry Goodkind",
    "publisher": "RosettaBooks",
    "publishedYear": null,
    "description": "The “wonderfully creative, seamless, and stirring” debut novel in the Sword of Truth epic fantasy series by the #1 New York Times bestselling author (Kirkus). Terry Goodkind’s debut novel, Wizard’s First Rule, was a phenomenon from the moment it was first published by Tor Books in 1994. In it, readers are drawn into the magical New World, where ordinary Westland forest guide Richard Cypher accepts his extraordinary destiny. As a Seeker of Truth, Richard is the only one who can stop the tyrannical wizard Darken Rahl from seizing the all-powerful Boxes of Orden. When the beautiful and mysterious Kahlan Amnell appears in Richard's forest seeking help, his humble world is turned on its head. After proving that he can wield the Sword of Truth, Richard knows that a confrontation with Darken Rahl looms. But Kahlan beseeches him to reach beyond his sword and invoke his inner nobility in order to face the dangerous challenges ahead.",
    "cover": "http://books.google.com/books/content?id=WzO7jSs6XTYC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api",
    "genres": [
      "Fiction"
    ],
    "isbn": "9780795330766"
  },
  ...
]

curl "https://abs.example.com/api/search/books?title=Wizard's%20First%20Rule&author=Terry%20Goodkind&provider=openlibrary" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

[
  {
    "title": "Wizard's First Rule",
    "author": "Terry Goodkind",
    "publishedYear": null,
    "cover": null,
    "id": "OL20134604W",
    "key": "/works/OL20134604W",
    "covers": [
      "https://covers.openlibrary.org/b/id/8785389-L.jpg"
    ],
    "description": null,
    "cleanedTitle": "wizards first rule",
    "titleDistance": 1,
    "totalPossibleDistance": 33,
    "cleanedAuthor": "terry goodkind",
    "authorDistance": 0,
    "includesAuthor": "terry goodkind",
    "totalDistance": 1,
    "includesTitle": "wizards first rule"
  },
  ...
]

curl "https://abs.example.com/api/search/books?title=Wizard's%20First%20Rule&author=Terry%20Goodkind&provider=itunes" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

[
  {
    "id": 293863242,
    "artistId": 279725677,
    "title": "Wizard's First Rule: Sword of Truth, Book 1 (Unabridged)",
    "author": "Terry Goodkind",
    "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of TruthIn 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.",
    "publishedYear": "2008",
    "genres": [
      "Sci-Fi & Fantasy"
    ],
    "cover": "https://is1-ssl.mzstatic.com/image/thumb/Music123/v4/e7/f9/05/e7f90571-b5be-be74-064e-81da7ce94143/rm_image.jpg/600x600bb.jpg"
  }
]

curl "https://abs.example.com/api/search/books?title=Wizard's%20First%20Rule&author=Terry%20Goodkind&provider=audible" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

[
  {
    "title": "Wizard's First Rule",
    "subtitle": "Sword of Truth, Book 1",
    "author": "Terry Goodkind",
    "narrator": "Sam Tsoutsouvas",
    "publisher": "Brilliance Audio",
    "publishedYear": "2008",
    "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.",
    "cover": "https://m.media-amazon.com/images/I/81E153-vqwL.jpg",
    "asin": "B002V0QK4C",
    "genres": [
      "Literature & Fiction",
      "Science Fiction & Fantasy"
    ],
    "tags": "Genre Fiction, Movie, TV & Video Game Tie-Ins, Fantasy, Epic",
    "series": [
      {
        "series": "Sword of Truth",
        "sequence": "1"
      }
    ],
    "language": "English",
    "duration": 2046,
    "region": null,
    "rating": "4.5"
  }
]

curl "https://abs.example.com/api/search/books?title=Wizard's%20First%20Rule&author=Terry%20Goodkind&provider=fantlab" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

[
  {
    "id": 3617,
    "title": "Первое правило волшебника",
    "subtitle": null,
    "author": "Терри Гудкайнд",
    "publisher": null,
    "publishedYear": 1994,
    "description": "Еще вчера молодой Ричард был всего лишь лесным проводником, а нынче ему выпал на долю тяжкий жребий Искателя Истины. Тяжкий, ибо магия не приносит радости, а за истину, как и за могущество, расплачиваются дорогой ценой. Тяжкий - ибо Искателю Истины надлежит вступить с величайшим из черных магов трех королевств, безжалостным Даркеном Ралом, повелителем Д'Хары, в смертельную схватку за обладание тремя волшебными шкатулками Одена, одна из которых дарует бессмертие, вторая - смерть, а третья - несет гибель всему живому...",
    "cover": "https://fantlab.ru/images/editions/big/11286?r=1492542872",
    "genres": [
      "Фэнтези",
      "Героическое фэнтези",
      "Эпическое фэнтези"
    ],
    "isbn": null
  }
]

This endpoint searches a metadata provider for a book. An array of book search results is returned.

HTTP Request

GET http://abs.example.com/api/search/books

Query Parameters

Parameter	Type	Default	Description
`title`	String	`''`	The book title to search for. If using Audible for `provider`, can also be the book's ASIN.
`author`	String	`''`	The author to search for.
`provider`	String	`google`	The metadata provider to use. See Metadata Providers for options.

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below

Response Schema

Each response will be an array of objects with the attributes depending on the requested metadata provider.

Metadata Provider: Google

Attribute	Type	Description
`id`	String	The book's Google ID.
`title`	String	The book's title.
`subtitle`	String or null	The book's subtitle.
`author`	String or null	The book's author.
`publisher`	String or null	The book's publisher.
`description`	String or null	The book's description.
`cover`	String or null	The URL of the book's cover image.
`genres`	Array of String	The book's genres.
`isbn`	String	The book's ISBN.

Metadata Provider: Open Library

Attribute	Type	Description
`title`	String	The book's title.
`author`	String or null	The book's author.
`publishedYear`	Integer	The year the book was published.
`cover`	String or null	The URL of the book's cover image.
`id`	String	The book's Open Library ID.
`key`	String	The path of the book's Open Library URL.
`covers`	Array of String	URLs of cover images for the book.
`description`	String or null	The book's description.
`cleanedTitle`	String	A cleaned version of the query title used for searching.
`titleDistance`	Integer	The Levenshtein distance between `cleanedTitle` and `title`.
`totalPossibleDistance`	Integer	The maximum for `totalDistance`.
`cleanedAuthor`	String	A cleaned version of the query author used for searching.
`authorDistance`	Integer	The Levenshtein distance between `cleanedAuthor` and `author`.
`includesAuthor`	String	The query author contained in `author`.
`totalDistance`	Integer	`titleDistance` + `authorDistance`
`includesTitle`	String	The query title contained in `title`.

Metadata Provider: iTunes

Attribute	Type	Description
`id`	Integer	The book's iTunes ID.
`artistId`	Integer	The book's author's iTunes ID.
`title`	String	The book's title.
`author`	String or null	The book's author.
`description`	String or null	The book's description.
`publishedYear`	String or null	The year the book was published.
`genres`	Array of String	The book's genres.
`cover`	String or null	The URL of the book's cover image.

Metadata Provider: Audible

Attribute	Type	Description
`title`	String	The book's title.
`subtitle`	String or null	The book's subtitle.
`author`	String or null	The book's author.
`narrator`	String or null	The book's narrator.
`publisher`	String or null	The book's publisher.
`publishedYear`	String or null	The year the book was published.
`description`	String or null	The book's description.
`cover`	String or null	The URL of the book's cover image.
`asin`	String	The book's ASIN.
`genres`	Array of String	The book's genres.
`tags`	String	A comma and space separated list of the book's tags.
`series`	Array of Series Sequence	The book's series.
`language`	String	The book's language.
`duration`	Integer	The total duration (in minutes) of the book.
`region`	String or null	The Audible region that was searched.
`rating`	String or null	The book's Audible rating.

Metadata Provider: FantLab

Attribute	Type	Description
`id`	Integer	The book's FantLab ID.
`title`	String	The book's title.
`subtitle`	String or null	The book's subtitle.
`author`	String or null	The book's author.
`publisher`	String or null	The book's publisher.
`publishedYear`	Integer or null	The book's published year.
`description`	String or null	The book's description.
`cover`	String or null	The URL of the book's cover image.
`genres`	Array of String	The book's genres.
`isbn`	String or null	The book's ISBN.

Search for Podcasts

curl "https://abs.example.com/api/search/podcast?term=Welcome%20To%20Night%20Vale" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

[
  {
    "id": 536258179,
    "artistId": 718704794,
    "title": "Welcome to Night Vale",
    "artistName": "Night Vale Presents",
    "description": "",
    "descriptionPlain": "",
    "releaseDate": "2022-11-15T05:00:00Z",
    "genres": [
      "Science Fiction",
      "Podcasts",
      "Fiction"
    ],
    "cover": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
    "trackCount": 280,
    "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
    "pageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
    "explicit": false
  },
  ...
]

This endpoint searches iTunes for podcasts and returns an array of the results.

HTTP Request

GET http://abs.example.com/api/search/podcast

Query Parameters

Parameter	Type	Description
`term`	String	The search term to search for (i.e. the title of the podcast).

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below

Response Schema

The response will be an array of objects with the following attributes:

Attribute	Type	Description
`id`	Integer	The iTunes ID of the podcast.
`artistId`	Integer	The podcast's author's iTunes ID.
`title`	String	The tile of the podcast.
`artistName`	String	The podcast's author.
`description`	String	An HTML encoded description of the podcast.
`descriptionPlain`	String	A plain text description of the podcast.
`releaseDate`	String	The podcast's release date.
`genres`	Array of String	The podcast's genres.
`cover`	String	The URL of the podcast's cover image.
`trackCount`	Integer	The number of episodes the podcast has.
`feedUrl`	String	The URL of the podcast's RSS feed.
`pageUrl`	String	The URL of the podcast's iTunes page.
`explicit`	Boolean	Whether the podcast is marked as explicit.

Search for an Author

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

{
  "asin": "B000APZOQA",
  "description": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork, ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20 languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's brilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind has an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying situations. With masterful storytelling, Goodkind brings us into the lives of his characters; characters that must rise to face not only challenges, but their deepest fears. For that reason, Goodkind’s characters speak to the best and worst in all of us. While ‘The Sword of Truth’ series is confirmation enough of Goodkind’s incredible storytelling abilities, his broad talents are also clearly evident in his contemporary novels, set within our own world. His post-‘Sword of Truth’ books are a thrilling, dizzying, mix of modern narrative, with every bit of Goodkind’s masterful voice intact. The bond built between the reader and one of the world’s great authors, rises above worlds and settings, mere backdrops for Goodkind’s uniquely intricate stories of life, love, challenge, and triumph. \"My privilege in life is the joy of writing books and telling stories about people who fascinate me, the good and the bad. I am grateful to all of my readers for the critical role they play in making these books possible. Your passion is my passion, and I thank you.\" - Terry Goodkind For more, please visit: http://terrygoodkind.com",
  "image": "https://images-na.ssl-images-amazon.com/images/I/51NoQTm33OL.jpg",
  "name": "Terry Goodkind"
}

This endpoint searches Audnexus (which mostly uses Audible for its data) for authors.

HTTP Request

GET http://abs.example.com/api/search/authors

Query Parameters

Parameter	Type	Description
`q`	String	The search query. The provided name must match the author's name on Audnexus exactly to get a result.

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below

Response Schema

Either null or an object with the following attributes will be returned.

Attribute	Type	Description
`asin`	String	The author's ASIN.
`description`	String	The author's description.
`image`	String	The URL of the author's image.
`name`	String	The author's name.

Search for a Book's Chapters

curl "https://abs.example.com/api/search/chapters?asin=B000APZOQA" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "asin": "B08G9PRS1K",
  "brandIntroDurationMs": 2043,
  "brandOutroDurationMs": 5061,
  "chapters": [
    {
      "lengthMs": 13307,
      "startOffsetMs": 0,
      "startOffsetSec": 0,
      "title": "Opening Credits"
    },
    {
      "lengthMs": 5909,
      "startOffsetMs": 13307,
      "startOffsetSec": 13,
      "title": "Dedication"
    },
    {
      "lengthMs": 2203908,
      "startOffsetMs": 19216,
      "startOffsetSec": 19,
      "title": "Chapter 1"
    },
    {
      "lengthMs": 1721527,
      "startOffsetMs": 2223124,
      "startOffsetSec": 2223,
      "title": "Chapter 2"
    },
    {
      "lengthMs": 2241282,
      "startOffsetMs": 3944651,
      "startOffsetSec": 3945,
      "title": "Chapter 3"
    },
    {
      "lengthMs": 2460850,
      "startOffsetMs": 6185933,
      "startOffsetSec": 6186,
      "title": "Chapter 4"
    },
    {
      "lengthMs": 3189400,
      "startOffsetMs": 8646783,
      "startOffsetSec": 8647,
      "title": "Chapter 5"
    },
    {
      "lengthMs": 2650650,
      "startOffsetMs": 11836183,
      "startOffsetSec": 11836,
      "title": "Chapter 6"
    },
    {
      "lengthMs": 1806744,
      "startOffsetMs": 14486833,
      "startOffsetSec": 14487,
      "title": "Chapter 7"
    },
    {
      "lengthMs": 2189734,
      "startOffsetMs": 16293577,
      "startOffsetSec": 16294,
      "title": "Chapter 8"
    },
    {
      "lengthMs": 1759608,
      "startOffsetMs": 18483311,
      "startOffsetSec": 18483,
      "title": "Chapter 9"
    },
    {
      "lengthMs": 2120817,
      "startOffsetMs": 20242919,
      "startOffsetSec": 20243,
      "title": "Chapter 10"
    },
    {
      "lengthMs": 1566928,
      "startOffsetMs": 22363736,
      "startOffsetSec": 22364,
      "title": "Chapter 11"
    },
    {
      "lengthMs": 1744236,
      "startOffsetMs": 23930664,
      "startOffsetSec": 23931,
      "title": "Chapter 12"
    },
    {
      "lengthMs": 1954655,
      "startOffsetMs": 25674900,
      "startOffsetSec": 25675,
      "title": "Chapter 13"
    },
    {
      "lengthMs": 2405262,
      "startOffsetMs": 27629555,
      "startOffsetSec": 27630,
      "title": "Chapter 14"
    },
    {
      "lengthMs": 1429838,
      "startOffsetMs": 30034817,
      "startOffsetSec": 30035,
      "title": "Chapter 15"
    },
    {
      "lengthMs": 1950336,
      "startOffsetMs": 31464655,
      "startOffsetSec": 31465,
      "title": "Chapter 16"
    },
    {
      "lengthMs": 1928602,
      "startOffsetMs": 33414991,
      "startOffsetSec": 33415,
      "title": "Chapter 17"
    },
    {
      "lengthMs": 1863772,
      "startOffsetMs": 35343593,
      "startOffsetSec": 35344,
      "title": "Chapter 18"
    },
    {
      "lengthMs": 2176359,
      "startOffsetMs": 37207365,
      "startOffsetSec": 37207,
      "title": "Chapter 19"
    },
    {
      "lengthMs": 1984841,
      "startOffsetMs": 39383724,
      "startOffsetSec": 39384,
      "title": "Chapter 20"
    },
    {
      "lengthMs": 2536919,
      "startOffsetMs": 41368565,
      "startOffsetSec": 41369,
      "title": "Chapter 21"
    },
    {
      "lengthMs": 2396531,
      "startOffsetMs": 43905484,
      "startOffsetSec": 43905,
      "title": "Chapter 22"
    },
    {
      "lengthMs": 1726217,
      "startOffsetMs": 46302015,
      "startOffsetSec": 46302,
      "title": "Chapter 23"
    },
    {
      "lengthMs": 1672672,
      "startOffsetMs": 48028232,
      "startOffsetSec": 48028,
      "title": "Chapter 24"
    },
    {
      "lengthMs": 2376608,
      "startOffsetMs": 49700904,
      "startOffsetSec": 49701,
      "title": "Chapter 25"
    },
    {
      "lengthMs": 1290100,
      "startOffsetMs": 52077512,
      "startOffsetSec": 52078,
      "title": "Chapter 26"
    },
    {
      "lengthMs": 613331,
      "startOffsetMs": 53367612,
      "startOffsetSec": 53368,
      "title": "Chapter 27"
    },
    {
      "lengthMs": 1191369,
      "startOffsetMs": 53980943,
      "startOffsetSec": 53981,
      "title": "Chapter 28"
    },
    {
      "lengthMs": 2198976,
      "startOffsetMs": 55172312,
      "startOffsetSec": 55172,
      "title": "Chapter 29"
    },
    {
      "lengthMs": 838616,
      "startOffsetMs": 57371288,
      "startOffsetSec": 57371,
      "title": "Chapter 30"
    },
    {
      "lengthMs": 43091,
      "startOffsetMs": 58209904,
      "startOffsetSec": 58210,
      "title": "End Credits"
    }
  ],
  "isAccurate": true,
  "runtimeLengthMs": 58252995,
  "runtimeLengthSec": 58253
}

This endpoint searches Audnexus for a book's chapters.

HTTP Request

GET http://abs.example.com/api/search/chapters

Query Parameters

Parameter	Type	Default	Description
`asin`	String	Required	The book's ASIN.
`region`	String	`us`	The book's region.

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below

Response Schema

Either the response will be an error:

Attribute	Type	Description
`error`	String	The error that occurred.

Or a result:

Attribute	Type	Description
`asin`	String	The book's ASIN.
`brandIntroDurationMs`	Integer	The duration (in ms) of the audiobook brand's intro (i.e. the "This is Audible." at the beginning).
`brandOutroDurationMs`	Integer	The duration (in ms) of the audiobook brand's outro (i.e. the "Audible hopes you have enjoyed this program." at the end).
`chapters`	Array of Search Result Chapter (See Below)	The book's chapters.
`isAccurate`	Boolean	Whether Audnexus thinks the chapters are accurate.
`runtimeLengthMs`	Integer	The total runtime length (in ms) of the book.
`runtimeLengthSec`	Integer	The total runtime length (in seconds) of the book.

Search Result Chapter

Attribute	Type	Description
`lengthMs`	Integer	The length (in ms) of the chapter.
`startOffsetMs`	Integer	The start offset (in ms) of the chapter.
`startOffsetSec`	Integer	The start offset (in seconds) of the chapter.
`title`	String	The chapter's title.

Cache

Purge All Cache

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

This endpoint purges all cache on the server, deleting the entire directory at /metadata/cache.

HTTP Request

POST http://abs.example.com/api/cache/purge

Response

Status	Meaning	Description
200	OK	Success
403	Forbidden	An admin user is required to purge the cache.

Purge Items Cache

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

This endpoint purges the items cache on the server, deleting the entire directory at /metadata/cache/items.

HTTP Request

POST http://abs.example.com/api/cache/items/purge

Response

Status	Meaning	Description
200	OK	Success
403	Forbidden	An admin user is required to purge the items cache.

Tools

Encode a Book as M4B

curl -X POST "https://abs.example.com/api/tools/item/li_8gch9ve09orgn4fdz8/encode-m4b" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

This endpoint starts a task on the server to take the existing audio files of a book, and merge and encode them into an .m4b file.

HTTP Request

POST http://abs.example.com/api/tools/item/<ID>/encode-m4b

URL Parameters

Parameter	Description
ID	The ID of the book library item.

Query Parameters

Parameter	Type	Default	Description
`bitrate`	String	`64k`	The bitrate to pass to ffmpeg.
`codec`	String	`aac`	The audio codec to pass to ffmpeg.
`channels`	Integer	`2`	The number of audio channels to pass to ffmpeg.

Response

Status	Meaning	Description
200	OK	Success
403	Forbidden	The user is not allowed to access the library item, or an admin user is required to make an `.m4b` file.
404	Not Found	No library item with the given ID exists, or the library item has missing or invalid files.
500	Internal Server Error	The library item is not a book, or does not have audio tracks.

Cancel an M4B Encode Task

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

This endpoint cancels an in-progress M4B encode task on the server.

HTTP Request

DELETE http://abs.example.com/api/tools/item/<ID>/encode-m4b

URL Parameters

Parameter	Description
ID	The ID of the book library item.

Response

Status	Meaning	Description
200	OK	Success
403	Forbidden	The user is not allowed to access the library item, or an admin user is required to cancel an M4B encode task.
404	Not Found	No library item with the given ID exists, or no M4B encode task is in-progress for the library item.

Update a Library Item's Audio Files' Embedded Metadata

curl -X POST "https://abs.example.com/api/tools/item/li_bufnnmp4y5o2gbbxfm/embed-metadata" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

This endpoint updates a library item's audio files' embedded metadata.

HTTP Request

POST http://abs.example.com/api/tools/item/<ID>/embed-metadata

URL Parameters

Parameter	Description
ID	The ID of the library item.

Optional Query Parameters

Parameter	Type	Description
`backup`	Binary	Whether to backup original audio files in `/metadata/cache/items`. Default is true if not specified. `0` for false, `1` for true.
`forceEmbedChapters`	Binary	Chapters are not embedded in multi-track audiobooks by default. Enable this setting to embed chapters in every audio file. `0` for false, `1` for true.

Response

Status	Meaning	Description
200	OK	Success
403	Forbidden	The user is not allowed to access the library item, or an admin user is required to update a library item's audio files' embedded metadata.
404	Not Found	No library item with the given ID exists.
500	Internal Server Error	The library item has missing parts, does not have audio files, or is not a book.

RSS Feeds

Open an RSS Feed for a Library Item

curl -X POST "https://abs.example.com/api/feeds/item/li_bufnnmp4y5o2gbbxfm/open" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"serverAddress": "https://abs.example.com", "slug": "li_bufnnmp4y5o2gbbxfm"}'

{
  "feed": {
    "id": "li_bufnnmp4y5o2gbbxfm",
    "entityType": "item",
    "entityId": "li_bufnnmp4y5o2gbbxfm",
    "feedUrl": "https://abs.example.com/feed/li_bufnnmp4y5o2gbbxfm",
    "meta": {
      "title": "Welcome to Night Vale",
      "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    ",
      "preventIndexing": true,
      "ownerName": null,
      "ownerEmail": null
    }
  }
}

This endpoint opens an RSS feed for a library item.

HTTP Request

POST http://abs.example.com/api/feeds/item/<LibraryItemID>/open

URL Parameters

Parameter	Description
LibraryItemID	The ID of the library item.

Parameters

Parameter	Type	Description
`serverAddress`	String	The URL address of the server.
`slug`	String	The slug (the last part of the URL) to use for the RSS feed.

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
400	Bad Request	The `serverAddress` and `slug` parameters are required, or the item does not have audio tracks, or the `slug` is already in use.
403	Forbidden	An admin user is required to open an RSS feed.
404	Not Found	No library item with the given ID exists.

Response Schema

Attribute	Type	Description
`feed`	RSS Feed Minified Object	The RSS feed that was opened.

Open an RSS Feed for a Collection

curl -X POST "https://abs.example.com/api/feeds/collection/col_fpfstanv6gd7tq2qz7/open" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"serverAddress": "https://abs.example.com", "slug": "col_fpfstanv6gd7tq2qz7"}'

{
  "feed": {
    "id": "col_fpfstanv6gd7tq2qz7",
    "entityType": "collection",
    "entityId": "col_fpfstanv6gd7tq2qz7",
    "feedUrl": "https://abs.example.com/feed/col_fpfstanv6gd7tq2qz7",
    "meta": {
      "title": "Favorites",
      "description": null,
      "preventIndexing": true,
      "ownerName": null,
      "ownerEmail": null
    }
  }
}

This endpoint opens an RSS feed for a collection.

HTTP Request

POST http://abs.example.com/api/feeds/collection/<CollectionID>/open

URL Parameters

Parameter	Description
CollectionID	The ID of the collection.

Parameters

Parameter	Type	Description
`serverAddress`	String	The URL address of the server.
`slug`	String	The slug (the last part of the URL) to use for the RSS feed.

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
400	Bad Request	The `serverAddress` and `slug` parameters are required, or the collection does not have audio tracks, or the `slug` is already in use.
403	Forbidden	An admin user is required to open an RSS feed.
404	Not Found	No collection with the given ID exists.

Response Schema

Attribute	Type	Description
`feed`	RSS Feed Minified Object	The RSS feed that was opened.

Open an RSS Feed for a Series

curl -X POST "https://abs.example.com/api/feeds/series/ser_cabkj4jeu8be3rap4g/open" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"serverAddress": "https://abs.example.com", "slug": "ser_cabkj4jeu8be3rap4g"}'

{
  "feed": {
    "id": "ser_cabkj4jeu8be3rap4g",
    "entityType": "series",
    "entityId": "ser_cabkj4jeu8be3rap4g",
    "feedUrl": "https://abs.example.com/feed/ser_cabkj4jeu8be3rap4g",
    "meta": {
      "title": "Sword of Truth",
      "description": null,
      "preventIndexing": true,
      "ownerName": null,
      "ownerEmail": null
    }
  }
}

This endpoint opens an RSS feed for a series.

HTTP Request

POST http://abs.example.com/api/feeds/series/<SeriesID>/open

URL Parameters

Parameter	Description
SeriesID	The ID of the series.

Parameters

Parameter	Type	Description
`serverAddress`	String	The URL address of the server.
`slug`	String	The slug (the last part of the URL) to use for the RSS feed.

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
400	Bad Request	The `serverAddress` and `slug` parameters are required, or the series does not have audio tracks, or the `slug` is already in use.
403	Forbidden	An admin user is required to open an RSS feed.
404	Not Found	No series with the given ID exists.

Response Schema

Attribute	Type	Description
`feed`	RSS Feed Minified Object	The RSS feed that was opened.

Close an RSS Feed

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

This endpoint closes an RSS feed.

HTTP Request

POST http://abs.example.com/api/feeds/<ID>/close

URL Parameters

Parameter	Description
ID	The ID of the RSS feed.

Response

Status	Meaning	Description
200	OK	Success
403	Forbidden	An admin user is required to close an RSS feed.

Misc

Upload Files

curl -X POST "https://abs.example.com/api/upload" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -F title="Wizard's First Rule" \
  -F author="Terry Goodkind" \
  -F series="Sword of Truth" \
  -F library="lib_c1u6t4p45c35rf0nzd" \
  -F folder="fol_bev1zuxhb0j0s1wehr" \
  -F 0=@"Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3" \
  -F 1=@"Terry Goodkind - SOT Bk01 - Wizards First Rule 02.mp3" \
  -F 2=@cover.jpg

This endpoint uploads library item files to the server.

HTTP Request

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

Form Parameters

Parameter	Type	Description
`title`	String	The library item's title.
`author`	String	Optionally, the library item's author.
`series`	String	Optionally, the library item's series.
`library`	String	The ID of the library to put the item in.
`folder`	String	The ID of the folder to put the item in.

The files will be put in a directory at <folderDir>/<author>/<series>/<title>.

The form keys for the files can be anything as they are ignored.

The following file types are supported:

.png
.jpg
.jpeg
.webp
.m4b
.mp3
.m4a
.flac
.opus
.ogg
.oga
.mp4
.aac
.wma
.aiff
.wav
.webm
.webma
.epub
.pdf
.mobi
.azw3
.cbr
.cbz
.nfo
.txt
.opf
.abs

Response

Status	Meaning	Description
200	OK	Success
400	Bad Request	No files were provided.
403	Forbidden	A user with upload permissions is required.
404	Not Found	No library with the given ID exists, or no folder with the given ID exists in the library.
500	Internal Server Error	No files were provided, or the upload directory already exists.

Update Server Settings

curl -X PATCH "https://abs.example.com/api/settings" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"scannerFindCovers": false}'

{
  "success": true,
  "serverSettings": {
    "id": "server-settings",
    "scannerFindCovers": false,
    "scannerCoverProvider": "google",
    "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",
    "timeFormat": "HH:mm",
    "language": "en-us",
    "logLevel": 2,
    "version": "2.2.5"
  }
}

This endpoint updates the server's settings.

HTTP Request

PATCH http://abs.example.com/api/settings

Parameters

Provide a Server Settings object with the key-value pairs to update.

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
403	Forbidden	An admin user is required to update server settings.
500	Internal Server Error	Invalid server settings update object.

Response Schema

Attribute	Type	Description
`success`	Boolean	Whether the server settings were updated successfully.
`serverSettings`	Server Settings Object	The updated server settings.

Get Authorized User and Server Information

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

{
  "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",
    "timeFormat": "HH:mm",
    "language": "en-us",
    "logLevel": 2,
    "version": "2.2.5"
  },
  "Source": "docker"
}

This endpoint retrieves information about the authorized user and the server. Used for logging into a client if an API token was persisted. Returns the same payload as /login (Login).

HTTP Request

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

Response

Status	Meaning	Description	Schema
200	OK	Success	See below.
401	Unauthorized	No authorization was provided.

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.

Get All Tags

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

{
  "tags": [
    "Favorite"
  ]
}

This endpoint retrieves all tags assigned to library items.

HTTP Request

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

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below
404	Not Found	An admin user is required to get all tags.

Response Schema

Attribute	Type	Description
`tags`	Array of String	The requested tags.

Rename a Tag

curl -X POST "https://abs.example.com/api/tags/rename" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"tag": "Favorite", "newTag": "The Best"}'

{
  "tagMerged": false,
  "numItemsUpdated": 1
}

This endpoint renames an existing tag.

HTTP Request

POST http://abs.example.com/api/tags/rename

Parameters

Parameter	Type	Description
`tag`	String	The current name of the tag.
`newTag`	String	The new name for the tag.

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below
400	Bad Request	`tag` and `newTag` are required parameters.
404	Not Found	An admin user is required to rename tags.

Response Schema

Attribute	Type	Description
`tagMerged`	Boolean	Whether the renamed tag was merged into another tag.
`numItemsUpdated`	Integer	The number of library items that had their tags changed.

Delete a Tag

curl -X DELETE "https://abs.example.com/api/tags/VGhlIEJlc3Q%3D" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "numItemsUpdated": 1
}

This endpoint deletes a tag, removing it from all library items.

HTTP Request

DELETE http://abs.example.com/api/tags/<Tag>

URL Parameters

Parameter	Description
Tag	The name of the tag to delete, Base64 and URL encoded.

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below
404	Not Found	An admin user is required to delete tags.

Response Schema

Attribute	Type	Description
`numItemsUpdated`	Integer	The number of library items that had their tags changed.

Get All Genres

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

{
  "genres": [
    "Fantasy"
  ]
}

This endpoint retrieves all genres assigned to library items.

HTTP Request

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

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below
404	Not Found	An admin user is required to get all genres.

Response Schema

Attribute	Type	Description
`genres`	Array of String	The requested genres.

Rename a Genre

curl -X POST "https://abs.example.com/api/genres/rename" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"genre": "Fantasy", "newGenre": "Magic"}'

{
  "genreMerged": false,
  "numItemsUpdated": 1
}

This endpoint renames an existing genre.

HTTP Request

POST http://abs.example.com/api/genres/rename

Parameters

Parameter	Type	Description
`genre`	String	The current name of the genre.
`newGenre`	String	The new name for the genre.

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below
400	Bad Request	`genre` and `newGenre` are required parameters.
404	Not Found	An admin user is required to rename genres.

Response Schema

Attribute	Type	Description
`genreMerged`	Boolean	Whether the renamed genre was merged into another genre.
`numItemsUpdated`	Integer	The number of library items that had their genres changed.

Delete a Genre

curl -X DELETE "https://abs.example.com/api/genres/TWFnaWM%3D" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY"

{
  "numItemsUpdated": 1
}

This endpoint deletes a genre, removing it from all library items.

HTTP Request

DELETE http://abs.example.com/api/genres/<Genre>

URL Parameters

Parameter	Description
Genre	The name of the genre to delete, Base64 and URL encoded.

Response

Status	Meaning	Description	Schema
200	OK	Success	See Below
404	Not Found	An admin user is required to delete genres.

Response Schema

Attribute	Type	Description
`numItemsUpdated`	Integer	The number of library items that had their genres changed.

Validate a Cron Expression

curl -X POST "https://abs.example.com/api/validate-cron" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"expression": "30 1 * * *"}'

This endpoint validates a given cron expression.

HTTP Request

POST http://abs.example.com/api/validate-cron

Parameters

Parameter	Type	Description
`expression`	String	The cron expression to validate.

Response

Status	Meaning	Description
200	OK	Success
400	Bad Request	The `expression` parameter is required, or the `expression` is invalid.

Socket

Audiobookshelf uses Socket.io for bidirectional communication between clients and the server. Each client must first authenticate itself using a user's API token in order to subscribe to events for that user. There is also an example for how to use the socket.

Client Events

socket.emit('auth', 'exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY')

socket.emit('cancel_scan', 'lib_c1u6t4p45c35rf0nzd')

socket.emit('set_log_listener', 2)

socket.emit('message_all_users', { message: 'Message from admin' })

These are events that clients can emit. See Miscellaneous Events for events that the server responds to these events with.

Name	Description	Schema
`auth`	Authenticates the socket connection. Causes the server to emit the `init` or `invalid_token` event.	API Token String
`cancel_scan`	Cancels an in progress library scan.	Library ID String
`set_log_listener`	Makes the server emit `log` events of the given level or below to the client.	Log Level Integer: `1` for debug, `2` for info, or `3` for warnings, `4` for errors.
`remove_log_listener`	Removes the client as a log listener.
`fetch_daily_logs`	Causes the server to emit the `daily_logs` event.
`message_all_users`	Admin Users Only Send a message to all users using the `admin_message` server event.	Message All Users Object
`ping`	Causes the server to emit the `pong` event.

Message All Users

Attribute	Type	Description
`message`	String	The message to send to all users.

Server Events

The events that the server can emit are in the sections below. Events marked with "Admin Only" are only sent to sockets with an authenticated admin user.

User Events

Name	Description	Schema
`user_online`	Admin Only A user is online.	User with Session Object
`user_offline`	Admin Only A user is offline.	User with Session Object
`user_added`	Admin Only A user was created.	User Object
`user_updated`	The authenticated user has been updated.	User Object
`user_removed`	Admin Only A user was deleted.	User Object
`user_item_progress_updated`	One of the authenticated user's media progress was created/updated.	User Item Progress Updated Event
`user_stream_update`	Admin Only A user started or stopped a playback session.	User with Session Object

User Item Progress Updated Event

{
  "id": "li_bufnnmp4y5o2gbbxfm-ep_lh6ko39pumnrma3dhv",
  "data": {...}
}

Attribute	Type	Description
`id`	String	The ID of the updated media progress.
`data`	Media Progress Object	The updated media progress.

Stream Events

Name	Description	Schema
`stream_open`	A stream has opened.	Stream Object
`stream_closed`	A stream has closed.	Stream ID String
`stream_progress`	A stream transcode progress update.	Stream Progress Object
`stream_ready`	A stream is ready, transcoding has already been completed on the requested stream.
`stream_reset`	A stream was reset.	Stream Reset Event Object
`stream_error`	A stream error occurred. Emitted when ffmpeg has an error while transcoding.	Stream Error Event Object

Stream Reset Event

{
  "startTime": 0,
  "streamId": "play_c786zm3qtjz6bd5q3n"
}

Attribute	Type	Description
`startTime`	Float	The new start time (in seconds) of the stream.
`streamId`	String	The ID of the stream being reset.

Stream Error Event

{
  "id": "play_c786zm3qtjz6bd5q3n",
  "error": "ffmpeg exited with code 1"
}

Attribute	Type	Description
`id`	String	The ID of the stream where the error occurred.
`error`	String	The error's message.

Library Events

Name	Description	Schema
`library_added`	A library was created.	Library Object
`library_updated`	A library was updated.	Library Object
`library_removed`	A library was deleted.	Library Object

Library Scan Events

Name	Description	Schema
`scan_start`	A library scan was started.	Library Scan Object
`scan_complete`	A library scan was completed.	Library Scan Object

Library Scan

{
  "id": "lib_yq748byukae93rulli",
  "type": "scan",
  "name": "Audiobooks",
  "results": {...}
}

Attribute	Type	Description
`id`	String	The ID of the scanned library.
`type`	String	The type of the library scan. Will be `scan` or `match`.
`name`	String	The name of the scanned library.
`results`	Library Scan Results Object or null	The results of the library scan. Will be `null` if the scan was canceled.

Library Scan Results

{
  "added": 0,
  "updated": 0,
  "missing": 0
}

Attribute	Type	Description
`added`	Integer	The number of library items added during the scan.
`updated`	Integer	The number of library items updated during the scan.
`missing`	Integer	The number of library items discovered to be missing during the scan.

Library Item Events

Name	Description	Schema
`item_added`	A library item was created.	Library Item Expanded Object
`item_updated`	A library item was updated.	Library Item Expanded Object
`item_removed`	A library item was deleted.	Library Item Expanded Object
`items_added`	Library items were created.	Array of Library Item Expanded
`items_updated`	Library items were updated.	Array of Library Item Expanded
`batch_quickmatch_complete`	Batch library item quick matching is complete.	Batch Quick Match Result Object

Batch Quick Match Result

{
  "success": true,
  "updates": 3,
  "unmatched": 0
}

Attribute	Type	Description
`success`	Boolean	Whether library items were successfully updated.
`updates`	Integer	The number of library items that were updated.
`unmatched`	Integer	The number of library items that a match could not be found for.

Author Events

Name	Description	Schema
`author_added`	An author was created.	Author Object
`author_updated`	An author was updated.	Author Expanded Object
`author_removed`	An author was deleted.	Author Object
`authors_added`	Authors were created.	Array of Author

Series Events

Name	Description	Schema
`series_added`	A series was created.	Series Object
`series_updated`	A series was updated.	Series Object
`multiple_series_added`	Multiple series were created.	Array of Series

Collection Events

Name	Description	Schema
`collection_added`	A collection was created.	Collection Expanded Object
`collection_updated`	A collection was updated.	Collection Expanded Object
`collection_removed`	A collection was deleted.	Collection Expanded Object

Playlist Events

Name	Description	Schema
`playlist_added`	A playlist was created.	Playlist Expanded Object
`playlist_updated`	A playlist was updated.	Playlist Expanded Object
`playlist_removed`	A playlist was deleted.	Playlist Expanded Object

RSS Feed Events

Name	Description	Schema
`rss_feed_open`	An RSS feed was opened.	RSS Feed Minified Object
`rss_feed_closed`	An RSS feed was closed.	RSS Feed Minified Object

Backup Events

Name	Description	Schema
`backup_applied`	A backup was applied to the server.

Podcast Episode Download Events

Name	Description	Schema
`episode_download_queued`	A podcast episode has been queued for download.	Podcast Episode Download Object
`episode_download_queue_updated`	The podcast episode download queue has updated.	Same as Get a Library's Podcast Episode Downloads Response
`episode_download_started`	A podcast episode has started downloading.	Podcast Episode Download Object
`episode_download_finished`	A podcast episode has finished downloading.	Podcast Episode Download Object

Audio Metadata Events

Name	Description	Schema
`audio_metadata_started`	A library item has started updating its audio files' metadata.	Audio Metadata Started Event Object
`audio_metadata_finished`	A library item has finished updating its audio files' metadata.	Audio Metadata Finished Event Object
`audiofile_metadata_started`	An audio file has started updating its metadata.	Audio File Metadata Started Event Object
`audiofile_metadata_finished`	An audio file has finished updating its metadata.	Audio File Metadata Finished Event Object

Audio Metadata Started Event

{
  "userId": "root",
  "libraryItemId": "li_8gch9ve09orgn4fdz8",
  "startedAt": 1671741903065,
  "audioFiles": [...]
}

Attribute	Type	Description
`userId`	String	The ID of the user that requested the metadata update.
`libraryItemId`	String	The ID of the library item whose audio files' metadata are being updated.
`startedAt`	Integer	The time (in ms since POSIX epoch) when the metadata update request was sent.
`audioFiles`	Array of Event Audio File	The audio files whose metadata is being updated.

Event Audio File

{
  "index": 1,
  "ino": "649644248522215260",
  "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3"
}

Attribute	Type	Description
`index`	Integer	The index of the audio file.
`ino`	String	The inode of the audio file.
`filename`	String	The filename of the audio file.

Audio Metadata Finished Event

{
  "userId": "root",
  "libraryItemId": "li_8gch9ve09orgn4fdz8",
  "startedAt": 1671741903065,
  "audioFiles": [...],
  "results": [...],
  "elapsed": 3065,
  "finishedAt": 1671741906130
}

The same as Audio Metadata Started Event with following added attributes:

Attribute	Type	Description
`results`	Array of Audio File Metadata Finished Event	The results of the audio file metadata updates.
`elapsed`	Integer	The time (in ms) it took to complete the metadata updates (approx. `finishedAt` - `startedAt`)
`finishedAt`	Integer	The time (in ms since POSIX epoch) when the metadata updates were finished.

Audio File Metadata Started Event

{
  "libraryItemId": "li_8gch9ve09orgn4fdz8",
  "index": 1,
  "ino": "649644248522215260",
  "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3"
}

Attribute	Type	Description
`libraryItemId`	String	The ID of the library item which the audio file belongs to.
`index`	Integer	The index of the audio file.
`ino`	String	The inode of the audio file.
`filename`	String	The filename of the audio file.

Audio File Metadata Finished Event

{
  "libraryItemId": "li_8gch9ve09orgn4fdz8",
  "index": 1,
  "ino": "649644248522215260",
  "filename": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3",
  "success": true
}

The same as Audio File Metadata Started Event with following added attributes:

Attribute	Type	Description
`success`	Boolean	Whether the audio file's metadata was successfully updated.

Notification Events

Name	Description	Schema
`notifications_updated`	A notification was fired.	Notification Settings Object

Miscellaneous Events

Name	Description	Schema
`init`	Successfully authenticated the socket. Response to `auth` client event.	Init Event Object
`invalid_token`	An invalid token was given when authenticating. Response to `auth` client event.
`log`	A single log event. Emitted after `set_log_listener` client event is sent. Cancelable with `remove_log_listener` client event.	Log Event Object
`daily_logs`	The current day's log events. Response to `fetch_daily_logs` client event.	Array of Log Event
`admin_message`	A message sent by an admin user.	String
`pong`	Response to `ping` client event.

Init Event

{
  "userId": "root",
  "username": "root",
  "librariesScanning": [
    "lib_c1u6t4p45c35rf0nzd"
  ],
  "usersOnline": [...]
}

Attribute	Type	Description
`userId`	String	The ID of the authenticated user.
`username`	String	The username of the authenticated user.
`librariesScanning`	Array of String	The IDs of libraries currently being scanned.
`usersOnline`	Array of User with Session	Users that are currently online. Will only exist when the authenticated user is an admin.

Log Event

{
  "timestamp": "2022-12-21 15:08:47",
  "message": "[Server] Socket Connected dak2d0lroqBoL-MnAAAL",
  "levelName": "INFO",
  "level": 2
}

Attribute	Type	Description
`timestamp`	String	The date and time of the log event.
`message`	String	The log event's message.
`levelName`	String	The name of the log level. Can be `DEBUG`, `INFO`, `WARN`, or `ERROR`.
`level`	Integer	The log event's log level. Can be `1` (debug), `2` (info), `3` (warning), or `4` (error).

Metadata Providers

Books

Value	Display Name
`google`	Google Books
`openlibrary`	Open Library
`itunes`	iTunes
`audible`	Audible.com
`audible.ca`	Audible.ca
`audible.uk`	Audible.co.uk
`audible.au`	Audible.com.au
`audible.fr`	Audible.fr
`audible.de`	Audible.de
`audible.jp`	Audible.co.jp
`audible.it`	Audible.it
`audible.in`	Audible.co.in
`audible.es`	Audible.es
`fantlab`	FantLab.ru

Podcasts

Value	Display Name
`itunes`	iTunes

Filtering

Most filters are composed of two parts, a group and a value, put together as group.value.

The groups are:

genres
tags
series
authors
progress
narrators
missing
languages
tracks

The series, authors, narrators, missing, and tracks groups only apply to books.

The available values depend on the group:

For the genres, tags, narrators, and languages groups, the value is what genre, tag, narrator, or language to filter by.
For the series and authors groups, the value is the ID of the series or author.
For the series group, the value can also be no-series.
For the progress group, the value can be:
- finished
- not-started
- not-finished
- in-progress
For the missing group, the value can be:
- asin
- isbn
- subtitle
- authors
- publishedYear
- series
- description
- genres
- tags
- narrators
- publisher
- language
For the tracks group, the value can be:
- single
- multi

All values must be first Base64 encoded and then URL encoded.

Other filters are issues and feed-open.

Examples:

To filter for the Sci Fi genre:
- Sci Fi is Base64 encoded as U2NpIEZp
- Already URL encoded.
- Then use filter=genres.U2NpIEZp.
To filter for the author Terry Goodkind who has the ID of aut_z3leimgybl7uf3y4ab:
- aut_z3leimgybl7uf3y4ab is Base64 encoded as YXV0X3ozbGVpbWd5Ymw3dWYzeTRhYg==.
- YXV0X3ozbGVpbWd5Ymw3dWYzeTRhYg== is URL encoded as YXV0X3ozbGVpbWd5Ymw3dWYzeTRhYg%3D%3D.
- Then use filter=authors.YXV0X3ozbGVpbWd5Ymw3dWYzeTRhYg%3D%3D.
To filter for in progress items:
- in-progress is Base64 encoded as aW4tcHJvZ3Jlc3M=.
- aW4tcHJvZ3Jlc3M= is URL encoded as aW4tcHJvZ3Jlc3M%3D.
- Then use filter=progress.aW4tcHJvZ3Jlc3M%3D.
To filter for items with their RSS feed open:
- Use filter=feed-open.

Schemas

Library

{
  "id": "lib_c1u6t4p45c35rf0nzd",
  "name": "Main",
  "folders": [...],
  "displayOrder": 1,
  "icon": "audiobookshelf",
  "mediaType": "book",
  "provider": "audible",
  "settings": {...},
  "createdAt": 1633522963509,
  "lastUpdate": 1646520916818
}

Attribute	Type	Description
`id`	String	The ID of the library. (Read Only)
`name`	String	The name of the library.
`folders`	Array of Folder	The folders that the library is composed of on the server.
`displayOrder`	Integer	Display position of the library in the list of libraries. Must be `>= 1`.
`icon`	String	The selected icon for the library. See Library Icons for a list of possible icons.
`mediaType`	String	The type of media that the library contains. Will be `book` or `podcast`. (Read Only)
`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.
`createdAt`	Integer	The time (in ms since POSIX epoch) when the library was created. (Read Only)
`lastUpdate`	Integer	The time (in ms since POSIX epoch) when the library was last updated. (Read Only)

Library Settings

{
  "coverAspectRatio": 1,
  "disableWatcher": false,
  "skipMatchingMediaWithAsin": false,
  "skipMatchingMediaWithIsbn": false,
  "autoScanCronExpression": null
}

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

Library Filter Data

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

Attribute	Type	Description
`authors`	Array of Author Minified	The authors of books in the library.
`genres`	Array of String	The genres of books in the library.
`tags`	Array of String	The tags in the library.
`series`	Array of Series	The series in the library. The series will only have their `id` and `name`.
`narrators`	Array of String	The narrators of books in the library.
`languages`	Array of String	The languages of books in the library.

Folder

{
  "id": "fol_bev1zuxhb0j0s1wehr",
  "fullPath": "/podcasts",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "addedAt": 1650462940610
}

Attribute	Type	Description
`id`	String	The ID of the folder. (Read Only)
`fullPath`	String	The path on the server for the folder. (Read Only)
`libraryId`	String	The ID of the library the folder belongs to. (Read Only)
`addedAt`	Integer	The time (in ms since POSIX epoch) when the folder was added. (Read Only)

Only provide fullPath when creating a new folder. The other attributes will be automatically set.

Library Item

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

{
  "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,
  "isMissing": false,
  "isInvalid": false,
  "mediaType": "book",
  "media": {...},
  "numFiles": 2,
  "size": 268990279
}

{
  "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": {...},
  "libraryFiles": [...],
  "size": 268990279
}

Attribute	Type	Description
`id`	String	The ID of the library item.
`ino`	String	The inode of the library item.
`libraryId`	String	The ID of the library the item belongs to.
`folderId`	String	The ID of the folder the library item is in.
`path`	String	The path of the library item on the server.
`relPath`	String	The path, relative to the library folder, of the library item.
`isFile`	Boolean	Whether the library item is a single file in the root of the library folder.
`mtimeMs`	Integer	The time (in ms since POSIX epoch) when the library item was last modified on disk.
`ctimeMs`	Integer	The time (in ms since POSIX epoch) when the library item status was changed on disk.
`birthtimeMs`	Integer	The time (in ms since POSIX epoch) when the library item was created on disk. Will be `0` if unknown.
`addedAt`	Integer	The time (in ms since POSIX epoch) when the library item was added to the library.
`updatedAt`	Integer	The time (in ms since POSIX epoch) when the library item was last updated. (Read Only)
`lastScan`	Integer or null	The time (in ms since POSIX epoch) when the library item was last scanned. Will be `null` if the server has not yet scanned the library item.
`scanVersion`	String or null	The version of the scanner when last scanned. Will be `null` if it has not been scanned.
`isMissing`	Boolean	Whether the library item was scanned and no longer exists.
`isInvalid`	Boolean	Whether the library item was scanned and no longer has media files.
`mediaType`	String	What kind of media the library item contains. Will be `book` or `podcast`.
`media`	Book or Podcast Object	The media of the library item.
`libraryFiles`	Array of Library File	The files of the library item.

Library Item Minified

Removed Attributes

lastScan
scanVersion
libraryFiles

Modified Attributes

media is Book Minified or Podcast Minified

Added Attributes

Attribute	Type	Description
`numFiles`	Integer	The number of library files for the library item.
`size`	Integer	The total size (in bytes) of the library item.

Library Item Expanded

Modified Attributes

media is Book Expanded or Podcast Expanded

Added Attributes

Attribute	Type	Description
`size`	Integer	The total size (in bytes) of the library item.

Book

{
  "libraryItemId": "li_8gch9ve09orgn4fdz8",
  "metadata": {...},
  "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
  "tags": [
    "Favorite"
  ],
  "audioFiles": [...],
  "chapters": [...],
  "ebookFile": null
}

{
  "metadata": {...},
  "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
  "tags": [
    "Favorite"
  ],
  "numTracks": 1,
  "numAudioFiles": 1,
  "numChapters": 1,
  "duration": 33854.905,
  "size": 268824228,
  "ebookFormat": null
}

{
  "libraryItemId": "li_8gch9ve09orgn4fdz8",
  "metadata": {...},
  "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
  "tags": [
    "Favorite"
  ],
  "audioFiles": [...],
  "chapters": [...],
  "duration": 33854.905,
  "size": 268824228,
  "tracks": [...],
  "ebookFile": null
}

Attribute	Type	Description
`libraryItemId`	String	The ID of the library item that contains the book.
`metadata`	Book Metadata Object	The book's metadata.
`coverPath`	String or null	The absolute path on the server of the cover file. Will be `null` if there is no cover.
`tags`	Array of String	The book's tags.
`audioFiles`	Array of Audio File	The book's audio files.
`chapters`	Array of Book Chapter	The book's chapters.
`ebookFile`	EBook File Object or null	The book's ebook file. Will be `null` if this is an audiobook.

Book Minified

Removed Attributes

libraryItemId
audioFiles
chapters
ebookFile

Modified Attributes

metadata is Book Metadata Minified

Added Attributes

Attribute	Type	Description
`numTracks`	Integer	The number of tracks the book's audio files have.
`numAudioFiles`	Integer	The number of audio files the book has.
`numChapters`	Integer	The number of chapters the book has.
`duration`	Float	The total length (in seconds) of the book.
`size`	Integer	The total size (in bytes) of the book.
`ebookFormat`	String or null	The format of ebook of the book. Will be `null` if the book is an audiobook.

Book Expanded

Modified Attributes

metadata is Book Metadata Expanded

Added Attributes

Attribute	Type	Description
`duration`	Float	The total length (in seconds) of the book.
`size`	Integer	The total size (in bytes) of the book.
`tracks`	Array of Audio Track	The book's audio tracks from the audio files.

Book Metadata

{
  "title": "Wizards First Rule",
  "subtitle": null,
  "authors": [...],
  "narrators": [
    "Sam Tsoutsouvas"
  ],
  "series": [...],
  "genres": [
    "Fantasy"
  ],
  "publishedYear": "2008",
  "publishedDate": null,
  "publisher": "Brilliance Audio",
  "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
  "isbn": null,
  "asin": "B002V0QK4C",
  "language": null,
  "explicit": false
}

{
  "title": "Wizards First Rule",
  "titleIgnorePrefix": "Wizards First Rule",
  "subtitle": null,
  "authorName": "Terry Goodkind",
  "authorNameLF": "Goodkind, Terry",
  "narratorName": "Sam Tsoutsouvas",
  "seriesName": "Sword of Truth",
  "genres": [
    "Fantasy"
  ],
  "publishedYear": "2008",
  "publishedDate": null,
  "publisher": "Brilliance Audio",
  "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
  "isbn": null,
  "asin": "B002V0QK4C",
  "language": null,
  "explicit": false
}

{
  "title": "Wizards First Rule",
  "titleIgnorePrefix": "Wizards First Rule",
  "subtitle": null,
  "authors": [...],
  "narrators": [
    "Sam Tsoutsouvas"
  ],
  "series": [...],
  "genres": [
    "Fantasy"
  ],
  "publishedYear": "2008",
  "publishedDate": null,
  "publisher": "Brilliance Audio",
  "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
  "isbn": null,
  "asin": "B002V0QK4C",
  "language": null,
  "explicit": false,
  "authorName": "Terry Goodkind",
  "authorNameLF": "Goodkind, Terry",
  "narratorName": "Sam Tsoutsouvas",
  "seriesName": "Sword of Truth"
}

Attribute	Type	Description
`title`	String or null	The title of the book. Will be `null` if unknown.
`subtitle`	String or null	The subtitle of the book. Will be `null` if there is no subtitle.
`authors`	Array of Author Minified	The authors of the book.
`narrators`	Array of String	The narrators of the audiobook.
`series`	Array of Series Sequence	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. Will be `null` if unknown.
`publishedDate`	String or null	The date the book was published. Will be `null` if unknown.
`publisher`	String or null	The publisher of the book. Will be `null` if unknown.
`description`	String or null	A description for the book. Will be `null` if empty.
`isbn`	String or null	The ISBN of the book. Will be `null` if unknown.
`asin`	String or null	The ASIN of the book. Will be `null` if unknown.
`language`	String or null	The language of the book. Will be `null` if unknown.
`explicit`	Boolean	Whether the book has been marked as explicit.

Book Metadata Minified

Removed Attributes

authors
narrators
series

Added Attributes

Attribute	Type	Description
`titleIgnorePrefix`	String	The title of the book with any prefix moved to the end.
`authorName`	String	The name of the book's author(s).
`authorNameLF`	String	The name of the book's author(s) with last names first.
`narratorName`	String	The name of the audiobook's narrator(s).
`seriesName`	String	The name of the book's series.

Book Metadata Expanded

Added Attributes

Attribute	Type	Description
`titleIgnorePrefix`	String	The title of the book with any prefix moved to the end.
`authorName`	String	The name of the book's author(s).
`authorNameLF`	String	The name of the book's author(s) with last names first.
`narratorName`	String	The name of the audiobook's narrator(s).
`seriesName`	String	The name of the book's series.

Book Chapter

{
  "id": 0,
  "start": 0,
  "end": 6004.6675,
  "title": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01"
}

Attribute	Type	Description
`id`	Integer	The ID of the book chapter.
`start`	Float	When in the book (in seconds) the chapter starts.
`end`	Float	When in the book (in seconds) the chapter ends.
`title`	String	The title of the chapter.

Podcast

{
  "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
  "metadata": {...},
  "coverPath": "/podcasts/Welcome to Night Vale/cover.jpg",
  "tags": [
    "Favorite"
  ],
  "episodes": [...],
  "autoDownloadEpisodes": true,
  "autoDownloadSchedule": "0 0 * * 1",
  "lastEpisodeCheck": 1667326662087,
  "maxEpisodesToKeep": 0,
  "maxNewEpisodesToDownload": 3
}

{
  "metadata": {...},
  "coverPath": "/podcasts/Welcome to Night Vale/cover.jpg",
  "tags": [
    "Favorite"
  ],
  "numEpisodes": 1,
  "autoDownloadEpisodes": true,
  "autoDownloadSchedule": "0 0 * * 1",
  "lastEpisodeCheck": 1667326662087,
  "maxEpisodesToKeep": 0,
  "maxNewEpisodesToDownload": 3,
  "size": 23706728
}

{
  "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
  "metadata": {...},
  "coverPath": "/podcasts/Welcome to Night Vale/cover.jpg",
  "tags": [
    "Favorite"
  ],
  "episodes": [...],
  "autoDownloadEpisodes": true,
  "autoDownloadSchedule": "0 0 * * 1",
  "lastEpisodeCheck": 1667326662087,
  "maxEpisodesToKeep": 0,
  "maxNewEpisodesToDownload": 3,
  "size": 23706728
}

Attribute	Type	Description
`libraryItemId`	String	The ID of the library item that contains the podcast.
`metadata`	Podcast Metadata Object	The metadata for the podcast.
`coverPath`	String or null	The absolute path on the server of the cover file. Will be `null` if there is no cover.
`tags`	Array of String	The podcast's tags.
`episodes`	Array of Podcast Episode	The downloaded episodes of the podcast.
`autoDownloadEpisodes`	Boolean	Whether the server will automatically download podcast episodes according to the schedule.
`autoDownloadSchedule`	String	The cron expression for when to automatically download podcast episodes. Will not exist if `autoDownloadEpisodes` is `false`.
`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 Minified

Removed Attributes

libraryItemId
episodes

Modified Attributes

metadata is Podcast Metadata Minified

Added Attributes

Attribute	Type	Description
`numEpisodes`	Integer	The number of downloaded episodes for the podcast.
`size`	Integer	The total size (in bytes) of the podcast.

Podcast Expanded

Modified Attributes

metadata is Podcast Metadata Expanded
episodes is an Array of Podcast Episodes Expanded

Added Attributes

Attribute	Type	Description
`size`	Integer	The total size (in bytes) of the podcast.

Podcast Metadata

{
  "title": "Welcome to Night Vale",
  "author": "Night Vale Presents",
  "description": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
  "releaseDate": "2022-10-20T19:00:00Z",
  "genres": [
    "Science Fiction",
    "Podcasts",
    "Fiction"
  ],
  "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
  "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
  "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
  "itunesId": 536258179,
  "itunesArtistId": 718704794,
  "explicit": false,
  "language": null,
  "type": "episodic"
}

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

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

Attribute	Type	Description
`title`	String or null	The title of the podcast. Will be `null` if unknown.
`author`	String or null	The author of the podcast. Will be `null` if unknown.
`description`	String or null	The description for the podcast. Will be `null` if unknown.
`releaseDate`	String or null	The release date of the podcast. Will be `null` if unknown.
`genres`	Array of String	The podcast's genres.
`feedUrl`	String or null	A URL of an RSS feed for the podcast. Will be `null` if unknown.
`imageUrl`	String or null	A URL of a cover image for the podcast. Will be `null` if unknown.
`itunesPageUrl`	String or null	A URL of an iTunes page for the podcast. Will be `null` if unknown.
`itunesId`	Integer or null	The iTunes ID for the podcast. Will be `null` if unknown.
`itunesArtistId`	Integer or null	The iTunes Artist ID for the author of the podcast. Will be `null` if unknown.
`explicit`	Boolean	Whether the podcast has been marked as explicit.
`language`	String or null	The language of the podcast. Will be `null` if unknown.
`type`	String or null	The type of the podcast.

Podcast Metadata Minified

Added Attributes

Attribute	Type	Description
`titleIgnorePrefix`	String	The title of the podcast with any prefix moved to the end.

Podcast Metadata Expanded

Added Attributes

Attribute	Type	Description
`titleIgnorePrefix`	String	The title of the podcast with any prefix moved to the end.

Podcast Episode

{
  "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": "\n        <p>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.</p>\n\n<p>Weather: \"These and More Than These\" by Joseph Fink</p>\n\n<p>Music: Disparition, <a target=\"_blank\">disparition.info</a></p>\n\n<p>Logo: Rob Wilson, <a target=\"_blank\">silastom.com</a></p>\n\n<p>Produced by Night Vale Presents. Written by Joseph Fink and Jeffrey Cranor. Narrated by Cecil Baldwin. More Info: <a target=\"_blank\">welcometonightvale.com</a>, and follow <a target=\"_blank\">@NightValeRadio</a> on Twitter or <a target=\"_blank\">Facebook</a>.</p>\n      ",
  "enclosure": {...},
  "pubDate": "Fri, 15 Jun 2012 12:00:00 -0000",
  "audioFile": {...},
  "publishedAt": 1339761600000,
  "addedAt": 1667326679503,
  "updatedAt": 1667326679503
}

{
  "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": "\n        <p>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.</p>\n\n<p>Weather: \"These and More Than These\" by Joseph Fink</p>\n\n<p>Music: Disparition, <a target=\"_blank\">disparition.info</a></p>\n\n<p>Logo: Rob Wilson, <a target=\"_blank\">silastom.com</a></p>\n\n<p>Produced by Night Vale Presents. Written by Joseph Fink and Jeffrey Cranor. Narrated by Cecil Baldwin. More Info: <a target=\"_blank\">welcometonightvale.com</a>, and follow <a target=\"_blank\">@NightValeRadio</a> on Twitter or <a target=\"_blank\">Facebook</a>.</p>\n      ",
  "enclosure": {...},
  "pubDate": "Fri, 15 Jun 2012 12:00:00 -0000",
  "audioFile": {...},
  "audioTrack": {...},
  "publishedAt": 1339761600000,
  "addedAt": 1667326679503,
  "updatedAt": 1667326679503,
  "duration": 1454.18449,
  "size": 23653735
}

Attribute	Type	Description
`libraryItemId`	String	The ID of the library item that contains the podcast.
`id`	String	The ID of the podcast episode.
`index`	Integer	The index of the podcast episode.
`season`	String	The season of the podcast episode, if known.
`episode`	String	The episode of the season of the podcast, if known.
`episodeType`	String	The type of episode that the podcast episode is.
`title`	String	The title of the podcast episode.
`subtitle`	String	The subtitle of the podcast episode.
`description`	String	A HTML encoded, description of the podcast episode.
`enclosure`	Podcast Episode Enclosure Object	Information about the podcast episode from when it was downloaded.
`pubDate`	String	When the podcast episode was published.
`audioFile`	Audio File Object	The audio file for the podcast episode.
`publishedAt`	Integer	The time (in ms since POSIX epoch) when the podcast episode was published.
`addedAt`	Integer	The time (in ms since POSIX epoch) when the podcast episode was added to the library.
`updatedAt`	Integer	The time (in ms since POSIX epoch) when the podcast episode was last updated.

Podcast Episode Expanded

Added Attributes

Attribute	Type	Description
`audioTrack`	Audio Track Object	The podcast episode's audio tracks from the audio file.
`duration`	Float	The total length (in seconds) of the podcast episode.
`size`	Integer	The total size (in bytes) of the podcast episode.

Podcast Episode 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"
}

Attribute	Type	Description
`url`	String	The URL where the podcast episode's audio file was downloaded from.
`type`	String	The MIME type of the podcast episode's audio file.
`length`	String	The size (in bytes) that was reported when downloading the podcast episode's audio file.

Podcast Episode Download

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

Attribute	Type	Description
`id`	String	The ID of the podcast episode download.
`episodeDisplayTitle`	String	The display title of the episode to be downloaded.
`url`	String	The URL from which to download the episode.
`libraryItemId`	String	The ID of the library item the episode belongs to.
`libraryId`	String	The ID of the library the episode's podcast belongs to.
`isFinished`	Boolean	Whether the episode has finished downloading.
`failed`	Boolean	Whether the episode failed to download.
`startedAt`	Integer or null	The time (in ms since POSIX epoch) when the episode started downloading. Will be `null` if it has not started downloading yet.
`createdAt`	Integer	The time (in ms since POSIX epoch) when the podcast episode download request was created.
`finishedAt`	Integer or null	The time (in ms since POSIX epoch) when the episode finished downloading. Will be `null` if it has not finished.
`podcastTitle`	String or null	The title of the episode's podcast.
`podcastExplicit`	Boolean	Whether the episode's podcast is explicit.
`season`	String or null	The season of the podcast episode.
`episode`	String or null	The episode number of the podcast episode.
`episodeType`	String	The type of the podcast episode.
`publishedAt`	Integer or null	The time (in ms since POSIX epoch) when the episode was published.

Podcast Feed

{
  "metadata": {...},
  "episodes": [...]
}

{
  "metadata": {...},
  "numEpisodes": 280
}

Attribute	Type	Description
`metadata`	Podcast Feed Metadata Object	The podcast's metadata from the feed.
`episodes`	Array of Podcast Feed Episode	The podcast's episodes from the feed.

Podcast Feed Minified

Removed Attributes

episodes

Added Attributes

Attribute	Type	Description
`numEpisodes`	Integer	The number of episodes the podcast has.

Podcast Feed Metadata

{
  "image": "https://f.prxu.org/126/images/1f749c5d-c83a-4db9-8112-a3245da49c54/nightvalelogo-web4.jpg",
  "categories": [
    "Fiction:Science Fiction"
  ],
  "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
  "description": "\n      <p>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.</p>\n    ",
  "descriptionPlain": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
  "title": "Welcome to Night Vale",
  "language": "en",
  "explicit": "false",
  "author": "Night Vale Presents",
  "pubDate": "Thu, 17 Nov 2022 16:04:42 -0000",
  "link": "http://welcometonightvale.com"
}

Attribute	Type	Description
`image`	String	A URL for the podcast's cover image.
`categories`	Array of String	The podcast's categories. Can be similar to genres.
`feedUrl`	String	A URL of an RSS feed for the podcast.
`description`	String	A HTML encoded description of the podcast.
`descriptionPlain`	String	A plain text description of the podcast.
`title`	String	The podcast's title.
`language`	String	The podcast's language.
`explicit`	String	Whether the podcast is explicit. Will probably be `"true"` or `"false"`.
`author`	String	The podcast's author.
`pubDate`	String	The podcast's publication date.
`link`	String	A URL the RSS feed provided for possible display to the user.

Podcast Feed Episode

{
  "title": "1 - Pilot",
  "subtitle": "Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting. Weather: \"These and More Than These\" by Joseph Fink Music:...",
  "description": "\n        <p>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.</p>\n\n<p>Weather: \"These and More Than These\" by Joseph Fink</p>\n\n<p>Music: Disparition, <a target=\"_blank\">disparition.info</a></p>\n\n<p>Logo: Rob Wilson, <a target=\"_blank\">silastom.com</a></p>\n\n<p>Produced by Night Vale Presents. Written by Joseph Fink and Jeffrey Cranor. Narrated by Cecil Baldwin. More Info: <a target=\"_blank\">welcometonightvale.com</a>, and follow <a target=\"_blank\">@NightValeRadio</a> on Twitter or <a target=\"_blank\">Facebook</a>.</p>\n      ",
  "descriptionPlain": "\n        Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting.\n\nWeather: \"These and More Than These\" by Joseph Fink\n\nMusic: Disparition, disparition.info\n\nLogo: Rob Wilson, silastom.com\n\nProduced by 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.\n      ",
  "pubDate": "Fri, 15 Jun 2012 12:00:00 -0000",
  "episodeType": "full",
  "season": "",
  "episode": "",
  "author": "",
  "duration": "21:02",
  "explicit": "",
  "publishedAt": 1339761600000,
  "enclosure": {...}
}

Attribute	Type	Description
`title`	String	The podcast episode's title.
`subtitle`	String	The podcast episode's subtitle.
`description`	String	A HTML encoded description of the podcast episode.
`descriptionPlain`	String	A plain text description of the podcast episode.
`pubDate`	String	The podcast episode's publication date.
`episodeType`	String	The type of episode that the podcast episode is.
`season`	String	The season of the podcast episode.
`episode`	String	The episode of the season of the podcast.
`author`	String	The author of the podcast episode.
`duration`	String	The duration of the podcast episode as reported by the RSS feed.
`explicit`	String	Whether the podcast episode is explicit.
`publishedAt`	Integer	The time (in ms since POSIX epoch) when the podcast episode was published.
`enclosure`	Podcast Episode Enclosure Object	Download information for the podcast episode.

Audio File

{
  "index": 1,
  "ino": "649644248522215260",
  "metadata": {...},
  "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": {...},
  "mimeType": "audio/mpeg"
}

Attribute	Type	Description
`index`	Integer	The index of the audio file.
`ino`	String	The inode of the audio file.
`metadata`	File Metadata Object	The audio file's metadata.
`addedAt`	Integer	The time (in ms since POSIX epoch) when the audio file was added to the library.
`updatedAt`	Integer	The time (in ms since POSIX epoch) when the audio file last updated. (Read Only)
`trackNumFromMeta`	Integer or null	The track number of the audio file as pulled from the file's metadata. Will be `null` if unknown.
`discNumFromMeta`	Integer or null	The disc number of the audio file as pulled from the file's metadata. Will be `null` if unknown.
`trackNumFromFilename`	Integer or null	The track number of the audio file as determined from the file's name. Will be `null` if unknown.
`discNumFromFilename`	Integer or null	The track number of the audio file as determined from the file's name. Will be `null` if unknown.
`manuallyVerified`	Boolean	Whether the audio file has been manually verified by a user.
`exclude`	Boolean	Whether the audio file has been marked for exclusion.
`error`	String or null	Any error with the audio file. Will be `null` if there is none.
`format`	String	The format of the audio file.
`duration`	Float	The total length (in seconds) of the audio file.
`bitRate`	Integer	The bit rate (in bit/s) of the audio file.
`language`	String or null	The language of the audio file.
`codec`	String	The codec of the audio file.
`timeBase`	String	The time base of the audio file.
`channels`	Integer	The number of channels the audio file has.
`channelLayout`	String	The layout of the audio file's channels.
`chapters`	Array of Book Chapter	If the audio file is part of an audiobook, the chapters the file contains.
`embeddedCoverArt`	String or null	The type of embedded cover art in the audio file. Will be `null` if none exists.
`metaTags`	Audio Meta Tags Object	The audio metadata tags from the audio file.
`mimeType`	String	The MIME type of the audio file.

Audio Meta Tags

{
  "tagAlbum": "SOT Bk01",
  "tagArtist": "Terry Goodkind",
  "tagGenre": "Audiobook Fantasy",
  "tagTitle": "Wizards First Rule 01",
  "tagSeries": null,
  "tagSeriesPart": null,
  "tagTrack": "01/20",
  "tagDisc": null,
  "tagSubtitle": null,
  "tagAlbumArtist": "Terry Goodkind",
  "tagDate": null,
  "tagComposer": "Terry Goodkind",
  "tagPublisher": null,
  "tagComment": null,
  "tagDescription": null,
  "tagEncoder": null,
  "tagEncodedBy": null,
  "tagIsbn": null,
  "tagLanguage": null,
  "tagASIN": null,
  "tagOverdriveMediaMarker": null,
  "tagOriginalYear": null,
  "tagReleaseCountry": null,
  "tagReleaseType": null,
  "tagReleaseStatus": null,
  "tagISRC": null,
  "tagMusicBrainzTrackId": null,
  "tagMusicBrainzAlbumId": null,
  "tagMusicBrainzAlbumArtistId": null,
  "tagMusicBrainzArtistId": null
}

ID3 metadata tags pulled from the audio file on import. Only non-null tags will be returned in requests.

Audio Track

{
  "index": 1,
  "startOffset": 0,
  "duration": 33854.905,
  "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": {...}
}

Attribute	Type	Description
`index`	Integer	The index of the audio track.
`startOffset`	Float	When in the audio file (in seconds) the track starts.
`duration`	Float	The length (in seconds) of the audio track.
`title`	String	The filename of the audio file the audio track belongs to.
`contentUrl`	String	The URL path of the audio file.
`mimeType`	String	The MIME type of the audio file.
`metadata`	File Metadata Object or null	The metadata of the audio file.

EBook File

{
  "ino" : "9463162",
  "metadata": {...},
  "ebookFormat": "epub",
  "addedAt": 1650621073750,
  "updatedAt": 1650621110769
}

Attribute	Type	Description
`ino`	String	The inode of the ebook file.
`metadata`	File Metadata Object	The metadata of the ebook file.
`ebookFormat`	String	The ebook format of the ebook file.
`addedAt`	Integer	The time (in ms since POSIX epoch) when the library file was added.
`updatedAt`	Integer	The time (in ms since POSIX epoch) when the library file was last updated.

Library File

{
  "ino": "649644248522215260",
  "metadata": {...},
  "addedAt": 1650621052494,
  "updatedAt": 1650621052494,
  "fileType": "audio"
}

Attribute	Type	Description
`ino`	String	The inode of the library file.
`metadata`	File Metadata Object	The metadata for the library file.
`addedAt`	Integer	The time (in ms since POSIX epoch) when the library file was added.
`updatedAt`	Integer	The time (in ms since POSIX epoch) when the library file was last updated.
`fileType`	String	The type of file that the library file is (audio, image, etc.).

File 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
}

Attribute	Type	Description
`filename`	String	The filename of the file.
`ext`	String	The file extension of the file.
`path`	String	The absolute path on the server of the file.
`relPath`	String	The path of the file, relative to the book's or podcast's folder.
`size`	Integer	The size (in bytes) of the file.
`mtimeMs`	Integer	The time (in ms since POSIX epoch) when the file was last modified on disk.
`ctimeMs`	Integer	The time (in ms since POSIX epoch) when the file status was changed on disk.
`birthtimeMs`	Integer	The time (in ms since POSIX epoch) when the file was created on disk. Will be `0` if unknown.

Author

{
  "id": "aut_z3leimgybl7uf3y4ab",
  "asin": null,
  "name": "Terry Goodkind",
  "description": null,
  "imagePath": null,
  "addedAt": 1650621073750,
  "updatedAt": 1650621073750
}

{
  "id": "aut_z3leimgybl7uf3y4ab",
  "name": "Terry Goodkind"
}

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

Attribute	Type	Description
`id`	String	The ID of the author.
`asin`	String or null	The ASIN of the author. Will be `null` if unknown.
`name`	String	The name of the author.
`description`	String or null	A description of the author. Will be `null` if there is none.
`imagePath`	String or null	The absolute path for the author image. Will be `null` if there is no image.
`addedAt`	Integer	The time (in ms since POSIX epoch) when the author was added.
`updatedAt`	Integer	The time (in ms since POSIX epoch) when the author was last updated.

Author Minified

Removed Attributes

asin
description
imagePath
addedAt
updatedAt

Author Expanded

Added Attributes

Attribute	Type	Description
`numBooks`	Integer	The number of books associated with the author in the library.

Series

{
  "id": "ser_cabkj4jeu8be3rap4g",
  "name": "Sword of Truth",
  "description": null,
  "addedAt": 1650621073750,
  "updatedAt": 1650621073750
}

{
  "id": "ser_cabkj4jeu8be3rap4g",
  "name": "Sword of Truth",
  "nameIgnorePrefix": "Sword of Truth",
  "libraryItemIds": [
    "li_8gch9ve09orgn4fdz8"
  ],
  "numBooks": 1
}

{
  "id": "ser_cabkj4jeu8be3rap4g",
  "name": "Sword of Truth",
  "nameIgnorePrefix": "Sword of Truth",
  "nameIgnorePrefixSort": "Sword of Truth",
  "type": "series",
  "books": [...],
  "addedAt": 1650621073750,
  "totalDuration": 12000.946
}

{
  "id": "ser_cabkj4jeu8be3rap4g",
  "name": "Sword of Truth",
  "sequence": "1"
}

Attribute	Type	Description
`id`	String	The ID of the series.
`name`	String	The name of the series.
`description`	String or null	A description for the series. Will be `null` if there is none.
`addedAt`	Integer	The time (in ms since POSIX epoch) when the series was added.
`updatedAt`	Integer	The time (in ms since POSIX epoch) when the series was last updated.

Series Num Books

Removed Attributes

description
addedAt
updatedAt

Added Attributes

Attribute	Type	Description
`nameIgnorePrefix`	String	The name of the series with any prefix moved to the end.
`libraryItemIds`	Array of String	The IDs of the library items in the series.
`numBooks`	Integer	The number of books in the series.

Series Books

Removed Attributes

description
updatedAt

Added Attributes

Attribute	Type	Description
`nameIgnorePrefix`	String	The name of the series with any prefix moved to the end.
`nameIgnorePrefixSort`	String	The name of the series with any prefix removed.
`type`	String	Will always be `series`.
`books`	Array of Library Item	The library items that contain the books in the series. A `sequence` attribute that denotes the position in the series the book is in, is tacked on.
`totalDuration`	Float	The combined duration (in seconds) of all books in the series.

Series Sequence

Removed Attributes

description
addedAt
updatedAt

Added Attributes

Attribute	Type	Description
`sequence`	String or null	The position in the series the book is.

Collection

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

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

Attribute	Type	Description
`id`	String	The ID of the collection.
`libraryId`	String	The ID of the library the collection belongs to.
`userId`	String	The ID of the user that created the collection.
`name`	String	The name of the collection.
`description`	String or null	The collection's description. Will be `null` if there is none.
`books`	Array of Library Item	The books that belong to the collection.
`lastUpdate`	Integer	The time (in ms since POSIX epoch) when the collection was last updated.
`createdAt`	Integer	The time (in ms since POSIX epoch) when the collection was created.

Collection Expanded

Modified Attributes

books is an Array of Library Item Expanded.

Playlist

{
  "id": "pl_qbwet64998s5ra6dcu",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "Favorites",
  "description": null,
  "coverPath": null,
  "items": [...],
  "lastUpdate": 1669623431313,
  "createdAt": 1669623431313
}

{
  "id": "pl_qbwet64998s5ra6dcu",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "Favorites",
  "description": null,
  "coverPath": null,
  "items": [...],
  "lastUpdate": 1669623431313,
  "createdAt": 1669623431313
}

Attribute	Type	Description
`id`	String	The ID of the playlist.
`libraryId`	String	The ID of the library the playlist belongs to.
`userId`	String	The ID of the user the playlist belongs to.
`name`	String	The playlist's name.
`description`	String or null	The playlist's description.
`coverPath`	String or null	The path of the playlist's cover.
`items`	Array of Playlist Item	The items in the playlist.
`lastUpdate`	Integer	The time (in ms since POSIX epoch) when the playlist was last updated.
`createdAt`	Integer	The time (in ms since POSIX epoch) when the playlist was created.

Playlist Expanded

Modified Attributes

items is an Array of Playlist Item Expanded.

Playlist Item

{
  "libraryItemId": "li_8gch9ve09orgn4fdz8",
  "episodeId": null
}

{
  "libraryItemId": "li_8gch9ve09orgn4fdz8",
  "episodeId": null,
  "libraryItem": {...}
}

Attribute	Type	Description
`libraryItemId`	String	The ID of the library item the playlist item is for.
`episodeId`	String or null	The ID of the podcast episode the playlist item is for.

Playlist Item Expanded

Added Attributes

Attribute	Type	Description
`episode`	Podcast Episode Expanded Object	The podcast episode the playlist item is for. Will only exist if `episodeId` is not `null`.
`libraryItem`	Library Item Expanded or Library Item Minified Object	The library item the playlist item is for. Will be Library Item Minified if `episodeId` is not `null`.

Media Progress

{
  "id": "li_bufnnmp4y5o2gbbxfm-ep_lh6ko39pumnrma3dhv",
  "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
  "episodeId": "ep_lh6ko39pumnrma3dhv",
  "duration": 1454.18449,
  "progress": 0.011193983371394644,
  "currentTime": 16.278117,
  "isFinished": false,
  "hideFromContinueListening": false,
  "lastUpdate": 1668120246620,
  "startedAt": 1668120083771,
  "finishedAt": null
}

{
  "id": "li_bufnnmp4y5o2gbbxfm-ep_lh6ko39pumnrma3dhv",
  "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
  "episodeId": "ep_lh6ko39pumnrma3dhv",
  "duration": 1454.18449,
  "progress": 0.011193983371394644,
  "currentTime": 16.278117,
  "isFinished": false,
  "hideFromContinueListening": false,
  "lastUpdate": 1668120246620,
  "startedAt": 1668120083771,
  "finishedAt": null,
  "media": {...},
  "episode": {...}
}

Attribute	Type	Description
`id`	String	The ID of the media progress. If the media progress is for a book, this will just be the `libraryItemId`. If for a podcast episode, it will be a hyphenated combination of the `libraryItemId` and `episodeId`.
`libraryItemId`	String	The ID of the library item the media progress is of.
`episodeId`	String or null	The ID of the podcast episode the media progress is of. Will be `null` if the progress is for a book.
`duration`	Float	The total duration (in seconds) of the media. Will be `0` if the media was marked as finished without the user listening to it.
`progress`	Float	The percentage completion progress of the media. Will be `1` if the media is finished.
`currentTime`	Float	The current time (in seconds) of the user's progress. If the media has been marked as finished, this will be the time the user was at beforehand.
`isFinished`	Boolean	Whether the media is finished.
`hideFromContinueListening`	Boolean	Whether the media will be hidden from the "Continue Listening" shelf.
`lastUpdate`	Integer	The time (in ms since POSIX epoch) when the media progress was last updated.
`startedAt`	Integer	The time (in ms since POSIX epoch) when the media progress was created.
`finishedAt`	Integer or null	The time (in ms since POSIX epoch) when the media was finished. Will be `null` if the media has is not finished.

Media Progress with Media

Added Attributes

Attribute	Type	Description
`media`	Book Expanded or Podcast Expanded Object	The media of the library item the media progress is for.
`episode`	Podcast Episode	The podcast episode the media progress is for. Will only exist if the media progress is for a podcast episode.

Playback Session

{
  "id": "play_c786zm3qtjz6bd5q3n",
  "userId": "root",
  "libraryId": "lib_p9wkw2i85qy9oltijt",
  "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
  "episodeId": "ep_lh6ko39pumnrma3dhv",
  "mediaType": "podcast",
  "mediaMetadata": {...},
  "chapters": [],
  "displayTitle": "1 - Pilot",
  "displayAuthor": "Night Vale Presents",
  "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
  "duration": 1454.18449,
  "playMethod": 0,
  "mediaPlayer": "unknown",
  "deviceInfo": {...},
  "serverVersion": "2.4.4",
  "date": "2022-11-11",
  "dayOfWeek": "Friday",
  "timeListening": 0,
  "startTime": 0,
  "currentTime": 0,
  "startedAt": 1668206493239,
  "updatedAt": 1668206493239
}

{
  "id": "play_c786zm3qtjz6bd5q3n",
  "userId": "root",
  "libraryId": "lib_p9wkw2i85qy9oltijt",
  "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
  "episodeId": "ep_lh6ko39pumnrma3dhv",
  "mediaType": "podcast",
  "mediaMetadata": {...},
  "chapters": [],
  "displayTitle": "1 - Pilot",
  "displayAuthor": "Night Vale Presents",
  "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
  "duration": 1454.18449,
  "playMethod": 0,
  "mediaPlayer": "unknown",
  "deviceInfo": {...},
  "serverVersion": "2.4.4",
  "date": "2022-11-11",
  "dayOfWeek": "Friday",
  "timeListening": 0,
  "startTime": 0,
  "currentTime": 0,
  "startedAt": 1668206493239,
  "updatedAt": 1668206493239,
  "audioTracks": [...],
  "videoTrack": null,
  "libraryItem": {...}
}

Attribute	Type	Description
`id`	UUIDv4	The ID of the playback session.
`userId`	UUIDv4	The ID of the user the playback session is for.
`libraryId`	UUIDv4	The ID of the library that contains the library item.
`libraryItemId`	UUIDv4	The ID of the library item.
`episodeId`	UUIDv4 or null	The ID of the podcast episode. Will be `null` if this playback session was started without an episode ID.
`mediaType`	String	The media type of the library item. Will be `book` or `podcast`.
`mediaMetadata`	Book Metadata or Podcast Metadata Object	The metadata of the library item's media.
`chapters`	Array of Book Chapter	If the library item is a book, the chapters it contains.
`displayTitle`	String	The title of the playing item to show to the user.
`displayAuthor`	String	The author of the playing item to show to the user.
`coverPath`	String	The cover path of the library item's media.
`duration`	Float	The total duration (in seconds) of the playing item.
`playMethod`	Play Method Enumerated Integer	What play method the playback session is using. See below for values.
`mediaPlayer`	String	The given media player when the playback session was requested.
`deviceInfo`	Device Info Object	The given device info when the playback session was requested.
`serverVersion`	String	The server version the playback session was started with.
`date`	String	The day (in the format YYYY-MM-DD) the playback session was started.
`dayOfWeek`	String	The day of the week the playback session was started.
`timeListening`	Float	The amount of time (in seconds) the user has spent listening using this playback session.
`startTime`	Float	The time (in seconds) where the playback session started.
`currentTime`	Float	The current time (in seconds) of the playback position.
`startedAt`	Integer	The time (in ms since POSIX epoch) when the playback session was started.
`updatedAt`	Integer	The time (in ms since POSIX epoch) when the playback session was last updated.

Play Method

Value	Meaning
`0`	Direct Play
`1`	Direct Stream
`2`	Transcode
`3`	Local

Playback Session Expanded

Added Attributes

Attribute	Type	Description
`audioTracks`	Array of Audio Tracks	The audio tracks that are being played with the playback session.
`videoTrack`	Video Track Object or null	The video track that is being played with the playback session. Will be `null` if the playback session is for a book or podcast.
`libraryItem`	Library Item Expanded Object	The library item of the playback session.

Device Info

{
  "id": "69b7e852-23a6-4587-bed3-6a5966062e38",
  "userId": "3c479fe6-6bf8-44e4-a4a6-680c768b501c",
  "deviceId": "4dd05e7fadca538b",
  "ipAddress": "192.168.1.118",
  "browserName": "Firefox",
  "browserVersion": "106.0",
  "osName": "Linux",
  "osVersion": "x86_64",
  "deviceType": null,
  "manufacturer": null,
  "model": null,
  "sdkVersion": null,
  "clientName": "Abs Web",
  "clientVersion": "2.3.3"
}

Any attributes with a null value will be filtered out in responses.

Attribute	Type	Description
`id`	UUIDv4	Unique identifier.
`userId`	UUIDv4	User identifier.
`deviceId`	String	Device identifier, as provided in the request.
`ipAddress`	String or null	The IP address that the request came from.
`browserName`	String or null	The browser name, taken from the user agent.
`browserVersion`	String or null	The browser version, taken from the user agent.
`osName`	String or null	The name of OS, taken from the user agent.
`osVersion`	String or null	The version of the OS, taken from the user agent.
`deviceName`	String or null	The device name, constructed automatically from other attributes.
`deviceType`	String or null	The device type, taken from the user agent.
`manufacturer`	String or null	The client device's manufacturer, as provided in the request.
`model`	String or null	The client device's model, as provided in the request.
`sdkVersion`	Integer or null	For an Android device, the Android SDK version of the client, as provided in the request.
`clientName`	String	Name of the client, as provided in the request.
`clientVersion`	String	Version of the client, as provided in the request.

User

{
  "id": "root",
  "username": "root",
  "type": "root",
  "token": "exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY",
  "mediaProgress": [...],
  "seriesHideFromContinueListening": [],
  "bookmarks": [...],
  "isActive": true,
  "isLocked": false,
  "lastSeen": 1668296147437,
  "createdAt": 1666543632566,
  "permissions": {...},
  "librariesAccessible": [...],
  "itemTagsAccessible": [...]
}

{
  "id": "root",
  "username": "root",
  "type": "root",
  "token": "exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY",
  "mediaProgress": [...],
  "seriesHideFromContinueListening": [],
  "bookmarks": [...],
  "isActive": true,
  "isLocked": false,
  "lastSeen": 1668296147437,
  "createdAt": 1666543632566,
  "permissions": {...},
  "librariesAccessible": [...],
  "itemTagsAccessible": [...]
}

{
  "id": "root",
  "username": "root",
  "type": "root",
  "session": null,
  "lastSeen": 1668296147437,
  "createdAt": 1666543632566
}

Attribute	Type	Description
`id`	String	The ID of the user. Only the root user has the `root` ID.
`username`	String	The username of the user.
`type`	String	The type of the user. Will be `root`, `guest`, `user`, or `admin`. There will be only one root user which is created when the server first starts.
`token`	String	The authentication token of the user.
`mediaProgress`	Array of Media Progress	The user's media progress.
`seriesHideFromContinueListening`	Array of String	The IDs of series to hide from the user's "Continue Series" shelf.
`bookmarks`	Array of Audio Bookmark	The user's bookmarks.
`isActive`	Boolean	Whether the user's account is active.
`isLocked`	Boolean	Whether the user is locked.
`lastSeen`	Integer or null	The time (in ms since POSIX epoch) when the user was last seen by the server. Will be `null` if the user has never logged in.
`createdAt`	Integer	The time (in ms since POSIX epoch) when the user was created.
`permissions`	User Permissions Object	The user's permissions.
`librariesAccessible`	Array of String	The IDs of libraries accessible to the user. An empty array means all libraries are accessible.
`itemTagsAccessible`	Array of String	The tags accessible to the user. An empty array means all tags are accessible.

User with Progress Details

Modified Attributes

mediaProgress is an Array of Media Progress with Media

User with Session

Removed Attributes

token
mediaProgress
seriesHideFromContinueListening
bookmarks
isActive
isLocked
settings
permissions
librariesAccessible
itemTagsAccessible

Added Attributes

Attribute	Type	Description
`session`	Playback Session Expanded Object or null	The user's currently playing session. Will be `null` if the user is not currently playing anything.

User Permissions

{
  "download": true,
  "update": true,
  "delete": true,
  "upload": true,
  "accessAllLibraries": true,
  "accessAllTags": true,
  "accessExplicitContent": true
}

Attribute	Type	Description
`download`	Boolean	Whether the user can download items to 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.

Audio Bookmark

{
  "libraryItemId": "li_8gch9ve09orgn4fdz8",
  "title": "the good part",
  "time": 16,
  "createdAt": 1668120083771
}

Attribute	Type	Description
`libraryItemId`	String	The ID of the library item the bookmark is for.
`title`	String	The title of the bookmark.
`time`	Integer	The time (in seconds) the bookmark is at in the book.
`createdAt`	Integer	The time (in ms since POSIX epoch) when the bookmark was created.

Backup

{
  "id": "2022-11-14T0130",
  "backupMetadataCovers": true,
  "backupDirPath": "/metadata/backups",
  "datePretty": "Mon, Nov 14 2022 01:30",
  "fullPath": "/metadata/backups/2022-11-14T0130.audiobookshelf",
  "path": "backups/2022-11-14T0130.audiobookshelf",
  "filename": "2022-11-14T0130.audiobookshelf",
  "fileSize": 7776983,
  "createdAt": 1668411000329,
  "serverVersion": "2.2.4"
}

Attribute	Type	Description
`id`	String	The ID of the backup. Will be the date and time when the backup was created.
`backupMetadataCovers`	Boolean	Whether the backup includes library item covers and author images located in metadata.
`backupDirPath`	String	The backup directory path.
`datePretty`	String	The date and time when the backup was created in a human-readable format.
`fullPath`	String	The full path of the backup on the server.
`path`	String	The path of the backup relative to the metadata directory.
`filename`	String	The filename of the backup.
`fileSize`	Integer	The size (in bytes) of the backup file.
`createdAt`	Integer	The time (in ms since POSIX epoch) when the backup was created.
`serverVersion`	String	The version of the server when the backup was created.

Notification Settings

{
  "id": "notification-settings",
  "appriseType": "api",
  "appriseApiUrl": "https://apprise.example.com/notify",
  "notifications": [...],
  "maxFailedAttempts": 5,
  "maxNotificationQueue": 20,
  "notificationDelay": 1000
}

Attribute	Type	Description
`id`	String	The ID of the notification settings.
`appriseType`	String	The type of Apprise that will be used. At the moment, only `api` is available.
`appriseApiUrl`	String or null	The full URL where the Apprise API to use is located.
`notifications`	Array of Notification	The set notifications.
`maxFailedAttempts`	Integer	The maximum number of times a notification fails before being disabled.
`maxNotificationQueue`	Integer	The maximum number of notifications in the notification queue before events are ignored.
`notificationDelay`	Integer	The time (in ms) between notification pushes.

Notification

{
  "id": "noti_nod281qwkj5ow7h7fi",
  "libraryId": null,
  "eventName": "onPodcastEpisodeDownloaded",
  "urls": [
    "apprises://apprise.example.com/email"
  ],
  "titleTemplate": "New {{podcastTitle}} Episode!",
  "bodyTemplate": "{{episodeTitle}} has been added to {{libraryName}} library.",
  "enabled": true,
  "type": "info",
  "lastFiredAt": 1668776410792,
  "lastAttemptFailed": false,
  "numConsecutiveFailedAttempts": 0,
  "numTimesFired": 5,
  "createdAt": 1666545142424
}

Attribute	Type	Description
`id`	String	The ID of the notification.
`libraryId`	String or null	The ID of the library the notification is associated with.
`eventName`	String	The name of the event the notification will fire on.
`urls`	Array of String	The Apprise URLs to use for the notification.
`titleTemplate`	String	The template for the notification title.
`bodyTemplate`	String	The template for the notification body.
`enabled`	Boolean	Whether the notification is enabled.
`type`	String	The notification's type.
`lastFiredAt`	Integer or null	The time (in ms since POSIX epoch) when the notification was last fired. Will be `null` if the notification has not fired.
`lastAttemptFailed`	Boolean	Whether the last notification attempt failed.
`numConsecutiveFailedAttempts`	Integer	The number of consecutive times the notification has failed.
`numTimesFired`	Integer	The number of times the notification has fired.
`createdAt`	Integer	The time (in ms since POSIX epoch) when the notification was created.

Notification Event

{
  "name": "onPodcastEpisodeDownloaded",
  "requiresLibrary": true,
  "libraryMediaType": "podcast",
  "description": "Triggered when a podcast episode is auto-downloaded",
  "variables": [
    "libraryItemId",
    "libraryId",
    "libraryName",
    "mediaTags",
    "podcastTitle",
    "podcastAuthor",
    "podcastDescription",
    "podcastGenres",
    "episodeId",
    "episodeTitle",
    "episodeSubtitle",
    "episodeDescription"
  ],
  "defaults": {
    "title": "New {{podcastTitle}} Episode!",
    "body": "{{episodeTitle}} has been added to {{libraryName}} library."
  },
  "testData": {
    "libraryItemId": "li_notification_test",
    "libraryId": "lib_test",
    "libraryName": "Podcasts",
    "podcastTitle": "Abs Test Podcast",
    "episodeId": "ep_notification_test",
    "episodeTitle": "Successful Test"
  }
}

The notification events that are available are predefined here.

Attribute	Type	Description
`name`	String	The name of the notification event.
`requiresLibrary`	Boolean	Whether the notification event depends on a library existing.
`libraryMediaType`	String	The type of media of the library the notification depends on existing. Will not exist if `requiresLibrary` is `false`.
`description`	String	The description of the notification event.
`variables`	Array of String	The variables of the notification event that can be used in the notification templates.
`defaults.title`	String	The default title template for notifications using the notification event.
`defaults.body`	String	The default body template for notifications using the notification event.
`testData`	Object	The keys of the `testData` object will match the list of `variables`. The values will be the data used when sending a test notification.

Server Settings

{
  "id": "server-settings",
  "scannerFindCovers": false,
  "scannerCoverProvider": "google",
  "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",
  "timeFormat": "HH:mm",
  "language": "en-us",
  "logLevel": 2,
  "version": "2.2.5"
}

Attribute	Type	Description
`id`	String	The ID of the server settings.
`scannerFindCovers`	Boolean	Whether the scanner will attempt to find a cover if your audiobook does not have an embedded cover or a cover image inside the folder. Note: This will extend scan time.
`scannerCoverProvider`	String	If `scannerFindCovers` is `true`, which metadata provider to use. See Metadata Providers for options.
`scannerParseSubtitle`	Boolean	Whether to extract subtitles from audiobook folder names. Subtitles must be separated by `-`, i.e. `/audiobooks/Book Title - A Subtitle Here/` has the subtitle `A Subtitle Here`.
`scannerPreferMatchedMetadata`	Boolean	Whether matched data will override item details when using Quick Match. By default, Quick Match will only fill in missing details.
`scannerDisableWatcher`	Boolean	Whether to disable the automatic adding/updating of items when file changes are detected. Requires server restart for changes to take effect.
`storeCoverWithItem`	Boolean	Whether to store covers in the library item's folder. By default, covers are stored in `/metadata/items`. Only one file named `cover` will be kept.
`storeMetadataWithItem`	Boolean	Whether to store metadata files in the library item's folder. By default, metadata files are stored in `/metadata/items`. Uses the `.abs` file extension.
`metadataFileFormat`	String	Must be either `json` or `abs`
`rateLimitLoginRequests`	Integer	The maximum number of login requests per `rateLimitLoginWindow`.
`rateLimitLoginWindow`	Integer	The length (in ms) of each login rate limit window.
`backupSchedule`	String	The cron expression for when to do automatic backups.
`backupsToKeep`	Integer	The number of backups to keep.
`maxBackupSize`	Integer	The maximum backup size (in GB) before they fail, a safeguard against misconfiguration.
`loggerDailyLogsToKeep`	Integer	The number of daily logs to keep.
`loggerScannerLogsToKeep`	Integer	The number of scanner logs to keep.
`homeBookshelfView`	Binary	Whether the home page should use a skeuomorphic design with wooden shelves.
`bookshelfView`	Binary	Whether other bookshelf pages should use a skeuomorphic design with wooden shelves.
`sortingIgnorePrefix`	Boolean	Whether to ignore prefixes when sorting. For example, for the prefix `the`, the book title `The Book Title` would sort as `Book Title, The`.
`sortingPrefixes`	Array of String	If `sortingIgnorePrefix` is `true`, what prefixes to ignore.
`chromecastEnabled`	Boolean	Whether to enable streaming to Chromecast devices.
`dateFormat`	String	What date format to use. Options are `MM/dd/yyyy`, `dd/MM/yyyy`, `dd.MM.yyyy`, `yyyy-MM-dd`, `MMM do, yyyy`, `MMMM do, yyyy`, `dd MMM yyyy`, or `dd MMMM yyyy`.
`timeFormat`	String	What time format to use. Options are `HH:mm` (24-hour) and `h:mma` (am/pm).
`language`	String	The default server language.
`logLevel`	Integer	What log level the server should use when logging. `1` for debug, `2` for info, or `3` for warnings.
`version`	String	The server's version.

RSS Feed

{
  "id": "169cf198-8645-4d73-8948-4e60fb329c5a",
  "slug": "169cf198-8645-4d73-8948-4e60fb329c5a",
  "userId": "root",
  "entityType": "item",
  "entityId": "169cf198-8645-4d73-8948-4e60fb329c5a",
  "coverPath": "/metadata/items/169cf198-8645-4d73-8948-4e60fb329c5a/cover.jpg",
  "serverAddress": "https://abs.example.com",
  "feedUrl": "https://abs.example.com/feed/169cf198-8645-4d73-8948-4e60fb329c5a",
  "meta": {...},
  "episodes": [...],
  "createdAt": 1669031843179,
  "updatedAt": 1669031843179
}

{
  "id": "2294c42b-a964-48fe-a544-982fab209a5f",
  "entityType": "item",
  "entityId": "169cf198-8645-4d73-8948-4e60fb329c5a",
  "feedUrl": "https://abs.example.com/feed/169cf198-8645-4d73-8948-4e60fb329c5a",
  "meta": {
    "title": "Welcome to Night Vale",
    "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    ",
    "preventIndexing": true,
    "ownerName": null,
    "ownerEmail": null
  }
}

Attribute	Type	Description
`id`	UUIDv4	The ID of the RSS feed.
`slug`	String	The slug (the last part of the URL) for the RSS feed.
`userId`	UUIDv4	The ID of the user that created the RSS feed.
`entityType`	String	The type of entity the RSS feed is for.
`entityId`	UUIDv4	The ID of the entity the RSS feed is for.
`coverPath`	String	The path of the cover to use for the RSS feed.
`serverAddress`	String	The server's address.
`feedUrl`	String	The full URL of the RSS feed.
`meta`	RSS Feed Metadata Object	The RSS feed's metadata.
`episodes`	Array of RSS Feed Episode	The RSS feed's episodes.
`createdAt`	Integer	The time (in ms since POSIX epoch) when the RSS feed was created.
`updatedAt`	Integer	The time (in ms since POSIX epoch) when the RSS feed was last updated.

RSS Feed Minified

Removed Attributes

slug
userId
coverPath
serverAddress
episodes
createdAt
updatedAt

Modified Attributes

meta is an RSS Feed Metadata Minified

RSS Feed Metadata

{
  "title": "Welcome to Night Vale",
  "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    ",
  "author": "Night Vale Presents",
  "imageUrl": "https://abs.example.com/feed/li_bufnnmp4y5o2gbbxfm/cover",
  "feedUrl": "https://abs.example.com/feed/li_bufnnmp4y5o2gbbxfm",
  "link": "https://abs.example.com/item/li_bufnnmp4y5o2gbbxfm",
  "explicit": false,
  "type": "episodic",
  "language": "en",
  "preventIndexing": true,
  "ownerName": null,
  "ownerEmail": null
}

{
  "title": "Welcome to Night Vale",
  "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    ",
  "preventIndexing": true,
  "ownerName": null,
  "ownerEmail": null
}

Attribute	Type	Description
`title`	String	The title of the entity the RSS feed is for.
`description`	String or null	The description of the entity the RSS feed is for.
`author`	String or null	The author of the entity the RSS feed is for.
`imageUrl`	String	The URL of the RSS feed's image.
`feedUrl`	String	The URL of the RSS feed.
`link`	String	The URL of the entity the RSS feed is for.
`explicit`	Boolean	Whether the RSS feed's contents are explicit.
`type`	String or null	The type of the RSS feed.
`language`	String or null	The language of the RSS feed.
`preventIndexing`	Boolean	Whether the RSS feed is marked to prevent indexing of the feed.
`ownerName`	String or null	The owner name of the RSS feed.
`ownerEmail`	String or null	The owner email of the RSS feed.

RSS Feed Metadata Minified

Removed Attributes

author
imageUrl
feedUrl
link
explicit
type
language

RSS Feed Episode

{
  "id": "ep_lh6ko39pumnrma3dhv",
  "title": "1 - Pilot",
  "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://abs.example.com/feed/li_bufnnmp4y5o2gbbxfm/item/ep_lh6ko39pumnrma3dhv/1 - Pilot.mp3",
    "type": "audio/mpeg",
    "size": 23653735
  },
  "pubDate": "Fri, 15 Jun 2012 12:00:00 -0000",
  "link": "https://abs.example.com/item/li_bufnnmp4y5o2gbbxfm",
  "author": "Night Vale Presents",
  "explicit": false,
  "duration": 1454.18449,
  "season": null,
  "episode": null,
  "episodeType": null,
  "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
  "episodeId": "ep_lh6ko39pumnrma3dhv",
  "trackIndex": 0,
  "fullPath": "/podcasts/Welcome to Night Vale/1 - Pilot.mp3"
}

Attribute	Type	Description
`id`	String	The ID of the RSS feed episode.
`title`	String	The title of the RSS feed episode.
`description`	String	An HTML encoded description of the RSS feed episode.
`enclosure`	Similar to Podcast Episode Enclosure	Download information for the RSS feed episode.
`pubDate`	String	The RSS feed episode's publication date.
`link`	String	A URL to display to the RSS feed user.
`author`	String	The author of the RSS feed episode.
`explicit`	Boolean	Whether the RSS feed episode is explicit.
`duration`	Float	The duration (in seconds) of the RSS feed episode.
`season`	String or null	The season of the RSS feed episode.
`episode`	String or null	The episode number of the RSS feed episode.
`episodeType`	String or null	The type of the RSS feed episode.
`libraryItemId`	String	The ID of the library item the RSS feed is for.
`episodeId`	String or null	The ID of the podcast episode the RSS feed episode is for. Will be `null` if the RSS feed is for a book.
`trackIndex`	Integer	The RSS feed episode's track index.
`fullPath`	String	The path on the server of the audio file the RSS feed episode is for.

Stream

{
  "id": "5a3046cd-11ff-43c9-a495-c2fbdca93e9d",
  "userId": "root",
  "libraryItem": {...},
  "episode": {...},
  "segmentLength": 6,
  "playlistPath": "/metadata/streams/5a3046cd-11ff-43c9-a495-c2fbdca93e9d/output.m3u8",
  "clientPlaylistUri": "/hls/5a3046cd-11ff-43c9-a495-c2fbdca93e9d/output.m3u8",
  "startTime": 0,
  "segmentStartNumber": 0,
  "isTranscodeComplete": false
}

Attribute	Type	Description
`id`	UUIDv4	The ID of the stream. It will be the same as the ID of the playback session that the stream is for.
`userId`	UUIDv4	The ID of the user that started the stream.
`libraryItem`	Library Item Expanded Object	The library item the stream is for.
`episode`	Podcast Episode Expanded Object or null	The podcast episode the stream is for. Will be `null` if the stream is for a book.
`segmentLength`	Integer	The length (in seconds) of each segment of the stream.
`playlistPath`	String	The path on the server of the stream output.
`clientPlaylistUri`	String	The URI path for the client to access the stream.
`startTime`	Float	The time (in seconds) where the playback session started.
`segmentStartNumber`	Integer	The segment where the transcoding began.
`isTranscodeComplete`	Boolean	Whether transcoding is complete.

Stream Progress

{
  "stream": "play_c786zm3qtjz6bd5q3n",
  "percent": "8.66%",
  "chunks": [
    "0-536"
  ],
  "numSegments": 6200
}

Attribute	Type	Description
`stream`	String	The ID of the stream the progress is for.
`percent`	String	A human-readable percentage of transcode completion.
`chunks`	Array of String	The segment ranges that have been transcoded.
`numSegments`	Integer	The total number of segments of the stream.

Attribute	Type	Description
`path`	String	The path of the directory.
`dirname`	String	The name of the directory.
`fullPath`	String	The full path of the directory.
`level`	Integer	The depth of the directory. `0` means a root level directory.
`dirs`	Array of Directory	The directories contained in this directory.