NAV
shell

Introduction

Audiobookshelf API and this documentation is a work in progress.

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

Authentication

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

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

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

API request header for authentication would look like this:

Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY

Optionally GET requests can use the API token like this:

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

Server

Login

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

Parameters

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

Response

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

Response Schema

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

Logout

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

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

HTTP Request

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

Optional Parameters

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

Response

Status Meaning Description
200 OK Success

OAuth2 Authorization Request

curl "https://abs.example.com/auth/openid?code_challenge=1234&code_challenge_method=S256&redirect_uri=audiobookshelf%3A%2F%2Foauth&client_id=Audiobookshelf-App&response_type=code&state=42"

Response header (depending on SSO provider)

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

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

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

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

Code Challenge Pseudo-Code

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

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

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

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

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

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

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 URL which is opened in the user's browser by the SSO Provider

redirect_uri?code=42&state=2000

HTTP Request

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

Query Parameters

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

The above command returns a JSON structured like this:

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

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

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

Query Parameters

Parameter Type Default Description
state String Required The state string you 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"

The above command returns JSON structured like this:

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

This endpoint reports the server's initialization status.

HTTP Request

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

Response

Status Meaning Description Schema
200 OK Success See Below

Response Schema

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

Ping the Server

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

The above command returns JSON structured like this:

{
  "success": true
}

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

HTTP Request

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

Response

Status Meaning Description Schema
200 OK Success See Below

Response Schema

Attribute Type Description
success Boolean Will always be true.

Healthcheck

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

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

HTTP Request

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

Response

Status Meaning Description
200 OK Success

Libraries

Create a Library

curl -X POST "https://abs.example.com/api/libraries" \
  -H "Authorization: Bearer exJhbGciOiJI6IkpXVCJ9.eyJ1c2Vyi5NDEyODc4fQ.ZraBFohS4Tg39NszY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Podcasts", "folders": [{"fullPath": "/podcasts"}], "icon": "podcast", "mediaType": "podcast", "provider": "itunes"}'

The above command returns JSON structured like this:

{
  "id": "lib_c1u6t4p45c35rf0nzd",
  "name": "Podcasts",
  "folders": [
    {
      "id": "fol_bev1zuxhb0j0s1wehr",
      "fullPath": "/podcasts",
      "libraryId": "lib_c1u6t4p45c35rf0nzd",
      "addedAt": 1650462940610
    }
  ],
  "displayOrder": 4,
  "icon": "podcast",
  "mediaType": "podcast",
  "provider": "itunes",
  "settings": {
    "coverAspectRatio": 1,
    "disableWatcher": false,
    "skipMatchingMediaWithAsin": false,
    "skipMatchingMediaWithIsbn": false,
    "autoScanCronExpression": null
  },
  "createdAt": 1650462940610,
  "lastUpdate": 1655423464567
}

This endpoint creates a library with the specified options.

HTTP Request

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

Parameters

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

Library Settings Parameters

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

Response

Status Meaning Description Schema
200 OK Success Library

Get All Libraries

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

The above command returns JSON structured like this:

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

This endpoint retrieves all libraries accessible to the user.

HTTP Request

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

Response

Status Meaning Description Schema
200 OK Success See Below

Response Schema

Attribute Type Description
libraries Array of Library The requested libraries.

Get a Library

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

The above command returns JSON structured like this:

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

This endpoint retrieves a library.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library to retrieve.

Optional Query Parameters

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

Response

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

Response Schema

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

Update a Library

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

The above command returns JSON structured like this:

{
  "id": "lib_c1u6t4p45c35rf0nzd",
  "name": "Pods",
  "folders": [
    {
      "id": "fol_bev1zuxhb0j0s1wehr",
      "fullPath": "/podcasts",
      "libraryId": "lib_c1u6t4p45c35rf0nzd",
      "addedAt": 1650462940610
    }
  ],
  "displayOrder": 4,
  "icon": "podcast",
  "mediaType": "podcast",
  "provider": "itunes",
  "settings": {
    "coverAspectRatio": 1,
    "disableWatcher": false,
    "skipMatchingMediaWithAsin": false,
    "skipMatchingMediaWithIsbn": false,
    "autoScanCronExpression": null
  },
  "createdAt": 1650462940610,
  "lastUpdate": 1655423464567
}

This endpoint updates a library.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library to update.

Parameters

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

Library Settings Parameters

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

Response

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

Delete a Library

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

If successful the deleted library will be returned like this:

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

This endpoint deletes a library.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library to delete.

Response

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

Get a Library's Items

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

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": "li_8gch9ve09orgn4fdz8",
      "ino": "649641337522215266",
      "libraryId": "main",
      "folderId": "audiobooks",
      "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
      "relPath": "Terry Goodkind/Sword of Truth/Wizards First Rule",
      "isFile": false,
      "mtimeMs": 1650621074299,
      "ctimeMs": 1650621074299,
      "birthtimeMs": 0,
      "addedAt": 1650621073750,
      "updatedAt": 1650621110769,
      "isMissing": false,
      "isInvalid": false,
      "mediaType": "book",
      "media": {
        "metadata": {
          "title": "Wizards First Rule",
          "titleIgnorePrefix": "Wizards First Rule",
          "subtitle": null,
          "authorName": "Terry Goodkind",
          "narratorName": "Sam Tsoutsouvas",
          "seriesName": "Sword of Truth",
          "genres": ["Fantasy"],
          "publishedYear": "2008",
          "publishedDate": null,
          "publisher": "Brilliance Audio",
          "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
          "isbn": null,
          "asin": "B002V0QK4C",
          "language": null,
          "explicit": false
        },
        "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
        "tags": [],
        "numTracks": 2,
        "numAudioFiles": 2,
        "numChapters": 2,
        "duration": 12000.946,
        "size": 96010240,
        "ebookFileFormat": null
      },
      "numFiles": 3,
      "size": 96335771,
      "collapsedSeries": {
        "id": "ser_cabkj4jeu8be3rap4g",
        "name": "Sword of Truth",
        "nameIgnorePrefix": "Sword of Truth",
        "numBooks": 1
      }
    }
  ],
  "total": 1,
  "limit": 0,
  "page": 0,
  "sortBy": "media.metadata.title",
  "sortDesc": false,
  "filterBy": "authors.YXV0X3ozbGVpbWd5Ymw3dWYzeTRhYg==",
  "mediaType": "book",
  "minified": false,
  "collapseseries": true,
  "include": ""
}

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Optional Query Parameters

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

Response

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

Response Schema

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

Remove a Library's Items With Issues

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Response

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

Get a Library's Podcast Episode Downloads

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

The above command returns JSON structured like this:

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

This endpoint retrieves the podcast episodes downloads of the library.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Response

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

Response Schema

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

Get a Library's Series

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

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": "ser_cabkj4jeu8be3rap4g",
      "name": "Sword of Truth",
      "nameIgnorePrefix": "Sword of Truth",
      "nameIgnorePrefixSort": "Sword of Truth",
      "type": "series",
      "books": [
        {
          "id": "li_8gch9ve09orgn4fdz8",
          "ino": "649641337522215266",
          "libraryId": "main",
          "folderId": "audiobooks",
          "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
          "relPath": "Terry Goodkind/Sword of Truth/Wizards First Rule",
          "isFile": false,
          "mtimeMs": 1650621074299,
          "ctimeMs": 1650621074299,
          "birthtimeMs": 0,
          "addedAt": 1650621073750,
          "updatedAt": 1650621110769,
          "isMissing": false,
          "isInvalid": false,
          "mediaType": "book",
          "media": {
            "metadata": {
              "title": "Wizards First Rule",
              "titleIgnorePrefix": "Wizards First Rule",
              "subtitle": null,
              "authorName": "Terry Goodkind",
              "narratorName": "Sam Tsoutsouvas",
              "seriesName": "Sword of Truth",
              "genres": ["Fantasy"],
              "publishedYear": "2008",
              "publishedDate": null,
              "publisher": "Brilliance Audio",
              "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
              "isbn": null,
              "asin": "B002V0QK4C",
              "language": null,
              "explicit": false
            },
            "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
            "tags": [],
            "numTracks": 2,
            "numAudioFiles": 2,
            "numChapters": 2,
            "duration": 12000.946,
            "size": 96010240,
            "ebookFileFormat": null
          },
          "numFiles": 3,
          "size": 96335771,
          "sequence": "1"
        }
      ],
      "addedAt": 1650621073750,
      "totalDuration": 12000.946
    }
  ],
  "total": 1,
  "limit": 0,
  "page": 0,
  "sortBy": "media.metadata.title",
  "sortDesc": false,
  "filterBy": "authors.YXV0X3ozbGVpbWd5Ymw3dWYzeTRhYg==",
  "mediaType": "book",
  "minified": false,
  "collapseseries": true,
  "include": ""
}

This endpoint returns a library's series.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Query Parameters

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

Response

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

Response Schema

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

Get a Library's Collections

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

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": "col_fpfstanv6gd7tq2qz7",
      "libraryId": "lib_c1u6t4p45c35rf0nzd",
      "userId": "root",
      "name": "Favorites",
      "description": null,
      "books": [
        {
          "id": "li_8gch9ve09orgn4fdz8",
          "ino": "649641337522215266",
          "libraryId": "main",
          "folderId": "audiobooks",
          "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
          "relPath": "Terry Goodkind/Sword of Truth/Wizards First Rule",
          "isFile": false,
          "mtimeMs": 1650621074299,
          "ctimeMs": 1650621074299,
          "birthtimeMs": 0,
          "addedAt": 1650621073750,
          "updatedAt": 1650621110769,
          "isMissing": false,
          "isInvalid": false,
          "mediaType": "book",
          "media": {
            "metadata": {
              "title": "Wizards First Rule",
              "titleIgnorePrefix": "Wizards First Rule",
              "subtitle": null,
              "authorName": "Terry Goodkind",
              "narratorName": "Sam Tsoutsouvas",
              "seriesName": "Sword of Truth",
              "genres": ["Fantasy"],
              "publishedYear": "2008",
              "publishedDate": null,
              "publisher": "Brilliance Audio",
              "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
              "isbn": null,
              "asin": "B002V0QK4C",
              "language": null,
              "explicit": false
            },
            "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
            "tags": [],
            "numTracks": 2,
            "numAudioFiles": 2,
            "numChapters": 2,
            "duration": 12000.946,
            "size": 96010240,
            "ebookFileFormat": null
          },
          "numFiles": 3,
          "size": 96335771
        }
      ],
      "lastUpdate": 1650621110769,
      "createdAt": 1650621073750
    }
  ],
  "total": 1,
  "limit": 0,
  "page": 0,
  "sortDesc": false,
  "minified": true,
  "include": ""
}

This endpoint returns a library's collections.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Optional Query Parameters

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

Response

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

Response Schema

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

Get a Library's User Playlists

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Query Parameters

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

Response

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

Response Schema

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

Get a Library's Personalized View

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

The above command returns JSON structured like this:

[
  {
    "id": "continue-listening",
    "label": "Continue Listening",
    "labelStringKey": "LabelContinueListening",
    "type": "book",
    "entities": [
      {
        "id": "li_8gch9ve09orgn4fdz8",
        "ino": "649641337522215266",
        "libraryId": "main",
        "folderId": "audiobooks",
        "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
        "relPath": "Terry Goodkind/Sword of Truth/Wizards First Rule",
        "isFile": false,
        "mtimeMs": 1650621074299,
        "ctimeMs": 1650621074299,
        "birthtimeMs": 0,
        "addedAt": 1650621073750,
        "updatedAt": 1650621110769,
        "isMissing": false,
        "isInvalid": false,
        "mediaType": "book",
        "media": {
          "metadata": {
            "title": "Wizards First Rule",
            "titleIgnorePrefix": "Wizards First Rule",
            "subtitle": null,
            "authorName": "Terry Goodkind",
            "narratorName": "Sam Tsoutsouvas",
            "seriesName": "Sword of Truth",
            "genres": ["Fantasy"],
            "publishedYear": "2008",
            "publishedDate": null,
            "publisher": "Brilliance Audio",
            "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
            "isbn": null,
            "asin": "B002V0QK4C",
            "language": null,
            "explicit": false
          },
          "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
          "tags": [],
          "numTracks": 2,
          "numAudioFiles": 2,
          "numChapters": 2,
          "duration": 12000.946,
          "size": 96010240,
          "ebookFileFormat": null
        },
        "numFiles": 3,
        "size": 96335771,
        "progressLastUpdate": 1650621110769
      }
    ],
    "category": "recentlyListened"
  },
  {
    "id": "continue-series",
    "label": "Continue Series",
    "labelStringKey": "LabelContinueSeries",
    "type": "book",
    "entities": [
      {
        "id": "li_8gch9ve09orgn4fdz8",
        "ino": "649641337522215266",
        "libraryId": "main",
        "folderId": "audiobooks",
        "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
        "relPath": "Terry Goodkind/Sword of Truth/Wizards First Rule",
        "isFile": false,
        "mtimeMs": 1650621074299,
        "ctimeMs": 1650621074299,
        "birthtimeMs": 0,
        "addedAt": 1650621073750,
        "updatedAt": 1650621110769,
        "isMissing": false,
        "isInvalid": false,
        "mediaType": "book",
        "media": {
          "metadata": {
            "title": "Wizards First Rule",
            "titleIgnorePrefix": "Wizards First Rule",
            "subtitle": null,
            "authorName": "Terry Goodkind",
            "narratorName": "Sam Tsoutsouvas",
            "seriesName": "Sword of Truth",
            "genres": ["Fantasy"],
            "publishedYear": "2008",
            "publishedDate": null,
            "publisher": "Brilliance Audio",
            "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
            "isbn": null,
            "asin": "B002V0QK4C",
            "language": null,
            "explicit": false,
            "series": {
              "id": "ser_cabkj4jeu8be3rap4g",
              "name": "Sword of Truth",
              "sequence": "1"
            }
          },
          "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
          "tags": [],
          "numTracks": 2,
          "numAudioFiles": 2,
          "numChapters": 2,
          "duration": 12000.946,
          "size": 96010240,
          "ebookFileFormat": null
        },
        "numFiles": 3,
        "size": 96335771,
        "prevBookInProgressLastUpdate": 1650621110769
      }
    ],
    "category": "continueSeries"
  },
  {
    "id": "recently-added",
    "label": "Recently Added",
    "labelStringKey": "LabelRecentlyAdded",
    "type": "book",
    "entities": [
      {
        "id": "li_8gch9ve09orgn4fdz8",
        "ino": "649641337522215266",
        "libraryId": "main",
        "folderId": "audiobooks",
        "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
        "relPath": "Terry Goodkind/Sword of Truth/Wizards First Rule",
        "isFile": false,
        "mtimeMs": 1650621074299,
        "ctimeMs": 1650621074299,
        "birthtimeMs": 0,
        "addedAt": 1650621073750,
        "updatedAt": 1650621110769,
        "isMissing": false,
        "isInvalid": false,
        "mediaType": "book",
        "media": {
          "metadata": {
            "title": "Wizards First Rule",
            "titleIgnorePrefix": "Wizards First Rule",
            "subtitle": null,
            "authorName": "Terry Goodkind",
            "narratorName": "Sam Tsoutsouvas",
            "seriesName": "Sword of Truth",
            "genres": ["Fantasy"],
            "publishedYear": "2008",
            "publishedDate": null,
            "publisher": "Brilliance Audio",
            "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
            "isbn": null,
            "asin": "B002V0QK4C",
            "language": null,
            "explicit": false
          },
          "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
          "tags": [],
          "numTracks": 2,
          "numAudioFiles": 2,
          "numChapters": 2,
          "duration": 12000.946,
          "size": 96010240,
          "ebookFileFormat": null
        },
        "numFiles": 3,
        "size": 96335771
      }
    ],
    "category": "newestItems"
  },
  {
    "id": "recent-series",
    "label": "Recent Series",
    "labelStringKey": "LabelRecentSeries",
    "type": "series",
    "entities": [
      {
        "id": "ser_cabkj4jeu8be3rap4g",
        "name": "Sword of Truth",
        "description": null,
        "addedAt": 1650621073750,
        "updatedAt": 1650621073750,
        "books": [
          {
            "id": "li_8gch9ve09orgn4fdz8",
            "ino": "649641337522215266",
            "libraryId": "main",
            "folderId": "audiobooks",
            "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
            "relPath": "Terry Goodkind/Sword of Truth/Wizards First Rule",
            "isFile": false,
            "mtimeMs": 1650621074299,
            "ctimeMs": 1650621074299,
            "birthtimeMs": 0,
            "addedAt": 1650621073750,
            "updatedAt": 1650621110769,
            "isMissing": false,
            "isInvalid": false,
            "mediaType": "book",
            "media": {
              "metadata": {
                "title": "Wizards First Rule",
                "titleIgnorePrefix": "Wizards First Rule",
                "subtitle": null,
                "authorName": "Terry Goodkind",
                "narratorName": "Sam Tsoutsouvas",
                "seriesName": "Sword of Truth",
                "genres": ["Fantasy"],
                "publishedYear": "2008",
                "publishedDate": null,
                "publisher": "Brilliance Audio",
                "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
                "isbn": null,
                "asin": "B002V0QK4C",
                "language": null,
                "explicit": false
              },
              "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
              "tags": [],
              "numTracks": 2,
              "numAudioFiles": 2,
              "numChapters": 2,
              "duration": 12000.946,
              "size": 96010240,
              "ebookFileFormat": null
            },
            "numFiles": 3,
            "size": 96335771,
            "seriesSequence": "1"
          }
        ],
        "inProgress": true,
        "hasActiveBook": true,
        "hideFromContinueListening": false,
        "bookInProgressLastUpdate": 1650621110769,
        "firstBookUnread": null
      }
    ],
    "category": "newestSeries"
  },
  {
    "id": "recommended",
    "label": "Recommended",
    "labelStringKey": "LabelRecommended",
    "type": "book",
    "entities": [
      {
        "id": "li_8gch9ve09orgn4fdz8",
        "ino": "649641337522215266",
        "libraryId": "main",
        "folderId": "audiobooks",
        "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
        "relPath": "Terry Goodkind/Sword of Truth/Wizards First Rule",
        "isFile": false,
        "mtimeMs": 1650621074299,
        "ctimeMs": 1650621074299,
        "birthtimeMs": 0,
        "addedAt": 1650621073750,
        "updatedAt": 1650621110769,
        "isMissing": false,
        "isInvalid": false,
        "mediaType": "book",
        "media": {
          "metadata": {
            "title": "Wizards First Rule",
            "titleIgnorePrefix": "Wizards First Rule",
            "subtitle": null,
            "authorName": "Terry Goodkind",
            "narratorName": "Sam Tsoutsouvas",
            "seriesName": "Sword of Truth",
            "genres": ["Fantasy"],
            "publishedYear": "2008",
            "publishedDate": null,
            "publisher": "Brilliance Audio",
            "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
            "isbn": null,
            "asin": "B002V0QK4C",
            "language": null,
            "explicit": false
          },
          "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
          "tags": [],
          "numTracks": 2,
          "numAudioFiles": 2,
          "numChapters": 2,
          "duration": 12000.946,
          "size": 96010240,
          "ebookFileFormat": null
        },
        "numFiles": 3,
        "size": 96335771,
        "weight": 0.9215686274509803
      }
    ],
    "category": "recommended"
  },
  {
    "id": "listen-again",
    "label": "Listen Again",
    "labelStringKey": "LabelListenAgain",
    "type": "book",
    "entities": [
      {
        "id": "li_8gch9ve09orgn4fdz8",
        "ino": "649641337522215266",
        "libraryId": "main",
        "folderId": "audiobooks",
        "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
        "relPath": "Terry Goodkind/Sword of Truth/Wizards First Rule",
        "isFile": false,
        "mtimeMs": 1650621074299,
        "ctimeMs": 1650621074299,
        "birthtimeMs": 0,
        "addedAt": 1650621073750,
        "updatedAt": 1650621110769,
        "isMissing": false,
        "isInvalid": false,
        "mediaType": "book",
        "media": {
          "metadata": {
            "title": "Wizards First Rule",
            "titleIgnorePrefix": "Wizards First Rule",
            "subtitle": null,
            "authorName": "Terry Goodkind",
            "narratorName": "Sam Tsoutsouvas",
            "seriesName": "Sword of Truth",
            "genres": ["Fantasy"],
            "publishedYear": "2008",
            "publishedDate": null,
            "publisher": "Brilliance Audio",
            "description": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
            "isbn": null,
            "asin": "B002V0QK4C",
            "language": null,
            "explicit": false
          },
          "coverPath": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg",
          "tags": [],
          "numTracks": 2,
          "numAudioFiles": 2,
          "numChapters": 2,
          "duration": 12000.946,
          "size": 96010240,
          "ebookFileFormat": null
        },
        "numFiles": 3,
        "size": 96335771,
        "finishedAt": 1650621110769
      }
    ],
    "category": "recentlyFinished"
  },
  {
    "id": "newest-authors",
    "label": "Newest Authors",
    "labelStringKey": "LabelNewestAuthors",
    "type": "authors",
    "entities": [
      {
        "id": "aut_z3leimgybl7uf3y4ab",
        "asin": null,
        "name": "Terry Goodkind",
        "description": null,
        "imagePath": null,
        "addedAt": 1650621073750,
        "updatedAt": 1650621073750,
        "numBooks": 1
      }
    ],
    "category": "newestAuthors"
  }
]

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Optional Query Parameters

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

Response

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

Shelf

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

Shelf Entities

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

Get a Library's Filter Data

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Response

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

Search a Library

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Query Parameters

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

Response

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

Response Schema

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

Library Item Search Result

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

Get a Library's Stats

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

The above command returns JSON structured like this:

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

This endpoint returns a library's stats.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Response

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

Response Schema

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

Library Item Duration Stats

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

Library Item Size Stats

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

Author Stats

Attribute Type Description
id String The ID of the author.
name String The title of the author.
count Integer The number of books by the author in the library.

Genre Stats

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

Get a Library's Authors

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

The above command returns JSON structured like this:

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

This endpoint returns a library's authors.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Response

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

Response Schema

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

Match All of a Library's Items

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Response

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

Scan a Library's Folders

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Optional Query Parameters

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

Response

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

Get a Library's Recent Episodes

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

The above command returns JSON structured like this:

{
  "episodes": [
    {
      "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
      "id": "ep_lh6ko39pumnrma3dhv",
      "index": 1,
      "season": "",
      "episode": "",
      "episodeType": "full",
      "title": "1 - Pilot",
      "subtitle": "Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting. Weather: \"These and More Than These\" by Joseph Fink Music:...",
      "description": "<div><br>Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting.<br><br></div><div><br>Weather: \"These and More Than These\" by Joseph Fink<br><br></div><div><br>Music: Disparition, disparition.info<br><br></div><div><br>Logo: Rob Wilson, silastom.com<br><br></div><div><br>Produced by Night Vale Presents. Written by Joseph Fink and Jeffrey Cranor. Narrated by Cecil Baldwin. More Info: welcometonightvale.com, and follow @NightValeRadio on Twitter or Facebook.<br><br></div>",
      "enclosure": {
        "url": "https://www.podtrac.com/pts/redirect.mp3/dovetail.prxu.org/_/126/1fadf1ad-aad8-449f-843b-6e8bb6949622/1_Pilot.mp3",
        "type": "audio/mpeg",
        "length": "20588611"
      },
      "pubDate": "Fri, 15 Jun 2012 12:00:00 -0000",
      "audioFile": {
        "index": 1,
        "ino": "22587",
        "metadata": {
          "filename": "1 - Pilot.mp3",
          "ext": ".mp3",
          "path": "/podcasts/Welcome to Night Vale/1 - Pilot.mp3",
          "relPath": "1 - Pilot.mp3",
          "size": 23653735,
          "mtimeMs": 1667326682557,
          "ctimeMs": 1667326682557,
          "birthtimeMs": 1667326679508
        },
        "addedAt": 1667326682605,
        "updatedAt": 1667327311570,
        "trackNumFromMeta": null,
        "discNumFromMeta": null,
        "trackNumFromFilename": null,
        "discNumFromFilename": null,
        "manuallyVerified": false,
        "exclude": false,
        "error": null,
        "format": "MP2/3 (MPEG audio layer 2/3)",
        "duration": 1454.18449,
        "bitRate": 128000,
        "language": null,
        "codec": "mp3",
        "timeBase": "1/14112000",
        "channels": 2,
        "channelLayout": "stereo",
        "chapters": [],
        "embeddedCoverArt": "mjpeg",
        "metaTags": {
          "tagAlbum": "Welcome to Night Vale",
          "tagArtist": "Night Vale Presents",
          "tagGenre": "Podcast",
          "tagTitle": "1 - Pilot",
          "tagDate": "2012",
          "tagEncoder": "Lavf58.45.100"
        },
        "mimeType": "audio/mpeg"
      },
      "audioTrack": {
        "index": 1,
        "startOffset": 0,
        "duration": 1454.18449,
        "title": "1 - Pilot.mp3",
        "contentUrl": "/s/item/li_bufnnmp4y5o2gbbxfm/1 - Pilot.mp3",
        "mimeType": "audio/mpeg",
        "metadata": {
          "filename": "1 - Pilot.mp3",
          "ext": ".mp3",
          "path": "/podcasts/Welcome to Night Vale/1 - Pilot.mp3",
          "relPath": "1 - Pilot.mp3",
          "size": 23653735,
          "mtimeMs": 1667326682557,
          "ctimeMs": 1667326682557,
          "birthtimeMs": 1667326679508
        }
      },
      "publishedAt": 1339761600000,
      "addedAt": 1667326679503,
      "updatedAt": 1667428186431,
      "duration": 1454.18449,
      "size": 23653735,
      "podcast": {
        "metadata": {
          "title": "Welcome to Night Vale",
          "titleIgnorePrefix": "Welcome to Night Vale",
          "author": "Night Vale Presents",
          "description": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
          "releaseDate": "2022-10-20T19:00:00Z",
          "genres": ["Science Fiction", "Podcasts", "Fiction"],
          "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
          "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
          "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
          "itunesId": 536258179,
          "itunesArtistId": 718704794,
          "explicit": false,
          "language": null
        },
        "coverPath": "/podcasts/Welcome to Night Vale/cover.jpg",
        "tags": [],
        "numEpisodes": 1,
        "autoDownloadEpisodes": false,
        "autoDownloadSchedule": "0 0 * * 1",
        "lastEpisodeCheck": 1667326662087,
        "maxEpisodesToKeep": 0,
        "maxNewEpisodesToDownload": 3,
        "size": 23653735
      }
    }
  ],
  "total": 1,
  "limit": 0,
  "page": 0
}

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library.

Optional Query Parameters

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

Response

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

Response Schema

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

Reorder Library List

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

Required Parameters

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

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

Response

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

Response Schema

Attribute Type Description
libraries Array of Library All the libraries.

Library Icons

Available library icons are:

Library Items

Delete All Library Items

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

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

HTTP Request

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

Response

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

Get a Library Item

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

The above command returns JSON structured like this:

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

This endpoint retrieves a library item.

HTTP Request

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

URL Parameters

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

Optional Query Parameters

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

Response

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

Extra Attributes

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

Delete a Library Item

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

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

HTTP Request

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

URL Parameters

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

Response

Status Meaning Description
200 OK Success

Update a Library Item's Media

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library item.

Parameters

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

Book Parameters

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

Book Metadata Parameters

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

Author Parameters

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

Parameter Type Description
name String The name of the author.

Series Parameters

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

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

Podcast Parameters

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

Podcast Metadata Parameters

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

Response

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

Get a Library Item's Cover

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

The above command writes an image file.

This endpoint retrieves a library item's cover.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library item.

Optional Query Parameters

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

Response

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

Upload a Library Item Cover

Upload a cover image:

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

Or download a cover image from a URL:

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

The above commands return JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library item.

Form Parameters

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

JSON Parameters

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

Response

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

Response Schema

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

Update a Library Item's Cover

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library item.

Parameters

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

Response

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

Response Schema

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

Remove a Library Item's Cover

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

This endpoint removes a library item's cover.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library item.

Response

Status Meaning Description
200 OK Success

Match a Library Item

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library item.

Parameters

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

Response

Status Meaning Description Schema
200 OK Success See below.

Response Schema

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

Play a Library Item or Podcast Episode

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

The above command returns JSON structured like this:

{
  "id": "play_c786zm3qtjz6bd5q3n",
  "userId": "root",
  "libraryId": "lib_p9wkw2i85qy9oltijt",
  "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
  "episodeId": "ep_lh6ko39pumnrma3dhv",
  "mediaType": "podcast",
  "mediaMetadata": {
    "title": "Welcome to Night Vale",
    "author": "Night Vale Presents",
    "description": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
    "releaseDate": "2022-10-20T19:00:00Z",
    "genres": [
      "Science Fiction",
      "Podcasts",
      "Fiction"
    ],
    "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
    "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
    "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
    "itunesId": 536258179,
    "itunesArtistId": 718704794,
    "explicit": false,
    "language": null
  },
  "chapters": [],
  "displayTitle": "1 - Pilot",
  "displayAuthor": "Night Vale Presents",
  "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
  "duration": 1454.18449,
  "playMethod": 0,
  "mediaPlayer": "unknown",
  "deviceInfo": {
    "ipAddress": "192.168.1.118",
    "clientVersion": "0.0.1",
    "serverVersion": "2.2.2"
  },
  "date": "2022-11-11",
  "dayOfWeek": "Friday",
  "timeListening": 0,
  "startTime": 0,
  "currentTime": 0,
  "startedAt": 1668206493239,
  "updatedAt": 1668206493239,
  "audioTracks": [
    {
      "index": 1,
      "startOffset": 0,
      "duration": 1454.18449,
      "title": "1 - Pilot.mp3",
      "contentUrl": "/s/item/li_bufnnmp4y5o2gbbxfm/1 - Pilot.mp3",
      "mimeType": "audio/mpeg",
      "metadata": {
        "filename": "1 - Pilot.mp3",
        "ext": ".mp3",
        "path": "/podcasts/Welcome to Night Vale/1 - Pilot.mp3",
        "relPath": "1 - Pilot.mp3",
        "size": 23653735,
        "mtimeMs": 1667326682557,
        "ctimeMs": 1667326682557,
        "birthtimeMs": 1667326679508
      }
    }
  ],
  "videoTrack": null,
  "libraryItem": {
    "id": "li_bufnnmp4y5o2gbbxfm",
    "ino": "652",
    "libraryId": "lib_p9wkw2i85qy9oltijt",
    "folderId": "fol_crxarzs17jtw5k7ie9",
    "path": "/podcasts/Welcome to Night Vale",
    "relPath": "Welcome to Night Vale",
    "isFile": false,
    "mtimeMs": 1667326679508,
    "ctimeMs": 1667326679508,
    "birthtimeMs": 1667326662083,
    "addedAt": 1667326662087,
    "updatedAt": 1668157565937,
    "lastScan": 1667327311529,
    "scanVersion": "2.2.1",
    "isMissing": false,
    "isInvalid": false,
    "mediaType": "podcast",
    "media": {
      "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
      "metadata": {
        "title": "Welcome to Night Vale",
        "titleIgnorePrefix": "Welcome to Night Vale",
        "author": "Night Vale Presents",
        "description": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
        "releaseDate": "2022-10-20T19:00:00Z",
        "genres": [
          "Science Fiction",
          "Podcasts",
          "Fiction"
        ],
        "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
        "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
        "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
        "itunesId": 536258179,
        "itunesArtistId": 718704794,
        "explicit": false,
        "language": null
      },
      "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
      "tags": [],
      "episodes": [
        {
          "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
          "id": "ep_lh6ko39pumnrma3dhv",
          "index": 1,
          "season": "",
          "episode": "",
          "episodeType": "full",
          "title": "1 - Pilot",
          "subtitle": "Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting. Weather: \"These and More Than These\" by Joseph Fink Music:...",
          "description": "<div><br>Pilot Episode. A new dog park opens in Night Vale. Carlos, a scientist, visits and discovers some interesting things. Seismic things. Plus, a helpful guide to surveillance helicopter-spotting.<br><br></div><div><br>Weather: \"These and More Than These\" by Joseph Fink<br><br></div><div><br>Music: Disparition, disparition.info<br><br></div><div><br>Logo: Rob Wilson, silastom.com<br><br></div><div><br>Produced by Night Vale Presents. Written by Joseph Fink and Jeffrey Cranor. Narrated by Cecil Baldwin. More Info: welcometonightvale.com, and follow @NightValeRadio on Twitter or Facebook.<br><br></div>",
          "enclosure": {
            "url": "https://www.podtrac.com/pts/redirect.mp3/dovetail.prxu.org/_/126/1fadf1ad-aad8-449f-843b-6e8bb6949622/1_Pilot.mp3",
            "type": "audio/mpeg",
            "length": "20588611"
          },
          "pubDate": "Fri, 15 Jun 2012 12:00:00 -0000",
          "audioFile": {
            "index": 1,
            "ino": "22587",
            "metadata": {
              "filename": "1 - Pilot.mp3",
              "ext": ".mp3",
              "path": "/podcasts/Welcome to Night Vale/1 - Pilot.mp3",
              "relPath": "1 - Pilot.mp3",
              "size": 23653735,
              "mtimeMs": 1667326682557,
              "ctimeMs": 1667326682557,
              "birthtimeMs": 1667326679508
            },
            "addedAt": 1667326682605,
            "updatedAt": 1667327311570,
            "trackNumFromMeta": null,
            "discNumFromMeta": null,
            "trackNumFromFilename": null,
            "discNumFromFilename": null,
            "manuallyVerified": false,
            "exclude": false,
            "error": null,
            "format": "MP2/3 (MPEG audio layer 2/3)",
            "duration": 1454.18449,
            "bitRate": 128000,
            "language": null,
            "codec": "mp3",
            "timeBase": "1/14112000",
            "channels": 2,
            "channelLayout": "stereo",
            "chapters": [],
            "embeddedCoverArt": "mjpeg",
            "metaTags": {
              "tagAlbum": "Welcome to Night Vale",
              "tagArtist": "Night Vale Presents",
              "tagGenre": "Podcast",
              "tagTitle": "1 - Pilot",
              "tagDate": "2012",
              "tagEncoder": "Lavf58.45.100"
            },
            "mimeType": "audio/mpeg"
          },
          "audioTrack": {
            "index": 1,
            "startOffset": 0,
            "duration": 1454.18449,
            "title": "1 - Pilot.mp3",
            "contentUrl": "/s/item/li_bufnnmp4y5o2gbbxfm/1 - Pilot.mp3",
            "mimeType": "audio/mpeg",
            "metadata": {
              "filename": "1 - Pilot.mp3",
              "ext": ".mp3",
              "path": "/podcasts/Welcome to Night Vale/1 - Pilot.mp3",
              "relPath": "1 - Pilot.mp3",
              "size": 23653735,
              "mtimeMs": 1667326682557,
              "ctimeMs": 1667326682557,
              "birthtimeMs": 1667326679508
            }
          },
          "publishedAt": 1339761600000,
          "addedAt": 1667326679503,
          "updatedAt": 1667428186431,
          "duration": 1454.18449,
          "size": 23653735
        }
      ],
      "autoDownloadEpisodes": false,
      "autoDownloadSchedule": "0 0 * * 1",
      "lastEpisodeCheck": 1667326662087,
      "maxEpisodesToKeep": 0,
      "maxNewEpisodesToDownload": 3,
      "size": 23653735
    },
    "libraryFiles": [
      {
        "ino": "22587",
        "metadata": {
          "filename": "1 - Pilot.mp3",
          "ext": ".mp3",
          "path": "/podcasts/Welcome to Night Vale/1 - Pilot.mp3",
          "relPath": "1 - Pilot.mp3",
          "size": 23653735,
          "mtimeMs": 1667326682557,
          "ctimeMs": 1667326682557,
          "birthtimeMs": 1667326679508
        },
        "addedAt": 1667326682561,
        "updatedAt": 1667326682561,
        "fileType": "audio"
      },
      {
        "ino": "10113",
        "metadata": {
          "filename": "cover.jpg",
          "ext": ".jpg",
          "path": "/podcasts/Welcome to Night Vale/cover.jpg",
          "relPath": "cover.jpg",
          "size": 52993,
          "mtimeMs": 1667326662178,
          "ctimeMs": 1667326662184,
          "birthtimeMs": 1667326662090
        },
        "addedAt": 1667327311529,
        "updatedAt": 1667327311529,
        "fileType": "image"
      }
    ],
    "size": 23706728
  }
}

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

HTTP Request

URL Parameters

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

Parameters

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

Device Info Parameters

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

Response

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

Update a Library Item's Audio Tracks

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library item.

Parameters

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

Audio File Data Parameters

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

Response

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

Scan a Library Item

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

The above command returns JSON structured like this:

{
  "result": "UPDATED"
}

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library item.

Response

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

Response Schema

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

Get a Library Item's Tone Metadata Object

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library item.

Response

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

Response Schema

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

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

Update a Library Item's Chapters

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the library item.

Parameters

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

Response

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

Response Schema

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

Tone Scan a Library Item

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

The above command returns JSON structured like this:

{
  "audio": {
    "bitrate": 64,
    "format": "MPEG Audio (Layer III)",
    "formatShort": "MPEG",
    "sampleRate": 22050,
    "duration": 6004667,
    "channels": {
      "count": 2,
      "description": "Joint Stereo"
    },
    "frames": {
      "offset": 3857,
      "length": 66381321
    },
    "metaFormat": [
      "id3V23",
      "id3V1"
    ]
  },
  "meta": {
    "album": "Sword of Truth",
    "albumArtist": "Terry Goodkind",
    "artist": "Terry Goodkind",
    "composer": "Sam Tsoutsouvas",
    "comment": "The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.",
    "encoderSettings": "LAME 32bits version 3.99.5 (http://lame.sf.net)",
    "genre": "Fantasy",
    "recordingDate": "2008-01-01T00:00:00",
    "title": "Wizards First Rule",
    "trackNumber": 1,
    "additionalFields": {
      "ufid": "FID",
      "narratedby": "ARRATEDBY",
      "woas": "OAS"
    }
  },
  "file": {
    "size": 48037888,
    "created": "2022-04-22T09:51:14.299+00:00",
    "modified": "2022-04-22T09:51:14.299+00:00",
    "accessed": "2022-04-22T09:51:14.299+00:00",
    "path": "/audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule",
    "name": "Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3"
  }
}

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

HTTP Request

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

URL Parameters

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

Response

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

Response Schema

See tone for details.

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

Batch Delete Library Items

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

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

HTTP Request

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

Parameters

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

Response

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

Batch Update Library Items

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

The above command returns JSON structured like this:

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

This endpoint batch updates library items.

HTTP Request

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

Parameters

Provide an array of objects with the following parameters:

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

Response

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

Response Schema

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

Batch Get Library Items

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

The above command returns JSON structured like this:

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

This endpoint batch gets library items.

HTTP Request

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

Parameters

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

Response

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

Response Schema

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

Batch Quick Match Library Items

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

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

HTTP Request

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

Parameters

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

Options Parameters

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

Response

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

Users

Create a User

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

The above command returns JSON structured like this:

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

This endpoint creates a user.

HTTP Request

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

Parameters

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

User Permissions Parameters

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

Response

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

Get All Users

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

The above command returns JSON structured like this:

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

This endpoint retrieves all users.

HTTP Request

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

Response

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

Response Schema

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

Get Online Users

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

The above command returns JSON structured like this:

{
  "usersOnline": [
    {
      "id": "root",
      "username": "paul",
      "type": "root",
      "session": null,
      "lastSeen": 1668324661087,
      "createdAt": 1666543632566
    }
  ],
  "openSessions": [
    {
      "id": "play_3m7y81exxkpodebwvd",
      "userId": "root",
      "libraryId": "lib_p9wkw2i85qy9oltijt",
      "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
      "episodeId": "ep_lh6ko39pumnrma3dhv",
      "mediaType": "podcast",
      "mediaMetadata": {
        "title": "Welcome to Night Vale",
        "author": "Night Vale Presents",
        "description": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
        "releaseDate": "2022-10-20T19:00:00Z",
        "genres": [
          "Science Fiction",
          "Podcasts",
          "Fiction"
        ],
        "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
        "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
        "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
        "itunesId": 536258179,
        "itunesArtistId": 718704794,
        "explicit": false,
        "language": null
      },
      "chapters": [],
      "displayTitle": "1 - Pilot",
      "displayAuthor": "Night Vale Presents",
      "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
      "duration": 1454.18449,
      "playMethod": 0,
      "mediaPlayer": "html5",
      "deviceInfo": {
        "ipAddress": "192.168.1.118",
        "browserName": "Firefox",
        "browserVersion": "106.0",
        "osName": "Linux",
        "osVersion": "x86_64",
        "serverVersion": "2.2.3"
      },
      "date": "2022-11-13",
      "dayOfWeek": "Sunday",
      "timeListening": 595,
      "startTime": 0,
      "currentTime": 595,
      "startedAt": 1668329239515,
      "updatedAt": 1668329240593
    }
  ]
}

This endpoint retrieves all online users.

HTTP Request

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

Response

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

Response Schema

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

Get a User

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

The above command returns JSON structured like this:

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

This endpoint retrieves a user.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the user.

Response

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

Update a User

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

The above command returns JSON structured like this:

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

This endpoint updates a user.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the user.

Parameters

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

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

User Permissions Parameters

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

Response

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

Response Schema

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

Delete a User

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

The above command returns JSON structured like this:

{
  "success": true
}

This endpoint deletes a user.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the user.

Response

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

Response Schema

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

Get a User's Listening Sessions

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

The above command returns JSON structured like this:

{
  "total": 37,
  "numPages": 37,
  "page": 0,
  "itemsPerPage": 1,
  "sessions": [
    {
      "id": "play_4oq00chunexu9s03jw",
      "userId": "root",
      "libraryId": "lib_p9wkw2i85qy9oltijt",
      "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
      "episodeId": "ep_lh6ko39pumnrma3dhv",
      "mediaType": "podcast",
      "mediaMetadata": {
        "title": "Welcome to Night Vale",
        "author": "Night Vale Presents",
        "description": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
        "releaseDate": "2022-10-20T19:00:00Z",
        "genres": [
          "Science Fiction",
          "Podcasts",
          "Fiction"
        ],
        "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
        "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
        "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
        "itunesId": 536258179,
        "itunesArtistId": 718704794,
        "explicit": false,
        "language": null
      },
      "chapters": [],
      "displayTitle": "1 - Pilot",
      "displayAuthor": "Night Vale Presents",
      "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
      "duration": 1454.18449,
      "playMethod": 0,
      "mediaPlayer": "html5",
      "deviceInfo": {
        "ipAddress": "192.168.1.118",
        "browserName": "Firefox",
        "browserVersion": "106.0",
        "osName": "Linux",
        "osVersion": "x86_64",
        "serverVersion": "2.2.3"
      },
      "date": "2022-11-13",
      "dayOfWeek": "Sunday",
      "timeListening": 15,
      "startTime": 596.779402,
      "currentTime": 611.590717,
      "startedAt": 1668330137087,
      "updatedAt": 1668330152157
    }
  ]
}

This endpoint retrieves a user's listening sessions.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the user.

Query Parameters

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

Response

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

Response Schema

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

Get a User's Listening Stats

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

The above command returns JSON structured like this:

{
  "totalTime": 493,
  "items": {
    "li_bufnnmp4y5o2gbbxfm": {
      "id": "li_bufnnmp4y5o2gbbxfm",
      "timeListening": 63,
      "mediaMetadata": {
        "title": "Welcome to Night Vale",
        "author": "Night Vale Presents",
        "description": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
        "releaseDate": "2022-10-20T19:00:00Z",
        "genres": [
          "Science Fiction",
          "Podcasts",
          "Fiction"
        ],
        "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
        "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
        "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
        "itunesId": 536258179,
        "itunesArtistId": 718704794,
        "explicit": false,
        "language": null,
        "type": "episodic"
      }
    },
    ...
  },
  "days": {
    "2022-11-13": 104,
    "2022-11-12": 3,
    "2022-11-11": 1,
    "2022-11-10": 30,
    "2022-11-06": 14,
    "2022-11-05": 12,
    "2022-11-04": 20,
    "2022-10-26": 12,
    "2022-10-25": 206,
    "2022-10-24": 73,
    "2022-10-23": 12
  },
  "dayOfWeek": {
    "Sunday": 130,
    "Saturday": 15,
    "Friday": 21,
    "Thursday": 30,
    "Wednesday": 12,
    "Tuesday": 206,
    "Monday": 73
  },
  "today": 104,
  "recentSessions": [
    {
      "id": "play_4oq00chunexu9s03jw",
      "userId": "root",
      "libraryId": "lib_p9wkw2i85qy9oltijt",
      "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
      "episodeId": "ep_lh6ko39pumnrma3dhv",
      "mediaType": "podcast",
      "mediaMetadata": {
        "title": "Welcome to Night Vale",
        "author": "Night Vale Presents",
        "description": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
        "releaseDate": "2022-10-20T19:00:00Z",
        "genres": [
          "Science Fiction",
          "Podcasts",
          "Fiction"
        ],
        "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
        "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
        "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
        "itunesId": 536258179,
        "itunesArtistId": 718704794,
        "explicit": false,
        "language": null,
        "type": "episodic"
      },
      "chapters": [],
      "displayTitle": "1 - Pilot",
      "displayAuthor": "Night Vale Presents",
      "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
      "duration": 1454.18449,
      "playMethod": 0,
      "mediaPlayer": "html5",
      "deviceInfo": {
        "ipAddress": "192.168.1.118",
        "browserName": "Firefox",
        "browserVersion": "106.0",
        "osName": "Linux",
        "osVersion": "x86_64",
        "serverVersion": "2.2.3"
      },
      "date": "2022-11-13",
      "dayOfWeek": "Sunday",
      "timeListening": 15,
      "startTime": 596.779402,
      "currentTime": 611.590717,
      "startedAt": 1668330137087,
      "updatedAt": 1668330152157
    },
    ...
  ]
}

This endpoint retrieves a user's listening statistics.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the user.

Response

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

Response Schema

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

Items Listened To

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

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

Day Time Totals

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

Day of Week Totals

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

Purge a User's Media Progress

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the user.

Response

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

Collections

Create a Collection

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

The above command returns JSON structured like this:

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

This endpoint creates a collection and returns it.

HTTP Request

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

Parameters

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

Response

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

Get All Collections

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

The above command returns JSON structured like this:

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

This endpoint retrieves all collections.

HTTP Request

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

Response

Status Meaning Description Schema
200 OK Success See Below

Response Schema

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

Get a Collection

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

The above command returns JSON structured like this:

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

This endpoint retrieves a collection.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the collection.

Optional Query Parameters

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

Response

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

Extra Attributes

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

Update a Collection

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

The above command returns JSON structured like this:

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

This endpoint updates a collection and returns it.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the collection.

Parameters

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

Response

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

Delete a Collection

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

This endpoint deletes a collection from the database.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the collection.

Response

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

Add a Book to a Collection

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the collection.

Parameters

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

Response

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

Remove a Book From a Collection

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

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

Response

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

Batch Add Books to a Collection

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the collection.

Parameters

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

Response

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

Batch Remove Books From a Collection

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the collection.

Parameters

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

Response

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

Playlists

Create a Playlist

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

The above command returns JSON structured like this:

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

This endpoint creates a playlist and returns it.

HTTP Request

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

Parameters

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

Response

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

Get All User Playlists

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

The above command returns JSON structured like this:

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

This endpoint retrieves all playlists belonging to the authenticated user.

HTTP Request

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

Response

Status Meaning Description Schema
200 OK Success See Below

Response Schema

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

Get a Playlist

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

The above command returns JSON structured like this:

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

This endpoint retrieves a playlist.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the playlist.

Response

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

Update a Playlist

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

{
  "id": "pl_qbwet64998s5ra6dcu",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "The Best Books",
  "description": null,
  "coverPath": null,
  "items": [],
  "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

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

{
  "id": "pl_qbwet64998s5ra6dcu",
  "libraryId": "lib_c1u6t4p45c35rf0nzd",
  "userId": "root",
  "name": "The Best Books",
  "description": null,
  "coverPath": null,
  "items": [],
  "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"

The above command returns JSON structured like this:

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

This endpoint creates a playlist 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"

The above command returns JSON structured like this:

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

This endpoint retrieves 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"

The above command returns JSON structured like this:

{
  "total": 37,
  "numPages": 37,
  "page": 0,
  "itemsPerPage": 1,
  "sessions": [
    {
      "id": "play_4oq00chunexu9s03jw",
      "userId": "root",
      "libraryId": "lib_p9wkw2i85qy9oltijt",
      "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
      "episodeId": "ep_lh6ko39pumnrma3dhv",
      "mediaType": "podcast",
      "mediaMetadata": {
        "title": "Welcome to Night Vale",
        "author": "Night Vale Presents",
        "description": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
        "releaseDate": "2022-10-20T19:00:00Z",
        "genres": [
          "Science Fiction",
          "Podcasts",
          "Fiction"
        ],
        "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
        "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
        "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
        "itunesId": 536258179,
        "itunesArtistId": 718704794,
        "explicit": false,
        "language": null
      },
      "chapters": [],
      "displayTitle": "1 - Pilot",
      "displayAuthor": "Night Vale Presents",
      "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
      "duration": 1454.18449,
      "playMethod": 0,
      "mediaPlayer": "html5",
      "deviceInfo": {
        "ipAddress": "192.168.1.118",
        "browserName": "Firefox",
        "browserVersion": "106.0",
        "osName": "Linux",
        "osVersion": "x86_64",
        "serverVersion": "2.2.3"
      },
      "date": "2022-11-13",
      "dayOfWeek": "Sunday",
      "timeListening": 15,
      "startTime": 596.779402,
      "currentTime": 611.590717,
      "startedAt": 1668330137087,
      "updatedAt": 1668330152157
    }
  ]
}

This endpoint retrieves 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"

The above command returns JSON structured like this:

{
  "totalTime": 493,
  "items": {
    "li_bufnnmp4y5o2gbbxfm": {
      "id": "li_bufnnmp4y5o2gbbxfm",
      "timeListening": 63,
      "mediaMetadata": {
        "title": "Welcome to Night Vale",
        "author": "Night Vale Presents",
        "description": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
        "releaseDate": "2022-10-20T19:00:00Z",
        "genres": [
          "Science Fiction",
          "Podcasts",
          "Fiction"
        ],
        "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
        "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
        "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
        "itunesId": 536258179,
        "itunesArtistId": 718704794,
        "explicit": false,
        "language": null,
        "type": "episodic"
      }
    },
    ...
  },
  "days": {
    "2022-11-13": 104,
    "2022-11-12": 3,
    "2022-11-11": 1,
    "2022-11-10": 30,
    "2022-11-06": 14,
    "2022-11-05": 12,
    "2022-11-04": 20,
    "2022-10-26": 12,
    "2022-10-25": 206,
    "2022-10-24": 73,
    "2022-10-23": 12
  },
  "dayOfWeek": {
    "Sunday": 130,
    "Saturday": 15,
    "Friday": 21,
    "Thursday": 30,
    "Wednesday": 12,
    "Tuesday": 206,
    "Monday": 73
  },
  "today": 104,
  "recentSessions": [
    {
      "id": "play_4oq00chunexu9s03jw",
      "userId": "root",
      "libraryId": "lib_p9wkw2i85qy9oltijt",
      "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
      "episodeId": "ep_lh6ko39pumnrma3dhv",
      "mediaType": "podcast",
      "mediaMetadata": {
        "title": "Welcome to Night Vale",
        "author": "Night Vale Presents",
        "description": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
        "releaseDate": "2022-10-20T19:00:00Z",
        "genres": [
          "Science Fiction",
          "Podcasts",
          "Fiction"
        ],
        "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
        "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
        "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
        "itunesId": 536258179,
        "itunesArtistId": 718704794,
        "explicit": false,
        "language": null
      },
      "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"

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

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

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

Directory

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.

Authors

Get an Author

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command writes an image file.

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"

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

{
  "total": 37,
  "numPages": 37,
  "page": 0,
  "itemsPerPage": 1,
  "sessions": [
    {
      "id": "play_4oq00chunexu9s03jw",
      "userId": "root",
      "libraryId": "lib_p9wkw2i85qy9oltijt",
      "libraryItemId": "li_bufnnmp4y5o2gbbxfm",
      "episodeId": "ep_lh6ko39pumnrma3dhv",
      "mediaType": "podcast",
      "mediaMetadata": {
        "title": "Welcome to Night Vale",
        "author": "Night Vale Presents",
        "description": "\n      Twice-monthly community updates for the small desert town of Night Vale, where every conspiracy theory is true. Turn on your radio and hide. Never listened before? It's an ongoing radio show. Start with the current episode, and you'll catch on in no time. Or, go right to Episode 1 if you wanna binge-listen.\n    ",
        "releaseDate": "2022-10-20T19:00:00Z",
        "genres": [
          "Science Fiction",
          "Podcasts",
          "Fiction"
        ],
        "feedUrl": "http://feeds.nightvalepresents.com/welcometonightvalepodcast",
        "imageUrl": "https://is4-ssl.mzstatic.com/image/thumb/Podcasts125/v4/4a/31/35/4a3135d0-1fe7-a2d7-fb43-d182ec175402/mza_8232698753950666850.jpg/600x600bb.jpg",
        "itunesPageUrl": "https://podcasts.apple.com/us/podcast/welcome-to-night-vale/id536258179?uo=4",
        "itunesId": 536258179,
        "itunesArtistId": 718704794,
        "explicit": false,
        "language": null
      },
      "chapters": [],
      "displayTitle": "1 - Pilot",
      "displayAuthor": "Night Vale Presents",
      "coverPath": "/metadata/items/li_bufnnmp4y5o2gbbxfm/cover.jpg",
      "duration": 1454.18449,
      "playMethod": 0,
      "mediaPlayer": "html5",
      "deviceInfo": {
        "ipAddress": "192.168.1.118",
        "browserName": "Firefox",
        "browserVersion": "106.0",
        "osName": "Linux",
        "osVersion": "x86_64",
        "serverVersion": "2.2.3"
      },
      "date": "2022-11-13",
      "dayOfWeek": "Sunday",
      "timeListening": 15,
      "startTime": 596.779402,
      "currentTime": 611.590717,
      "startedAt": 1668330137087,
      "updatedAt": 1668330152157
    }
  ],
  "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}]}'

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

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"

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

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"

The above command returns JSON structured like this:

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

Metadata Provider: Google

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

The above command returns JSON structured like this:

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

Metadata Provider: Open Library

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

The above command returns JSON structured like this:

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

Metadata Provider: iTunes

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

The above command returns JSON structured like this:

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

Metadata Provider: Audible

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

The above command returns JSON structured like this:

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

Metadata Provider: FantLab

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

The above command returns JSON structured like this:

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

auth

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

cancel_scan

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

set_log_listener

socket.emit('set_log_listener', 2)

message_all_users

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

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

The available values depend on the group:

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

Other filters are issues and feed-open.

Examples:

Schemas

Library

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

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

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

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)

Library Item

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

Library Item Minified

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

Library Item Expanded

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

Modified Attributes

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

Added Attributes

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

Book

Book

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

Book Minified

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

Book Expanded

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

Modified Attributes

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

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

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
}

Book Metadata Minified

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

Book Metadata Expanded

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

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

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

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
}

Podcast Minified

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

Podcast Expanded

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

Modified Attributes

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

Added Attributes

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

Podcast Metadata

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

Podcast Metadata Minified

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

Podcast Metadata Expanded

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

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
}

Podcast Episode Expanded

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

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

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

Podcast Feed

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

Podcast Feed Minified

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

Added Attributes

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

Podcast Feed Metadata

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

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

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

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

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

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

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

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

Author

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

Author Minified

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

Author Expanded

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

Author Expanded

Added Attributes

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

Series

Series

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

Series Num Books

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

Series Books

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

Series Sequence

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

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

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

Added Attributes

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

Collection

Collection

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

Collection Expanded

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

Playlist

Playlist

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

Playlist Expanded

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

Playlist Item

Playlist Item

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

Playlist Item Expanded

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

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
}

Media Progress with Media

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

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
}

Playback Session Expanded

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

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

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

User with Progress Details

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

User with Session

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

User with Session

Removed Attributes

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

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

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

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

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

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

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

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

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
}

RSS Feed Minified

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

Modified Attributes

RSS Feed Metadata

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
}

RSS Feed Metadata Minified

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

RSS Feed Episode

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

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